Kling 视频 - OrcaRouter

OrcaRouter 原生对接 Kling 的视频生成。你提交任务、轮询任务 ID 直到状态完成，然后从上游拿到生成好的 MP4（通常 30 - 90 秒完成）。这种异步”提交-轮询”模式是视频独有的。Chat / 图像 / TTS 都是同步请求-响应；Kling 视频不是。

提交端点 POST /v1/video/generations 在多个视频服务商之间共用—— 请求体形态由 model 前缀选择。本页面针对 model: kling/...。对 ByteDance Seedance 模型请使用 model: byteplus/...，并参阅 Seedance 视频。获取端点 GET /v1/video/generations/{task_id} 对两者完全相同。

模型

所有模型都支持文生视频和图生视频。高级特性因模型而异：

模型	多源参考¹	4K	原生音频²	多镜头
`kling/kling-v2-master`
`kling/kling-v2-1-master`
`kling/kling-v2-5-turbo`
`kling/kling-v2-6`			pro 模式
`kling/kling-v3`		✓	✓	✓
`kling/kling-video-o1`	✓（受限）
`kling/kling-v3-omni`	✓（完整）	✓	✓	✓

¹ 多源参考 = image_list / video_list 元数据字段。当出现这些字段时会被路由到 Kling 的 Omni-Video 上游端点。kling/kling-video-o1 是一个受限子集（只支持 5s / 10s，无多镜头，无音频）；要使用完整 Omni 能力请选 kling/kling-v3-omni。 ² 原生音频 = Kling 自动生成与视频匹配的配乐。上游另行计费。通过 metadata.sound: "on" 开启。所有模型的提交端点都是 POST /v1/video/generations。变化的是上游按上表认可哪些 metadata 字段。

提交任务

向 /v1/video/generations 发 POST，携带 model、prompt 和上游特定的参数（放在 metadata 下）：

curl https://api.orcarouter.ai/v1/video/generations \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v3-omni",
    "prompt": "cat playing piano in a sunny room",
    "metadata": {
      "mode": "std",
      "aspect_ratio": "16:9",
      "duration": "5"
    }
  }'

响应携带任务 ID：

{
  "id": "task_9q9oz6tjtgABYWC1QIqoz3sscgVz7ycw",
  "task_id": "task_9q9oz6tjtgABYWC1QIqoz3sscgVz7ycw",
  "object": "video",
  "model": "kling/kling-v3-omni",
  "status": "queued",
  "progress": 0,
  "created_at": 1777975188
}

POST 返回的 status 是小写的 "queued"。GET 返回的是包裹后的信封，其中状态是大写（SUBMITTED / IN_PROGRESS / SUCCESS / FAILURE） ——见下方”轮询结果”。

通用 metadata 字段

这三个对每种端点变体都有效：

字段	类型	说明
`mode`	string	`std`（720P）/ `pro`（1080P）/ `4k`。`4k` 仅在 `kling/kling-v3` 和 `kling/kling-v3-omni` 可用。文生/图生视频默认 `std`，Omni-Video 默认 `pro`。
`aspect_ratio`	string	`16:9` / `9:16` / `1:1`。Omni-Video 必填，除非你提供首帧参考或 `video_list`（此时可由输入推断）。
`duration`	string	时长（秒）。默认 `"5"`。`kling/kling-v3-omni` 和 `kling/kling-v3` 接受 `"3"` 到 `"15"`。v2 系列（`v2-master`、`v2-1-master`、`v2-5-turbo`、`v2-6`）和 `kling/kling-video-o1` 接受 `"5"` 或 `"10"`。各模型权威范围请见 Kling 能力表。

这两个只对文生视频和图生视频有效（不对 Omni-Video）：

字段	类型	说明
`negative_prompt`	string	要避免的元素。最多 2500 字符。
`cfg_scale`	float	范围 `[0, 1]`，默认 `0.5`。越大越严格遵循 prompt。v2.x 模型不支持（`kling-v2-master` / `v2-1-master` / `v2-5-turbo` / `v2-6`）。

轮询结果

使用提交时返回的任务 ID：

curl https://api.orcarouter.ai/v1/video/generations/task_9q9oz6tjtgABYWC1QIqoz3sscgVz7ycw \
  -H "Authorization: Bearer sk-orca-..."

响应形态是包裹后的：

{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_9q9oz6tjtgABYWC1QIqoz3sscgVz7ycw",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://v16-kling-fdl.klingai.com/.../video.mp4?...",
    "action": "omniVideo",
    "submit_time": 1777975188,
    "start_time": 1777975241,
    "finish_time": 1777975277,
    "fail_reason": ""
  }
}

状态值（大写，原始任务状态）：

状态	含义
`NOT_START`	任务行已创建，尚未派发（瞬态，通常不到 2 秒）
`SUBMITTED`	已发送给 Kling 上游，在其队列中等待
`IN_PROGRESS`	Kling 正在渲染
`SUCCESS`	完成。`data.result_url` 携带 MP4
`FAILURE`	失败。`data.fail_reason` 给出原因

进度以百分比字符串返回（"30%"、"100%"），不是整数。每 5 - 10 秒轮询一次。典型的 std 5 秒短片在 30 - 60 秒内完成； 4K、15 秒以及多镜头任务需要 2 - 5 分钟。 data.result_url 是 Kling 签名 URL（注意 ksTime / ksSecret 查询参数）。如果你需要长期保留，请尽快下载或转存——签名有上游设定的过期时间。

端点变体

三种变体共用 POST /v1/video/generations。Kling 实际承接的端点由你提供的字段决定。

文生视频

只要 model + prompt（+ 可选的上述 metadata）。没有图像输入即为文生视频：

