openapi: 3.1.0
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
info:
  title: 剪狐短剧翻译 API（JIANHU Drama Translation API）
  version: 1.0.0
  description: >-
    面向短剧出海与漫剧本地化的剪狐国内 REST API 专用契约。


    - 仅包含短剧批量翻译（1–100 集）所需的上传、任务创建、查询、部分集重试、取消、余额查询与 Webhook 验签接口。

    - 默认高质量原声克隆（不开放相似/固定音色，无需传音色参数）、默认开启全剧共享术语与剧情上下文、暂不开放姓名卡（画面文字）翻译。

    - 支持可选角色分析（+¥0.010/秒）、去原硬字幕（单/多/全区域
    +¥0.020/+¥0.040/+¥0.060/秒）、完整字幕字体样式（subtitle_style）与布局（subtitle_layout）。

    - 计费按全剧总时长向上取整到整秒，整单最低 15 秒；独立人民币钱包，享 365 天累计净充值折扣。
servers:
  - url: https://unmarkai.cn/api
    description: 剪狐国内生产环境（路径已含 /v1）
tags:
  - name: Public Uploads
    description: 批量初始化分集视频直传或 HTTPS 直链导入
  - name: Public Jobs
    description: 创建、查询、部分集重试与取消短剧翻译任务
  - name: Public Balance
    description: 查询独立人民币 API 钱包与短剧折后单价
  - name: API Webhooks
    description: 任务状态变更 Webhook 签名回调
