Kling 3.0 Omni API 深挖:多鏡頭影片生成與物理連貫性
目標型號:
kling-v3-omni
推理介面:https://api.toapis.com/v1/videos/generations
相關閱讀:Kling 3.0 Turbo 自動化指南 · Kling V4 Flash API 指南 · kling-v3-omni 參考 · kling-v3-omni 型號指南
1. 核心摘要與性能速覽 (TL;DR)
- 先看目錄:規劃稿有時會寫成
kling-3-omni。該字串不是已文件化的公共型號。2026-11-18 檢查官方生成參考和 型號指南頁面(HTTP 200),列出的固定model值是kling-v3-omni。請傳送這一精確字串。 - 約定:向
POST /v1/videos/generations非同步提交,再輪詢GET /v1/videos/generations/{id},直到completed或failed。普通任務也可用GET /v1/tasks/{id}查詢。官方示例使用https://toapis.com(中國大陸使用https://toapis.cn)。本系列其他指南使用https://api.toapis.com。請選定一個源站並保持一致。 - 沒有
shots[]欄位:多鏡頭連貫與物理一致性,是提示詞加引用素材的問題。請使用官方佔位符<<<image_N>>>、<<<video_N>>>、<<<element_N>>>,配合metadata.image_list、video_list和metadata.element_list。列表順序必須與佔位符順序一致;系統不會自動插入佔位符,也不會自動補首幀。 - 媒體:只傳送可公開訪問的
http://或https://URL。本地檔案先透過POST /v1/uploads/images上傳,並使用返回的 URL。不要傳送 base64。audio與video_list互斥。 - 應丟棄的未核實表述:規劃稿裡的
$0.022/s一類單價、99.95% SLA,或自定義shots結構,都不是目前 ToAPIs 文件內容。請在帳戶中確認實時費率和渠道是否開放。
2. 官方 Omni 型號、佔位符與連貫工作流
在 model 欄位中使用公共型號名。不要替換成規劃稿別名、URL slug,或相關但不同的目錄 ID。
| 目錄型號 | 在本文中的角色 | 文件化任務 |
|---|---|---|
kling-v3-omni | 本文主型號 | 文生影片,以及官方 Omni 引用:image_list、video_list、element_list |
kling-3.0-turbo | 姊妹短影片型號;見 Turbo 指南 | 僅文生影片與首幀圖生影片——不是 Omni 引用約定 |
kling-v3 | 相關的非 Omni v3 型號 | 另有獨立生成參考。除非其自身文件說明,否則不要向該 ID 傳送 Omni 列表或佔位符 |
kling-v3-omni 的核心請求欄位:
| 欄位 | 文件化取值 | 說明 |
|---|---|---|
prompt | 必填字串 | 用從 1 開始的佔位符引用素材 |
mode | std(預設)或 pro | std 對應 720P,pro 對應 1080P,同一標誌也決定計費解析度 |
duration | 整數 3–15(預設 5) | 不限於 5 秒或 10 秒 |
aspect_ratio | 常用值 16:9(預設)、9:16、1:1 | 若行銷參數表更短,以生成參考為準 |
audio | 布林值,預設 false | true 按 Sound 計費;與 video_list 不相容 |
video_list | 最多 1 段 | 按 Video 計費。refer_type:base 或 feature。keep_original_sound:yes 或 no |
metadata.image_list | 公開的 image_url | 可選 type 為 first_frame 或 end_frame;傳 end_frame 時必須同時提供 first_frame |
metadata.element_list | 主體或角色資產 | url,以及可選的 type(例如 image 或 video)和 role |
watermark | 布林值 | 僅開關 |
client_business_id | 可選字串 | 中文 Omni 參考將其文件化為頂層欄位(也相容放在 metadata 中,但推薦頂層)。後續可用 GET /v1/videos/generations/{client_business_id} 查詢 |
佔位符從 1 開始編號,必須與列表順序保持一致:
| 語法 | 引用物件 |
|---|---|
<<<image_1>>> | metadata.image_list 的第 1 項 |
<<<video_1>>> | video_list 的第 1 項(按中文參考,也是唯一項) |
<<<element_1>>> | metadata.element_list 的第 1 項 |
英文生成頁面用 <<<video_2>>> 示範列表語法。中文參考將 video_list 限制為 1 段。除非你的帳戶參考日後另有說明,否則不要傳送第二段參考影片。
仍然可以用文件化欄位構建多鏡頭、物理上更連貫的片段:
- 用首尾幀鎖定鏡頭弧線。 將開場靜幀放入
image_list並設type: "first_frame",將結束靜幀設為type: "end_frame"。在 prompt 中同時引用兩者(例如从<<<image_1>>>过渡到<<<image_2>>>),並寫明兩者之間的運動、重力和運鏡。 - 用
element_list錨定身份。 在相關任務中複用同一主體 URL 和穩定的role(例如"subject"),避免只改鏡頭描述時服裝、面孔或比例漂移。 - 用
refer_type: "feature"借用動作。 讓<<<video_1>>>指向可公開訪問的動作參考,並要求<<<element_1>>>跟隨該動作。若是編輯源影片本身(例如替換背景),使用refer_type: "base"。 - 顯式串聯任務。 狀態文件並不是 Omni 專用的尾幀介面。若後一鏡必須接上一次結果,請把該次成片或你控制的靜幀託管為公開 URL,作為下一請求的
first_frame。請持久化每個任務 id。

