Kling O3 4K Text to Video API
kwaivgi/kling-video-o3-4k/text-to-videoKling O3 4K 文生视频:通过文本提示词生成 3–15 秒视频。输出为 4K,支持单镜头和多镜头;sound 必须显式传入,多镜头必须开启声音。
461/2,500
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-4k/text-to-video。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "kwaivgi/kling-video-o3-4k/text-to-video",
"input": {
"duration": 4,
"sound": true,
"multi_shots": false,
"prompt": "Photoreal slow lateral dolly through an empty ancient temple gallery in rain. Weathered floral stone reliefs fill the foreground; rows of pillars recede toward a quiet courtyard. Water follows carved grooves and drips from worn edges, revealing mineral grains, chisel marks and moss in cracks. Soft overcast daylight, subtle wet highlights, stable architecture and rich fine detail. Audio: gentle rain and isolated drips; no music. No text, logos or watermarks.",
"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": "EE4XVIYVL5IAX4YG",
"status": "finished",
"files": [
{
"file_type": "video",
"file_url": "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-video-o3-4k/text-to-video/v1/01/output.mp4"
}
],
"created_time": "2026-09-22T18:48:45",
"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-4k/text-to-video",
"input": {
"duration": 4,
"sound": true,
"multi_shots": false,
"prompt": "Photoreal slow lateral dolly through an empty ancient temple gallery in rain. Weathered floral stone reliefs fill the foreground; rows of pillars recede toward a quiet courtyard. Water follows carved grooves and drips from worn edges, revealing mineral grains, chisel marks and moss in cracks. Soft overcast daylight, subtle wet highlights, stable architecture and rich fine detail. Audio: gentle rain and isolated drips; no music. No text, logos or watermarks.",
"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-4k/text-to-video | 快手可灵 O3 原生 4K 超高清文生视频旗舰端点,支持极清微观材质与影视分镜叙事。 |
| 时长 | 3-15 s | 必填,3–15 整数秒。多镜头时必须等于各分镜时长之和,按此时长计费。 |
Kling O3 4K Text to Video
Kling O3 4K 文生视频:通过文本提示词生成 3–15 秒视频。输出为 4K,支持单镜头和多镜头;sound 必须显式传入,多镜头必须开启声音。
为什么选择此模型
原生 4K 超高清点对点渲染非插值后处理放大,直接生成原生 4K 超高清画面,微观毛孔、水滴折射与复杂纹理清晰锐利。
高维时空物理与材质建模深度解析刚体碰撞、流体飞溅与光学色散,在大动态画面下依然保持惊人的物理真实感。
电影工业级分镜与镜头语言支持多个分镜的专业剧作推进,精准掌控电影摄影机的升降、俯仰与跟拍运动。
全沉浸式原生空间声场在生成原生 4K 视频的同时同步解算全频段高保真音轨,让环境声与动作 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(方形),用于设置视频画幅。 默认值 - |
使用步骤
拟定 4K 超高清提示词细致刻画场景微观材质、环境光照(如丁达尔效应、冷暖对撞)与主角动态细节。
设定拍摄画幅与叙事结构选定 16:9 影视宽银幕、9:16 移动端或 1:1 比例,并规划单镜头或多镜头分镜脚本。
配置成片时长与音频通道指定 3–15 秒的整秒时长,并开启 sound=true 激活原生同步音轨合成。
提交深度渲染任务发送 API 请求或在控制台运行任务,底层高密度 GPU 集群进行 4K 点对点扩散推理。
检视画质并下载成片在状态变为 finished 后检视超清视频,下载无损画质 4K MP4 母带文件。
价格
费用 = 顶层 duration × 每秒费率。1 积分 = $0.005。若任务执行失败,系统将全额自动返还扣除的积分。
| 计费项 | 费率 | 说明 |
|---|---|---|
| 无声 | 50 积分/秒 ($0.250/s) | 原生 4K 超高清极清画质,适用于后期专业配音调色流程。 |
| 有声 | 50 积分/秒 ($0.250/s) | 原生 4K 极清画面结合多模态空间音效与口型同步轨道。 |
适用场景
高端奢品与科技旗舰广告展现腕表齿轮咬合、汽车车漆反光、珠宝钻石折射等极致微观质感,直供大屏商业放映。
电影院线与剧集母带制作生成院线级特效镜头与宏大世界观定景镜头,满足 4K 巨幕放映标准。
裸眼 3D 与大型户外广告屏借助原生 4K 级画面纯净度与空间深度立体感,打造震撼的户外视觉焦点。
纪录片高保真自然生态复原细腻还原鸟类羽毛丝缕、激流飞瀑与星空延时,展现震撼人心的自然史诗画面。
使用技巧
- 建议在提示词中加入具体的物理材质词,如“手工拉丝钛合金表面”、“微观晨露折射晨光”、“8K 摄影机极清质感”。
- 4K 渲染对光影逻辑敏感,描述清楚光源方向(如“侧逆光勾勒金色发丝轮廓”)能大幅强化画面立体雕刻感。
- 多镜头分镜模式下,建议在每个分镜中保持主角服装材质与环境天气的一致性描述,确保镜头切换自然。
- 如需对白,请使用中英文引号标注角色台词,原生 4K 口型同步系统将呈现极其精确的唇齿微动作。
- 由于 4K 算力推理深度极大,建议将单次任务时长设为 5–10 秒以兼顾出色的动态稳定度与制作效率。
注意事项
- 4K 档位生成原生 3840×2160 级别视频,推理耗时较长,请设置充足的客户端轮询超时时间。
- 开启 multi_shots 模式必须设置 sound=true,且所有分镜时长之和必须与顶层 duration 完全匹配。
- 生成任务采用异步处理,建议提交任务后以 3–5 秒间隔轮询状态直至完成。
Kling O3 4K Text to Video API 常见问题
这个端点可以生成什么?
Kling O3 4K 文生视频:通过文本提示词生成 3–15 秒视频。输出为 4K,支持单镜头和多镜头;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 秒。无声视频 50 credits/秒,有声视频 50 credits/秒;积分为顶层 duration 乘以对应费率。
生成失败或请求超时怎么办?
非法参数会在创建生成任务和扣费前被拒绝。已受理的生成任务状态变为 failed 后,已扣积分会退回。客户端超时不代表任务失败,请先查询原 task_id 的状态,再决定是否重新提交。