长视频连续性: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 入门。







