openapi: 3.1.0
info:
  title: LoopRouter 生成 API
  description: LoopRouter AI 网关的视频与 Doubao Seedream 图片生成接口
  version: "1.0.0"
servers:
  - url: https://api.looprouter.com
security:
  - bearerAuth: []
paths:
  /api/v3/contents/generations/tasks:
    post:
      operationId: createVideoTask
      summary: 创建视频生成任务
      description: |
        提交一个异步视频生成任务。仅返回任务 ID，成片需通过查询接口轮询获取。
        文生视频、图生视频、多模态参考共用本接口，靠 `content` 数组组合区分模式。
        Seedance 2.5 的任务类型还取决于提示词；首帧 / 首尾帧、编辑、延长任务仅支持 ratio=adaptive，编辑任务仅支持 duration=-1。
        平台不会按 edit / extend 自动修正 ratio 或 duration；调用方须设置符合约束的值。编辑应锁定比例和时长，延长只需锁定比例，时长仍可选 -1 或 4–30 秒整数。
        Seedance 2.5 支持 output_format（mp4 / mov）和 omni_reference_task_type（auto / reference / edit / extend），参数值与任务约束由上游校验。其他模型请勿传入这两个字段。
        显式请求 mov 时保留上游原生规格产物；省略格式或指定 mp4 的任务按平台默认交付策略处理。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateVideoTaskRequest"
            example:
              model: doubao-seedance-2-0-260128
              content:
                - type: text
                  text: "海边日落，无人机航拍视角缓缓推进，金色阳光洒在海面上"
              resolution: 720p
              ratio: "16:9"
              duration: 5
      responses:
        "200":
          description: 任务创建成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: 任务 ID，用于查询任务状态
              example:
                id: task_xxxx
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
  /api/v3/contents/generations/tasks/{task_id}:
    get:
      operationId: getVideoTask
      summary: 查询视频生成任务
      description: |
        查询任务状态与结果。状态机：`queued → running → succeeded / failed / cancelled / expired`。
        成功后 `content.video_url` 为临时成片下载地址（下载时不要携带 Authorization 头）。
        官方原始视频 URL 有效期为 24 小时，Seedance 2.5 视频 URL 最多下载 100 次；平台转存链接以实际存储策略为准，请及时转存。
        Seedance 2.5 在上游返回时提供 output_format（mp4 / mov）；旧任务或上游未返回时省略。
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
          description: 创建任务时返回的任务 ID
      responses:
        "200":
          description: 任务详情
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VideoTask"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: 任务不存在或不属于当前账号
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /api/v1/services/aigc/video-generation/video-synthesis:
    post:
      operationId: createWan3VideoTask
      summary: 创建视频生成任务（万相 3.0）
      description: |
        提交一个异步视频生成任务（万相 3.0，`wan3.0-video` 或 `wan3.0-video-prime`，两个模型调用方式完全相同）。
        接口与阿里百炼（DashScope）原生完全一致：把 Base URL 指向网关、仅换 API Key 即可调用，无需
        `WorkspaceId` 子域。仅返回 `task_id`，成片需通过查询接口轮询获取。文生 / 图生（首帧、首尾帧）/
        参考生视频共用本接口，靠 `input.media` 数组组合区分模式。
      parameters:
        - name: X-DashScope-Async
          in: header
          required: false
          schema:
            type: string
            enum: [enabled]
          description: 可选，值为 `enabled`。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Wan3CreateRequest"
            example:
              model: wan3.0-video
              input:
                prompt: "一只小猫在月光下的屋顶上奔跑，城市的霓虹灯在远处闪烁，电影级画质，流畅运镜。"
              parameters:
                resolution: 1080P
                ratio: adaptive
                duration: 5
                prompt_extend: true
      responses:
        "200":
          description: 任务创建成功（仅返回任务 ID）
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Wan3TaskCreated"
              example:
                output:
                  task_id: 17ed7e50-00cf-4509-aea1-xxxxxx
                  task_status: PENDING
                request_id: 78c9b768-0285-996c-b682-xxxxxx
        "400":
          $ref: "#/components/responses/Wan3Error"
        "401":
          $ref: "#/components/responses/Wan3Error"
        "403":
          $ref: "#/components/responses/Wan3Error"
        "429":
          $ref: "#/components/responses/Wan3Error"
  /api/v1/tasks/{task_id}:
    get:
      operationId: getWan3VideoTask
      summary: 查询视频生成任务（万相 3.0）
      description: |
        根据任务 ID 查询状态与结果。状态机：`PENDING → RUNNING → SUCCEEDED / FAILED / CANCELED`；
        `UNKNOWN` 表示任务不存在或已过查询有效期。成功后 `output.video_url` 为成片下载地址
        （临时链接，请尽快转存；下载时不要携带 Authorization 头）。
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
          description: 创建任务时返回的 output.task_id
      responses:
        "200":
          description: 任务详情
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Wan3VideoTask"
              example:
                request_id: 78c9b768-0285-996c-b682-xxxxxx
                output:
                  task_id: 17ed7e50-00cf-4509-aea1-xxxxxx
                  task_status: SUCCEEDED
                  submit_time: "2026-08-06 10:01:35.452"
                  scheduled_time: "2026-08-06 10:01:35.507"
                  end_time: "2026-08-06 10:13:33.838"
                  orig_prompt: "一只小猫在月光下的屋顶上奔跑……"
                  video_url: https://.../output.mp4
                usage:
                  video_count: 1
                  duration: 5.0
                  input_video_duration: 0.0
                  output_video_duration: 5.0
                  fps: 30
                  SR: 1080
                  ratio: "16:9"
        "401":
          $ref: "#/components/responses/Wan3Error"
        "404":
          $ref: "#/components/responses/Wan3Error"
  /api/v3/images/generations:
    post:
      operationId: createImage
      summary: 创建图像生成请求（Doubao Seedream 5.0 Pro）
      description: |
        本同步接口兼容火山方舟图片生成 API 的请求与响应契约，无需创建任务或轮询。
        普通模式须提供 `prompt`，支持文生图、单图编辑、多参考图融合与交互编辑；最多输入 10 张参考图，返回一张基础图。
        图层拆分模式须设置 `layer_decomposition: true` 并输入一张不超过 30 MB 的 png 或 jpeg 图片；返回一张基础图和最多 16 个透明 PNG 图层，最多 17 项。
        `background: transparent` 仅用于单图编辑，且须设置 `output_format: png`；`response_format: url` 的结果链接在生成后 24 小时内有效。
        不支持 `n`、组图（`sequential_image_generation` 及其 options）与联网搜索（`tools`）。接口仅支持同步调用：`stream: true` 会被拒绝，省略 `stream` 或传 `false` 均保持同步。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSeedreamImageRequest"
            examples:
              generation:
                summary: 普通模式：文生图
                value:
                  model: doubao-seedream-5-0-pro-260628
                  prompt: "一只戴宇航头盔的柴犬，坐在月球表面，背景是地球，写实风格"
                  size: "2K"
                  response_format: url
                  watermark: true
              base64Generation:
                summary: 普通模式：返回 Base64 PNG
                value:
                  model: doubao-seedream-5-0-pro-260628
                  prompt: "极简产品图标，透明感玻璃材质"
                  size: "1K"
                  response_format: b64_json
                  output_format: png
              layerDecomposition:
                summary: 图层拆分模式：自动完整拆分
                value:
                  model: doubao-seedream-5-0-pro-260628
                  image: "https://example.com/images/poster.png"
                  layer_decomposition: true
                  size: auto
      responses:
        "200":
          description: 生成成功，返回图片数据与用量
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SeedreamImageResponse"
              examples:
                generation:
                  summary: 普通模式响应
                  value:
                    model: doubao-seedream-5-0-pro-260628
                    created: 1784696685
                    data:
                      - url: "https://example.com/images/seedream-result.jpeg"
                        size: "2048x2048"
                        output_format: jpeg
                    usage:
                      input_images: 0
                      generated_images: 1
                      output_tokens: 16384
                      total_tokens: 16384
                base64Generation:
                  summary: Base64 PNG 响应
                  value:
                    model: doubao-seedream-5-0-pro-260628
                    created: 1784696685
                    data:
                      - b64_json: "iVBORw0KGgo="
                        size: "1024x1024"
                        output_format: png
                    usage:
                      input_images: 0
                      generated_images: 1
                      output_tokens: 4096
                      total_tokens: 4096
                layerDecomposition:
                  summary: 图层拆分模式响应
                  value:
                    model: doubao-seedream-5-0-pro-260628
                    created: 1784696685
                    data:
                      - url: "https://example.com/images/seedream-base.jpeg"
                        size: "2048x2048"
                        output_format: jpeg
                        z_index: 0
                      - url: "https://example.com/images/seedream-layer-1.png"
                        size: "1280x256"
                        output_format: png
                        z_index: 1
                        bounding_box:
                          absolute: [384, 128, 1664, 384]
                          normalized: [188, 63, 813, 188]
                        name: "Seedream 标题文字"
                        description: "黄色大号衬线字体的 Seedream 标题文字"
                    usage:
                      input_images: 1
                      generated_images: 2
                      output_tokens: 17664
                      total_tokens: 17664
        "400":
          description: 请求参数无效或参数组合不受支持
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SeedreamImageErrorResponse"
              example:
                error:
                  code: InvalidParameter
                  message: prompt is required
        "401":
          description: API Key 缺失或无效
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SeedreamImageErrorResponse"
              example:
                error:
                  code: AuthenticationError
                  message: invalid token
        "403":
          description: 当前凭证无权使用请求的模型或资源
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SeedreamImageErrorResponse"
        "413":
          description: 请求体超过允许大小
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SeedreamImageErrorResponse"
        "429":
          description: 请求频率超出当前可用额度
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SeedreamImageErrorResponse"
              example:
                error:
                  code: RateLimitExceeded
                  message: too many requests
        "5XX":
          description: 服务端错误；错误码和消息按实际失败原因返回
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SeedreamImageErrorResponse"
        default:
          description: 其他失败响应；HTTP 状态码按实际失败原因返回
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SeedreamImageErrorResponse"
  /special/v2/video_generation:
    post:
      operationId: createSpecialH3VideoTask
      summary: 创建视频生成任务（MiniMax-H3）（特惠版）
      description: MiniMax-H3 格式的异步任务，model 仍为 MiniMax-H3。支持 768P 与 2K 输出，任务完成后交付成片。生成时长5–15秒，ratio必须显式指定具体比例，不支持adaptive。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SpecialH3CreateRequest"
            example:
              model: MiniMax-H3
              content:
                - type: text
                  text: 一个男孩在海边打篮球，镜头缓缓拉远
              resolution: 768P
              duration: 5
              ratio: 16:9
      responses:
        "200":
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MinimaxTaskCreated"
              example:
                task_id: "424010985738629"
        "400":
          $ref: "#/components/responses/MinimaxError"
        "401":
          $ref: "#/components/responses/MinimaxError"
        "403":
          $ref: "#/components/responses/MinimaxError"
        "404":
          $ref: "#/components/responses/MinimaxError"
        "429":
          $ref: "#/components/responses/MinimaxError"
  /special/v2/query/video_generation/{task_id}:
    get:
      operationId: getSpecialH3VideoTask
      summary: 查询视频生成任务（MiniMax-H3）（特惠版）
      description: 只查询本账号通过/special/v2创建的任务。返回MiniMax格式task对象；任务完成前仅显示排队/运行状态。官方/v2创建的任务在此返回404。
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
          description: 创建任务时返回的 task_id
      responses:
        "200":
          description: 任务详情
          content:
            application/json:
              schema:
                type: object
                properties:
                  task:
                    $ref: "#/components/schemas/MinimaxVideoTask"
        "401":
          $ref: "#/components/responses/MinimaxError"
        "403":
          $ref: "#/components/responses/MinimaxError"
        "404":
          $ref: "#/components/responses/MinimaxError"
  /special/v2/query/video_generation:
    get:
      operationId: listSpecialH3VideoTasks
      summary: 任务列表（MiniMax-H3）（特惠版）
      description: 按现有MiniMax分页及过滤参数读取本账号特惠版任务，不混入官方MiniMax任务。
      parameters:
        - name: page_num
          in: query
          schema:
            type: integer
            default: 1
          description: 页码，从 1 开始
        - name: page_size
          in: query
          schema:
            type: integer
            default: 20
          description: 每页数量
        - name: filter.status
          in: query
          schema:
            type: string
            enum:
              - queued
              - running
              - succeeded
              - failed
              - cancelled
          description: 按状态过滤
        - name: filter.model
          in: query
          schema:
            type: string
          description: 按模型过滤，如 MiniMax-H3
        - name: filter.task_type
          in: query
          schema:
            type: string
            enum:
              - generation
              - h3_context_ir
              - regeneration
          description: 按任务类型过滤
      responses:
        "200":
          description: 任务列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/MinimaxVideoTask"
                  total:
                    type: integer
        "401":
          $ref: "#/components/responses/MinimaxError"
        "403":
          $ref: "#/components/responses/MinimaxError"
        "404":
          $ref: "#/components/responses/MinimaxError"
  /special/v2/h3_context_ir:
    post:
      operationId: createSpecialH3ContextIR
      summary: 提示增强 Context-IR（MiniMax-H3）（特惠版）
      description: 异步提示词增强，不生成视频；duration为4–15秒整数。完成后从task.content.prompt取文本。特惠版不产生官方token用量，不将上游耗时或金额伪装为token。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SpecialH3ContextIRRequest"
            example:
              model: MiniMax-H3
              content:
                - type: text
                  text: 一个男孩在海边打篮球
              duration: 5
              ratio: 16:9
      responses:
        "200":
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MinimaxTaskCreated"
              example:
                task_id: "426586401755526"
        "400":
          $ref: "#/components/responses/MinimaxError"
        "401":
          $ref: "#/components/responses/MinimaxError"
        "403":
          $ref: "#/components/responses/MinimaxError"
        "404":
          $ref: "#/components/responses/MinimaxError"
  /special/v2/video_regeneration:
    post:
      operationId: createSpecialH3Regeneration
      summary: 视频 2K 再生成（MiniMax-H3）（特惠版）
      description: 根据原始最终提示词及素材，基于源视频重新生成 2K 视频。可传本账号特惠版已成功生成任务的source_task_id，或content内包含恰好一个role=base_video项；两种方式互斥，首尾帧与普通参考素材不能混用。源视频须满足上游音轨、24fps、32倍数尺寸及帧数要求；不能将任意视频视为兼容输入。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SpecialH3RegenerationRequest"
            example:
              model: MiniMax-H3
              content:
                - type: text
                  text: 原始生成时实际使用的完整提示词
                - type: video_url
                  video_url:
                    url: https://media.example.com/original-768p.mp4
                  role: base_video
              resolution: 2K
      responses:
        "200":
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MinimaxTaskCreated"
              example:
                task_id: "424010985999999"
        "400":
          $ref: "#/components/responses/MinimaxError"
        "401":
          $ref: "#/components/responses/MinimaxError"
        "403":
          $ref: "#/components/responses/MinimaxError"
        "404":
          $ref: "#/components/responses/MinimaxError"
  /special/v2/video_generation/{task_id}:
    delete:
      operationId: deleteSpecialH3VideoTask
      summary: 删除已结束的特惠任务记录
      description: 仅删除本账号已成功或失败的特惠版任务记录，不取消上游任务，不删除上游媒体，不改变已经结算的费用。仍在执行的任务返回501，不能假定上游付费任务已经取消。
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
          description: 创建任务时返回的 task_id
      responses:
        "200":
          description: 操作结果
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id:
                    type: string
                  action:
                    type: string
                    enum:
                      - deleted
                  status:
                    type: string
                    enum:
                      - deleted
        "401":
          $ref: "#/components/responses/MinimaxError"
        "403":
          $ref: "#/components/responses/MinimaxError"
        "404":
          $ref: "#/components/responses/MinimaxError"
        "501":
          $ref: "#/components/responses/MinimaxError"
  /v2/video_generation:
    post:
      operationId: createMinimaxVideoTask
      summary: 创建视频生成任务（MiniMax-H3）
      description: |
        提交 MiniMax-H3 异步视频生成任务，仅返回 `task_id`，成片需轮询查询接口获取。
        文生 / 图生 / 多模态参考共用本接口，靠 `content` 数组组合区分模式。注意路径**没有** `/api` 前缀。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MinimaxCreateRequest"
            example:
              model: MiniMax-H3
              content:
                - type: text
                  text: "一个男孩在海边打篮球，镜头缓缓拉远"
              resolution: "768P"
              duration: 5
              ratio: "16:9"
      responses:
        "200":
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MinimaxTaskCreated"
              example:
                task_id: "424010985738629"
        "400":
          $ref: "#/components/responses/MinimaxError"
        "401":
          $ref: "#/components/responses/MinimaxError"
        "429":
          $ref: "#/components/responses/MinimaxError"
  /v2/video_generation/{task_id}:
    delete:
      operationId: deleteMinimaxVideoTask
      summary: 取消 / 删除任务（MiniMax-H3）
      description: |
        `queued` → 取消（`cancelled`，不计费）；`succeeded` / `failed` → 删除（`deleted`）；`running` / `cancelled` 不可操作。
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
          description: 创建任务时返回的 task_id
      responses:
        "200":
          description: 操作结果
          content:
            application/json:
              schema:
                type: object
                properties:
                  task_id:
                    type: string
                  action:
                    type: string
                    enum: [cancelled, deleted]
                  status:
                    type: string
                    enum: [cancelled, deleted]
        "401":
          $ref: "#/components/responses/MinimaxError"
  /v2/query/video_generation/{task_id}:
    get:
      operationId: getMinimaxVideoTask
      summary: 查询视频生成任务（MiniMax-H3）
      description: |
        查询任务状态与结果。状态机：`queued → running → succeeded / failed / cancelled`。仅可查询近 7 天的任务。
        成功后视频类任务从 `task.content.url` 下载成片，Context-IR 从 `task.content.prompt` 读取增强提示词。
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
          description: 创建任务时返回的 task_id
      responses:
        "200":
          description: 任务详情
          content:
            application/json:
              schema:
                type: object
                properties:
                  task:
                    $ref: "#/components/schemas/MinimaxVideoTask"
        "401":
          $ref: "#/components/responses/MinimaxError"
  /v2/query/video_generation:
    get:
      operationId: listMinimaxVideoTasks
      summary: 任务列表（MiniMax-H3）
      description: 分页查询近 7 天的任务，可按状态 / 任务 ID / 模型 / 任务类型筛选。
      parameters:
        - name: page_num
          in: query
          schema:
            type: integer
            default: 1
          description: 页码，从 1 开始
        - name: page_size
          in: query
          schema:
            type: integer
            default: 20
          description: 每页数量
        - name: filter.status
          in: query
          schema:
            type: string
            enum: [queued, running, succeeded, failed, cancelled]
          description: 按状态过滤
        - name: filter.model
          in: query
          schema:
            type: string
          description: 按模型过滤，如 MiniMax-H3
        - name: filter.task_type
          in: query
          schema:
            type: string
            enum: [generation, h3_context_ir, regeneration]
          description: 按任务类型过滤
      responses:
        "200":
          description: 任务列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: "#/components/schemas/MinimaxVideoTask"
                  total:
                    type: integer
        "401":
          $ref: "#/components/responses/MinimaxError"
  /v2/h3_context_ir:
    post:
      operationId: createMinimaxContextIR
      summary: 提示增强 Context-IR（MiniMax-H3）
      description: |
        理解多模态上下文，输出结构化增强提示词（**不生成视频**）。成功后 `task.content.prompt` 返回增强提示词，
        `modality` 为 `text`、`task_type` 为 `h3_context_ir`，按 token 计费。请求体无 `resolution` 字段。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MinimaxContextIRRequest"
            example:
              model: MiniMax-H3
              content:
                - type: text
                  text: "一个男孩在海边打篮球"
              duration: 5
              ratio: "16:9"
      responses:
        "200":
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MinimaxTaskCreated"
              example:
                task_id: "426586401755526"
        "400":
          $ref: "#/components/responses/MinimaxError"
        "401":
          $ref: "#/components/responses/MinimaxError"
  /v2/video_regeneration:
    post:
      operationId: createMinimaxRegeneration
      summary: 视频 2K 再生成（MiniMax-H3）
      description: |
        基于源视频重新生成 2K 视频。两种入参**二选一**：
        方式一传 `source_task_id`（引用已成功的生成任务）；方式二传 `content`（包含全部原始输入 + 恰好一个 `role=base_video` 的源视频）。
        输出分辨率恒为 `2K`，`task_type` 回显 `regeneration`。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MinimaxRegenerationRequest"
            example:
              model: MiniMax-H3
              source_task_id: "424010985738629"
              resolution: "2K"
      responses:
        "200":
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MinimaxTaskCreated"
              example:
                task_id: "424010985999999"
        "400":
          $ref: "#/components/responses/MinimaxError"
        "401":
          $ref: "#/components/responses/MinimaxError"
  /text-to-video/{model}:
    post:
      operationId: createKlingTextToVideo
      summary: 文生视频（可灵 3.0）
      description: |
        提交可灵 3.0 文生视频任务。模型名写在路径中（kling-3.0 / kling-3.0-turbo），
        请求体用 prompt + settings。仅返回任务 id，成片需轮询 GET /tasks 获取。

        所有可灵 3.0 端点的路径都可选加 `/v1` 前缀（如 `/v1/text-to-video/{model}`），
        行为完全一致，方便 Base URL 带 `/v1` 的可灵 SDK 直接接入。
      parameters:
        - name: model
          in: path
          required: true
          schema:
            type: string
            enum: [kling-3.0, kling-3.0-turbo]
          description: 可灵 3.0 模型名
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KlingSubmitRequest"
            example:
              prompt: 一只柯基犬在草地上奔跑，阳光明媚，慢镜头
              settings:
                resolution: 1080p
                aspect_ratio: "16:9"
                duration: 5
                audio: native
                multi_shot: true
      responses:
        "200":
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KlingSubmitResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
  /image-to-video/{model}:
    post:
      operationId: createKlingImageToVideo
      summary: 图生视频（可灵 3.0）
      description: |
        提交可灵 3.0 图生视频任务。contents 放 first_frame（可加 last_frame）。
        模型名写在路径中（kling-3.0 / kling-3.0-turbo）。
      parameters:
        - name: model
          in: path
          required: true
          schema:
            type: string
            enum: [kling-3.0, kling-3.0-turbo]
          description: 可灵 3.0 模型名
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KlingSubmitRequest"
            example:
              prompt: 镜头缓缓推进，人物转身微笑
              settings:
                resolution: 1080p
                duration: 5
              contents:
                - type: first_frame
                  url: https://example.com/first.jpg
                - type: last_frame
                  url: https://example.com/last.jpg
      responses:
        "200":
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KlingSubmitResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
  /omni-video/{model}:
    post:
      operationId: createKlingOmniVideo
      summary: Omni 多模态生成（可灵 3.0）
      description: |
        提交可灵 3.0 Omni 多模态任务。contents 可组合 refer_image / feature_video /
        base_video / element；网关按顺序把素材绑定进提示词。模型名固定 kling-3.0-omni。
      parameters:
        - name: model
          in: path
          required: true
          schema:
            type: string
            enum: [kling-3.0-omni]
          description: 可灵 3.0 Omni 模型名
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KlingSubmitRequest"
            example:
              prompt: 让参考图中的角色在城市夜景中行走，参考该视频的运镜
              settings:
                resolution: 1080p
                aspect_ratio: "16:9"
                duration: 5
                audio: original
              options:
                external_task_id: my-biz-001
              contents:
                - type: refer_image
                  url: https://example.com/character.jpg
                - type: feature_video
                  url: https://example.com/motion.mp4
      responses:
        "200":
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KlingSubmitResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
  /tasks:
    get:
      operationId: listKlingVideoTasks
      summary: 任务查询（可灵 3.0）
      description: |
        批量查询可灵 3.0 任务。task_ids 与 external_task_ids 二选一（task_ids 优先），
        均支持逗号分隔批量。data 恒为数组。状态机：submitted → processing → succeeded / failed。
      parameters:
        - name: task_ids
          in: query
          schema:
            type: string
          description: 网关任务 ID 列表，逗号分隔
        - name: external_task_ids
          in: query
          schema:
            type: string
          description: 业务自定义 ID 列表（options.external_task_id），逗号分隔
      responses:
        "200":
          description: 任务列表
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KlingTasksResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /motion-control/{model}:
    post:
      operationId: createKlingMotionControl
      summary: 动作控制（可灵 3.0）
      description: |
        提交可灵 3.0 动作控制任务：用一段参考视频驱动图片 / 主体做出对应动作。计费模型固定
        kling-3.0-motion-control（路径里的 model 仅作占位，可写 kling-3.0）。输出时长由参考
        视频决定（≤30 秒），提交时按最大计费时长（30 秒）预扣、完成后按实际时长多退少补。
        成片轮询 GET /tasks 获取（动作控制属视频任务，不走数字人专属查询）。

        请求体支持两种形态：官方 contents[] + settings（推荐），或扁平结构（image_url /
        video_url / mode / character_orientation / keep_original_sound，兼容别名）。两者并存
        时以 contents / settings 优先。路径可加 /v1 前缀；扁平结构还可走
        POST /videos/motion-control（无路径 model）。
      parameters:
        - name: model
          in: path
          required: true
          schema:
            type: string
            enum: [kling-3.0, kling-3.0-motion-control]
          description: 占位模型名，计费固定 kling-3.0-motion-control
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KlingMotionControlRequest"
            example:
              contents:
                - type: image
                  url: https://example.com/char.png
                - type: video
                  url: https://example.com/drive.mp4
                - type: prompt
                  text: the character dances energetically
              settings:
                character_orientation: video
                audio: original
                resolution: 720p
      responses:
        "200":
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KlingSubmitResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
  /videos/avatar/image2video:
    post:
      operationId: createKlingAvatar
      summary: 数字人提交（可灵 3.0）
      description: |
        提交可灵 3.0 数字人任务：用音频驱动人像口型说话。请求体是扁平结构，计费模型固定
        kling-3.0-avatar。输出时长跟随驱动音频（2-300 秒），提交时按最大计费时长（300 秒）
        预扣、完成后回收。image 必填；音源用 sound_file（URL）或 audio_id（既有音色）二选一。

        数字人用官方 ack 信封（data.task_id / task_status / task_result.videos[]），成功态为
        succeed（注意与视频端点的 succeeded 不同）。查询走专属端点
        GET /videos/avatar/image2video/{task_id}，不走 GET /tasks。路径均可加 /v1 前缀。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KlingAvatarRequest"
            example:
              image: https://example.com/face.png
              audio_id: voice-abc-123
              prompt: news anchor reading headlines
              mode: std
      responses:
        "200":
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KlingAvatarResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
  /videos/avatar/image2video/{task_id}:
    get:
      operationId: getKlingAvatar
      summary: 数字人查询（可灵 3.0）
      description: |
        查询数字人任务。成功时 data.task_result.videos[] 返回成片（id / url / duration）。
        状态：submitted / processing / succeed / failed（成功态是 succeed，与视频端点的
        succeeded 不同）。数字人不走 GET /tasks，用本专属端点查询。路径可加 /v1 前缀。
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
          description: 提交时返回的网关任务 ID
      responses:
        "200":
          description: 任务详情
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KlingAvatarResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /general/custom-voices:
    post:
      operationId: createKlingVoice
      summary: 声音复刻提交（可灵 3.0）
      description: |
        提交可灵 3.0 声音复刻任务：用一段音源克隆音色，产出可复用的 voice_id（可作数字人的
        audio_id）。请求体是扁平结构，计费模型固定 kling-3.0-voice，按次计费（非视频，无预扣
        回收）。查询走 GET /general/custom-voices/{task_id}。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KlingVoiceRequest"
            example:
              voice_name: my-anchor-voice
              voice_url: https://example.com/sample-voice.mp3
      responses:
        "200":
          description: 任务创建成功
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KlingVoiceResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
    get:
      operationId: listKlingVoices
      summary: 声音复刻列表（可灵 3.0）
      description: |
        列出当前令牌下已复刻的音色。data 恒为数组，每项是一条声音复刻任务的 ack 信封
        （task_id / task_status / task_result.voices[]），成功态为 succeed。路径可加 /v1 前缀。
      responses:
        "200":
          description: 音色列表
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KlingVoiceListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /general/custom-voices/{task_id}:
    get:
      operationId: getKlingVoice
      summary: 声音复刻查询（可灵 3.0）
      description: |
        查询声音复刻任务。成功时 data.task_result.voices[] 返回复刻音色（voice_id 可用于
        数字人的 audio_id）。状态：submitted / processing / succeed / failed
        （注意成功态是 succeed，与视频端点的 succeeded 不同）。
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
          description: 提交时返回的网关任务 ID
      responses:
        "200":
          description: 任务详情
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KlingVoiceResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /general/advanced-custom-elements:
    post:
      operationId: createKlingCustomElement
      summary: 创建自定义主体（可灵 3.0）
      description: |
        创建可灵 3.0 高级自定义主体（advanced custom elements / 主体管理）：用参考图或参考视频
        定义一个可复用主体。成功查询后拿到的 element_id 可在 Omni（POST /omni-video）或动作控制
        （POST /motion-control）中通过 element 素材引用。主体管理是渠道级能力，不计费。
        返回的 data.task_id 是网关签名的不透明令牌（ace_ 开头），后续查询必须原样使用它——
        它会把查询无状态地路由回创建时的同一渠道。路径可加 /v1 前缀。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/KlingCustomElementCreateRequest"
            example:
              element_name: my-hero
              element_description: 一位身穿红色斗篷的动画英雄
              reference_type: image_refer
              element_image_list:
                frontal_image: https://example.com/hero-front.png
                refer_images:
                  - image_url: https://example.com/hero-side.png
                  - image_url: https://example.com/hero-back.png
              tag_list:
                - tag_id: o_101
      responses:
        "200":
          description: 主体创建已受理（data.task_id 为网关签名令牌，无 task_result）
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KlingCustomElementResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "502":
          description: 上游主体创建失败（按上游报文透传）
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /general/advanced-custom-elements/{task_id}:
    get:
      operationId: getKlingCustomElement
      summary: 查询自定义主体（可灵 3.0）
      description: |
        按创建时返回的 task_id 令牌查询单个主体。task_id 必须是本网关签发的 ace_ 令牌，它会把
        查询路由回创建时的同一渠道。成功时 data.task_result.elements[] 携带 element_id 与主体
        元数据；element_id 可在 Omni / 动作控制中引用。路径可加 /v1 前缀。
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
          description: 创建时返回的网关签名令牌（ace_ 开头）
      responses:
        "200":
          description: 主体详情
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KlingCustomElementResponse"
        "400":
          description: task_id 令牌无效、结构错误或签名不匹配
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: 令牌对应的渠道不存在
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
  /general/advanced-presets-elements:
    get:
      operationId: listKlingPresetElements
      summary: 查询官方预置主体（可灵 3.0）
      description: |
        分页查询可灵官方预置主体列表。data 为主体任务对象数组，每项 task_result.elements[]
        携带 element_id（可直接在 Omni / 动作控制中引用）。每条的 task_id 同样是网关签名令牌
        （白标 + 路由回本次解析出的渠道）。路径可加 /v1 前缀。
      parameters:
        - name: pageNum
          in: query
          required: false
          schema:
            type: integer
            default: 1
          description: 页码，默认 1（缺省或非正数交由上游取默认值）
        - name: pageSize
          in: query
          required: false
          schema:
            type: integer
            default: 30
          description: 每页条数，默认 30（缺省或非正数交由上游取默认值）
      responses:
        "200":
          description: 预置主体列表
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KlingPresetElementsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "LoopRouter API Key（sk- 开头），在控制台「令牌」页创建"
  schemas:
    CreateVideoTaskRequest:
      type: object
      required: [model, content]
      properties:
        model:
          type: string
          description: 模型名，如 doubao-seedance-2-0-260128、doubao-seedance-2-5-260628
        content:
          type: array
          description: 生成素材数组（文本 / 图片 / 视频 / 音频）
          items:
            $ref: "#/components/schemas/ContentItem"
        resolution:
          type: string
          enum: [480p, 720p, 1080p, 4k]
          description: 输出分辨率。Seedance 2.0 支持 480p / 720p / 1080p / 4k；Seedance 2.5 支持 480p / 720p / 1080p（默认 720p，暂不支持 4k，传入 4k 返回 400 且不扣费）。具体可用档位以控制台「模型广场」为准
        ratio:
          type: string
          enum: ["16:9", "4:3", "1:1", "3:4", "9:16", "21:9", "adaptive"]
          description: 画面宽高比，默认 adaptive。Seedance 2.5 的首帧 / 首尾帧、视频编辑、视频延长任务仅支持 adaptive；文生视频与参考生成可指定比例
        duration:
          type: integer
          description: 输出时长（秒）。Seedance 2.0 为 4–15 秒整数或 -1；Seedance 2.5 为 4–30 秒整数或 -1（默认 -1，智能选择），编辑任务仅支持 -1
        generate_audio:
          type: boolean
          description: 是否生成同步音频，默认 true；有声视频输出为单声道
        watermark:
          type: boolean
          description: 是否叠加 AI 生成水印，默认 false
        output_format:
          type: string
          enum: [mp4, mov]
          description: 仅 Seedance 2.5 支持，默认 mp4。输出容器格式；mov 适合专业后期，保留上游原生规格产物。其他模型请勿传入
        omni_reference_task_type:
          type: string
          enum: [auto, reference, edit, extend]
          description: 仅 Seedance 2.5 全模态参考任务支持，默认 auto。reference 为参考生成；edit 为视频编辑，须包含 4–30 秒 reference_video、ratio=adaptive、duration=-1；extend 为视频延长，须包含 reference_video、ratio=adaptive。其他模型请勿传入
        seed:
          type: integer
          description: 旧版 Seedance 1.x 随机种子参数；官方未将 Seedance 2.0 / 2.5 列入支持模型，请勿在这两代模型的请求中传入
        return_last_frame:
          type: boolean
          description: 成功后额外返回无水印 PNG 末帧图片，尺寸与输出视频一致
        execution_expires_after:
          type: integer
          minimum: 3600
          maximum: 259200
          default: 172800
          description: 从任务创建时间起计算的超时秒数，超时未完成转为 expired
    ContentItem:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [text, image_url, video_url, audio_url]
        text:
          type: string
          description: type=text 时的提示词
        image_url:
          type: object
          description: 首帧 1 张、首尾帧 2 张；多模态参考中 Seedance 2.0 最多 9 张，2.5 最多 30 张。单张小于 30 MB，宽高比 [0.4, 2.5]，宽高均为 [300, 6000] 像素
          properties:
            url:
              type: string
              description: 公网 URL / Base64 data URI / asset://素材ID
        video_url:
          type: object
          description: MP4 / MOV，视频编码 H.264/AVC 或 H.265/HEVC，24–60fps，单个不超过 200 MB。Seedance 2.0 最多 3 个、单个 2–15 秒、总时长不超过 15 秒；2.5 最多 10 个、单个 2–30 秒（编辑任务 4–30 秒）、总时长不超过 30 秒
          properties:
            url:
              type: string
              description: 公网 URL 或 asset://素材ID，不支持视频 Base64
        audio_url:
          type: object
          description: WAV / MP3，单段不超过 15 MB。Seedance 2.0 最多 3 段、单段 2–15 秒、总时长不超过 15 秒，须搭配图片或视频；2.5 最多 10 段、单段 2–30 秒、总时长不超过 30 秒，支持仅输入音频
          properties:
            url:
              type: string
              description: 公网 URL / Base64 data URI / asset://素材ID
        role:
          type: string
          enum: [first_frame, last_frame, reference_image, reference_video, reference_audio]
          description: 素材角色。首帧、首尾帧、多模态参考是互斥场景，不可混用 first_frame / last_frame 与 reference_image / reference_video / reference_audio
    VideoTask:
      type: object
      properties:
        id:
          type: string
        model:
          type: string
        status:
          type: string
          enum: [queued, running, succeeded, failed, cancelled, expired]
        content:
          type: object
          properties:
            video_url:
              type: string
              description: 临时成片下载地址。官方原始视频 URL 有效期为 24 小时，Seedance 2.5 视频 URL 最多下载 100 次；平台转存链接以实际存储策略为准
            last_frame_url:
              type: string
              description: return_last_frame=true 时返回的无水印 PNG 末帧图地址
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
        usage:
          type: object
          properties:
            completion_tokens:
              type: integer
            total_tokens:
              type: integer
        seed:
          type: integer
        resolution:
          type: string
        ratio:
          type: string
        duration:
          type: integer
          description: 输出视频的整数秒约数。Seedance 2.5 按实际总帧数 / 24 向下取整，不保证等于文件精确时长
        framespersecond:
          type: integer
        generate_audio:
          type: boolean
        output_format:
          type: string
          enum: [mp4, mov]
          description: Seedance 2.5 上游生成视频的格式；旧任务或上游未返回时省略
        created_at:
          type: integer
        updated_at:
          type: integer
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            param:
              type: string
            type:
              type: string
              enum:
                - BadRequest
                - Unauthorized
                - Forbidden
                - NotFound
                - RateLimitExceeded
                - InternalServerError
                - RequestError
    CreateSeedreamImageRequest:
      description: 普通生成/编辑或图层拆分请求，两种结构由 layer_decomposition 区分
      oneOf:
        - $ref: "#/components/schemas/SeedreamGenerationRequest"
        - $ref: "#/components/schemas/SeedreamLayerDecompositionRequest"
    SeedreamGenerationRequest:
      type: object
      required: [model, prompt]
      allOf:
        - not:
            anyOf:
              - required: [n]
              - required: [sequential_image_generation]
              - required: [sequential_image_generation_options]
              - required: [tools]
        - if:
            required: [background]
            properties:
              background:
                const: transparent
          then:
            required: [image, output_format]
            properties:
              image:
                oneOf:
                  - type: string
                    minLength: 1
                    pattern: '\S'
                  - type: array
                    minItems: 1
                    maxItems: 1
                    items:
                      type: string
                      minLength: 1
                      pattern: '\S'
              output_format:
                const: png
      properties:
        model:
          type: string
          const: doubao-seedream-5-0-pro-260628
          description: 模型 ID，固定为 doubao-seedream-5-0-pro-260628
        prompt:
          type: string
          minLength: 1
          pattern: '\S'
          description: 非空提示词，支持模型提供的多语种输入。交互编辑中的 `<point>` 与 `<bbox>` 坐标值使用 0..999
        image:
          oneOf:
            - type: string
              minLength: 1
              pattern: '\S'
            - type: array
              minItems: 1
              maxItems: 10
              items:
                type: string
                minLength: 1
                pattern: '\S'
          description: 非空参考图 URL 或 Data URI；普通模式最多 10 张。单图格式支持 jpeg（含 jpg 别名）、png、webp、bmp、tiff（含 tif 别名）、gif、heic、heif；单张不超过 30 MB，宽高均大于 14 px，总像素 [196, 36000000]，宽高比 [1/16, 16]
        size:
          oneOf:
            - type: string
              enum: [1K, 1k, 1.5K, 1.5k, 2K, 2k]
            - type: string
              pattern: "^[1-9][0-9]*x[1-9][0-9]*$"
          default: 2K
          description: 分辨率档位（K/k 大小写均可，建议使用示例中的规范写法），或显式「宽x高」。显式宽高总像素须在 [921600, 4624220]，宽高比须在 [1/16, 16]
        optimize_prompt_options:
          type: object
          description: 提示词优化配置
          properties:
            mode:
              type: string
              enum: [standard, fast]
              default: standard
              description: 提示词优化模式
        output_format:
          type: string
          enum: [jpeg, png]
          default: jpeg
          description: 输出图片格式
        background:
          type: string
          enum: [opaque, transparent]
          default: opaque
          description: 背景模式。transparent 仅用于恰好输入一张图片的编辑请求，且 output_format 须为 png
        response_format:
          type: string
          enum: [url, b64_json]
          default: url
          description: 返回方式。url 链接在图片生成后 24 小时内有效
        layer_decomposition:
          type: boolean
          const: false
          default: false
          description: 普通模式须省略或设为 false
        watermark:
          type: boolean
          default: true
          description: 是否添加「AI 生成」水印
        stream:
          type: boolean
          const: false
          description: 仅接受 false，调用仍为同步；true 会返回参数错误
    SeedreamLayerDecompositionRequest:
      type: object
      description: 图层拆分请求。任一图层生成失败时整个请求失败，不返回部分结果
      required: [model, image, layer_decomposition]
      allOf:
        - not:
            anyOf:
              - required: [n]
              - required: [sequential_image_generation]
              - required: [sequential_image_generation_options]
              - required: [tools]
        - if:
            required: [background]
            properties:
              background:
                const: transparent
          then:
            required: [output_format]
            properties:
              output_format:
                const: png
      properties:
        model:
          type: string
          const: doubao-seedream-5-0-pro-260628
          description: 模型 ID，固定为 doubao-seedream-5-0-pro-260628
        prompt:
          type: string
          description: 可选；省略或传空字符串时自动完整拆分，填写非空内容时用于定向拆分或图层编辑
        image:
          oneOf:
            - type: string
              minLength: 1
              pattern: '\S'
            - type: array
              minItems: 1
              maxItems: 1
              items:
                type: string
                minLength: 1
                pattern: '\S'
          description: 必须且只能输入一张 png 或 jpeg（含 jpg 别名）图片；不超过 30 MB，宽高均大于 14 px，总像素 [262144, 36000000]，宽高比 [1/16, 16]
        size:
          type: string
          enum: [auto, AUTO, 1K, 1k, 1.5K, 1.5k, 2K, 2k]
          default: auto
          description: 图层拆分尺寸（大小写不敏感，建议使用 auto、1K、1.5K、2K）；不支持显式「宽x高」
        optimize_prompt_options:
          type: object
          description: 提示词优化配置
          properties:
            mode:
              type: string
              enum: [standard, fast]
              default: standard
              description: 提示词优化模式
        output_format:
          type: string
          enum: [jpeg, png]
          default: jpeg
          description: 基础图格式；拆分图层始终为带透明通道的 png
        background:
          type: string
          enum: [opaque, transparent]
          default: opaque
          description: 背景模式。transparent 要求 output_format 为 png
        response_format:
          type: string
          enum: [url, b64_json]
          default: url
          description: 返回方式。url 链接在图片生成后 24 小时内有效
        layer_decomposition:
          type: boolean
          const: true
          description: 图层拆分模式必须为 true
        watermark:
          type: boolean
          default: true
          description: 是否添加「AI 生成」水印
        stream:
          type: boolean
          const: false
          description: 仅接受 false，调用仍为同步；true 会返回参数错误
    SeedreamImageOutput:
      type: object
      required: [size, output_format]
      oneOf:
        - required: [url]
        - required: [b64_json]
      properties:
        url:
          type: string
          format: uri
          description: response_format=url 时返回的图片链接，生成后 24 小时内有效
        b64_json:
          type: string
          description: response_format=b64_json 时返回的 Base64 图片数据
        size:
          type: string
          description: 当前输出项的实际「宽x高」像素值
        output_format:
          type: string
          enum: [jpeg, png]
          description: 当前输出项的图片格式；拆分图层始终为 png
        z_index:
          type: integer
          minimum: 0
          maximum: 16
          description: 仅图层模式出现；基础图为 0，后续图层从 1 递增
        bounding_box:
          $ref: "#/components/schemas/SeedreamLayerBoundingBox"
        name:
          type: string
          description: 仅图层模式出现的图层名称
        description:
          type: string
          description: 仅图层模式出现的图层内容说明
    SeedreamLayerBoundingBox:
      type: object
      description: 仅图层模式出现的图层位置
      required: [absolute, normalized]
      properties:
        absolute:
          type: array
          minItems: 4
          maxItems: 4
          items:
            type: integer
            minimum: 0
          description: "[left, top, right, bottom]，相对于基础输出图的像素坐标"
        normalized:
          type: array
          minItems: 4
          maxItems: 4
          items:
            type: integer
            minimum: 0
            maximum: 1000
          description: "[left, top, right, bottom]，每个值位于 0..1000。交互编辑提示词坐标使用 0..999"
    SeedreamImageUsage:
      type: object
      required: [input_images, generated_images, output_tokens, total_tokens]
      properties:
        input_images:
          type: integer
          minimum: 0
          maximum: 10
          description: 输入参考图数量
        generated_images:
          type: integer
          minimum: 1
          maximum: 17
          description: 输出图片数量；普通模式为 1，图层模式最多为 17
        output_tokens:
          type: integer
          minimum: 0
          description: 各输出图片像素总和除以 256 后取整
        total_tokens:
          type: integer
          minimum: 0
          description: 此接口中与 output_tokens 一致
    SeedreamImageResponse:
      type: object
      required: [model, created, data, usage]
      properties:
        model:
          type: string
          description: 实际请求模型
        created:
          type: integer
          description: 请求创建时间的 Unix 时间戳（秒）
        data:
          type: array
          minItems: 1
          maxItems: 17
          description: 普通模式包含一张基础图；图层模式包含一张基础图和最多 16 个图层
          items:
            $ref: "#/components/schemas/SeedreamImageOutput"
        usage:
          $ref: "#/components/schemas/SeedreamImageUsage"
    SeedreamImageErrorResponse:
      type: object
      required: [error]
      description: 图片请求失败时返回。error.code 存在且不为 null，或 error.message / error.type 非空时，响应均按失败处理
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              description: 客户端可见错误码；本地参数校验失败为 InvalidParameter
            message:
              type: string
              description: 客户端可见错误说明
            param:
              type: string
              description: 仅在错误明确关联某个参数时返回
            type:
              type: string
              description: 仅在错误源提供明确类型时返回
    SpecialH3ContentItem:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - text
            - image_url
            - video_url
            - audio_url
        text:
          type: string
          description: type=text 时的提示词；生成最多20000字符，Context-IR最多7000字符，再生最多40000字符。
        image_url:
          type: object
          properties:
            url:
              type: string
              description: 公网HTTP(S)图片URL；不支持data URI或mm_file://。生成图片仅支持JPG/PNG。
          required:
            - url
          additionalProperties: false
        video_url:
          type: object
          properties:
            url:
              type: string
          required:
            - url
          additionalProperties: false
        audio_url:
          type: object
          properties:
            url:
              type: string
          required:
            - url
          additionalProperties: false
        role:
          type: string
          enum:
            - first_frame
            - last_frame
            - reference_image
            - reference_video
            - reference_audio
            - base_video
          description: 素材角色；base_video 仅用于视频再生
      additionalProperties: false
    SpecialH3CreateRequest:
      type: object
      required:
        - model
        - content
        - resolution
        - duration
        - ratio
      properties:
        model:
          type: string
          description: 固定 MiniMax-H3
          enum:
            - MiniMax-H3
        content:
          type: array
          description: 生成素材数组（文本 / 图片 / 视频 / 音频）
          items:
            $ref: "#/components/schemas/SpecialH3ContentItem"
        resolution:
          type: string
          enum:
            - 768P
            - 2K
          description: 输出分辨率
        duration:
          type: integer
          minimum: 5
          maximum: 15
          description: 生成时长（秒），不支持4秒生成
        ratio:
          type: string
          enum:
            - 21:9
            - 16:9
            - 4:3
            - 1:1
            - 3:4
            - 9:16
          description: 显式具体比例；不支持adaptive，不自动根据素材猜测比例。
      additionalProperties: false
    SpecialH3ContextIRRequest:
      type: object
      required:
        - model
        - content
        - duration
      properties:
        model:
          type: string
          description: 固定 MiniMax-H3
          enum:
            - MiniMax-H3
        content:
          type: array
          items:
            $ref: "#/components/schemas/SpecialH3ContentItem"
        duration:
          type: integer
          minimum: 4
          maximum: 15
          description: 目标时长（秒）；上游转换为字符串
        ratio:
          type: string
          description: 纯文本须指定具体比例；多参考可用adaptive（默认）；首尾帧模式由图片决定比例，此字段不传给上游。
          enum:
            - adaptive
            - 21:9
            - 16:9
            - 4:3
            - 1:1
            - 3:4
            - 9:16
      additionalProperties: false
    SpecialH3RegenerationRequest:
      type: object
      required:
        - model
        - resolution
      description: source_task_id与content二选一；content须包含完整原始素材与一个base_video，prompt为生成源视频时实际使用的最终提示词。
      oneOf:
        - required: [source_task_id]
          not:
            required: [content]
        - required: [content]
          not:
            required: [source_task_id]
      properties:
        model:
          type: string
          description: 固定 MiniMax-H3
          enum:
            - MiniMax-H3
        source_task_id:
          type: string
          minLength: 1
          description: 本账号通过/special/v2创建且已成功的768P视频任务；不能引用官方/v2任务或Context-IR任务。
        resolution:
          type: string
          enum:
            - 2K
          description: 输出恒为 2K
        content:
          type: array
          description: 方式二：原始输入 + 恰好一个 role=base_video 的源视频项
          items:
            $ref: "#/components/schemas/SpecialH3ContentItem"
      additionalProperties: false
    MinimaxContentItem:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [text, image_url, video_url, audio_url]
        text:
          type: string
          description: type=text 时的提示词（≤7000 字符；视频再生 content 模式 ≤40000）
        image_url:
          type: object
          properties:
            url:
              type: string
              description: 公网 URL / Base64 data URI / mm_file://{file_id}
        video_url:
          type: object
          properties:
            url:
              type: string
        audio_url:
          type: object
          properties:
            url:
              type: string
        role:
          type: string
          enum: [first_frame, last_frame, reference_image, reference_video, reference_audio, base_video]
          description: 素材角色；base_video 仅用于视频再生
    MinimaxCreateRequest:
      type: object
      required: [model, content, resolution, duration]
      properties:
        model:
          type: string
          description: 固定 MiniMax-H3
        content:
          type: array
          description: 生成素材数组（文本 / 图片 / 视频 / 音频）
          items:
            $ref: "#/components/schemas/MinimaxContentItem"
        resolution:
          type: string
          enum: ["768P", "2K"]
          description: 输出分辨率
        duration:
          type: integer
          description: 输出时长（秒），4–15
        ratio:
          type: string
          enum: [adaptive, "21:9", "16:9", "4:3", "1:1", "3:4", "9:16"]
          description: 画面宽高比；文生视频必填且不能为 adaptive；图生视频恒按 adaptive
        aigc_watermark:
          type: boolean
          description: 是否叠加 AIGC 水印，默认 false
        callback_url:
          type: string
          description: 任务状态变化回调地址
    MinimaxContextIRRequest:
      type: object
      required: [model, content, duration]
      properties:
        model:
          type: string
          description: 固定 MiniMax-H3
        content:
          type: array
          items:
            $ref: "#/components/schemas/MinimaxContentItem"
        duration:
          type: integer
          description: 目标时长（秒），4–15
        ratio:
          type: string
          enum: [adaptive, "21:9", "16:9", "4:3", "1:1", "3:4", "9:16"]
        callback_url:
          type: string
    MinimaxRegenerationRequest:
      type: object
      required: [model, resolution]
      description: source_task_id 与 content 二选一（互斥）
      properties:
        model:
          type: string
          description: 固定 MiniMax-H3
        resolution:
          type: string
          enum: ["2K"]
          description: 输出恒为 2K
        source_task_id:
          type: string
          description: 方式一：已成功的 /v2/video_generation 任务 ID（7 天内、属于当前账号）
        content:
          type: array
          description: 方式二：原始输入 + 恰好一个 role=base_video 的源视频项
          items:
            $ref: "#/components/schemas/MinimaxContentItem"
        aigc_watermark:
          type: boolean
        callback_url:
          type: string
    MinimaxTaskCreated:
      type: object
      properties:
        task_id:
          type: string
          description: 任务 ID，用于查询任务状态
    MinimaxVideoTask:
      type: object
      properties:
        id:
          type: string
        model:
          type: string
        status:
          type: string
          enum: [queued, running, succeeded, failed, cancelled]
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
        content:
          type: object
          properties:
            url:
              type: string
              description: 成片下载地址（限时链接）
            prompt:
              type: string
              description: Context-IR 增强提示词（modality=text 时）
        resolution:
          type: string
        duration:
          type: integer
        ratio:
          type: string
          description: 可能为空字符串
        task_type:
          type: string
          enum: [generation, h3_context_ir, regeneration]
        modality:
          type: string
          enum: [video, text]
        usage:
          type: object
          description: 视频类返回 *_seconds / input_image_count；Context-IR 返回 *_tokens
          properties:
            total_seconds:
              type: integer
            input_seconds:
              type: integer
            output_seconds:
              type: integer
            input_image_count:
              type: integer
            total_tokens:
              type: integer
            prompt_tokens:
              type: integer
            completion_tokens:
              type: integer
        created_at:
          type: integer
        updated_at:
          type: integer
    MinimaxErrorResponse:
      type: object
      description: MiniMax 原生错误结构，顶层 type=error；message 末尾括号内为内部码，如 "(1002)"
      properties:
        type:
          type: string
          example: error
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - bad_request_error
                - authorized_error
                - insufficient_balance_error
                - unprocessable_entity_error
                - rate_limit_error
                - server_error
            message:
              type: string
            http_code:
              type: string
        request_id:
          type: string
    KlingSettings:
      type: object
      properties:
        resolution:
          type: string
          enum: ["720p", "1080p", "4k"]
          description: 输出分辨率，默认 720p（Turbo 通常至 1080p）
        aspect_ratio:
          type: string
          enum: ["16:9", "9:16", "1:1"]
          description: 画面宽高比，默认 16:9
        duration:
          type: integer
          description: 输出时长（整数秒），如 5 / 10
        audio:
          type: string
          enum: [native, original, off]
          description: native 生成配套音频；original 保留参考视频原声（仅 Omni feature_video）；off 静音（默认）
        multi_shot:
          type: boolean
          description: 多镜头分镜叙事开关，默认 true
    KlingWatermarkInfo:
      type: object
      properties:
        enabled:
          type: boolean
    KlingOptions:
      type: object
      properties:
        external_task_id:
          type: string
          description: 业务自定义 ID，回显在任务 external_id，可用 GET /tasks?external_task_ids= 反查
        watermark_info:
          $ref: "#/components/schemas/KlingWatermarkInfo"
        callback_url:
          type: string
          description: 预留字段，当前不投递回调，请改用轮询 GET /tasks
    KlingContentItem:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [prompt, first_frame, last_frame, refer_image, feature_video, base_video, element]
        text:
          type: string
          description: type=prompt 时的提示词
        url:
          type: string
          description: 图片 / 视频素材地址（first_frame / last_frame / refer_image / feature_video / base_video）
        element_id:
          type: integer
          format: int64
          description: type=element 时引用的既有主体 ID
    KlingSubmitRequest:
      type: object
      properties:
        prompt:
          type: string
          description: 主提示词；文生视频必填，也可作为 contents 里的 type=prompt 项提供
        settings:
          $ref: "#/components/schemas/KlingSettings"
        options:
          $ref: "#/components/schemas/KlingOptions"
        contents:
          type: array
          description: 素材数组（图生视频与 Omni 必填）
          items:
            $ref: "#/components/schemas/KlingContentItem"
    KlingSubmitData:
      type: object
      properties:
        id:
          type: string
          description: 网关任务 ID，后续查询用它
        status:
          type: string
          enum: [submitted, processing, succeeded, failed]
        create_time:
          type: integer
          format: int64
          description: Unix 毫秒时间戳
        update_time:
          type: integer
          format: int64
          description: Unix 毫秒时间戳
        external_id:
          type: string
    KlingSubmitResponse:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: SUCCEED
        request_id:
          type: string
        data:
          $ref: "#/components/schemas/KlingSubmitData"
    KlingOutput:
      type: object
      properties:
        id:
          type: string
          description: 产物 ID（与任务 id 一致）
        url:
          type: string
          description: 成片下载地址（限时链接）
        duration:
          type: string
          description: 成片时长（秒）
    KlingTaskItem:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
          enum: [submitted, processing, succeeded, failed]
        create_time:
          type: integer
          format: int64
        update_time:
          type: integer
          format: int64
        external_id:
          type: string
        outputs:
          type: array
          items:
            $ref: "#/components/schemas/KlingOutput"
    KlingTasksResponse:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: SUCCEED
        request_id:
          type: string
        data:
          type: array
          items:
            $ref: "#/components/schemas/KlingTaskItem"
    KlingElementRef:
      type: object
      properties:
        element_id:
          type: integer
          format: int64
          description: 已创建的自定义主体 ID
    KlingMotionControlContentItem:
      type: object
      required: [type]
      properties:
        type:
          type: string
          enum: [prompt, image, refer_image, first_frame, video, feature_video, base_video, element]
          description: image/refer_image/first_frame→被驱动图；video/feature_video/base_video→驱动视频；prompt→提示词；element→已有主体
        text:
          type: string
          description: type=prompt 时的提示词
        url:
          type: string
          description: 图片 / 视频素材地址
        element_id:
          type: integer
          format: int64
          description: type=element 时引用的既有主体 ID
    KlingMotionControlSettings:
      type: object
      properties:
        character_orientation:
          type: string
          enum: [image, video]
          description: 主体朝向基准
        audio:
          type: string
          enum: [original, native, off]
          description: original/native 保留参考视频原声（keep_original_sound=yes），off 静音
        resolution:
          type: string
          enum: ["720p", "1080p"]
          description: 输出分辨率，映射生成模式（720p→std，1080p→pro）
    KlingMotionControlRequest:
      type: object
      description: |
        动作控制请求，支持两种形态。官方形态：contents[] + settings。扁平兼容形态：顶层
        image_url / video_url / mode / character_orientation / keep_original_sound / element_list。
        两者并存时以 contents / settings 优先。
      properties:
        contents:
          type: array
          description: 官方形态素材数组（image / video / prompt / element）
          items:
            $ref: "#/components/schemas/KlingMotionControlContentItem"
        settings:
          $ref: "#/components/schemas/KlingMotionControlSettings"
        prompt:
          type: string
          description: 动作 / 场景描述（扁平形态）
        image_url:
          type: string
          description: 被驱动的图片 / 主体图地址（扁平形态）
        video_url:
          type: string
          description: 驱动动作的参考视频地址（扁平形态）
        element_list:
          type: array
          description: 可选，引用已创建的自定义主体（扁平形态）
          items:
            $ref: "#/components/schemas/KlingElementRef"
        keep_original_sound:
          type: string
          enum: ["yes", "no"]
          description: 是否保留参考视频原声（扁平形态）
        character_orientation:
          type: string
          enum: [image, video]
          description: 主体朝向基准（扁平形态）
        mode:
          type: string
          enum: [std, pro]
          description: 生成模式，映射分辨率档位（std→720p，pro→1080p）（扁平形态）
        watermark_info:
          $ref: "#/components/schemas/KlingWatermarkInfo"
    KlingAvatarRequest:
      type: object
      required: [image]
      properties:
        image:
          type: string
          description: 人像图地址（必填）
        sound_file:
          type: string
          description: 驱动音频地址（与 audio_id 二选一）
        audio_id:
          type: string
          description: 既有音色 ID（与 sound_file 二选一，可用声音复刻产出的 voice_id）
        prompt:
          type: string
          description: 可选，场景 / 表演描述
        mode:
          type: string
          enum: [std, pro]
          description: 生成模式，映射分辨率档位（std→720p，pro→1080p），默认 std
        watermark_info:
          $ref: "#/components/schemas/KlingWatermarkInfo"
    KlingAvatarVideo:
      type: object
      properties:
        id:
          type: string
          description: 成片 ID（与任务 task_id 一致）
        url:
          type: string
          description: 成片下载地址（限时链接）
        duration:
          type: string
          description: 成片时长（秒）
    KlingAvatarResult:
      type: object
      properties:
        videos:
          type: array
          items:
            $ref: "#/components/schemas/KlingAvatarVideo"
    KlingAvatarData:
      type: object
      properties:
        task_id:
          type: string
          description: 网关任务 ID
        task_status:
          type: string
          enum: [submitted, processing, succeed, failed]
          description: 数字人状态；成功态为 succeed（注意与视频端点的 succeeded 不同）
        task_status_msg:
          type: string
        task_result:
          $ref: "#/components/schemas/KlingAvatarResult"
        created_at:
          type: integer
          format: int64
          description: Unix 毫秒时间戳
        updated_at:
          type: integer
          format: int64
          description: Unix 毫秒时间戳
    KlingAvatarResponse:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: SUCCEED
        request_id:
          type: string
        data:
          $ref: "#/components/schemas/KlingAvatarData"
    KlingVoiceRequest:
      type: object
      required: [voice_name]
      properties:
        voice_name:
          type: string
          description: 音色名称（必填，≤20 字符）
        voice_url:
          type: string
          description: 音源地址（.mp3/.wav/.mp4/.mov，建议 5-30 秒）
    KlingVoice:
      type: object
      properties:
        voice_id:
          type: string
          description: 复刻音色 ID，可用作数字人的 audio_id
        voice_name:
          type: string
        trial_url:
          type: string
          description: 试听地址（限时链接）
        owned_by:
          type: string
    KlingVoiceResult:
      type: object
      properties:
        voices:
          type: array
          items:
            $ref: "#/components/schemas/KlingVoice"
    KlingVoiceData:
      type: object
      properties:
        task_id:
          type: string
          description: 网关任务 ID
        task_status:
          type: string
          enum: [submitted, processing, succeed, failed]
          description: 声音复刻状态；成功态为 succeed（注意与视频端点的 succeeded 不同）
        task_status_msg:
          type: string
        task_result:
          $ref: "#/components/schemas/KlingVoiceResult"
        created_at:
          type: integer
          format: int64
          description: Unix 毫秒时间戳
        updated_at:
          type: integer
          format: int64
          description: Unix 毫秒时间戳
    KlingVoiceResponse:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: SUCCEED
        request_id:
          type: string
        data:
          $ref: "#/components/schemas/KlingVoiceData"
    KlingVoiceListResponse:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: SUCCEED
        request_id:
          type: string
        data:
          type: array
          items:
            $ref: "#/components/schemas/KlingVoiceData"
    KlingCustomElementImageRef:
      type: object
      properties:
        image_url:
          type: string
          description: 参考图 URL（.jpg/.jpeg/.png 或 Base64URL；≤10MB，短边 ≥300px，宽高比 1:2.5~2.5:1）
    KlingCustomElementImageList:
      type: object
      description: image_refer 主体的参考图集合（reference_type=image_refer 时必填）
      properties:
        frontal_image:
          type: string
          description: 一张正脸图 URL
        refer_images:
          type: array
          description: 1~3 张其他角度参考图
          items:
            $ref: "#/components/schemas/KlingCustomElementImageRef"
    KlingCustomElementVideoRef:
      type: object
      properties:
        video_url:
          type: string
          description: 参考视频 URL（MP4/MOV，3~8 秒，16:9 或 9:16，≤200MB）
    KlingCustomElementVideoList:
      type: object
      description: video_refer 主体的参考视频集合（reference_type=video_refer 时必填，至多 1 段）
      properties:
        refer_videos:
          type: array
          items:
            $ref: "#/components/schemas/KlingCustomElementVideoRef"
    KlingCustomElementTag:
      type: object
      properties:
        tag_id:
          type: string
          enum: [o_101, o_102, o_103, o_104, o_105, o_106, o_107, o_108]
          description: 主体标签 ID（枚举 o_101~o_108）
    KlingCustomElementCreateRequest:
      type: object
      required: [element_name, element_description, reference_type]
      properties:
        element_name:
          type: string
          description: 主体名称（必填，≤20 字符）
        element_description:
          type: string
          description: 主体描述（必填，≤100 字符）
        reference_type:
          type: string
          enum: [image_refer, video_refer]
          description: 参考类型；image_refer 用 element_image_list，video_refer 用 element_video_list
        element_image_list:
          $ref: "#/components/schemas/KlingCustomElementImageList"
        element_video_list:
          $ref: "#/components/schemas/KlingCustomElementVideoList"
        element_voice_id:
          type: string
          description: 绑定的音色 ID（仅 video_refer 主体可绑定，可选）
        tag_list:
          type: array
          description: 主体标签（可选）
          items:
            $ref: "#/components/schemas/KlingCustomElementTag"
    KlingCustomElementData:
      type: object
      properties:
        task_id:
          type: string
          description: 网关签名令牌（ace_ 开头，不透明；无状态地把查询路由回创建时的同一渠道，后续查询请原样使用，请勿自行拼接或改写）
        task_status:
          type: string
          enum: [submitted, processing, succeed, failed]
          description: 主体任务状态；成功态为 succeed
        task_status_msg:
          type: string
          description: 失败原因（若有）
        task_result:
          type: object
          description: |
            成功查询 / 预置列表时出现（创建 ack 省略）。含 elements[]，每项携带 element_id
            （可在 Omni / 动作控制中引用）与主体元数据（element_name / element_description /
            element_type / element_image_list / element_video_list / element_voice_info /
            tag_list 等）。注意：响应里主体类型字段为 element_type，而创建请求里是 reference_type。
        created_at:
          type: integer
          format: int64
          description: Unix 毫秒时间戳
        updated_at:
          type: integer
          format: int64
          description: Unix 毫秒时间戳
    KlingCustomElementResponse:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: SUCCEED
        request_id:
          type: string
        data:
          $ref: "#/components/schemas/KlingCustomElementData"
    KlingPresetElementsResponse:
      type: object
      properties:
        code:
          type: integer
          example: 0
        message:
          type: string
          example: SUCCEED
        request_id:
          type: string
        data:
          type: array
          items:
            $ref: "#/components/schemas/KlingCustomElementData"
    Wan3CreateRequest:
      type: object
      required: [model, input]
      description: DashScope 原生请求体（万相 3.0）
      properties:
        model:
          type: string
          enum: [wan3.0-video, wan3.0-video-prime]
          description: wan3.0-video 或 wan3.0-video-prime（两者调用方式完全相同）
        input:
          $ref: "#/components/schemas/Wan3Input"
        parameters:
          $ref: "#/components/schemas/Wan3Parameters"
    Wan3Input:
      type: object
      description: 输入信息；prompt 与 media 至少填其一
      properties:
        prompt:
          type: string
          description: 文本提示词，中英文均可，≤20000 字符；参考模式下可用「图1」「视频1」指代 media 素材
        media:
          type: array
          description: 媒体素材数组
          items:
            $ref: "#/components/schemas/Wan3MediaItem"
    Wan3MediaItem:
      type: object
      required: [type, url]
      properties:
        type:
          type: string
          enum: [first_frame, last_frame, reference_image, reference_video, reference_audio, file, link]
          description: 素材类型；first_frame/last_frame 与 reference_*/file/link 互斥，不可混用
        url:
          type: string
          description: 公网 URL / OSS 临时 URL（oss://...）/ Base64 data URI（data:{MIME};base64,{data}）
    Wan3Parameters:
      type: object
      description: 视频处理参数
      properties:
        resolution:
          type: string
          enum: [480P, 720P, 1080P]
          description: 输出分辨率，默认 1080P；传入其他档位返回 400 且不扣费
        ratio:
          type: string
          enum: [adaptive, "16:9", "4:3", "1:1", "3:4", "9:16"]
          description: 画面宽高比，默认 adaptive（跟随输入素材）；两个模型均不支持 21:9
        duration:
          type: integer
          minimum: 2
          maximum: 30
          description: 输出时长（秒），2–30 的明确整数；有视频输入时「输入 + 输出 ≤ 30」。不支持智能时长 -1
        audio:
          type: boolean
          description: 输出视频是否含音轨，默认 true（开关声音价格相同）
        prompt_extend:
          type: boolean
          description: 是否开启 prompt 智能改写，默认 true；短提示词效果提升明显但略增耗时
        seed:
          type: integer
          description: 随机种子，取值 [0, 2147483647]，用于复现结果
        watermark:
          type: boolean
          description: 是否添加水印标识，默认 false
    Wan3TaskCreated:
      type: object
      description: 创建任务响应（与百炼原生一致，仅返回任务 ID）
      properties:
        output:
          type: object
          properties:
            task_id:
              type: string
              description: 任务 ID，用于查询任务状态
            task_status:
              type: string
              enum: [PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED, UNKNOWN]
        request_id:
          type: string
    Wan3VideoTask:
      type: object
      properties:
        request_id:
          type: string
        output:
          type: object
          properties:
            task_id:
              type: string
            task_status:
              type: string
              enum: [PENDING, RUNNING, SUCCEEDED, FAILED, CANCELED, UNKNOWN]
            submit_time:
              type: string
              description: 任务提交时间
            scheduled_time:
              type: string
              description: 任务开始调度时间
            end_time:
              type: string
              description: 任务结束时间
            orig_prompt:
              type: string
              description: 原始提示词
            video_url:
              type: string
              description: 成片下载地址（临时链接，请尽快转存）
            code:
              type: string
              description: 任务失败错误码（task_status=FAILED 时回填）
            message:
              type: string
              description: 任务失败原因（task_status=FAILED 时回填）
        usage:
          $ref: "#/components/schemas/Wan3Usage"
    Wan3Usage:
      type: object
      description: 成功任务的用量统计
      properties:
        video_count:
          type: integer
          description: 生成视频数量
        duration:
          type: number
          description: 总计费时长（秒）
        input_video_duration:
          type: number
          description: 输入视频总时长（秒）
        output_video_duration:
          type: number
          description: 实际输出时长（秒），结算依据，向上取整到整秒计费
        fps:
          type: integer
          description: 输出帧率，固定 30
        SR:
          type: integer
          description: 输出分辨率（如 480 / 720 / 1080）
        ratio:
          type: string
          description: 实际输出宽高比
    Wan3ErrorResponse:
      type: object
      description: 百炼原生错误结构
      properties:
        code:
          type: string
          enum: [InvalidParameter, InvalidApiKey, AccessDenied, Throttling, InternalError]
          description: 错误码
        message:
          type: string
          description: 错误描述（末尾常带 request id）
        request_id:
          type: string
  responses:
    BadRequest:
      description: 请求参数无效或参数组合不受支持
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    Unauthorized:
      description: API Key 缺失或无效
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    RateLimited:
      description: 请求频率超出当前可用额度，请稍后重试
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    MinimaxError:
      description: MiniMax 原生错误结构（顶层 type=error）；400/401/402/422/429/500 共用此结构
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/MinimaxErrorResponse"
    Wan3Error:
      description: 百炼原生错误结构（400/401/403/404/429/5xx 共用）；参数 / 鉴权 / 审核失败不扣费，已预扣的失败任务自动退款
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Wan3ErrorResponse"