paths:
  /v1/uploads:
    post:
      tags:
        - Public Uploads
      operationId: createApiUpload
      summary: 初始化视频直传
      description: |
        返回有效 1 小时的 signed PUT URL。调用方必须使用返回的
        `content-type`、`content-length` 和 `if-none-match` 原样上传视频字节。
        `if-none-match: *` 使对象只能创建一次；同一 ticket 重复 PUT 会被拒绝（409 或 412）。
        上传记录未被使用时有效 24 小时。账号至少要有一次最低计费余额；最多同时
        保留 100 个未绑定 Job 的有效 ticket，滚动 24 小时未消费上传量最多 20 GiB；
        已进入资金冻结或实际扣费的 Job 输入不再计入该上传量。
      security:
        - ApiKeyBearer: []
      parameters:
        - $ref: "#/components/parameters/OptionalRequestId"
      requestBody:
        required: true
        description: JSON 请求体不得超过 64 KiB；视频字节不经过此接口。
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UploadCreateRequest"
            example:
              filename: source.mp4
              content_type: video/mp4
              file_size_bytes: 10485760
      responses:
        "201":
          description: 上传已初始化
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadTicket"
        "400":
          $ref: "#/components/responses/PublicBadRequest"
        "401":
          $ref: "#/components/responses/PublicUnauthorized"
        "402":
          $ref: "#/components/responses/PublicPaymentRequired"
        "403":
          $ref: "#/components/responses/PublicForbidden"
        "405":
          $ref: "#/components/responses/PublicMethodNotAllowed"
        "413":
          $ref: "#/components/responses/PublicPayloadTooLarge"
        "415":
          $ref: "#/components/responses/PublicUnsupportedMediaType"
        "429":
          $ref: "#/components/responses/PublicRateLimited"
        "500":
          $ref: "#/components/responses/PublicServerError"
        "502":
          $ref: "#/components/responses/PublicGatewayError"
        "503":
          $ref: "#/components/responses/PublicServiceUnavailable"
  /v1/url-uploads:
    post:
      tags:
        - Public Uploads
      operationId: createApiUrlUpload
      summary: 从直链异步导入视频
      description: |
        从可直接下载的公网 HTTPS 视频 URL 异步导入。支持带签名查询参数的 URL，
        不支持网页、YouTube 或 TikTok 页面链接。源站必须返回稳定的
        `Content-Length` 和受支持的视频 MIME；最大 2 GiB。
        `Idempotency-Key` 在 API account 内有效 24 小时。
      security:
        - ApiKeyBearer: []
      parameters:
        - $ref: "#/components/parameters/OptionalRequestId"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UrlUploadCreateRequest"
            example:
              source_url: https://cdn.example.com/source.mp4?signature=xxx
              filename: source.mp4
      responses:
        "200":
          description: 幂等重放已有导入
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Upload"
        "202":
          description: 已开始异步导入
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Upload"
        "400":
          $ref: "#/components/responses/PublicBadRequest"
        "401":
          $ref: "#/components/responses/PublicUnauthorized"
        "402":
          $ref: "#/components/responses/PublicPaymentRequired"
        "403":
          $ref: "#/components/responses/PublicForbidden"
        "409":
          $ref: "#/components/responses/PublicConflict"
        "413":
          $ref: "#/components/responses/PublicPayloadTooLarge"
        "415":
          $ref: "#/components/responses/PublicUnsupportedMediaType"
        "429":
          $ref: "#/components/responses/PublicRateLimited"
        "500":
          $ref: "#/components/responses/PublicServerError"
        "502":
          $ref: "#/components/responses/PublicGatewayError"
        "503":
          $ref: "#/components/responses/PublicServiceUnavailable"
  /v1/uploads/{upload_id}:
    get:
      tags:
        - Public Uploads
      operationId: getApiUpload
      summary: 查询上传或 URL 导入状态
      security:
        - ApiKeyBearer: []
      parameters:
        - $ref: "#/components/parameters/UploadId"
        - $ref: "#/components/parameters/OptionalRequestId"
      responses:
        "200":
          description: 上传状态
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Upload"
        "400":
          $ref: "#/components/responses/PublicBadRequest"
        "401":
          $ref: "#/components/responses/PublicUnauthorized"
        "403":
          $ref: "#/components/responses/PublicForbidden"
        "404":
          $ref: "#/components/responses/PublicNotFound"
        "429":
          $ref: "#/components/responses/PublicRateLimited"
        "500":
          $ref: "#/components/responses/PublicServerError"
        "502":
          $ref: "#/components/responses/PublicGatewayError"
        "503":
          $ref: "#/components/responses/PublicServiceUnavailable"
  /v1/jobs:
    post:
      tags:
        - Public Jobs
      operationId: createApiJob
      summary: 创建短剧翻译 Job
      description: 创建 1–100
        集的异步短剧翻译任务。默认高质量原声克隆、全剧共享术语与剧情上下文，支持可选角色分析（+¥0.010/秒）、去原硬字幕（单/多/全区域
        +¥0.020/+¥0.040/+¥0.060/秒）及完整字幕字体样式设置。按全剧总时长向上取整到整秒，整单最低 15 秒。
      security:
        - ApiKeyBearer: []
      parameters:
        - $ref: "#/components/parameters/OptionalRequestId"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        description: 视频翻译创建请求体最多 512 KiB；其他 Job 创建请求体最多 64 KiB。
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DramaTranslationCreateRequest"
            example:
              type: drama_translation
              input:
                episodes:
                  - upload_id: upl_ep01
                  - upload_id: upl_ep02
                  - upload_id: upl_ep03
              source_language: zh
              target_language: en
              target_locale: en-US
              advanced_quality: false
              cast_enabled: true
              subtitle_erase:
                enabled: true
                mode: sel_area
                rect:
                  x1: 60
                  y1: 1460
                  x2: 1020
                  y2: 1740
              subtitle_enabled: true
              subtitle_mode: translated
              subtitle_style:
                preset: bold
                font_id: montserrat
                primary_color: "#FFFFFF"
                outline_color: "#000000"
                font_weight: 800
                font_scale: 1
                outline_width: 4
                shadow: 0
                background_opacity: 0
                animation: none
              subtitle_layout:
                top_percent: 76
                height_percent: 16
              metadata:
                drama_id: drama_001
      responses:
        "202":
          description: 已接受；幂等重放也返回此状态
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DramaTranslationJob"
        "400":
          $ref: "#/components/responses/PublicBadRequest"
        "401":
          $ref: "#/components/responses/PublicUnauthorized"
        "402":
          $ref: "#/components/responses/PublicPaymentRequired"
        "403":
          $ref: "#/components/responses/PublicForbidden"
        "404":
          $ref: "#/components/responses/PublicNotFound"
        "405":
          $ref: "#/components/responses/PublicMethodNotAllowed"
        "409":
          $ref: "#/components/responses/PublicConflict"
        "413":
          $ref: "#/components/responses/PublicPayloadTooLarge"
        "415":
          $ref: "#/components/responses/PublicUnsupportedMediaType"
        "422":
          $ref: "#/components/responses/PublicUnprocessable"
        "429":
          $ref: "#/components/responses/PublicRateLimited"
        "500":
          $ref: "#/components/responses/PublicServerError"
        "502":
          $ref: "#/components/responses/PublicGatewayError"
        "503":
          $ref: "#/components/responses/PublicServiceUnavailable"
    get:
      tags:
        - Public Jobs
      operationId: listApiJobs
      summary: 列出 Job
      description: 按 `created_at,id` 倒序进行 cursor 分页。
      security:
        - ApiKeyBearer: []
      parameters:
        - $ref: "#/components/parameters/OptionalRequestId"
        - name: status
          in: query
          required: false
          description: 按公开状态过滤
          schema:
            $ref: "#/components/schemas/JobStatus"
        - name: limit
          in: query
          required: false
          description: 每页数量
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: after
          in: query
          required: false
          description: 上一页 `next_cursor` 返回的不透明 base64url cursor
          schema:
            type: string
            maxLength: 1024
      responses:
        "200":
          description: Job 列表
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DramaJobList"
        "400":
          $ref: "#/components/responses/PublicBadRequest"
        "401":
          $ref: "#/components/responses/PublicUnauthorized"
        "403":
          $ref: "#/components/responses/PublicForbidden"
        "405":
          $ref: "#/components/responses/PublicMethodNotAllowed"
        "429":
          $ref: "#/components/responses/PublicRateLimited"
        "500":
          $ref: "#/components/responses/PublicServerError"
        "502":
          $ref: "#/components/responses/PublicGatewayError"
        "503":
          $ref: "#/components/responses/PublicServiceUnavailable"
  /v1/jobs/{job_id}:
    get:
      tags:
        - Public Jobs
      operationId: getApiJob
      summary: 查询 Job、状态与进度
      description: |
        这是公共 API 的进度查询接口。Webhook 仅在状态跃迁时发送，不推送每个进度值。
        成功结果默认保留 7 天；`result.url` 每次最多签名 1 小时并受剩余保留期限制。
        客户只能使用 Job 响应中的临时签名 URL 下载结果。
      security:
        - ApiKeyBearer: []
      parameters:
        - $ref: "#/components/parameters/JobId"
        - $ref: "#/components/parameters/OptionalRequestId"
      responses:
        "200":
          description: Job
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DramaTranslationJob"
        "400":
          $ref: "#/components/responses/PublicBadRequest"
        "401":
          $ref: "#/components/responses/PublicUnauthorized"
        "403":
          $ref: "#/components/responses/PublicForbidden"
        "404":
          $ref: "#/components/responses/PublicNotFound"
        "405":
          $ref: "#/components/responses/PublicMethodNotAllowed"
        "429":
          $ref: "#/components/responses/PublicRateLimited"
        "500":
          $ref: "#/components/responses/PublicServerError"
        "502":
          $ref: "#/components/responses/PublicGatewayError"
        "503":
          $ref: "#/components/responses/PublicServiceUnavailable"
  /v1/jobs/{job_id}/retry:
    post:
      tags:
        - Public Jobs
      operationId: retryApiDramaJob
      summary: 在原短剧任务内重试失败分集
      description: 仅支持 drama_translation。复用已成功分集与原剧共享术语、剧情上下文及角色声纹库，按原锁定单价补冻结差额。省略
        episode_indexes 重试全部失败节点；传入 episode_indexes 仅重试指定 0-based 失败分集。7
        天保留期内有效，不可重试的媒体/选区错误返回 409 job_not_retryable。
      security:
        - ApiKeyBearer: []
      parameters:
        - $ref: "#/components/parameters/JobId"
        - $ref: "#/components/parameters/OptionalRequestId"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DramaRetryRequest"
            examples:
              retryAll:
                summary: 重试全部失败分集或聚合节点
                value: {}
              retrySelected:
                summary: 仅重试第 4、5 集（0-based）
                value:
                  episode_indexes:
                    - 3
                    - 4
      responses:
        "202":
          description: 已重新排队执行
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DramaTranslationJob"
        "400":
          $ref: "#/components/responses/PublicBadRequest"
        "401":
          $ref: "#/components/responses/PublicUnauthorized"
        "402":
          $ref: "#/components/responses/PublicPaymentRequired"
        "403":
          $ref: "#/components/responses/PublicForbidden"
        "404":
          $ref: "#/components/responses/PublicNotFound"
        "409":
          $ref: "#/components/responses/PublicConflict"
        "429":
          $ref: "#/components/responses/PublicRateLimited"
        "500":
          $ref: "#/components/responses/PublicServerError"
        "503":
          $ref: "#/components/responses/PublicServiceUnavailable"
  /v1/jobs/{job_id}/cancel:
    post:
      tags:
        - Public Jobs
      operationId: cancelApiJob
      summary: 取消 Job
      description: Remove Text 只允许取消 validating 或 queued；视频翻译还可取消 processing。已取消时幂等返回当前 Job。
      security:
        - ApiKeyBearer: []
      parameters:
        - $ref: "#/components/parameters/JobId"
        - $ref: "#/components/parameters/OptionalRequestId"
      responses:
        "200":
          description: 已取消或原本已经取消
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DramaTranslationJob"
        "400":
          $ref: "#/components/responses/PublicBadRequest"
        "401":
          $ref: "#/components/responses/PublicUnauthorized"
        "403":
          $ref: "#/components/responses/PublicForbidden"
        "404":
          $ref: "#/components/responses/PublicNotFound"
        "405":
          $ref: "#/components/responses/PublicMethodNotAllowed"
        "409":
          $ref: "#/components/responses/PublicConflict"
        "429":
          $ref: "#/components/responses/PublicRateLimited"
        "500":
          $ref: "#/components/responses/PublicServerError"
        "502":
          $ref: "#/components/responses/PublicGatewayError"
        "503":
          $ref: "#/components/responses/PublicServiceUnavailable"
  /v1/balance:
    get:
      tags:
        - Public Balance
      operationId: getApiBalance
      summary: 查询人民币 API 钱包余额与短剧实时折后单价
      description: |
        金额计算使用整数 microusd；USD 字段为固定 6 位小数的展示字符串。
        API 钱包与 Web 订阅、Web credits 完全分开。
        符合注册权益条件的新用户获得 1.000000 USD 使用额度；赠送不计入累计净充值。
      security:
        - ApiKeyBearer: []
      parameters:
        - $ref: "#/components/parameters/OptionalRequestId"
      responses:
        "200":
          description: 钱包和当前费率快照
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DramaBalance"
        "401":
          $ref: "#/components/responses/PublicUnauthorized"
        "403":
          $ref: "#/components/responses/PublicForbidden"
        "405":
          $ref: "#/components/responses/PublicMethodNotAllowed"
        "429":
          $ref: "#/components/responses/PublicRateLimited"
        "500":
          $ref: "#/components/responses/PublicServerError"
        "502":
          $ref: "#/components/responses/PublicGatewayError"
        "503":
          $ref: "#/components/responses/PublicServiceUnavailable"
