長影片連續性:Kling Video O1 的工作流與實踐
目標型號:
kling-video-o1
推理介面:https://api.toapis.com/v1/videos/generations
相關閱讀:Kling 3.0 Omni 多鏡頭指南 · Kling 3.0 Turbo 自動化指南 · Wan 3.0 影片 API 入門 · Wan 3.0 Prime 與 Wan 2.6 Flash 對比 · kling-video-o1 參考 · kling-video-o1 型號指南
1. TL;DR 與能力概覽
- 先核對目錄:規劃稿有時寫成
kling-3-omni。該字串不是 Kling Video O1 已文件化的公共 ID,也不能替代kling-v3-omni。2026-11-20 核對官方 O1 生成參考 與 型號指南頁面(HTTP 200),固定model值為kling-video-o1。 - 一次任務不是長片:文件化的
duration是 3–10 秒的整數(預設5)。規劃稿中的自迴歸記憶緩衝、previous_task_id、tail_frame_url、“最後 8 幀”或“6 次呼叫 = 30 秒”並未出現在公開合同中。更長的成片應拆成多次已文件化的請求,再自行拼接檔案。 - 連續性是參考素材問題:使用官方佔位符
<<<image_N>>>、<<<video_N>>>、<<<element_N>>>,配合metadata.image_list、video_list和metadata.element_list。列表順序必須與佔位符順序一致;系統不會自動插入佔位符,也不會自動補首幀。 - 呼叫約定:非同步提交到
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。選定一個源站並保持一致。 - 應丟棄的未核實說法:諸如
$0.030/s、$0.038/s的規劃稿單價,以及 SLA 或時延數字,都不是當前 ToAPIs 文件。請在賬戶目錄中確認實時價格。
2. 官方 O1 ID 與已文件化的連續性工具
在 model 欄位中使用公共型號名。不要替換成規劃稿別名、URL slug,或相關但不同的目錄 ID。
| 目錄 ID | 在本文中的角色 | 已文件化的能力 |
|---|---|---|
kling-video-o1 | 本文主角 ID | 文生影片,以及官方 Omni 引用:image_list、video_list、element_list |
kling-v3-omni | 相關 Omni ID;見 Day 17 多鏡頭指南 | 另一份已文件化的 Omni 合同——佔位符風格相近,但型號字串和時長視窗不同 |
kling-3.0-turbo | 短影片姊妹 ID;見 Turbo 指南 | 僅文生影片與首幀圖生影片——不是 Omni 引用合同 |
kling-video-o1 的核心請求欄位:
| 欄位 | 文件化取值 | 說明 |
|---|---|---|
prompt | 必填字串 | 用從 1 開始的佔位符引用素材 |
mode | std(預設)或 pro | std 對應 720P;pro 對應 1080P,同一標誌也決定計費解析度 |
duration | 3–10 的整數(預設 5) | 比 kling-v3-omni(3–15)更窄。以本生成參考為準,而不是更短的 Playground 預覽 |
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 | 可選字串 | 中文 O1 參考將其文件化為頂層欄位(也相容放在 metadata 下,推薦頂層)。之後可用 GET /v1/videos/generations/{client_business_id} 查詢 |
佔位符從 1 開始編號,且必須與列表順序對齊:
| 語法 | 引用物件 |
|---|---|
<<<image_1>>> | metadata.image_list 的第一項 |
<<<video_1>>> | video_list 的第一項(按中文參考,也是唯一一項) |
<<<element_1>>> | metadata.element_list 的第一項 |
英文生成頁用 <<<video_2>>> 說明列表語法。中文參考將 video_list 限制為 1 段,並補充素材規則:公開可訪問的 MP4 或 MOV、時長不少於 3 秒、解析度 720px–2160px、幀率 24–60fps、大小不超過 200MB。除非你的賬戶參考日後另有說明,否則不要傳送第二段參考影片。
一套仍落在該合同之內的實用長影片工作流:
- 按 3–10 秒分鏡。 每一拍寫一條提示詞。用
type: "first_frame"和type: "end_frame"鎖定開場與收束靜幀,並在提示詞中同時提到它們(從 <<<image_1>>> 過渡到 <<<image_2>>>)。 - 用
element_list錨定身份。 在相關任務中複用同一主體 URL 和穩定的role(例如"subject"),避免只改鏡頭描述時服裝、面孔或比例漂移。 - 用
refer_type: "feature"借用動作,或用refer_type: "base"編輯上一鏡。 讓<<<video_1>>>指向公開的動作參考,並要求<<<element_1>>>跟隨該動作。編輯源片段本身時使用base。當refer_type為base時,中文參考禁止定義首尾幀,要求源影片為 3–10 秒,並寫明生成時長以上傳影片為準。不要同時設定audio=true。 - 顯式串聯任務,再自行拼接。 任務狀態文件並不是 O1 專用的末幀或“繼續該任務”介面。
completed之後下載result.data[0].url(若狀態載荷中包含last_frame_url,可優先使用它),把靜幀或片段託管為公開 URL,再作為下一次的first_frame或video_url傳送。在自己的剪輯或 ffmpeg 流水線中拼接檔案。持久化每個任務 ID 和帶版本號的提示詞模板。

