openapi: 3.1.0
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
info:
  title: UnmarkAI Video API
  version: 1.4.0
  description: |
    UnmarkAI 视频文字移除、视频翻译与视频高清公共 API，以及向客户 endpoint 投递的 Webhook 事件契约。

    `/v1/*` 使用 `uma_live_*` API key，成功时直接返回资源，失败时返回
    `error.code/error.message/error.request_id`。公共 API 的 JSON 请求体最大为
    翻译创建为 512 KiB，其他请求为 64 KiB；超限返回 413。
servers:
  - url: https://api.unmarkai.net
    description: Overseas production
  - url: https://unmarkai.cn/api
    description: Mainland China production
tags:
  - name: Public Uploads
    description: 使用 API key 初始化视频直传
  - name: Public Jobs
    description: 使用 API key 创建、查询和取消视频处理 Job
  - name: Public Balance
    description: 使用 API key 查询独立 API USD 钱包与实时价格
  - name: API Webhooks
    description: UnmarkAI 向客户 endpoint 投递的签名事件
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:
        "202":
          description: 已开始异步导入
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Upload"
        "200":
          description: 幂等重放已有导入
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
          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: |
        创建异步 Job。服务端先验证实际文件、时长、分辨率和选区，再按服务端探测时长
        冻结钱包余额。`Idempotency-Key` 在 API account 内有效 24 小时；相同 key 与
        相同规范化请求返回同一个 Job，并带 `Idempotent-Replayed: true`。
      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/JobCreateRequest"
            examples:
              allArea:
                summary: 全画面移除文字
                value:
                  type: remove_text
                  input:
                    upload_id: upl_xxx
                  mode: all_area
                  rect: null
                  metadata:
                    external_order_id: order_123
              selectedArea:
                summary: 指定源视频像素区域
                value:
                  type: remove_text
                  input:
                    upload_id: upl_xxx
                  mode: sel_area
                  rect:
                    x1: 100
                    y1: 80
                    x2: 900
                    y2: 220
      responses:
        "202":
          description: 已接受；幂等重放也返回此状态
          headers:
            X-Request-Id:
              $ref: "#/components/headers/RequestId"
            Idempotent-Replayed:
              $ref: "#/components/headers/IdempotentReplayed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Job"
        "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/JobList"
        "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/Job"
        "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}/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/Job"
        "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/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/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/PublicBalance"
        "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/voices:
    get:
      operationId: listTranslationVoices
      summary: List video translation preset voices and similar-voice availability
      security:
      - ApiKeyBearer: []
      description: Requires jobs:read. Availability is informational and is revalidated for explicit choices at job
        creation.
      parameters:
      - in: query
        name: target_language
        required: false
        schema:
          type: string
        description: Optional single target-language filter.
      responses:
        '200':
          description: Available translation voices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TranslationVoiceCatalog'

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]
    JobMode:
      type: string
      enum: [all_area, sel_area, multi_area]
    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
    JobInput:
      type: object
      required: [upload_id]
      properties:
        upload_id:
          $ref: "#/components/schemas/ResourceId"
    RemoveTextJobCreateRequest:
      type: object
      required: [type, input, mode]
      description: |
        `mode=sel_area` 时 `rect` 为单个矩形，面积不得超过源画面的一半；
        `mode=multi_area` 时 `rect` 为非空矩形数组，每个矩形须在源画面内，按 all_area 费率计费；
        `mode=all_area` 时 `rect` 必须省略或为 null。
        metadata 序列化后的 UTF-8 大小不得超过 16 KiB。
      properties:
        type:
          type: string
          const: remove_text
        input:
          $ref: "#/components/schemas/JobInput"
        mode:
          $ref: "#/components/schemas/JobMode"
        rect:
          oneOf:
            - $ref: "#/components/schemas/Rect"
            - type: array
              minItems: 1
              items:
                $ref: "#/components/schemas/Rect"
            - type: "null"
        metadata:
          type: object
          default:
          additionalProperties: true
    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 的过期时间
    RemoveTextJob:
      type: object
      required:
        - currency
        - amounts
        - id
        - type
        - status
        - input
        - mode
        - rect
        - progress
        - queue_position
        - duration_ms
        - provider_duration_ms
        - billable_seconds
        - price_version
        - tier
        - multiplier_bps
        - error
        - result
        - metadata
        - created_at
        - updated_at
        - queued_at
        - processing_at
        - terminal_at
      properties:
        currency:
          type: string
          enum: [USD, CNY]
          description: 当前地区 API 钱包的币种。
        amounts:
          $ref: "#/components/schemas/PublicAmounts"
        id:
          $ref: "#/components/schemas/ResourceId"
        type:
          type: string
          const: remove_text
        status:
          $ref: "#/components/schemas/JobStatus"
        input:
          $ref: "#/components/schemas/JobInput"
        mode:
          $ref: "#/components/schemas/JobMode"
        rect:
          oneOf:
            - $ref: "#/components/schemas/Rect"
            - type: array
              minItems: 1
              items:
                $ref: "#/components/schemas/Rect"
            - type: "null"
        progress:
          type: integer
          minimum: 0
          maximum: 100
        queue_position:
          type: [integer, "null"]
          minimum: 0
        duration_ms:
          type: [integer, "null"]
          format: int64
          minimum: 0
          description: 服务端探测并用于预扣的源视频时长
        provider_duration_ms:
          type: [integer, "null"]
          format: int64
          minimum: 0
          description: 完成处理后用于最终结算的实测时长
        billable_seconds:
          type: [integer, "null"]
          format: int64
          minimum: 1
        price_version:
          type: [string, "null"]
        tier:
          type: [string, "null"]
        multiplier_bps:
          type: [integer, "null"]
          minimum: 1
          maximum: 10000
        base_rate_microusd_per_second:
          type: [integer, "null"]
          format: int64
          minimum: 1
        base_rate_usd_per_second:
          $ref: "#/components/schemas/NullableUsdString"
        effective_rate_microusd_per_second:
          type: [integer, "null"]
          format: int64
          minimum: 1
        effective_rate_usd_per_second:
          $ref: "#/components/schemas/NullableUsdString"
        reserved_microusd:
          $ref: "#/components/schemas/NonNegativeMicrousd"
        reserved_usd:
          $ref: "#/components/schemas/UsdString"
        charged_microusd:
          $ref: "#/components/schemas/NonNegativeMicrousd"
        charged_usd:
          $ref: "#/components/schemas/UsdString"
        error:
          oneOf:
            - $ref: "#/components/schemas/JobFailure"
            - type: "null"
        result:
          oneOf:
            - $ref: "#/components/schemas/JobResult"
            - type: "null"
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        queued_at:
          $ref: "#/components/schemas/DateTimeNullable"
        processing_at:
          $ref: "#/components/schemas/DateTimeNullable"
        terminal_at:
          $ref: "#/components/schemas/DateTimeNullable"
    JobList:
      type: object
      required: [data, next_cursor]
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/Job"
        next_cursor:
          type: [string, "null"]
          description: 不透明 base64url cursor
    PublicRate:
      type: object
      required: []
      properties:
        microusd_per_second:
          $ref: "#/components/schemas/NonNegativeMicrousd"
        usd_per_second:
          $ref: "#/components/schemas/UsdString"
    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
    PublicBalance:
      type: object
      required:
        - currency
        - amounts
        - account_id
        - status
        - qualifying_period_days
        - current_tier
        - price_version
        - multiplier_bps
        - rates
        - next_tier
        - next_qualifying_expiration
        - concurrency
      properties:
        upscale_rates:
          $ref: "#/components/schemas/UpscaleRates"
        currency:
          type: string
          enum: [USD, CNY]
          description: 当前地区 API 钱包的币种。
        amounts:
          $ref: "#/components/schemas/PublicAmounts"
        translation_rates:
          description: Standard and advanced rates include default source voice cloning; sim rates apply to similar voices, preset voices, and output without voiceover.
          type: object
          additionalProperties: false
          required: []
          properties:
            standard_usd_per_second:
              $ref: "#/components/schemas/UsdString"
            advanced_usd_per_second:
              $ref: "#/components/schemas/UsdString"
            sim_standard_usd_per_second:
              $ref: "#/components/schemas/UsdString"
              description: Similar or preset voice, or no voiceover; standard quality, after account discount.
            sim_advanced_usd_per_second:
              $ref: "#/components/schemas/UsdString"
              description: Similar or preset voice, or no voiceover; advanced quality, after account discount.
        account_id:
          type: string
          format: uuid
        status:
          type: string
          enum: [active, suspended]
        available_microusd:
          $ref: "#/components/schemas/NonNegativeMicrousd"
        available_usd:
          $ref: "#/components/schemas/UsdString"
        reserved_microusd:
          $ref: "#/components/schemas/NonNegativeMicrousd"
        reserved_usd:
          $ref: "#/components/schemas/UsdString"
        debt_microusd:
          $ref: "#/components/schemas/NonNegativeMicrousd"
        debt_usd:
          $ref: "#/components/schemas/UsdString"
        qualifying_period_days:
          type: integer
          const: 365
        trailing_365d_net_topup_microusd:
          $ref: "#/components/schemas/NonNegativeMicrousd"
        trailing_365d_net_topup_usd:
          $ref: "#/components/schemas/UsdString"
        cumulative_net_topup_microusd:
          $ref: "#/components/schemas/NonNegativeMicrousd"
          deprecated: true
          description: Deprecated alias of trailing_365d_net_topup_microusd.
        cumulative_net_topup_usd:
          $ref: "#/components/schemas/UsdString"
          deprecated: true
          description: Deprecated alias of trailing_365d_net_topup_usd.
        current_tier:
          type: string
          enum: [tier_100, tier_90, tier_80, tier_75, tier_70, tier_65, tier_60]
        price_version:
          type: string
          example: remove_text_v1
        multiplier_bps:
          type: integer
          minimum: 1
          maximum: 10000
        rates:
          type: object
          required: [all_area, sel_area]
          properties:
            all_area:
              $ref: "#/components/schemas/PublicRate"
            sel_area:
              $ref: "#/components/schemas/PublicRate"
        next_tier:
          oneOf:
            - $ref: "#/components/schemas/NextTier"
            - type: "null"
        next_qualifying_expiration:
          oneOf:
            - $ref: "#/components/schemas/QualifyingExpiration"
            - type: "null"
        concurrency:
          $ref: "#/components/schemas/PublicConcurrency"
    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"

    JobCreateRequest:
      oneOf:
        - $ref: "#/components/schemas/DramaTranslationCreateRequest"
        -
          $ref: "#/components/schemas/RemoveTextJobCreateRequest"
        -
          $ref: "#/components/schemas/VideoTranslationCreateRequest"
        - $ref: "#/components/schemas/VideoUpscaleCreateRequest"
      discriminator:
        propertyName: "type"

    Job:
      oneOf:
        - $ref: "#/components/schemas/DramaTranslationJob"
        -
          $ref: "#/components/schemas/RemoveTextJob"
        -
          $ref: "#/components/schemas/VideoTranslationJob"
        - $ref: "#/components/schemas/VideoUpscaleJob"
      discriminator:
        propertyName: "type"

    VideoTranslationCreateRequest:
      type: object
      additionalProperties: false
      required:
      - type
      - input
      - target_language
      properties:
        type:
          type: string
          const: video_translation
        input:
          type: object
          additionalProperties: false
          required:
          - upload_id
          properties:
            upload_id:
              $ref: '#/components/schemas/ResourceId'
        target_language:
          type: string
          description: 支持的目标语言规范码，例如 ja、en、es、zh。
        source_language:
          type: string
          default: auto
        advanced_quality:
          type: boolean
          default: false
        subtitle_enabled:
          type: boolean
          default: true
        metadata:
          type: object
          additionalProperties: true
          description: 客户自定义数据，序列化后最多 16 KiB。
        tts_enabled:
          type: boolean
          description: Boolean, default true. Generate translated speech. False preserves the original audio; subtitle
            translation still runs.
          default: true
        voice_strategy:
          type: string
          description: clone clones the source voice; sim automatically selects a similar measured voice. If omitted, it
            defaults to clone. An explicit unavailable sim choice returns
            an error.
          enum:
          - clone
          - sim
          default: clone
        voice_key:
          type: string
          description: Optional preset voice key from GET /v1/voices. Omit to clone the source voice when voice_strategy=clone.
            A key implies clone mode with that preset; never combine a key with sim.
          maxLength: 128
        target_locale:
          type: string
          description: Optional region of the single target language, such as en-US or pt-BR. Must match target_language;
            it does not add another output language.
        reference_text:
          type: string
          description: Optional reference dialogue for correcting recognized source text, not a translation instruction
            or replacement transcript. Maximum 50,000 characters. Audio remains the timing evidence; optional correction
            can degrade without blocking translation.
          maxLength: 50000
        preserve_background_audio:
          type: boolean
          description: Boolean. Defaults to true with voiceover, false without voiceover. Keeps separated background
            sound under translated speech; false removes background sound during speech and keeps source sound in voiceover
            gaps.
        subtitle_mode:
          type: string
          description: translated (default) or bilingual. Bilingual displays the translation and source together. Requires
            subtitle_enabled=true.
          enum:
          - translated
          - bilingual
          default: translated
        subtitle_style:
          $ref: '#/components/schemas/TranslationSubtitleStyle'
          description: Optional object controlling font, color, fixed font size, outline, background and animation.
            Missing fields use the same classic defaults as the Web editor; see the style table below.
        subtitle_layout:
          type: object
          description: Optional {top_percent, height_percent}, measured as percentages of the video frame. Defaults
            to {80, 16}. Height is 8–24; top must be nonnegative and top + height must not exceed 100.
          additionalProperties: false
          required:
          - top_percent
          - height_percent
          properties:
            top_percent:
              type: number
              minimum: 0
              maximum: 92
              default: 80
            height_percent:
              type: number
              minimum: 8
              maximum: 24
              default: 16
        output_resolution:
          type: string
          description: source (default), 720p or 1080p. Preserves aspect ratio and caps output size; low-resolution sources are not forcibly upscaled. It does not change billing duration. API customers
            do not need a Web subscription for these options.
          enum:
          - source
          - 720p
          - 1080p
          default: source
      description: Single-target ASR translation. No source-subtitle erasure. New jobs align with Web voice and caption
        processing defaults. Speech and subtitle timing are aligned automatically. Default voice cloning costs
        $0.011250/second for standard processing or $0.028125/second for advanced processing. Similar or preset
        voices and subtitles-only output cost $0.007500/second or $0.018750/second respectively. API wallet discounts
        apply; 15-second minimum. Subtitle styling and background audio have no additional fees.
        Request body maximum 512 KiB. Voice/background options require TTS; caption mode/style/layout require
        subtitle burn-in.

    VideoTranslationJob:
      type: object
      required:
      - currency
      - amounts
      - id
      - type
      - status
      - target_language
      - progress
      - error
      - blocker
      - result
      - metadata
      - created_at
      - updated_at
      properties:
        currency:
          type: string
          enum: [USD, CNY]
          description: 当前地区 API 钱包的币种。
        amounts:
          $ref: "#/components/schemas/PublicAmounts"
        id:
          $ref: '#/components/schemas/ResourceId'
        type:
          type: string
          const: video_translation
        status:
          $ref: '#/components/schemas/JobStatus'
        target_language:
          oneOf:
          - type: string
          - type: 'null'
        progress:
          type: integer
          minimum: 0
          maximum: 100
        reserved_usd:
          $ref: '#/components/schemas/UsdString'
        charged_usd:
          $ref: '#/components/schemas/UsdString'
        error:
          oneOf:
          - $ref: '#/components/schemas/JobFailure'
          - type: 'null'
        blocker:
          oneOf:
          - type: object
            additionalProperties: false
            required:
            - code
            - expires_at
            properties:
              code:
                type: string
                const: insufficient_balance
              expires_at:
                type: string
                format: date-time
          - type: 'null'
        result:
          oneOf:
          - type: object
            additionalProperties: false
            required:
            - video
            properties:
              video:
                oneOf:
                - $ref: '#/components/schemas/JobResult'
                - type: 'null'
                description: Null when both tts_enabled and subtitle_enabled are false.
              source_subtitles:
                $ref: '#/components/schemas/JobResult'
              translated_subtitles:
                $ref: '#/components/schemas/JobResult'
              asr_original_subtitles:
                $ref: '#/components/schemas/JobResult'
              audio:
                $ref: '#/components/schemas/JobResult'
          - type: 'null'
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    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

    TranslationVoiceCatalog:
      type: object
      additionalProperties: false
      required:
      - voices
      - similar_voice_languages
      - similar_voice_available
      properties:
        voices:
          type: array
          items:
            type: object
            additionalProperties: false
            required:
            - voice_key
            - display_name
            - language_code
            - gender
            - accent
            - preview_url
            properties:
              voice_key:
                type:
                - string
                - 'null'
              display_name:
                type:
                - string
                - 'null'
              language_code:
                type:
                - string
                - 'null'
              gender:
                type:
                - string
                - 'null'
              accent:
                type:
                - string
                - 'null'
              preview_url:
                type:
                - string
                - 'null'
        similar_voice_languages:
          type: array
          items:
            type: string
        similar_voice_available:
          type: boolean

    VideoUpscaleCreateRequest:
      type: object
      additionalProperties: false
      required: [type, input, upscale]
      properties:
        type:
          const: video_upscale
        input:
          type: object
          additionalProperties: false
          required: [upload_id]
          properties:
            upload_id:
              $ref: "#/components/schemas/ResourceId"
        upscale:
          type: object
          additionalProperties: false
          required: [target]
          properties:
            target:
              type: string
              enum: [1080p, 2k, 4k]
        metadata:
          type: object
          additionalProperties: true
          description: Optional customer metadata, at most 16 KiB.
      description: >-
        Upscale one uploaded video, preserving aspect ratio, source FPS and audio.
        Targets are bounding boxes 1920x1080, 2560x1440 and 3840x2160, with portrait supported.
        Source must not exceed the target. Up to 2 GiB and 60 minutes.
        International API returns 202 before media validation; invalid media becomes a failed Job.
        USD rates use the active all_area base rate times 1/2/3, then a 2x multiplier above 30 FPS,
        then the account discount. Minimum 15 seconds, rounded up to whole source seconds.
        No Web credits are used. Trial watermark policy follows the international API account.
    VideoUpscaleParameters:
      type: object
      required: [target]
      properties:
        target:
          type: string
          enum: [1080p, 2k, 4k]
        fps:
          type: number
          exclusiveMinimum: 0
          description: Verified source average FPS, available after media validation.
        multiplier:
          type: integer
          enum: [1, 2]
          description: Server-owned frame-rate multiplier, available after media validation.
    UpscaleRates:
      type: object
      required: [1080p, 2k, 4k]
      additionalProperties:
        type: object
        properties:
          microusd_per_second:
            type: integer
          usd_per_second:
            type: string
          per_second:
            type: string
      description: Account-discounted per-second rates at up to 30 FPS. Read amounts.upscale_rates for currency-neutral values.
    VideoUpscaleJob:
      type: object
      required:
        - currency
        - amounts
        - id
        - type
        - status
        - input
        - upscale
        - progress
        - queue_position
        - duration_ms
        - provider_duration_ms
        - billable_seconds
        - price_version
        - tier
        - multiplier_bps
        - error
        - result
        - metadata
        - created_at
        - updated_at
        - queued_at
        - processing_at
        - terminal_at
      properties:
        currency:
          type: string
          enum: [USD, CNY]
          description: 当前地区 API 钱包的币种。
        amounts:
          $ref: "#/components/schemas/PublicAmounts"
        id:
          $ref: "#/components/schemas/ResourceId"
        type:
          type: string
          const: video_upscale
        status:
          $ref: "#/components/schemas/JobStatus"
        input:
          $ref: "#/components/schemas/JobInput"
        upscale:
          $ref: "#/components/schemas/VideoUpscaleParameters"
        progress:
          type: integer
          minimum: 0
          maximum: 100
        queue_position:
          type: [integer, "null"]
          minimum: 0
        duration_ms:
          type: [integer, "null"]
          format: int64
          minimum: 0
          description: 服务端探测并用于预扣的源视频时长
        provider_duration_ms:
          type: [integer, "null"]
          format: int64
          minimum: 0
          description: 完成处理后用于最终结算的实测时长
        billable_seconds:
          type: [integer, "null"]
          format: int64
          minimum: 1
        price_version:
          type: [string, "null"]
        tier:
          type: [string, "null"]
        multiplier_bps:
          type: [integer, "null"]
          minimum: 1
          maximum: 10000
        base_rate_microusd_per_second:
          type: [integer, "null"]
          format: int64
          minimum: 1
        base_rate_usd_per_second:
          $ref: "#/components/schemas/NullableUsdString"
        effective_rate_microusd_per_second:
          type: [integer, "null"]
          format: int64
          minimum: 1
        effective_rate_usd_per_second:
          $ref: "#/components/schemas/NullableUsdString"
        reserved_microusd:
          $ref: "#/components/schemas/NonNegativeMicrousd"
        reserved_usd:
          $ref: "#/components/schemas/UsdString"
        charged_microusd:
          $ref: "#/components/schemas/NonNegativeMicrousd"
        charged_usd:
          $ref: "#/components/schemas/UsdString"
        error:
          oneOf:
            - $ref: "#/components/schemas/JobFailure"
            - type: "null"
        result:
          oneOf:
            - $ref: "#/components/schemas/JobResult"
            - type: "null"
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        queued_at:
          $ref: "#/components/schemas/DateTimeNullable"
        processing_at:
          $ref: "#/components/schemas/DateTimeNullable"
        terminal_at:
          $ref: "#/components/schemas/DateTimeNullable"

    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"