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 指南。







