Kling 3.0 参数与错误
本页描述 Kling 3.0 系列在统一异步接口 POST /v1/video/tasks 中的公开契约。当前只支持 generation。
能力矩阵
| 模型 | 时长 | 画幅 | frame | images |
|---|---|---|---|---|
adobe-kling-3.0-720p | 3-15 秒整数 | 16:9、9:16 | 0-2 图 | 不支持 |
adobe-kling-3.0-1080p | 3-15 秒整数 | 16:9、9:16 | 0-2 图 | 不支持 |
adobe-kling-3.0-omni-720p | 3-15 秒整数 | 16:9、9:16 | 最多 2 图 | 最多 3 图 |
adobe-kling-3.0-omni-1080p | 3-15 秒整数 | 16:9、9:16 | 最多 2 图 | 最多 3 图 |
模型名中的 720p 和 1080p 是固定输出规格。传 output.resolution 会返回 400 invalid_video_parameter。
创建任务字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
model | string | 是 | 完整 Kling 公开模型名 |
operation | string | 是 | 固定为 generation |
input.prompt | string | 是 | 非空视频提示词，最多 1200 个 Unicode 字符 |
input.reference_mode | string | 否 | frame 或 Omni 使用的 images；默认 frame |
input.image | object | 否 | 第一张图片；frame 中表示首帧 |
input.reference_images | array | 否 | 追加图片；frame 中第二张为尾帧 |
output.duration | integer | 是 | 3-15 秒 |
output.aspect_ratio | string | 否 | 16:9 或 9:16，默认 16:9 |
output.generate_audio | boolean | 否 | 是否生成成片音轨，省略时默认 true |
client_reference_id | string | 否 | 调用方业务关联 ID，最长 191 字符 |
metadata | object | 否 | 随任务查询和 Webhook 原样返回 |
请求使用严格字段校验。字段拼写错误、未知字段、错误类型或不受支持的参数组合会直接返回 400。
参考图对象
{
"url": "https://media.example.com/reference.jpg",
"name": "character"
}| 项目 | 限制 |
|---|---|
url | 必须是绝对 HTTP/HTTPS URL |
name | 可选，最长 100 字符；非空名称在同一请求中必须唯一 |
| Base64 / Data URL | 不支持 |
| multipart | /v1/video/tasks 不支持 |
provider + file_id | 不支持 |
| 参考视频 / 音频 | 不支持 |
本地文件应先通过 POST /v1/media/uploads 获取对象存储直传地址，再将确认响应中的临时 HTTPS URL 放入参考图字段。文件字节不应放入任务 JSON。
图片顺序
frame 不传图片时为纯文本生成。传入图片时顺序如下：
input.image：首帧。input.reference_images[0]：尾帧。
Kling 3.0 和 Omni 都可以不传图片，也可以使用首帧或首尾帧。
Omni 的 images 使用 input.reference_images[]，最多三项。所有图片都是普通参考图，不具有首尾帧位置语义。
旧参数迁移
{
"input": {
"reference_mode": "frame"
},
"output": {
"generate_audio": true
}
}旧的 provider_options.*.generate_audio 和 provider_options.*.reference_mode 已停止兼容，必须分别改用 output.generate_audio 和 input.reference_mode。旧写法返回 400 invalid_provider_options。
以下字段同样不能通过 provider_options 覆盖：
modelpromptdurationaspect_ratioresolutionimagereference_imagesreference_videosreference_audiosvideo
这些字段由公开请求或模型规格控制，不能通过兼容参数覆盖。
按秒计费
启用视频按秒计费的模型在提交前按请求时长预扣：
费用额度 = 每秒价格 × output.duration × 当前有效分组倍率- 720p 与 1080p 是不同模型和价格绑定，不使用分辨率倍率。
- 图片数量、
frame/images模式和素材大小不增加计费秒数。 - 分组倍率来自 Token 所属分组或聚合分组，不在请求中单独设置。
- 是否允许订阅余额由模型定价策略决定；未开启时只使用钱包余额。
- 参数校验失败不会预扣；上游异步失败按平台现有任务规则退款。
实际每秒价格与资金来源以控制台当前配置为准。
成功结果
result.videos[] 中的重要字段：
| 字段 | 说明 |
|---|---|
asset_id | 资源管理中心中的视频资源 ID |
url | 视频地址 |
temporary | 固定表示该地址应视为临时资源 |
url_auth | none 或 resource_api_key |
duration_ms | 结果时长元数据；当前回显已验证的请求时长 |
结果为 temporary: true、url_auth: "none" 时，可以直接访问 URL，不附加 SuperToken Key。URL 可能自然过期，平台不保证刷新或归档。
当前不会下载结果媒体重新探测时长。duration_ms 只用于展示和审计，不参与二次补扣或退款。
常见错误
| HTTP 状态或错误码 | 原因 | 处理方式 |
|---|---|---|
400 invalid_request | JSON 无效、duration 不是整数、参考图数量超限，或 frame/images 传了视频或音频 | 修正字段类型、JSON 和参考素材 |
400 video_duration_required | 缺少 output.duration | 传 3-15 的整数 |
400 invalid_video_duration | 时长不在 3-15 秒 | 传 3-15 的整数 |
400 invalid_video_aspect_ratio | 画幅不是 16:9 或 9:16 | 改用支持的画幅 |
400 unsupported_reference_mode | Kling 3.0 使用 images，或任一 Kling 使用 media | 按能力矩阵选择模式 |
400 invalid_video_parameter | 提示词超过 1200 个字符、传了 output.resolution 或其他非法组合 | 缩短提示词并用完整模型名选择分辨率 |
400 invalid_provider_options | 命名空间、字段或类型无效 | 只使用公开的兼容选项 |
400 unsupported_video_operation | 使用 edit、extension 或 remix | 改为 generation |
400 unsupported_video_model | 模型未开放或模型映射错误 | 查询 /v1/models 并核对模型 |
409 idempotency_key_conflict | 同一个幂等 Key 对应不同请求 | 新请求使用新的 Key |
401 / 403 | Key 无效、停用或类型错误 | 创建使用 sk-...，查询使用 ak_... |
404 task_not_found | 任务不存在或不属于当前账号 | 核对任务 ID 和资源 Key |
参数类 400 不会创建任务，也不会产生预扣。任务进入 failed 后，读取 error.retryable 决定是否使用新的幂等 Key 创建有限重试。