Animate the supplied chameleon photo as a natural-history macro shot. Preserve its exact striped skin, horns-free head, curled tail, branch and dry rocky terrarium. The visible turret eye slowly rotates toward the camera while the nearest forefoot opens its two opposing toe groups and reaches a short distance forward onto the same branch. End after the foot grips securely. Very subtle breathing. Fixed camera, no color transformation, no tongue strike, no new limbs. No text, logos or watermarks.
Kling O3 Pro Image to Video API
kwaivgi/kling-video-o3-pro/image-to-videoKling O3 Pro 图生视频:使用首帧和可选尾帧生成 3–15 秒视频。支持单镜头和多镜头;sound 必须显式传入,多镜头必须开启声音。
多镜头必须开启声音。表单自动按分镜总时长填写 duration。
Duration: 5 秒 (3-15)
![Image Urls[0]](https://cdn.vidgo.ai/apis/models/kwaivgi/kling-video-o3-pro/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-pro/image-to-video。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "kwaivgi/kling-video-o3-pro/image-to-video",
"input": {
"duration": 5,
"sound": true,
"multi_shots": true,
"multi_prompt": [
{
"prompt": "Begin with the supplied photograph. Preserve the female geologist, white helmet, charcoal jacket with teal collar, orange instrument and safety railing. Medium-wide view: she watches a distant lava fountain beyond the secured platform. Warm lava light touches her jacket; wind moves a loose hair strand. Restrained documentary realism, safe distance. Audio: quiet wind and low distant rumble. No text, logos or watermarks.",
"duration": 2
},
{
"prompt": "Cut to a closer three-quarter view of the same geologist on the same platform. Preserve her face, white helmet, teal collar and orange instrument. She lowers her gaze from the volcano to the instrument and makes one small thumb adjustment. Maintain warm lava reflections against cool twilight. Finish looking down. Low distant rumble and glove movement; no speech, alarm or music. No text, logos or watermarks.",
"duration": 3
}
],
"image_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-video-o3-pro/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": "WTSYQAI2J76PVHFW",
"status": "finished",
"files": [
{
"file_type": "video",
"file_url": "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-video-o3-pro/image-to-video/v1/01/output.mp4"
}
],
"created_time": "2026-09-22T18:46:21",
"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/image-to-video",
"input": {
"duration": 5,
"sound": true,
"multi_shots": true,
"multi_prompt": [
{
"prompt": "Begin with the supplied photograph. Preserve the female geologist, white helmet, charcoal jacket with teal collar, orange instrument and safety railing. Medium-wide view: she watches a distant lava fountain beyond the secured platform. Warm lava light touches her jacket; wind moves a loose hair strand. Restrained documentary realism, safe distance. Audio: quiet wind and low distant rumble. No text, logos or watermarks.",
"duration": 2
},
{
"prompt": "Cut to a closer three-quarter view of the same geologist on the same platform. Preserve her face, white helmet, teal collar and orange instrument. She lowers her gaze from the volcano to the instrument and makes one small thumb adjustment. Maintain warm lava reflections against cool twilight. Finish looking down. Low distant rumble and glove movement; no speech, alarm or music. No text, logos or watermarks.",
"duration": 3
}
],
"image_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-video-o3-pro/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-pro/image-to-video | 快手可灵 O3 旗舰级 1080p 图生视频专业版,支持单图首帧与双图首尾关键帧插值,具备演播室级原生音视频同步。 |
| 时长 | 3-15 s | 必填,3–15 整数秒。多镜头时必须等于各分镜时长之和,按此时长计费。 |
Kling O3 Pro Image to Video
Kling O3 Pro 图生视频:使用首帧和可选尾帧生成 3–15 秒视频。支持单镜头和多镜头;sound 必须显式传入,多镜头必须开启声音。
为什么选择此模型
首尾关键帧高精插值精确绑定始末两张静态画面的物理空间坐标与构图约束,基于动力学自动计算平滑连贯的过渡形变与相机轨迹。
1080p 影视级微纹理保真在 1080p 全高清分辨率下精准重构源图的面部毛孔、布料纤维、玻璃反光及阴影渐变,避免模糊与杂色。
严苛的人物与资产一致性深度特征匹配网络在运动全过程中牢牢锁定角色五官、服装纹饰及道具几何比例,杜绝形变漂移。
原生动作环境音画合成基于画面的物理运动轨迹(如击掌、水流撞击、脚步摩擦)原生解算声波时间对齐,提供演播室级听觉沉浸感。
弹性时长与分镜叙事支持 3–15 秒整秒输出,兼顾单镜头精细动力学插值与多镜头结构化镜头组接,赋予静态静帧更丰富的影视叙事力。
参数说明
| 参数 | 要求 | 说明 |
|---|---|---|
| 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 图片数据。 默认值 - |
使用步骤
上传高分辨率关键帧上传 1 张起始参考静帧(必传);若需精准控制动作终点,可追加 1 张结束静帧。
描述动作与运镜轨迹在提示词中描写主体从起始状态到后续动作的物理过渡细节、速度感及摄像机调度。
设定时长与音频选择 3–15 秒的整数成片时长,并决定是否开启原生音画同步开关以合成环境音。
提交渲染任务点击运行或通过 API 提交生成请求,底层推理引擎依据首尾帧进行高精物理轨迹解算。
预览成片并下载生成完成后在线核对人物一致性与动作流畅度,下载无水印 1080p MP4 视频成品。
价格
费用 = 顶层 duration × 每秒费率。1 积分 = $0.005。若任务未能成功交付可用视频,扣除的积分将全额自动返还。
| 计费项 | 费率 | 说明 |
|---|---|---|
| 无声 | 13 积分/秒 ($0.065/s) | 1080p 专业级关键帧动态插值,不包含音频轨道。 |
| 有声 | 16 积分/秒 ($0.080/s) | 1080p 专业级成片画面,深度整合动作 Foley 音效与环境音轨。 |
适用场景
高定品牌大片与电商动态化将拍摄好的高精模特写真与静物白底图转化为充满高级动态呼吸感的 1080p 视频。
影视特效关键帧精准过渡设定特定起幅与落幅静帧构图,自动补齐符合空气阻力与重力规律的连续动作镜头。
角色 IP 动态数字活化保持动漫角色或虚拟人面容五官毫厘不差,生成生动的表情对话与动作表演片段。
建筑设计与空间环视展示将效果图渲染图以平稳推拉摇移运镜转化为沉浸式漫游视频,光影变幻真实可信。
使用技巧
- 使用双关键帧时,建议首尾两张图在光影角度与人物特征上保持连贯,重点变化体现在机位景别或肢体姿态。
- 提示词着重描写两张图片之间的“过程动态”,例如“从沉思逐渐展露微笑并抬头望向窗外”。
- 输入图片建议使用清晰、无伪影的高清图,主体在画框中拥有充裕的运动缓冲空间。
- 如需生成特定语言的对话对白,在提示词中加入中英文双引号对话内容,并确保首帧人物面部无明显遮挡。
- 避免在提示词中要求发生瞬间突兀的角度反转(如从正面直接 180 度跳跃至背面),渐进式动作可获得最佳物理真实感。
注意事项
- image_urls 支持 1–2 张图片(第一张为首帧,第二张为尾帧)。成片宽高比将自然适配输入图片的构图比例。
- 开启多镜头 multi_shots 必须配置 sound=true,并确保每个分镜时长之和满足总时长约束。
- 生成过程为异步执行,请通过返回的 task_id 定期轮询任务状态直至 finished 或 failed。
Kling O3 Pro Image to Video API 常见问题
这个端点可以生成什么?
Kling O3 Pro 图生视频:使用首帧和可选尾帧生成 3–15 秒视频。支持单镜头和多镜头;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 秒。无声视频 13 credits/秒,有声视频 16 credits/秒;积分为顶层 duration 乘以对应费率。
生成失败或请求超时怎么办?
非法参数会在创建生成任务和扣费前被拒绝。已受理的生成任务状态变为 failed 后,已扣积分会退回。客户端超时不代表任务失败,请先查询原 task_id 的状态,再决定是否重新提交。