webhooks:
  unmarkAIEvent:
    post:
      tags:
        - API Webhooks
      operationId: receiveUnmarkAIWebhook
      summary: UnmarkAI 向客户 endpoint 投递事件
      description: |
        请求签名为 `v1=` + HMAC-SHA256 小写十六进制值。签名原文是
        `UnmarkAI-Timestamp + "." + raw_request_body`，key 为在 API Console 配置
        endpoint 时显示的一次性签名密钥。必须在解析 JSON 前按原始请求
        字节验签，并按 `UnmarkAI-Id` 去重。

        任意 2xx 表示成功。网络错误、超时、重定向或非 2xx 最多共投递 6 次；失败后
        计划延迟依次为 1 分钟、5 分钟、30 分钟、2 小时、12 小时。单次超时 10 秒。
      security: []
      parameters:
        - name: UnmarkAI-Id
          in: header
          required: true
          description: 事件唯一 ID，应作为幂等去重键
          schema:
            type: string
            pattern: ^evt_[A-Za-z0-9_-]+$
        - name: UnmarkAI-Timestamp
          in: header
          required: true
          description: 签名时使用的 Unix 秒时间戳
          schema:
            type: string
            pattern: ^\d+$
        - name: UnmarkAI-Signature
          in: header
          required: true
          description: "`v1=<lowercase hex HMAC-SHA256>`"
          schema:
            type: string
            pattern: ^v1=[0-9a-f]{64}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookEvent"
            examples:
              jobProcessing:
                value:
                  id: evt_xxx
                  type: job.processing
                  created_at: 2026-07-29T12:03:00.000Z
                  data:
                    job_id: job_xxx
                    status: processing
                    progress: 10
              endpointVerification:
                value:
                  id: evt_xxx
                  type: endpoint.verification
                  created_at: 2026-07-29T12:00:00.000Z
                  data:
                    challenge: whch_xxx
      responses:
        "200":
          description: |
            已接收。Job 事件 body 不做要求；验证事件须回显 challenge。
          content:
            text/plain:
              schema:
                type: string
              example: whch_xxx
            application/json:
              schema:
                oneOf:
                  - type: object
                    required:
                      - challenge
                    properties:
                      challenge:
                        type: string
                  - type: object
                    required:
                      - data
                    properties:
                      data:
                        type: object
                        required:
                          - challenge
                        properties:
                          challenge:
                            type: string
