openapi: 3.0.3
info:
  title: FishAudio 文字对口型
  version: 1.1.0
  description: >-
    将此文件导入扣子私有云端插件。工具会使用指定的 Fish Audio 音色将文字
    生成语音，再创建和查询异步对口型视频任务。每位用户在运行时通过
    Authorization 参数填写自己的 Fish Audio API Key。
servers:
  - url: https://fishaudio.org
paths:
  /api/open/v1/media/video-dubbing/jobs:
    post:
      operationId: create_text_lip_sync
      summary: 将文字生成语音并创建对口型视频
      description: >-
        使用文字和 Fish Audio 音色 ID 生成 TTS 音频，再创建一个异步对口型任务。
        保存响应中的 data.id。只有重试完全相同的请求时才复用原 Idempotency-Key。
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTextLipSyncRequest'
      responses:
        '200':
          description: TTS 已完成，对口型任务已成功创建
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoDubbingResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '402':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
        '413':
          $ref: '#/components/responses/ErrorResponse'
        '415':
          $ref: '#/components/responses/ErrorResponse'
        '422':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'
        '503':
          $ref: '#/components/responses/ErrorResponse'
        '504':
          $ref: '#/components/responses/ErrorResponse'
  /api/open/v1/media/video-dubbing/jobs/{jobId}:
    get:
      operationId: get_text_lip_sync_job
      summary: 查询文字对口型视频任务
      description: >-
        使用原任务 ID 查询进度。查询不会重新生成语音，也不会新建对口型任务或重复扣费。
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - name: jobId
          in: path
          required: true
          description: 填写 create_text_lip_sync 返回的 data.id。
          schema:
            type: string
      responses:
        '200':
          description: 任务状态查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VideoDubbingResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'
components:
  parameters:
    Authorization:
      name: Authorization
      in: header
      required: true
      description: 填写 Fish Audio API Key，格式为 Bearer + 空格 + API Key。
      schema:
        type: string
      example: Bearer YOUR_FISH_AUDIO_API_KEY
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: >-
        每次新生成填写一个唯一值。仅重试完全相同的请求时复用，避免重复创建和扣费。
      schema:
        type: string
        maxLength: 200
      example: coze-text-lip-sync-20260822-001
  schemas:
    CreateTextLipSyncRequest:
      type: object
      required:
        - video_url
        - text
        - reference_id
      properties:
        video_url:
          type: string
          format: uri
          description: 客户自有或已获授权、Fish Audio 服务端可直接下载的视频 URL。
        text:
          type: string
          minLength: 1
          maxLength: 5000
          description: 用于生成替换配音的文字，最长 5000 字符。
        reference_id:
          type: string
          minLength: 1
          description: 用于 TTS 的 Fish Audio 系统音色或当前账户私有音色 ID。
        model_id:
          type: string
          default: fishaudio-s21pro-flash
          description: Fish Audio 语音合成模型，首次测试建议使用默认值。
          enum:
            - fishaudio-s21pro
            - fishaudio-s21pro-flash
            - fishaudio-s2pro
            - fishaudio-s1
        speed:
          type: number
          minimum: 0.5
          maximum: 2
          default: 1
          description: 语速倍率，范围 0.5～2，默认为 1。
        volume:
          type: number
          minimum: -20
          maximum: 20
          default: 0
          description: 输出音量调整，范围 -20～20，默认为 0。
        pitch:
          type: number
          minimum: -12
          maximum: 12
          description: 可选。调整音高，范围 -12～12 个半音。
        stability:
          type: number
          minimum: 0.5
          maximum: 1.5
          description: 可选。控制声音稳定性，范围 0.5～1.5。
        similarity:
          type: number
          minimum: 0.5
          maximum: 1.5
          description: 可选。控制音色相似度，范围 0.5～1.5。
        language:
          type: string
          maxLength: 32
          description: 可选。指定合成语言提示，需所选模型支持。
        emotion:
          type: string
          maxLength: 64
          description: 可选。指定情绪，需所选模型支持。
        instruction:
          type: string
          maxLength: 1600
          description: 可选。描述角色、方言、语气、节奏或情绪，最长 1600 字符。
        text_normalization:
          type: boolean
          default: true
          description: 合成前对文本做规范化处理，默认为 true。
        fit_audio_to_video:
          type: boolean
          default: false
          description: >-
            设为 true 后，自动调整配音速度以匹配视频时长，且不改变音高。支持
            0.5x～2x；超出范围时会在创建对口型任务前返回错误。
    VideoDubbingResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
        message:
          type: string
        requestId:
          type: string
        data:
          type: object
          required:
            - id
            - status
            - stage
            - progress
          properties:
            id:
              type: string
              description: 保存该值，后续作为 jobId 查询任务。
            status:
              type: string
              enum:
                - pending
                - processing
                - completed
                - failed
            stage:
              type: string
              enum:
                - lip_sync
                - completed
                - failed
            progress:
              type: number
              minimum: 0
              maximum: 100
            result_url:
              type: string
              format: uri
              nullable: true
              description: 任务完成后返回的临时视频 URL，请及时下载或转存。
            audio_url:
              type: string
              format: uri
              nullable: true
              description: 第一步 TTS 生成的中间音频 URL。
            error_message:
              type: string
              nullable: true
            created_at:
              type: string
            updated_at:
              type: string
            completed_at:
              type: string
              nullable: true
            estimated_time:
              type: number
              nullable: true
            result_expires_at:
              type: string
              nullable: true
            result_expired:
              type: boolean
            credits_used:
              type: object
              properties:
                tts:
                  type: number
                lip_sync:
                  type: number
                total:
                  type: number
            quota_remaining:
              type: number
              nullable: true
            idempotency_replayed:
              type: boolean
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
        requestId:
          type: string
      additionalProperties: true
  responses:
    ErrorResponse:
      description: Fish Audio API 错误
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'