圖 1:每次已文件化的 O1 任務只返回一個片段。把完成結果中的靜幀或影片託管為公開 URL,在下一次請求中作為首幀或參考影片傳送,然後自行拼接檔案。
如果需要在 Day 17 型號上使用同類 Omni 列表,請改用 kling-v3-omni(時長 3–15 秒)。不需要 Omni 列表的高通量短影片草稿,請使用 kling-3.0-turbo。若希望在另一產品族上獲得更長的單次視窗,見 Wan 3.0 入門(文件為 2–30 秒,或 -1 智慧時長)。
3. 生產實現:cURL 與 Python
本系列的國際示例使用 https://api.toapis.com。官方文件要求中國大陸使用者使用 https://toapis.cn。每個環境只保留一個源站。路徑、型號 ID 和 Bearer 請求頭保持不變。
步驟 1:用 cURL 提交首尾幀分鏡
curl --request POST \
--url https://api.toapis.com/v1/videos/generations \
--header "Authorization: Bearer $TOAPIS_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "kling-video-o1",
"prompt": "Transition from <<<image_1>>> to <<<image_2>>>, keeping the same subject, lighting, and camera height as the streets empty at dusk",
"mode": "std",
"duration": 8,
"aspect_ratio": "16:9",
"client_business_id": "o1-episode-01-beat-03",
"metadata": {
"image_list": [
{"image_url": "https://example.com/beat-03-start.jpg", "type": "first_frame"},
{"image_url": "https://example.com/beat-03-end.jpg", "type": "end_frame"}
],
"element_list": [
{"url": "https://example.com/character.jpg", "type": "image", "role": "subject"}
]
}
}'
若希望主體列表真正參與生成,提示詞中也應寫上 <<<element_1>>>。輪詢之前先持久化返回的 id(或你的 client_business_id)。
步驟 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-video-o1"
DURATION_RANGE = range(3, 11)
def dispatch_o1(
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-video-o1; kling-3-omni and kling-v3-omni are not this model's 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 10")
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")
if video_list:
refer = video_list[0].get("refer_type", "base")
if refer == "base" and ("first_frame" in types or "end_frame" in types):
raise ValueError("refer_type=base cannot be combined with first_frame or end_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_o1(
"Keep <<<element_1>>> in frame while the camera moves from <<<image_1>>> to <<<image_2>>>",
duration=8,
image_list=[
{"image_url": "https://example.com/beat-03-start.jpg", "type": "first_frame"},
{"image_url": "https://example.com/beat-03-end.jpg", "type": "end_frame"},
],
element_list=[
{"url": "https://example.com/character.jpg", "type": "image", "role": "subject"},
],
client_business_id="o1-episode-01-beat-03",
)
print("Task:", task_id)
print("Video:", poll_task(task_id))
下載檔案後,把收束靜幀(或片段本身,若下一拍是 base 編輯)託管到公開 URL,再發起下一次 dispatch_o1。沒有已文件化的服務端拼接,也沒有讓 O1 指向前一個 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,或 base 與首尾幀混用 | 確認 kling-video-o1、佔位符順序與各列表一致、素材為公開 URL,且未組合互斥欄位 |
401 | 缺少或無效的 API Key | 在 ToAPIs 控制檯輪換金鑰,並確認 Authorization: Bearer 請求頭 |
429 | 速率或併發限制 | 如有 Retry-After 請遵守;加抖動退避;僅在安全時重試 |
5xx 或用戶端逾時 | 閘道器或上游暫時問題 | 先查詢已有任務 ID(或 client_business_id)再決定是否重提 |
status: queued 或 in_progress | 不是錯誤 | 等待並再次輪詢;不要為同一分鏡再建立第二個任務 |
status: failed | 生成未成功 | 讀取 error.code 與 error.message(若有 error.reason 也一併檢視)。不要原樣重試被策略拒絕的載荷 |
5. 定價與 FinOps
官方英文 O1 參考給出的是計費對映,而不是美元價表。先用它選擇 SKU 族,再讀取賬戶的實際報價。
| 請求形態 | 計費說明 |
|---|---|
mode=std、audio=false、無 video_list | 720P(std) |
mode=pro、audio=false、無 video_list | 1080P(pro) |
audio=true | 按 Sound 計費(且不能與 video_list 同時使用) |
請求包含 video_list | 按 Video 計費 |
2026-11-20 獲取的 kling-video-o1 型號指南頁面 顯示定價參考為 12 credits / 秒,並寫明最終計費以當前賬戶報價為準。該頁未公佈美元單價,也未把 Sound 或 Video 拆成單獨的美元或積分數字。不要自行把積分換算成貨幣,也不要沿用規劃稿中的 $0.030/s 或 $0.038/s。
- 先在
std下調參。 用 720P 和中等時長(例如 5 秒)迭代,保持帶版本的提示詞與靜幀包,每次只改一個參考列表,再考慮提升mode或把時長加到 10 秒。 - 長影片花費是成功片段之和,再加上你實際重新提交的失敗重試。用戶端逾時並不能證明該分鏡失敗——先查詢 ID,再決定是否重複提交。
- 展示價格不是渠道保證。 在預估整整合本之前,用
GET /v1/models?type=video和賬戶實時報價確認 ID、SKU 與可用性。
6. 常見問題
詳見 frontmatter 中的 FAQ。摘要:傳送 kling-video-o1,不要傳送 kling-3-omni 或 kling-v3-omni;沒有已文件化的 previous_task_id 或 tail_frame_url;時長為 3–10 秒;audio 與 video_list 不能同時使用;請自行串聯公開靜幀或片段,並持久化每個任務 ID。
7. 行動清單
- 在 ToAPIs 開發者門戶 建立金鑰。
- 透過
GET /v1/models?type=video確認當前金鑰能看到kling-video-o1——不要傳送kling-3-omni。 - 用帶首尾幀的
image_list、mode: "std"和duration: 5對 cURL 示例做冒煙測試。 - 以有界逾時輪詢
GET /v1/videos/generations/{id},在expires_at之前下載結果,並自行託管下一分鏡的公開靜幀或片段。 - 下一步:若需要 Day 17 的 Omni ID,參閱 Kling 3.0 Omni 多鏡頭指南;檢視 kling-video-o1 型號指南 瞭解實時目錄狀態;當單次請求需要超過 10 秒時,參閱 Wan 3.0 入門。