curl https://api.orcarouter.ai/v1/video/generations \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v2-6",
    "prompt": "ocean waves at sunset, cinematic",
    "metadata": {"mode": "pro", "duration": "5"}
  }'

图生视频

加上顶层 image（首帧）和/或 metadata.image_tail（尾帧）来做首/尾帧 i2v：

curl https://api.orcarouter.ai/v1/video/generations \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v2-master",
    "prompt": "the cat starts dancing",
    "image": "https://example.com/cat.png",
    "metadata": {"mode": "std", "duration": "5"}
  }'

多源参考（Omni-Video）

image_list 和 video_list 会把请求路由到 Kling 的 Omni-Video 端点。仅在 kling/kling-video-o1 和 kling/kling-v3-omni 上可用。 image_list —— 多图参考：

{ "image_list": [{ "image_url": "...", "type": "first_frame" }] }

image_url（必填）：URL 或裸 base64（不带 data: 前缀）。
type（可选）：first_frame / end_frame。除非该图像被当作帧锚点使用，否则可省略。不支持只给 end-frame（必须同时配一张 first-frame 图）。

video_list —— 视频参考（最多 1 个视频，MP4/MOV，≤200MB）：

{ "video_list": [{ "video_url": "...", "refer_type": "base", "keep_original_sound": "yes" }] }

refer_type：base（视频编辑——输入视频会被编辑；默认）或 feature（风格/构图参考——生成下一/上一镜头）。
keep_original_sound：yes / no。
在 kling/kling-v3-omni 上，视频参考只支持 3-10s 时长、std/pro 模式（不支持 4K）。

当 video_list 被设置时，metadata.sound 必须为 "off"——否则 Kling 会拒绝该组合。

在 prompt 中用 <<<>>> 语法引用图像 / 视频 / 元素： <<<image_1>>>、<<<video_1>>>、<<<element_1>>>。仅限 Omni。索引按数组顺序（1 起）。

curl https://api.orcarouter.ai/v1/video/generations \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling/kling-v3-omni",
    "prompt": "<<<image_1>>> waves at the camera, then walks toward the ocean",
    "metadata": {
      "image_list": [{"image_url": "https://example.com/person.jpg"}],
      "mode": "pro",
      "aspect_ratio": "16:9",
      "duration": "5",
      "sound": "on"
    }
  }'

高级特性

下列特性在文生视频、图生视频和 Omni-Video 端点上都可用——具体模型支持情况不同。通过 metadata 传入。

多镜头

生成由多个顺序镜头组成的视频，每个镜头有自己的 prompt 和时长。可用于 kling/kling-v3 和 kling/kling-v3-omni。

字段	类型	用途
`multi_shot`	bool	设为 `true` 启用。顶层 `prompt` 和首/尾帧输入会被忽略。
`shot_type`	string	`customize`（按 `multi_prompt` 字面值）或 `intelligence`（Kling 自动分段）。`multi_shot=true` 时必填。
`multi_prompt`	array	`[{index, prompt, duration}]`。1 - 6 个分镜。每个镜头的 `duration` ≥ 1s；合计必须等于任务总 `duration`。每个 `prompt` ≤ 512 字符。

原生音频

Kling 自动生成与视频匹配的配乐。上游另行计费。通过 metadata.sound: "on"（默认 "off"）切换。模型支持：

kling/kling-v3 和 kling/kling-v3-omni：任意模式（std / pro / 4K）
kling/kling-v2-6：仅 pro 模式
其他模型：不支持

水印

传 metadata.watermark_info: {enabled: true} 在生成视频上打上 Kling 的水印。默认无水印。

计费

Kling 视频按任务计费。OrcaRouter 收取的就是 Kling 收取的——上游的 final_unit_deduction 就是钱包扣款值，零加价。最终成本与 Kling 公布的费率表一致。提交时会预留一小笔预消费冻结，按你请求中可能的最高成本（如 4K + 音频）估算；任务成功后差额立即退回。具体每个任务的花费请查看控制台的钱包历史。

直接使用 Kling SDK

如果你已经基于 Kling 官方 SDK 写好了代码，OrcaRouter 也支持 Kling 原生协议 /kling/v1/videos/...。请求体字段保持平铺（model_name、mode 等）——只有 base URL、Authorization 头和 model_name 的值会变：

curl https://api.orcarouter.ai/kling/v1/videos/omni-video \
  -H "Authorization: Bearer sk-orca-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "kling/kling-v3-omni",
    "prompt": "cat playing piano",
    "mode": "pro",
    "aspect_ratio": "16:9",
    "duration": "5",
    "sound": "on"
  }'

model_name 必须用 OrcaRouter 侧的模型身份（即你在 /v1/video/generations 上用的同一名字），而不是 Kling 的裸模型名。 OrcaRouter 会通过该通道的 model_mapping 解析后再转发给 Kling。

对应的获取路径是 GET /kling/v1/videos/omni-video/{task_id}（或 text2video、image2video）。挑与你现有代码相匹配的协议形态即可。计费完全相同。

另见

API 参考 / Video — 完整 schema 与在线调试（从请求体 schema 下拉中挑选 Kling video request 变体）
Seedance 视频 — 同一端点，使用 Seedance 1.0 / 1.5 / 2.0 模型，请求体形态为 content[]
运维 / 计费与用量
运维 / 错误

​模型

​提交任务

​通用 metadata 字段

​轮询结果

​端点变体

​文生视频

​图生视频

​多源参考（Omni-Video）

​高级特性

​多镜头

​原生音频

​水印

​计费

​直接使用 Kling SDK

​另见

模型

提交任务

通用 metadata 字段

轮询结果

端点变体

文生视频

图生视频

多源参考（Omni-Video）

高级特性

多镜头

原生音频

水印

计费

直接使用 Kling SDK

另见