kling-video-v3 API

## 参数详情 文字生成的prompt最多3072字符，建议不超过2500；图生视频的contents中prompt文本最多2500字符。 请求体使用JSON；下面的点号表示嵌套字段，例如 `settings.resolution` 写在 `settings` 对象中。 | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `model` | string | 是 | 目标视频型号；可选 kling-video-v3 | | `prompt` | string | 否 | V3／Turbo文生视频时填写；使用contents的场景在type=prompt中填写text。 | | `contents` | array | 否 | Omni必填；V3／Turbo图生时必填。图片／视频素材与文字提示词列表，字段规则见下方参数详情。 | | `contents[].type` | string | 是 | 按当前型号与场景选择；可选 prompt, first_frame, last_frame, element | | `contents[].text` | string | 否 | type=prompt时必填 | | `contents[].url` | string | 否 | 图／视频类型必填，公网HTTPS地址 | | `contents[].element_id` | string | 否 | type=element必填，已有有效主体ID | | `settings` | object | 否 | 3～15秒；720p、1080p、4k；文生视频画幅16:9、9:16、1:1。 | | `settings.resolution` | string | 否 | 输出清晰度；可选 720p, 1080p, 4k；默认 "720p" | | `settings.duration` | integer | 否 | 输出时长3～15整数秒；默认 5 | | `settings.aspect_ratio` | string | 否 | 文生／适用Omni场景使用；图生不传；可选 16:9, 9:16, 1:1；默认 "16:9" | | `settings.audio` | string | 否 | 受素材组合限制；可选 native, off；默认 "off" | | `settings.multi_shot` | boolean | 否 | 多镜头；受素材组合限制；默认 true | | `options` | object | 否 | 可选水印和外部业务标识。 | | `options.external_task_id` | string | 否 | 业务标识；本站查询仍使用返回id | | `options.watermark_info` | object | 否 | 水印选项 | | `options.watermark_info.enabled` | boolean | 否 | 是否开启水印 | | `wait` | boolean | 否 | false：提交后立即返回任务ID；true：等待一段时间后返回当前任务状态。；默认 false | | `nonce` | string | 否 | 新生成更换nonce；异常恢复沿用原值 | | `idempotency_key` | string | 否 | 兼容字段，不作为当前视频去重依据 | ## 查询与响应 `GET /v1/videos/generations/{id}` 查询单个任务。`GET /v1/videos/generations?limit=20&offset=0` 查看任务列表，返回 `data`、`total`、`limit`、`offset`。 pending / submitted / processing 表示进行中；succeeded 表示生成成功；failed / timeout / canceled 表示任务已结束。 | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `id` | string | 否 | 原样保存的查询任务ID | | `model` | string | 否 | 公开型号 | | `status` | string | 否 | 本站权威状态；可选 pending, submitted, processing, succeeded, failed, timeout, canceled, unknown | | `created_at` | integer | 否 | Unix秒 | | `error` | object | 否 | 成功通常null，失败可有code和message | | `error.code` | string | 否 | 错误码 | | `error.message` | string | 否 | 错误说明 | | `request_id` | string | 否 | 结果请求标识，不是任务ID | | `code` | integer | 否 | 模型结果业务码 | | `message` | string | 否 | 结果说明 | | `data` | array | 否 | 模型终态结果列表；需容忍兼容对象形状 | | `data[].id` | string | 否 | 任务标识 | | `data[].status` | string | 否 | 模型结果状态 | | `data[].message` | string | 否 | 任务说明 | | `data[].create_time` | integer | 否 | Unix毫秒 | | `data[].update_time` | integer | 否 | Unix毫秒 | | `data[].outputs` | array | 否 | 视频结果 | | `data[].outputs[].type` | string | 否 | video | | `data[].outputs[].id` | string | 否 | 输出标识，不是查询任务ID | | `data[].outputs[].url` | string | 否 | 临时视频URL，及时保存 | | `data[].outputs[].duration` | string | 否 | 输出秒数，可能带小数；兼容number | | `data[].usage` | object | 否 | 可选原生统计，缺失不等于0 | | `data[].usage.prompt_tokens` | integer | 否 | 原生输入Token；未提供时未知 | | `data[].usage.input_tokens` | integer | 否 | 可选原生输入别名，按实际字段保留 | | `data[].usage.completion_tokens` | integer | 否 | 原生输出Token；不跨口径补值 | | `data[].usage.output_tokens` | integer | 否 | 可选原生输出别名，按实际字段保留 | | `data[].usage.total_tokens` | integer | 否 | 原生总量，允许与官方计费总量不同，不再次收费 | | `tokenhub_usage` | object | 否 | 官方计费及对账口径；不叠加原生统计 | | `tokenhub_usage.total_tokens` | integer | 否 | 有效非负整数，包括明确0；实际费用采用的官方总量 | | `usage` | object | 否 | 兼容量，可能是官方量别名或原生统计，不能再次计费 | | `usage.prompt_tokens` | integer | 否 | 原生输入Token；未提供时未知 | | `usage.input_tokens` | integer | 否 | 可选原生输入别名，按实际字段保留 | | `usage.completion_tokens` | integer | 否 | 原生输出Token；不跨口径补值 | | `usage.output_tokens` | integer | 否 | 可选原生输出别名，按实际字段保留 | | `usage.total_tokens` | integer | 否 | 依字段来源判别，不能与tokenhub_usage重复累计 | 顶层 `usage.total_tokens` 表示该任务返回的总用量，可能包含参考视频输入；核对用量时不要只看输出时长。`tokenhub_usage`、`data`内部的原始用量及输入／输出细项仅在响应提供时出现；不同口径不相加，缺失不表示0。示例中的时间、标识、媒体和Token数字均为虚构数据。 ## 重试与新任务 请求结果不明确时，先查询原任务。需要标识一次提交时，可设置 `nonce` 或 `idempotency_key`；同一次提交重试沿用原值，新生成使用新值。保留返回的任务id与请求id，便于查询。 ## 常见错误 | HTTP状态 | 处理说明 | |---|---| | 400 | 参数、素材、计费模式或当前能力不支持 | | 401 | 令牌无效 | | 403 | 权限不足 | | 402 | 可用余额不足或预留失败 | | 404 | 查询任务不存在或无权访问 | | 409 | 原提交待确认，不换nonce | | 422 | 公共Schema或JSON校验失败 | | 429 | 请求受限，先核对原任务 | | 500 | 内部错误，受理状态须核对 | | 502 | 生成服务错误，受理状态须核对 | | 503 | 暂不可用，受理状态须核对 | 任务未结束时不支持取消。生成后使用返回的HTTPS地址获取视频。错误响应的通用结构见右侧400示例，具体字段以实际返回为准。 ## 图生视频 使用contents同时传入prompt与first_frame。图片使用自己的公网HTTPS地址；图生视频画幅跟随图片，不传aspect_ratio。 图片使用JPG／JPEG／PNG，单张最多50MB，宽高至少300px，画幅比1:2.5～2.5:1。首尾帧只使用首帧或首帧加尾帧，不单独使用尾帧；Turbo仅首帧。本文示例使用公网HTTPS素材地址。 ```json { "model": "kling-video-v3", "contents": [ { "type": "prompt", "text": "The paper boat moves slowly forward." }, { "type": "first_frame", "url": "https://media.example.com/first-frame.png" } ], "settings": { "duration": 3, "resolution": "720p", "audio": "off" }, "wait": false } ``` V3支持额外的last_frame和已有element，Turbo使用prompt与first_frame。V3的audio可用native或off，默认off；multi_shot默认true。Turbo不使用audio或multi_shot。 ## 官方参考 [官方调用指南](https://www.tencentcloud.com/zh/document/product/1300/83714) · [国际版指南](https://intl.cloud.tencent.com/zh/document/product/1300/83714) · [官方价格说明](https://www.tencentcloud.com/zh/document/product/1300/78937)

curl --request POST \
  'https://api.router.ai/v1/videos/generations' \
  -H "Authorization: Bearer $OPENCROW_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "model": "kling-video-v3",
  "prompt": "A small paper boat floats on a calm lake.",
  "settings": {
    "duration": 3,
    "resolution": "720p",
    "audio": "off"
  },
  "wait": false
}'