components:
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      bearerFormat: UnmarkAI API key (uma_live_*)
      description: 产品级 API key；只能用于 `/v1/*`。
  parameters:
    OptionalRequestId:
      name: X-Request-Id
      in: header
      required: false
      description: 可选链路 ID；无效或缺失时服务端生成新值
      schema:
        type: string
        minLength: 1
        maxLength: 128
        pattern: ^[A-Za-z0-9._:/-]+$
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: API account 范围内有效 24 小时的创建幂等键
      schema:
        type: string
        minLength: 1
        maxLength: 255
        pattern: ^[!-~]+$
    JobId:
      name: job_id
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/ResourceId"
    UploadId:
      name: upload_id
      in: path
      required: true
      schema:
        $ref: "#/components/schemas/ResourceId"
  headers:
    RequestId:
      description: 服务端采用的链路追踪 ID
      schema:
        type: string
        maxLength: 128
    IdempotentReplayed:
      description: 仅在响应复用已有 Job 时出现，值为 `true`
      schema:
        type: string
        const: "true"
  responses:
    PublicBadRequest:
      description: 请求格式、字段、cursor 或幂等键无效
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PublicErrorEnvelope"
    PublicUnauthorized:
      description: API key 无效、已撤销或过期
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PublicErrorEnvelope"
          example:
            error:
              code: unauthorized
              message: Authentication failed
              request_id: req_xxx
    PublicPaymentRequired:
      description: API 钱包余额不足
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PublicErrorEnvelope"
          example:
            error:
              code: insufficient_balance
              message: Insufficient API balance
              request_id: req_xxx
    PublicForbidden:
      description: scope 不足或 API account 暂停
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PublicErrorEnvelope"
    PublicNotFound:
      description: 资源或路由不存在
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PublicErrorEnvelope"
    PublicMethodNotAllowed:
      description: 路由存在，但 HTTP method 不受支持
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PublicErrorEnvelope"
    PublicConflict:
      description: 上传未就绪、幂等冲突或 Job 不可取消
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PublicErrorEnvelope"
    PublicPayloadTooLarge:
      description: 视频超过 2 GiB，或 JSON 请求体超过端点上限（翻译创建 512 KiB，其他请求 64 KiB）
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PublicErrorEnvelope"
    PublicUnsupportedMediaType:
      description: 视频 MIME 类型不支持
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PublicErrorEnvelope"
    PublicUnprocessable:
      description: 无法验证已上传对象的元数据
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PublicErrorEnvelope"
    PublicRateLimited:
      description: 请求速率、账号队列、未绑定上传 ticket 或 24 小时上传字节达到限制
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PublicErrorEnvelope"
    PublicServerError:
      description: 公共 API 内部错误
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PublicErrorEnvelope"
    PublicGatewayError:
      description: 服务未能完成请求
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PublicErrorEnvelope"
    PublicServiceUnavailable:
      description: 服务暂不可用
      headers:
        X-Request-Id:
          $ref: "#/components/headers/RequestId"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/PublicErrorEnvelope"
  schemas:
    ResourceId:
      type: string
      minLength: 1
      maxLength: 128
      pattern: ^[A-Za-z0-9_-]+$
    DateTimeNullable:
      type:
        - string
        - "null"
      format: date-time
    Microusd:
      type: integer
      format: int64
      description: 百万分之一美元的整数
    NonNegativeMicrousd:
      type: integer
      format: int64
      minimum: 0
      description: 非负的百万分之一美元整数
    UsdString:
      type: string
      pattern: ^-?\d+\.\d{6}$
      description: 固定 6 位小数的 USD 展示字符串
      example: "1.000000"
    NullableUsdString:
      type:
        - string
        - "null"
      pattern: ^-?\d+\.\d{6}$
    UploadCreateRequest:
      type: object
      required:
        - filename
        - content_type
        - file_size_bytes
      properties:
        filename:
          type: string
          minLength: 1
          maxLength: 255
          description: 单个文件名，不允许路径分隔符或控制字符
        content_type:
          type: string
          enum:
            - video/mp4
            - video/quicktime
            - video/x-msvideo
            - video/x-matroska
            - video/webm
            - video/mpeg
        file_size_bytes:
          type: integer
          minimum: 1
          maximum: 2147483648
    UrlUploadCreateRequest:
      type: object
      additionalProperties: false
      required:
        - source_url
      properties:
        source_url:
          type: string
          format: uri
          pattern: ^https://
          description: 可直接下载的视频 HTTPS URL；允许签名查询参数
        filename:
          type: string
          minLength: 1
          maxLength: 255
          description: 可选目标文件名；省略时从 URL 或 MIME 推断
    UploadHeaders:
      type: object
      required:
        - content-type
        - content-length
      properties:
        content-type:
          type: string
        content-length:
          type: string
          pattern: ^\d+$
        if-none-match:
          type: string
          const: "*"
          description: 写入前置条件；必须原样发送，使本次上传凭证只能创建内容一次
      additionalProperties:
        type: string
    UploadTicket:
      type: object
      required:
        - upload_id
        - method
        - url
        - headers
        - expires_at
      additionalProperties: false
      properties:
        upload_id:
          $ref: "#/components/schemas/ResourceId"
        method:
          type: string
          const: PUT
        url:
          type: string
          format: uri
        headers:
          $ref: "#/components/schemas/UploadHeaders"
        expires_at:
          type: string
          format: date-time
    UploadStatus:
      type: string
      enum:
        - pending
        - importing
        - uploaded
        - failed
        - expired
    UploadSourceType:
      type: string
      enum:
        - local
        - url
    Upload:
      type: object
      additionalProperties: false
      required:
        - upload_id
        - source_type
        - status
        - filename
        - content_type
        - file_size_bytes
        - error
        - created_at
        - uploaded_at
      properties:
        upload_id:
          $ref: "#/components/schemas/ResourceId"
        source_type:
          $ref: "#/components/schemas/UploadSourceType"
        status:
          $ref: "#/components/schemas/UploadStatus"
        filename:
          type: string
        content_type:
          type: string
        file_size_bytes:
          type: integer
          minimum: 1
          maximum: 2147483648
        error:
          oneOf:
            - $ref: "#/components/schemas/JobFailure"
            - type: "null"
        created_at:
          type: string
          format: date-time
        uploaded_at:
          $ref: "#/components/schemas/DateTimeNullable"
    JobStatus:
      type: string
      enum:
        - validating
        - queued
        - processing
        - succeeded
        - failed
        - canceled
    Rect:
      type: object
      required:
        - x1
        - y1
        - x2
        - y2
      description: 源视频绝对像素坐标；要求 x1 < x2、y1 < y2
      properties:
        x1:
          type: number
          minimum: 0
        y1:
          type: number
          minimum: 0
        x2:
          type: number
          exclusiveMinimum: 0
        y2:
          type: number
          exclusiveMinimum: 0
    JobFailure:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
        message:
          type: string
    JobResult:
      type: object
      required:
        - url
        - expires_at
      properties:
        url:
          type: string
          format: uri
          description: 最多有效 1 小时的签名下载 URL
        expires_at:
          type: string
          format: date-time
          description: 当前签名 URL 的过期时间
    TranslationSubtitleStyle:
      type: object
      additionalProperties: false
      properties:
        preset:
          type: string
          enum:
            - classic
            - cinema
            - bold
            - shadow
            - box
            - brand
          default: classic
        font_id:
          type: string
          enum:
            - noto_sans
            - montserrat
            - roboto
            - open_sans
          default: noto_sans
        primary_color:
          type: string
          pattern: ^#[0-9a-fA-F]{6}$
          default: "#FFFFFF"
        secondary_color:
          type: string
          pattern: ^#[0-9a-fA-F]{6}$
          default: "#E4E4E4"
        highlight_color:
          type: string
          pattern: ^#[0-9a-fA-F]{6}$
          default: "#FFE600"
        outline_color:
          type: string
          pattern: ^#[0-9a-fA-F]{6}$
          default: "#000000"
        background_color:
          type: string
          pattern: ^#[0-9a-fA-F]{6}$
          default: "#000000"
        background_opacity:
          type: number
          minimum: 0
          maximum: 1
          default: 0
        font_weight:
          type: integer
          enum:
            - 400
            - 600
            - 700
            - 800
          default: 700
        font_scale:
          type: number
          minimum: 0.5
          maximum: 1.5
          default: 1
        outline_width:
          type: number
          minimum: 0
          maximum: 8
          default: 3
        shadow:
          type: number
          minimum: 0
          maximum: 8
          default: 0
        animation:
          type: string
          enum:
            - none
            - bounce
            - highlight
            - reveal
          default: none
    DramaSubtitleErase:
      description: 翻译前置去原硬字幕（可选，默认关闭）。单区域 +¥0.020/秒、多区域 +¥0.040/秒、全区域 +¥0.060/秒。
      oneOf:
        - type: object
          additionalProperties: false
          required:
            - enabled
          properties:
            enabled:
              const: false
        - type: object
          additionalProperties: false
          required:
            - enabled
            - mode
          properties:
            enabled:
              const: true
            mode:
              const: all_area
            rect:
              type: "null"
        - type: object
          additionalProperties: false
          required:
            - enabled
            - mode
          properties:
            enabled:
              const: true
            mode:
              const: sel_area
            rect:
              oneOf:
                - $ref: "#/components/schemas/Rect"
                - type: "null"
        - type: object
          additionalProperties: false
          required:
            - enabled
            - mode
          properties:
            enabled:
              const: true
            mode:
              const: multi_area
            rect:
              oneOf:
                - type: array
                  minItems: 1
                  maxItems: 5
                  items:
                    $ref: "#/components/schemas/Rect"
                - type: "null"
    DramaEpisodeInput:
      type: object
      additionalProperties: false
      required:
        - upload_id
      properties:
        upload_id:
          $ref: "#/components/schemas/ResourceId"
        rect:
          description: 可选单集去字幕像素选区覆盖（仅在 subtitle_erase.enabled=true 且 mode 为
            sel_area/multi_area 时允许；sel_area 为单矩形，multi_area 为 1–5 个矩形数组）。
          oneOf:
            - $ref: "#/components/schemas/Rect"
            - type: array
              minItems: 1
              maxItems: 5
              items:
                $ref: "#/components/schemas/Rect"
            - type: "null"
    DramaSubtitleLayout:
      type: object
      additionalProperties: false
      required:
        - top_percent
        - height_percent
      description: 字幕在画面中的纵向位置百分比（默认 top_percent=80, height_percent=16，二者之和不得超过 100）。
      properties:
        top_percent:
          type: number
          minimum: 0
          maximum: 99
        height_percent:
          type: number
          minimum: 1
          maximum: 100
    DramaTranslationCreateRequest:
      type: object
      additionalProperties: false
      required:
        - type
        - input
        - target_language
      description: 中国区短剧批量翻译（1–100
        集）。默认高质量原声克隆（不开放相似/固定音色，无需传音色参数）、默认开启全剧共享术语与剧情上下文、暂不开放姓名卡（画面文字）翻译。普通
        ¥0.060/秒、高级 ¥0.120/秒；角色分析 +¥0.010/秒；去字幕单/多/全区域
        +¥0.020/+¥0.040/+¥0.060/秒；按全剧总时长向上取整到整秒，整单最低 15 秒，再享 365 天累计充值折扣。
      properties:
        type:
          const: drama_translation
        input:
          type: object
          additionalProperties: false
          required:
            - episodes
          properties:
            episodes:
              type: array
              minItems: 1
              maxItems: 100
              items:
                $ref: "#/components/schemas/DramaEpisodeInput"
        source_language:
          type: string
          default: auto
          description: 源语言代码，默认 auto 自动识别。
        target_language:
          type: string
          description: 目标语言代码，如 en、es、ja、ko、id、th 等。
        target_locale:
          type: string
          description: 可选目标语言地区，如 en-US、es-MX，需与 target_language 匹配。
        advanced_quality:
          type: boolean
          default: false
          description: 是否启用高级翻译（标准价 ¥0.120/秒；默认 false 为普通 ¥0.060/秒）。
        cast_enabled:
          type: boolean
          default: false
          description: 是否启用角色分析与跨集统一克隆音色（默认 false；开启加收 ¥0.010/秒）。
        subtitle_erase:
          $ref: "#/components/schemas/DramaSubtitleErase"
        preserve_background_audio:
          type: boolean
          default: true
          description: 是否保留原视频背景音乐与环境音效（默认 true，不额外加价）。
        subtitle_enabled:
          type: boolean
          default: true
          description: 是否烧录译文字幕到视频画面（默认 true）。
        subtitle_mode:
          type: string
          enum:
            - translated
            - bilingual
          default: translated
          description: 字幕模式：translated（仅译文）或 bilingual（双语）。需 subtitle_enabled=true。
        subtitle_style:
          $ref: "#/components/schemas/TranslationSubtitleStyle"
        subtitle_layout:
          $ref: "#/components/schemas/DramaSubtitleLayout"
        output_resolution:
          type: string
          enum:
            - source
            - 720p
            - 1080p
          default: source
          description: 输出分辨率，默认 source 保持原分辨率。
        metadata:
          type: object
          additionalProperties: true
          description: 客户自定义元数据，序列化后最多 16 KiB。
    DramaEpisodeArtifacts:
      type: object
      additionalProperties: false
      properties:
        video:
          oneOf:
            - $ref: "#/components/schemas/JobResult"
            - type: "null"
        source_subtitles:
          oneOf:
            - $ref: "#/components/schemas/JobResult"
            - type: "null"
        translated_subtitles:
          oneOf:
            - $ref: "#/components/schemas/JobResult"
            - type: "null"
        asr_original_subtitles:
          oneOf:
            - $ref: "#/components/schemas/JobResult"
            - type: "null"
        audio:
          oneOf:
            - $ref: "#/components/schemas/JobResult"
            - type: "null"
    DramaEpisodeStatus:
      type: object
      additionalProperties: false
      required:
        - index
        - upload_id
        - status
        - progress
        - duration_ms
        - error
        - result
      properties:
        index:
          type: integer
          minimum: 0
        upload_id:
          oneOf:
            - $ref: "#/components/schemas/ResourceId"
            - type: "null"
        status:
          $ref: "#/components/schemas/JobStatus"
        progress:
          type: integer
          minimum: 0
          maximum: 100
        duration_ms:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
        error:
          oneOf:
            - $ref: "#/components/schemas/JobFailure"
            - type: "null"
        result:
          oneOf:
            - $ref: "#/components/schemas/DramaEpisodeArtifacts"
            - type: "null"
    DramaGlossarySummary:
      type: object
      additionalProperties: false
      required:
        - status
        - entry_count
        - entries
      properties:
        status:
          type: string
          enum:
            - pending
            - processing
            - succeeded
            - failed
        entry_count:
          type: integer
          minimum: 0
        entries:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - source
              - target
              - type
            properties:
              source:
                type: string
              target:
                type: string
              type:
                type: string
    DramaCastSummary:
      type: object
      additionalProperties: false
      required:
        - enabled
        - status
        - character_count
        - characters
      properties:
        enabled:
          type: boolean
        status:
          type: string
          enum:
            - pending
            - processing
            - succeeded
            - failed
        character_count:
          type: integer
          minimum: 0
        characters:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
              - id
              - name
            properties:
              id:
                type: string
              name:
                type: string
    DramaRetryRequest:
      type: object
      additionalProperties: false
      description: 在原短剧任务内重试失败分集或失败聚合阶段。省略 episode_indexes 重试全部失败节点；传入 episode_indexes
        仅重试指定 0-based 失败分集。复用已成功分集与原剧共享术语/角色声纹，按原锁定单价补冻结差额。
      properties:
        episode_indexes:
          type: array
          minItems: 1
          maxItems: 100
          items:
            type: integer
            minimum: 0
    DramaTranslationJob:
      type: object
      additionalProperties: true
      required:
        - id
        - type
        - status
        - source_language
        - target_language
        - advanced_quality
        - cast_enabled
        - shared_glossary_enabled
        - subtitle_erase
        - progress
        - episode_count
        - completed_episodes
        - retry_count
        - duration_ms
        - billable_seconds
        - episodes
        - error
        - blocker
        - metadata
        - created_at
        - updated_at
        - terminal_at
      properties:
        currency:
          type: string
          enum:
            - USD
            - CNY
        amounts:
          $ref: "#/components/schemas/PublicAmounts"
        id:
          $ref: "#/components/schemas/ResourceId"
        type:
          type: string
          const: drama_translation
        status:
          $ref: "#/components/schemas/JobStatus"
        source_language:
          type: string
        target_language:
          type:
            - string
            - "null"
        target_locale:
          type: string
        advanced_quality:
          type: boolean
        cast_enabled:
          type: boolean
        shared_glossary_enabled:
          type: boolean
        subtitle_erase:
          $ref: "#/components/schemas/DramaSubtitleErase"
        progress:
          type: integer
          minimum: 0
          maximum: 100
        episode_count:
          type: integer
          minimum: 1
          maximum: 100
        completed_episodes:
          type: integer
          minimum: 0
          maximum: 100
        retry_count:
          type: integer
          minimum: 0
        duration_ms:
          type:
            - integer
            - "null"
          format: int64
          minimum: 0
          description: 全剧各集真实时长之和（毫秒）。
        billable_seconds:
          type:
            - integer
            - "null"
          format: int64
          minimum: 15
          description: 全剧计费秒数：max(15, ceil(duration_ms / 1000))。
        price_version:
          type:
            - string
            - "null"
        tier:
          type:
            - string
            - "null"
        multiplier_bps:
          type:
            - integer
            - "null"
          minimum: 1
          maximum: 10000
        episodes:
          type: array
          items:
            $ref: "#/components/schemas/DramaEpisodeStatus"
        glossary:
          oneOf:
            - $ref: "#/components/schemas/DramaGlossarySummary"
            - type: "null"
        cast:
          oneOf:
            - $ref: "#/components/schemas/DramaCastSummary"
            - type: "null"
        error:
          oneOf:
            - $ref: "#/components/schemas/JobFailure"
            - type: "null"
        blocker:
          type:
            - object
            - "null"
          additionalProperties: true
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        terminal_at:
          $ref: "#/components/schemas/DateTimeNullable"
    NextTier:
      type: object
      required:
        - tier_code
        - multiplier_bps
      properties:
        tier_code:
          type: string
          enum:
            - tier_90
            - tier_80
            - tier_75
            - tier_70
            - tier_65
            - tier_60
        threshold_microusd:
          $ref: "#/components/schemas/NonNegativeMicrousd"
        threshold_usd:
          $ref: "#/components/schemas/UsdString"
        multiplier_bps:
          type: integer
          minimum: 1
          maximum: 10000
        amount_needed_microusd:
          $ref: "#/components/schemas/NonNegativeMicrousd"
        amount_needed_usd:
          $ref: "#/components/schemas/UsdString"
    QualifyingExpiration:
      type: object
      required:
        - expires_at
      properties:
        amount_microusd:
          $ref: "#/components/schemas/NonNegativeMicrousd"
        amount_usd:
          $ref: "#/components/schemas/UsdString"
        expires_at:
          type: string
          format: date-time
    PublicConcurrency:
      type: object
      required:
        - base_limit
        - extra_limit
        - effective_limit
        - slots_in_use
        - slots_available
      properties:
        base_limit:
          type: integer
          minimum: 1
          example: 4
        extra_limit:
          type: integer
          minimum: 0
          example: 2
        effective_limit:
          type: integer
          minimum: 1
          example: 6
        slots_in_use:
          type: integer
          minimum: 0
          example: 2
        slots_available:
          type: integer
          minimum: 0
          example: 4
    PublicAmounts:
      type: object
      description: 通用金额投影；移除原字段的 _usd 币种片段，不包含整数微单位。嵌套费率保持同样层级。海外旧字段继续返回，国内仅使用通用字段。
      additionalProperties:
        anyOf:
          - type: string
            pattern: ^-?[0-9]+\.[0-9]{6}$
          - type: "null"
          - $ref: "#/components/schemas/PublicAmounts"
    PublicErrorCode:
      type: string
      enum:
        - job_not_retryable
        - invalid_media
        - invalid_json
        - invalid_request
        - request_too_large
        - invalid_cursor
        - invalid_idempotency_key
        - unauthorized
        - insufficient_balance
        - insufficient_scope
        - account_inactive
        - not_found
        - upload_not_found
        - job_not_found
        - method_not_allowed
        - upload_not_ready
        - idempotency_conflict
        - idempotency_in_progress
        - job_not_cancelable
        - file_too_large
        - unsupported_media_type
        - upload_metadata_unavailable
        - rate_limit_exceeded
        - queue_limit_exceeded
        - upload_limit_exceeded
        - feature_unavailable
        - internal_error
        - gateway_error
        - gateway_unavailable
        - service_unavailable
    PublicErrorEnvelope:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - request_id
          properties:
            code:
              $ref: "#/components/schemas/PublicErrorCode"
            message:
              type: string
            request_id:
              type: string
    JobWebhookEventType:
      type: string
      enum:
        - job.created
        - job.queued
        - job.processing
        - job.succeeded
        - job.failed
        - job.canceled
    JobWebhookEvent:
      type: object
      required:
        - id
        - type
        - created_at
        - data
      properties:
        id:
          type: string
          pattern: ^evt_[A-Za-z0-9_-]+$
        type:
          $ref: "#/components/schemas/JobWebhookEventType"
        created_at:
          type: string
          format: date-time
        data:
          type: object
          required:
            - job_id
            - status
            - progress
          properties:
            job_id:
              $ref: "#/components/schemas/ResourceId"
            status:
              $ref: "#/components/schemas/JobStatus"
            progress:
              type: integer
              minimum: 0
              maximum: 100
    EndpointVerificationEvent:
      type: object
      required:
        - id
        - type
        - created_at
        - data
      properties:
        id:
          type: string
          pattern: ^evt_[A-Za-z0-9_-]+$
        type:
          type: string
          const: endpoint.verification
        created_at:
          type: string
          format: date-time
        data:
          type: object
          required:
            - challenge
          properties:
            challenge:
              type: string
              pattern: ^whch_[A-Za-z0-9_-]+$
    WebhookEvent:
      oneOf:
        - $ref: "#/components/schemas/JobWebhookEvent"
        - $ref: "#/components/schemas/EndpointVerificationEvent"
    DramaJobList:
      type: object
      additionalProperties: false
      required:
        - data
        - next_cursor
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/DramaTranslationJob"
        next_cursor:
          type:
            - string
            - "null"
    DramaBalance:
      type: object
      additionalProperties: true
      required:
        - account_id
        - status
        - currency
        - amounts
        - current_tier
        - multiplier_bps
        - concurrency
      properties:
        account_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - active
            - suspended
        currency:
          type: string
          const: CNY
        current_tier:
          type: string
        multiplier_bps:
          type: integer
          minimum: 1
          maximum: 10000
        next_tier:
          oneOf:
            - $ref: "#/components/schemas/NextTier"
            - type: "null"
        next_qualifying_expiration:
          oneOf:
            - $ref: "#/components/schemas/QualifyingExpiration"
            - type: "null"
        concurrency:
          $ref: "#/components/schemas/PublicConcurrency"
        amounts:
          type: object
          additionalProperties: true
          description: 通用人民币金额（六位小数字符串）。drama_translation_rates 返回当前账户折后的短剧基础价与附加项单价。
          properties:
            available:
              type: string
            reserved:
              type: string
            drama_translation_rates:
              type: object
              additionalProperties: false
              properties:
                standard_per_second:
                  type: string
                  description: 短剧普通翻译（含克隆与共享术语）折后秒价
                advanced_per_second:
                  type: string
                  description: 短剧高级翻译（含克隆与共享术语）折后秒价
                cast_addon_per_second:
                  type: string
                  description: 角色分析与跨集统一音色加价（折后）
                erase_sel_area_addon_per_second:
                  type: string
                  description: 去字幕单区域加价（折后）
                erase_multi_area_addon_per_second:
                  type: string
                  description: 去字幕多区域加价（折后）
                erase_all_area_addon_per_second:
                  type: string
                  description: 去字幕全区域加价（折后）