圖 1:僅含公開 URL 的 image_list、video_list 與 element_list 提交到 POST /v1/videos/generations;輪詢同一任務 id,僅在 status 為 completed 後讀取 result.data[0].url。
若只需要不依賴 Omni 列表的高頻短影片草稿,請使用 kling-3.0-turbo。若需要另一套 Kling 生成約定,參見 Kling V4 Flash 指南。
3. 生產級實作:cURL 與 Python
本系列的國際示例使用 https://api.toapis.com。官方文件要求中國大陸使用者使用 https://toapis.cn。請在同一環境中固定一個源站。路徑、型號 ID 和 Bearer 請求頭保持不變。
步驟 1:用 cURL 提交首尾幀任務
curl -X POST "https://api.toapis.com/v1/videos/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "kling-v3-omni",
"prompt": "Transition from <<<image_1>>> to <<<image_2>>>, keeping gravity, footsteps, and camera height consistent",
"mode": "std",
"duration": 5,
"aspect_ratio": "16:9",
"metadata": {
"image_list": [
{"image_url": "https://example.com/start.jpg", "type": "first_frame"},
{"image_url": "https://example.com/end.jpg", "type": "end_frame"}
]
}
}'
純文字任務可省略 metadata 和佔位符。主體加動作參考的任務應使用 refer_type: "feature" 的 video_list 以及 metadata.element_list,並且不能同時設定 audio: true。
步驟 2:Python 輔助函式與輪詢器
下面的片段遵循已文件化的任務狀態路徑,以及 queued / in_progress / completed / failed 狀態。上線前請對照你帳戶可見的 API 參考,確認 id、result.data[0].url 和響應結構。
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/videos/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
DOCUMENTED_ID = "kling-v3-omni"
DURATION_RANGE = range(3, 16)
def dispatch_omni(
prompt: str,
*,
model: str = DOCUMENTED_ID,
mode: str = "std",
duration: int = 5,
aspect_ratio: str = "16:9",
audio: bool = False,
image_list: list[dict] | None = None,
element_list: list[dict] | None = None,
video_list: list[dict] | None = None,
client_business_id: str | None = None,
) -> str:
if model != DOCUMENTED_ID:
raise ValueError("Send kling-v3-omni; kling-3-omni is not a documented public ID")
if mode not in {"std", "pro"}:
raise ValueError("mode must be std or pro")
if duration not in DURATION_RANGE:
raise ValueError("duration must be an integer from 3 to 15")
if audio and video_list:
raise ValueError("audio and video_list are mutually exclusive")
if video_list and len(video_list) > 1:
raise ValueError("video_list is documented as at most one clip")
types = [item.get("type") for item in (image_list or [])]
if "end_frame" in types and "first_frame" not in types:
raise ValueError("end_frame requires first_frame")
payload = {
"model": model,
"prompt": prompt,
"mode": mode,
"duration": duration,
"aspect_ratio": aspect_ratio,
}
if audio:
payload["audio"] = True
if video_list:
payload["video_list"] = video_list
metadata = {}
if image_list:
metadata["image_list"] = image_list
if element_list:
metadata["element_list"] = element_list
if metadata:
payload["metadata"] = metadata
if client_business_id:
payload["client_business_id"] = client_business_id
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_task(task_id: str, deadline_s: int = 600) -> str:
poll_url = f"{BASE}/v1/videos/generations/{task_id}"
interval = 10.0
start = time.time()
time.sleep(5)
while time.time() - start < deadline_s:
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 120))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
time.sleep(interval)
interval = min(interval * 1.5, 30.0)
raise TimeoutError(f"Task {task_id} exceeded {deadline_s}s; check status before retrying")
if __name__ == "__main__":
task_id = dispatch_omni(
"Transition from <<<image_1>>> to <<<image_2>>>, keeping gravity, footsteps, and camera height consistent",
image_list=[
{"image_url": "https://example.com/start.jpg", "type": "first_frame"},
{"image_url": "https://example.com/end.jpg", "type": "end_frame"},
],
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
請把提示詞模板版本與任務記錄放在一起,以便區分佔位符或列表順序的改動與措辭改動。在 expires_at 之前下載檔案;狀態參考寫明保留視窗為 30 天。
4. 錯誤處理與狀態碼對照
下表是排查起點,並不保證與 ToAPIs 的精確錯誤碼一一對應。HTTP 查詢成功後,仍須讀取任務 status。請求錯誤與 status: failed 的原因(例如 content_policy_rejected、insufficient_user_balance 或 generation_timeout)見 錯誤參考。
| HTTP 或任務狀態 | 常見類別 | 建議操作 |
|---|---|---|
400 | 欄位無效、佔位符與列表不一致、同時傳了 audio 與 video_list,或有 end_frame 卻無 first_frame | 確認型號為 kling-v3-omni,佔位符順序與各列表一致,媒體為公開 URL,且互斥欄位沒有同時出現 |
401 | 缺少或無效的 API Key | 在 ToAPIs 控制檯輪換金鑰,並確認 Authorization: Bearer 請求頭 |
429 | 速率或併發限制 | 若存在 Retry-After 請遵守;加抖動退避;僅在安全時重試 |
5xx 或用戶端逾時 | 閘道器或上游暫時異常 | 先查詢已有任務 id,再決定是否重新提交 |
status: queued 或 in_progress | 不是錯誤 | 繼續等待並輪詢;不要建立第二個任務 |
status: failed | 生成未成功 | 讀取 error.code 與 error.message(若有 error.reason 一併檢視)。不要對未修改的策略拒絕載荷直接重試 |
5. 定價與 FinOps ROI
官方中文 Omni 參考提供了計費對應。先用它選擇規格族,再讀取帳戶實際報價。
| 請求形態 | 計費規格 |
|---|---|
mode=std,audio=false,無 video_list | 720P |
mode=pro,audio=false,無 video_list | 1080P |
mode=std,audio=true | 720P+Sound |
mode=pro,audio=true | 1080P+Sound |
mode=std,有 video_list | 720P+Video |
mode=pro,有 video_list | 1080P+Video |
2026-11-18 獲取的 kling-v3-omni 型號指南頁面 給出的定價參考是 12 積分 / 秒,並寫明最終計費以帳戶目前報價為準。該頁沒有公佈 Omni 的美元每秒單價,也沒有把 Sound 或 Video 拆成單獨的美元數字。請不要自行把積分換算成貨幣,也不要沿用規劃稿中的 $0.022/s 一類費率。
- 先在較便宜的文件化模式下打樣。 用
std(720P)和中等時長(例如 5 秒)迭代,保留帶版本的提示詞模板,一次只改一個引用列表。 - 展示價格不等於渠道保證。 預測鏡頭成本前,請用
GET /v1/models?type=video以及帳戶中的實時報價確認 ID、規格和可用性。 - 在提示詞層控制支出:用戶端逾時後,先查任務狀態再決定是否重提。官方供應商合同常有承諾期或預付門檻;ToAPIs 計費通常是按量付費——請以帳戶目前條款為準。
6. 常見問題
詳見 frontmatter 中的 FAQ。摘要:傳送 kling-v3-omni,不要傳送 kling-3-omni;沒有已文件化的 shots[] 欄位;時長為 3–15 秒,mode 選擇 720P 或 1080P;audio 與 video_list 不能同時使用;始終輪詢 generations 狀態路徑並持久化任務 id。
7. 行動清單
- 在 ToAPIs 開發者門戶 建立金鑰。
- 透過
GET /v1/models?type=video確認你的金鑰能看到kling-v3-omni——不要傳送kling-3-omni。 - 用帶首尾幀的
image_list、mode: "std"和duration: 5冒煙測試上文 cURL 示例。 - 在有上限的時限內輪詢
GET /v1/videos/generations/{id},並在expires_at之前下載結果。 - 接下來:需要高頻短影片草稿時閱讀 Kling 3.0 Turbo 自動化指南,檢視 kling-v3-omni 型號指南 瞭解目錄現狀,若需要另一套 Kling 約定則參考 Kling V4 Flash 指南。







