Kling O3 4K Image to Video API
kwaivgi/kling-video-o3-4k/image-to-videoKling O3 4K 图生视频:使用首帧和可选尾帧生成 3–15 秒视频。输出为 4K,支持单镜头和多镜头;sound 必须显式传入,多镜头必须开启声音。
470/2,500
![Image Urls[0]](https://cdn.vidgo.ai/apis/models/kwaivgi/kling-video-o3-4k/image-to-video/v1/01/input-start.png)
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/image-to-video。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "kwaivgi/kling-video-o3-4k/image-to-video",
"input": {
"duration": 4,
"sound": true,
"multi_shots": false,
"prompt": "Begin with the supplied botanical macro. The foreground Venus flytrap slowly closes its two lobes around their central hinge, ending with marginal cilia interlaced. Preserve its vein pattern, dew beads, surrounding leaves and blurred greenhouse glazing. Droplet highlights shift naturally. Fixed macro camera, realistic plant motion; no insect, animal features or new leaves. Audio: quiet greenhouse ambience and one distant drip; no music. No text, logos or watermarks.",
"image_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-video-o3-4k/image-to-video/v1/01/input-start.png"
]
}
}
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": "MQX9Q1HSIUMLPP44",
"status": "finished",
"files": [
{
"file_type": "video",
"file_url": "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-video-o3-4k/image-to-video/v1/01/output.mp4"
}
],
"created_time": "2026-09-22T18:50:38",
"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/image-to-video",
"input": {
"duration": 4,
"sound": true,
"multi_shots": false,
"prompt": "Begin with the supplied botanical macro. The foreground Venus flytrap slowly closes its two lobes around their central hinge, ending with marginal cilia interlaced. Preserve its vein pattern, dew beads, surrounding leaves and blurred greenhouse glazing. Droplet highlights shift naturally. Fixed macro camera, realistic plant motion; no insect, animal features or new leaves. Audio: quiet greenhouse ambience and one distant drip; no music. No text, logos or watermarks.",
"image_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-video-o3-4k/image-to-video/v1/01/input-start.png"
]
}
}
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。图生会忽略该值,实际画幅由输入图片决定。 |
| image_urls | array | 是 | - | 必填,包含 1–2 张图片的数组,第一张为首帧,第二张为可选尾帧。支持公开 HTTP(S) URL、图片 Data URI 或原始 Base64 图片数据。 |
响应字段(查询状态接口)
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/image-to-video | 快手可灵 O3 原生 4K 图生视频旗舰端点,支持单图首帧与双图首尾关键帧插值,具备原生多模态空间音视频同步。 |
| 时长 | 3-15 s | 必填,3–15 整数秒。多镜头时必须等于各分镜时长之和,按此时长计费。 |
Kling O3 4K Image to Video
Kling O3 4K 图生视频:使用首帧和可选尾帧生成 3–15 秒视频。输出为 4K,支持单镜头和多镜头;sound 必须显式传入,多镜头必须开启声音。
为什么选择此模型
原生 4K 双关键帧动力学插值在 4K 超高清分辨率下严格对齐首尾两帧的像素几何坐标,以真实物理力学拟合自然流畅的中间动作与光影迁变。
微米级材质与光线追踪级质感精准保留原画的毛孔、织物经纬、金属微划痕及高光边缘,实现无噪点、无形变的纯净巨幕画质。
超强主体资产锁定能力深度特征追踪网络在 4K 超高像素矩阵下精准锁定角色五官骨骼与商品工业设计细节,杜绝漂移。
原生全景动作音频合成根据 4K 动态画面中的材质碰撞、呼吸动势与环境空间,自动渲染对应的时间对齐全频段音轨。
商业广告级成片交付输出可直接用于大屏展示、院线放映与商业调色套拍的超清无损 MP4 资产,大幅提升后期制作效率。
参数说明
| 参数 | 要求 | 说明 |
|---|---|---|
| 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。图生会忽略该值,实际画幅由输入图片决定。 默认值 - |
| image_urls | 是 | 必填,包含 1–2 张图片的数组,第一张为首帧,第二张为可选尾帧。支持公开 HTTP(S) URL、图片 Data URI 或原始 Base64 图片数据。 默认值 - |
使用步骤
准备 4K 超清参考底图上传 1 张起始高精静帧(必传),亦可追加 1 张结束静帧以精准约束终止姿态与构图。
编写动作与运镜提示词详细阐述两张关键帧之间的过渡动作路径、摄像机推进轨迹以及环境光影的动态变化。
配置成片时长与声音通道选择 3–15 秒的整秒时长,并开启 sound=true 以自动解算生成高保真原生动作音效。
启动 4K 扩散渲染提交任务至高性能计算集群,底层深度多模态网络将在 4K 像素空间内完成动力学插值推理。
检视微观细节并导出任务完成后在控制台回放核对微观细节与动态连贯性,下载原生 4K MP4 母带文件。
价格
费用 = 顶层 duration × 每秒费率。1 积分 = $0.005。若任务未能生成可用视频,扣除的积分将全额自动返还。
| 计费项 | 费率 | 说明 |
|---|---|---|
| 无声 | 50 积分/秒 ($0.250/s) | 原生 4K 关键帧物理插值视频,不包含音轨。 |
| 有声 | 50 积分/秒 ($0.250/s) | 原生 4K 极清视频并整合高质量动作 Foley 与环境声轨。 |
适用场景
顶级奢侈品与工业大片广告将高分辨率珠宝摄影、名表静帧及汽车工业渲染图升维为 4K 超清影视镜头,直接用于广告投放。
电影工业级首尾关键帧特效通过高精度的起止概念设计图,自动生成平滑无撕裂的 4K 复杂特效动作过渡镜头。
超大屏展览与沉浸式数字艺术使高精度数字绘画与国宝级文物画作在 4K 尺度下灵动复活,展现细腻入微的动态神韵。
超写实虚拟人商业代言演绎完美保持虚拟人面部毛孔、发丝与微表情一致性,生成高品质动态代言走秀与对话短片。
使用技巧
- 输入的源图片建议达到 2K 或 4K 原生分辨率,清晰的源图纹理能让 4K 动力学扩散模型获得最佳生动度。
- 使用双关键帧时,两张图的视角变化建议控制在 90 度以内,自然的机位过渡可保证极高的人物结构完整度。
- 提示词侧重描述两张图之间的物理运动机理(如“微风拂过发丝轻轻飘扬,眼神温和地转向镜头”)。
- 若需生成对白,请使用中英文引号规范输入台词内容,模型在 4K 分辨率下能精确解算微小唇形肌肉运动。
- 建议为 4K 复杂动态配置 5 秒以上的时长,赋予加速度与动力学惯性充分平滑演化的时间窗口。
注意事项
- image_urls 支持 1–2 张图片。成片比例将自然适配输入图片的原始宽高比与画幅尺寸。
- 多镜头 multi_shots 模式必须设置 sound=true,并确保所有分镜时长之和等于顶层 duration。
- 原生 4K 生成任务计算密集,处理耗时会高于常规端点,请保持合理的轮询重试间隔。
Kling O3 4K Image to Video API 常见问题
这个端点可以生成什么?
Kling O3 4K 图生视频:使用首帧和可选尾帧生成 3–15 秒视频。输出为 4K,支持单镜头和多镜头;sound 必须显式传入,多镜头必须开启声音。
如何使用首帧和尾帧?
必填,包含 1–2 张图片的数组,第一张为首帧,第二张为可选尾帧。支持公开 HTTP(S) URL、图片 Data URI 或原始 Base64 图片数据。
视频画幅如何确定?
可省略;若传入,仅接受 16:9、9:16 或 1:1。图生会忽略该值,实际画幅由输入图片决定。
如何设置多镜头?
必填,必须显式传入 false(单镜头)或 true(多镜头)。单镜头需要 prompt;多镜头需要 multi_prompt 和 sound=true,且顶层 prompt 不得为非空文本。省略此字段会报错。 multi_shots=true 时必填,单镜头模式请省略。至少提供一个分镜,每段包含非空 prompt(最多 2,500 字符)和整数 duration(1–12 秒)。分镜时长之和必须等于顶层 duration(3–15 秒)。分镜内的额外字段会被忽略。
如何控制声音和提示词长度?
必填,必须显式传入 true(生成声音)或 false(无声视频)。单镜头可使用任一值,多镜头必须为 true。 提示词的 API 校验上限为 2,500 字符。部分多镜头生成请求曾因单段提示词超过 512 字符而失败,建议每段控制在 512 字符以内;这项建议不改变 API 校验上限。
时长和积分如何计算?
时长为 3–15 秒。无声视频 50 credits/秒,有声视频 50 credits/秒;积分为顶层 duration 乘以对应费率。
生成失败或请求超时怎么办?
非法参数会在创建生成任务和扣费前被拒绝。已受理的生成任务状态变为 failed 后,已扣积分会退回。客户端超时不代表任务失败,请先查询原 task_id 的状态,再决定是否重新提交。