openapi: 3.0.3
info:
  title: FishAudio 图片/视频对口型
  version: 1.0.0
  description: >-
    将此文件导入扣子私有云端插件，用于创建和查询异步图片/视频对口型任务。
    每位用户在工具运行时通过 Authorization 参数填写自己的 Fish Audio API Key。
servers:
  - url: https://fishaudio.org
paths:
  /api/open/v1/media/lip-sync/jobs:
    post:
      operationId: create_media_sync
      summary: 创建异步图片/视频对口型任务
      description: >-
        使用 Fish Audio 服务端可直接下载的视频和音频 URL 创建一个任务。
        保存响应中的 data.id；查询期间不要重复创建任务，避免重复扣费。
      parameters:
        - $ref: '#/components/parameters/Authorization'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMediaSyncRequest'
      responses:
        '200':
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateMediaSyncResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '402':
          $ref: '#/components/responses/ErrorResponse'
        '403':
          $ref: '#/components/responses/ErrorResponse'
        '422':
          $ref: '#/components/responses/ErrorResponse'
        '500':
          $ref: '#/components/responses/ErrorResponse'
  /api/open/v1/media/lip-sync/jobs/{jobId}:
    get:
      operationId: get_media_sync_job
      summary: 查询图片/视频对口型任务
      description: 使用原任务 ID 查询进度。查询不会创建新任务，也不会重复扣费。
      parameters:
        - $ref: '#/components/parameters/Authorization'
        - name: jobId
          in: path
          required: true
          description: 填写 create_media_sync 返回的 data.id。
          schema:
            type: string
      responses:
        '200':
          description: 任务状态查询成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMediaSyncResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '403':
          $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
  schemas:
    CreateMediaSyncRequest:
      type: object
      required:
        - video_url
        - audio_url
      properties:
        video_url:
          type: string
          format: uri
          description: 客户自有或已获授权、Fish Audio 服务端可直接下载的视频 URL。
        audio_url:
          type: string
          format: uri
          description: 客户自有或已获授权、Fish Audio 服务端可直接下载的音频 URL。
        model:
          type: string
          nullable: true
          description: 可选。模型 ID；通常留空以使用当前默认模型。
        video_extension:
          type: boolean
          default: false
          description: >-
            默认保持 false，按视频和音频中较短时长计费。只有明确需要将视频
            延长到音频时长时才设为 true。
    CreateMediaSyncResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          type: object
          required:
            - id
            - status
            - created_at
            - credits_used
            - billing_duration_seconds
            - video_duration_seconds
            - audio_duration_seconds
            - billing_rule
            - quota_remaining
          properties:
            id:
              type: string
              description: 保存该值，后续作为 jobId 查询任务。
            status:
              type: string
              enum:
                - pending
                - processing
                - completed
                - failed
            created_at:
              type: string
            credits_used:
              type: number
            billing_duration_seconds:
              type: integer
              description: 向上取整后的计费秒数。
            video_duration_seconds:
              type: number
              nullable: true
            audio_duration_seconds:
              type: number
            billing_rule:
              type: string
              enum:
                - shorter_input_rounded_up
                - audio_rounded_up
            quota_remaining:
              type: number
    GetMediaSyncResponse:
      type: object
      required:
        - success
        - data
      properties:
        success:
          type: boolean
        message:
          type: string
        data:
          type: object
          required:
            - id
            - status
            - progress
          properties:
            id:
              type: string
            status:
              type: string
              enum:
                - pending
                - processing
                - completed
                - failed
            progress:
              type: number
              minimum: 0
              maximum: 100
            result_url:
              type: string
              format: uri
              nullable: true
            error_message:
              type: string
              nullable: true
            credits_used:
              type: number
            created_at:
              type: string
            updated_at:
              type: string
            completed_at:
              type: string
              nullable: true
    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'