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} 對兩者完全相同。

模型

所有模型都支持文生視頻和圖生視頻。高級特性因模型而異：

模型	多源參考1	4K	原生音頻2	多鏡頭
`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`	?（完整）	?	?	?

1 多源參考 = image_list / video_list 元數據字段。當出現這些字段時會被路由到 Kling 的 Omni-Video 上游端點。kling/kling-video-o1 是一個受限子集（只支持 5s / 10s，無多鏡頭，無音頻）；要使用完整 Omni 能力請選 kling/kling-v3-omni。 2 原生音頻 = 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

另見