Photoreal indoor roller-derby footage on a teal track. One adult skater in a mustard jersey, black helmet and protective pads takes a tight left curve on quad skates. Knees bent, center of gravity low, wheels contacting the floor as weight shifts naturally. Low camera tracks smoothly alongside. Empty stands, overhead arena lights and realistic motion blur. Complete one clear turn without falling. No text, logos or watermarks.
Kling O3 Pro Text to Video API
kwaivgi/kling-video-o3-pro/text-to-videoKling O3 Pro 文生视频:通过文本提示词生成 3–15 秒视频。支持单镜头和多镜头;sound 必须显式传入,多镜头必须开启声音。
多镜头必须开启声音。表单自动按分镜总时长填写 duration。
Duration: 5 秒 (3-15)
示例
REST API 规格
快速上手
提交任务并查询其状态。
第一步:配置身份鉴权
在控制台申请 API Key,并在发起请求时通过请求头携带 Authorization: Bearer <API_KEY>。
- 任务提交端点
- POST
https://api.vidgo.ai/api/generate/submit - 鉴权请求头
- Authorization: Bearer VIDGO_API_KEY
第二步:提交生成任务
POST /api/generate/submit,指定模型 kwaivgi/kling-video-o3-pro/text-to-video。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "kwaivgi/kling-video-o3-pro/text-to-video",
"input": {
"duration": 5,
"sound": true,
"multi_shots": true,
"multi_prompt": [
{
"prompt": "Cinematic whimsical realism in a warm oak library. Medium two-shot: a small ivory robot with an oval face and amber eyes shelves a blue book, accidentally knocking one red book onto the floor. Beside it, an adult librarian wears a green cardigan and round glasses. Both remain visible under warm reading lamps. One distinct book thud against quiet room tone. Unmarked book covers. No text, logos or watermarks.",
"duration": 2
},
{
"prompt": "Cut closer to the same ivory robot and green-cardigan librarian in the same oak library. The librarian raises one finger to her lips. The robot tilts its head apologetically and softly says exactly \"Sorry.\" in a gentle robotic voice, synchronized with its small mouth light. Preserve their appearance, positions and warm lighting. End in an embarrassed pause; no music. No text, logos or watermarks.",
"duration": 3
}
],
"aspect_ratio": "16:9"
}
}
JSON
)
RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
printf 'API error: %s
' "$RESPONSE" >&2
exit 1
fi
printf '%s
' "$RESPONSE"第三步:轮询任务执行结果
使用 task_id 查询进度;not_started 或 running 时继续轮询,finished 或 failed 时停止。成功后读取 data.files[].file_url,失败时读取 data.error_message。
状态查询端点
GET https://api.vidgo.ai/api/generate/status/{task_id}使用 task_id 查询进度;not_started 或 running 时继续轮询,finished 或 failed 时停止。成功后读取 data.files[].file_url,失败时读取 data.error_message。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "task-submitted-example",
"status": "not_started",
"created_time": "2026-09-22T00:00:00Z"
}
}{
"code": 200,
"data": {
"task_id": "BRDSCRKN4Q0WH4T6",
"status": "finished",
"files": [
{
"file_type": "video",
"file_url": "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-video-o3-pro/text-to-video/v1/01/output.mp4"
}
],
"created_time": "2026-09-22T18:43:52",
"error_message": null,
"progress": 100
}
}端到端完整脚本示例
展开查看在生产环境中具备轮询重试、异常保护和超时处理的完整自动化脚本。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "kwaivgi/kling-video-o3-pro/text-to-video",
"input": {
"duration": 5,
"sound": true,
"multi_shots": true,
"multi_prompt": [
{
"prompt": "Cinematic whimsical realism in a warm oak library. Medium two-shot: a small ivory robot with an oval face and amber eyes shelves a blue book, accidentally knocking one red book onto the floor. Beside it, an adult librarian wears a green cardigan and round glasses. Both remain visible under warm reading lamps. One distinct book thud against quiet room tone. Unmarked book covers. No text, logos or watermarks.",
"duration": 2
},
{
"prompt": "Cut closer to the same ivory robot and green-cardigan librarian in the same oak library. The librarian raises one finger to her lips. The robot tilts its head apologetically and softly says exactly \"Sorry.\" in a gentle robotic voice, synchronized with its small mouth light. Preserve their appearance, positions and warm lighting. End in an embarrassed pause; no music. No text, logos or watermarks.",
"duration": 3
}
],
"aspect_ratio": "16:9"
}
}
JSON
)
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
--request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data "$REQUEST_BODY")
TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
printf 'Timed out after 600 seconds
' >&2
exit 1
fi
STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
--url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
--header "Authorization: Bearer $VIDGO_API_KEY")
STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
exit 1
fi
case "$STATUS" in
finished)
printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
break
;;
failed)
printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
exit 1
;;
not_started|running)
sleep "$POLL_DELAY"
if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
done请求参数(input 对象)
生成参数放在 input 中。建议使用标准 JSON 数字和布尔值。兼容 "5" 这样的整数字符串。布尔字符串 true/1/yes/y/on 表示 true,false/0/no/n/off 表示 false,不区分大小写并忽略首尾空白;布尔字段也接受数值 1 和 0。提示词中的数字和布尔值会转为文本,0、false 和 null 按空值处理;对象和数组不能作为提示词。 提示词的 API 校验上限为 2,500 字符。部分多镜头生成请求曾因单段提示词超过 512 字符而失败,建议每段控制在 512 字符以内;这项建议不改变 API 校验上限。
| 字段 | 类型 | 必填 | 默认值 | 描述 |
|---|---|---|---|---|
| prompt | string | 条件必填 | - | multi_shots=false 时必填,描述场景、动作和镜头运动。去除首尾空白后须为非空文本,最多 2,500 字符。multi_shots=true 时请省略 prompt。 |
| multi_shots | boolean | 是 | - | 必填,必须显式传入 false(单镜头)或 true(多镜头)。单镜头需要 prompt;多镜头需要 multi_prompt 和 sound=true,且顶层 prompt 不得为非空文本。省略此字段会报错。 |
| multi_prompt | array | 条件必填 | - | multi_shots=true 时必填,单镜头模式请省略。至少提供一个分镜,每段包含非空 prompt(最多 2,500 字符)和整数 duration(1–12 秒)。分镜时长之和必须等于顶层 duration(3–15 秒)。分镜内的额外字段会被忽略。 |
| duration | integer | 是 | - | 必填,3–15 秒的整数。多镜头模式下必须等于所有分镜时长之和,积分按此值计算。 |
| sound | boolean | 是 | - | 必填,必须显式传入 true(生成声音)或 false(无声视频)。单镜头可使用任一值,多镜头必须为 true。 |
| aspect_ratio | string | 否 | - | 可选,支持 16:9(横屏)、9:16(竖屏)或 1:1(方形),用于设置视频画幅。 |
响应字段(查询状态接口)
GET /api/generate/status/{task_id} 接口返回的详细参数说明:
| 字段 | 类型 | 描述 |
|---|---|---|
| code | integer | 接口响应状态码(200 表示成功)。 |
| data.task_id | string | 全局唯一的生成任务标识符。 |
| data.status | string | 任务执行阶段:not_started(排队)、running(处理中)、finished(已完成)或 failed(失败)。 |
| data.files | array | 生成成功时返回的媒体资产列表,包含 file_url 与 file_type。 |
| data.error_message | string | null | 当任务失败时返回的具体诊断错误信息。 |
任务生命周期
客户端应持续轮询任务状态,直至进入 finished 或 failed 终态:
not_started排队中
running生成中
finished已就绪
failed失败
轮询与异常处理
- 轮询频率建议建议提交任务后前 10 秒每隔 2-3 秒轮询一次,之后可适度放缓至 5 秒一次。
- 网络容错设计遇到临时网络抖动或网关 5xx 错误时不要重新提交任务,应使用原 task_id 继续轮询重试。
- 回调机制(Webhook)在提交任务时传入 callback_url,可在任务完成时自动接收系统推送的最终结果。
接口规格
| 规格项 | 取值 | 说明 |
|---|---|---|
| 模型 | kwaivgi/kling-video-o3-pro/text-to-video | 快手可灵 O3 旗舰级 1080p 文生视频专业版,具备视觉思维链推理与多镜头分镜时序控制。 |
| 时长 | 3-15 s | 必填,3–15 整数秒。多镜头时必须等于各分镜时长之和,按此时长计费。 |
Kling O3 Pro Text to Video
Kling O3 Pro 文生视频:通过文本提示词生成 3–15 秒视频。支持单镜头和多镜头;sound 必须显式传入,多镜头必须开启声音。
为什么选择此模型
1080p 广播级成片质感输出细腻的 1080p 全高清画质,真实还原发丝细节、皮肤微纹理与电影级丁达尔光效。
深度视觉思维链(vCoT)生成前对场景透视、多主体互动与摄影机推拉摇移进行前置推理,杜绝空间形变与穿模。
专业级多镜头分镜语法在单次任务中容纳多个分镜叙事段落,支持跨分镜的人物身份与环境色调高度统一。
演播室级原生音画同步结合场景语义自动生成多声道空间环境音、物理接触 Foley 音效与精准唇形同步语音。
电影摄影机运动模拟精准还原升降、环绕、希区柯克变焦等高难度影视运镜,呈现平稳且富有叙事张力的视觉运动。
参数说明
| 参数 | 要求 | 说明 |
|---|---|---|
| prompt | 条件必填 | multi_shots=false 时必填,描述场景、动作和镜头运动。去除首尾空白后须为非空文本,最多 2,500 字符。multi_shots=true 时请省略 prompt。 默认值 - |
| multi_shots | 是 | 必填,必须显式传入 false(单镜头)或 true(多镜头)。单镜头需要 prompt;多镜头需要 multi_prompt 和 sound=true,且顶层 prompt 不得为非空文本。省略此字段会报错。 默认值 - |
| multi_prompt | 条件必填 | multi_shots=true 时必填,单镜头模式请省略。至少提供一个分镜,每段包含非空 prompt(最多 2,500 字符)和整数 duration(1–12 秒)。分镜时长之和必须等于顶层 duration(3–15 秒)。分镜内的额外字段会被忽略。 默认值 - |
| duration | 是 | 必填,3–15 秒的整数。多镜头模式下必须等于所有分镜时长之和,积分按此值计算。 默认值 - |
| sound | 是 | 必填,必须显式传入 true(生成声音)或 false(无声视频)。单镜头可使用任一值,多镜头必须为 true。 默认值 - |
| aspect_ratio | 否 | 可选,支持 16:9(横屏)、9:16(竖屏)或 1:1(方形),用于设置视频画幅。 默认值 - |
使用步骤
构建影视级提示词详细描写场景的影调色彩、构图比例、主角外貌以及核心戏剧性冲突动作。
配置镜头与分镜结构选择单镜头长镜头推进,或开启多镜头分镜并细化各小节的分镜脚本与时长分配。
选定输出参数选择 3–15 秒的整秒成片时长,并选定 16:9、9:16 或 1:1 的成片画幅。
开启原生音频通道勾选 sound 选项,激活原生多模态声音合成引擎以自动配对对白与音效。
渲染交付与下载提交任务后进入异步渲染,在控制台监控进度并最终下载无水印 1080p MP4 视频。
价格
费用 = 顶层 duration × 每秒费率。1 积分 = $0.005。任务若执行失败,系统将全额自动返还扣除的积分。
| 计费项 | 费率 | 说明 |
|---|---|---|
| 无声 | 13 积分/秒 ($0.065/s) | 专业 1080p 影视级画质,不包含声音轨道。 |
| 有声 | 16 积分/秒 ($0.080/s) | 包含 1080p 全高清画面与演播室级原生音画同步轨道。 |
适用场景
影视与剧集概念预演将导演分镜本快速转为 1080p 动态视频样片,直观评估视听语言与机位剪辑点。
商业品牌广告成片生成具备细腻光影质感与高级调色的 1080p 广告短片,满足大屏投放要求。
高质量微短剧制作借助多镜头与口型同步能力,单批次生成具备完整情节叙事与对白的小短剧片段。
游戏与动画概念片将世界观设定转化为富有视觉冲击力的动态概念视频,表现复杂幻想生物与科幻机械运转。
使用技巧
- 建议融入电影专业词汇指导画面,如“35mm 镜头景深”、“逆光边缘轮廓光”、“低机位缓慢跟拍”。
- 当涉及多人物互动时,在提示词中分别描述各人物的位置分布与先后动作次序,引导模型建立明确的空间层级。
- 多镜头模式下,各镜头的提示词风格保持统一的光影基调(如“冷色调胶片颗粒”),可实现镜头间丝滑的自然剪接。
- 若需强调口型同步,提示词中请使用双引号明确标出对白内容并标明角色名。
- 复杂动作场景建议配置 5 秒以上的时长,让物理形变与动量释放具有更充裕的动画插值空间。
注意事项
- Pro 档位专注交付 1080p 高清画质,计算开销与推理深度显著高于 Standard 档位。
- 开启 multi_shots 必须同时配置 sound=true,且顶层 prompt 必须置空。
- 任务执行采用异步处理机制,请利用 task_id 查询进度,建议初始间隔 2–3 秒轮询。
Kling O3 Pro Text to Video API 常见问题
这个端点可以生成什么?
Kling O3 Pro 文生视频:通过文本提示词生成 3–15 秒视频。支持单镜头和多镜头;sound 必须显式传入,多镜头必须开启声音。
如何设置多镜头?
必填,必须显式传入 false(单镜头)或 true(多镜头)。单镜头需要 prompt;多镜头需要 multi_prompt 和 sound=true,且顶层 prompt 不得为非空文本。省略此字段会报错。 multi_shots=true 时必填,单镜头模式请省略。至少提供一个分镜,每段包含非空 prompt(最多 2,500 字符)和整数 duration(1–12 秒)。分镜时长之和必须等于顶层 duration(3–15 秒)。分镜内的额外字段会被忽略。
视频画幅如何确定?
可选,支持 16:9(横屏)、9:16(竖屏)或 1:1(方形),用于设置视频画幅。
如何控制声音?
必填,必须显式传入 true(生成声音)或 false(无声视频)。单镜头可使用任一值,多镜头必须为 true。
提示词有哪些长度限制?
提示词的 API 校验上限为 2,500 字符。部分多镜头生成请求曾因单段提示词超过 512 字符而失败,建议每段控制在 512 字符以内;这项建议不改变 API 校验上限。
时长和积分如何计算?
时长为 3–15 秒。无声视频 13 credits/秒,有声视频 16 credits/秒;积分为顶层 duration 乘以对应费率。
生成失败或请求超时怎么办?
非法参数会在创建生成任务和扣费前被拒绝。已受理的生成任务状态变为 failed 后,已扣积分会退回。客户端超时不代表任务失败,请先查询原 task_id 的状态,再决定是否重新提交。