Animate the exact lacquered wooden fox marionette in the source image. It makes one small polite forward bow and returns toward upright over three seconds. Preserve the carved face, blue waistcoat, rigid wood pieces, joint locations and delicate strings. No biological mouth motion, extra limbs or costume changes. Fixed camera, subtle leaf shadows on the stage, no cut.
Kling 3.0 Pro Image to Video API
kwaivgi/kling-v3.0-pro/image-to-videoKling 3.0 Pro Image to Video 将参考图生成1080p视频,结合原生音频与首尾帧引导。主体参考帮助约束角色和产品外观,让镜头运动围绕既定视觉展开。
542/2,500
拖拽文件、粘贴剪贴板素材,或输入 URL。 按顺序添加:第一张作为首帧,第二张作为尾帧(可选)。
1/2 个素材
在提示词中使用 @diver 引用
拖拽文件、粘贴剪贴板素材,或输入 URL。 2–4 张 JPG/PNG,每张最多 10 MB。
2/4 个素材
示例
REST API
快速开始
提交 Kling 3.0 Pro Image to Video 请求,再使用返回的任务标识获取视频。
身份验证
在 Authorization 请求头中以 Bearer 格式传入 Vidgo API 密钥。
- 提交地址
- POST
https://api.vidgo.ai/api/generate/submit - 身份验证
- Authorization: Bearer YOUR_API_KEY
提交请求
将模型标识与 input 对象发送至提交接口。图片示例含有首帧素材地址,可替换为自己的图片链接。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "kwaivgi/kling-v3.0-pro/image-to-video",
"input": {
"prompt": "镜头缓慢靠近画面主体,柔和日光照亮场景,微风轻拂。",
"duration": 5,
"multi_shots": false,
"sound": true,
"image_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/image-to-video/v1/01/input.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} 替换为提交后返回的任务标识。
状态地址
https://api.vidgo.ai/api/generate/status/{task_id}使用返回的 task_id 查询此地址,直到 finished 或 failed;完成的视频列在 data.files 中。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "example-task-id",
"status": "not_started",
"created_time": "2026-09-27T00:00:00Z"
}
}{
"code": 200,
"data": {
"task_id": "example-task-id",
"status": "finished",
"created_time": "2026-09-27T00:00:00Z",
"files": [
{
"file_type": "video",
"file_url": "https://example.com/generated-video.mp4"
}
]
}
}完整示例
status 为 finished 时,从 files 的视频条目中读取 file_url。下方任务标识与输出地址仅用于展示响应格式。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "kwaivgi/kling-v3.0-pro/image-to-video",
"input": {
"prompt": "镜头缓慢靠近画面主体,柔和日光照亮场景,微风轻拂。",
"duration": 5,
"multi_shots": false,
"sound": true,
"image_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-pro/image-to-video/v1/01/input.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请求参数
选择单条提示词或分镜序列,再填写当前端点的时长与声音设置。
| 字段 | 类型 | 填写条件 | 默认值 | 用法 |
|---|---|---|---|---|
| image_urls | string[] | 必填 | 明确填写 | 索引 0 填首帧,索引 1 可填尾帧,使用可公开访问的 HTTP(S) 图片地址。单镜头使用 1–2 张图片,多镜头使用一张首帧。 |
| prompt | string | multi_shots=false 时 | 明确填写 | 用 1–2,500 个字符描述参考画面中的动作和镜头运动。多镜头模式在 multi_prompt 中逐镜填写。 |
| multi_shots | boolean | 可选 | false | false 使用单条提示词;true 使用 multi_prompt 分别编排镜头,并设置 sound=true。 |
| multi_prompt | object[] | multi_shots=true 时 | 明确填写 | 添加至少一个含 prompt 和 duration 的对象。每条提示词为 1–2,500 个字符,每个镜头为 1–12 整数秒,分镜时长之和须等于 duration。 |
| duration | integer | 必填 | 明确填写 | 总时长填写 3–15 的整数秒;多镜头模式填写各分镜时长之和。 |
| sound | boolean | 可选 | true | true 生成音频,静音单镜头使用 false,多镜头使用 true。 |
| aspect_ratio | string | 可选 | 由首帧确定 | 输出画幅由首帧确定,请按目标构图准备首帧。 |
| kling_elements | object[] | 可选 | 不使用时省略 | 与 image_urls 一起提供元素对象,在提示词中用 @element_name 引用具名主体。每个元素填写 name,并选择 2–4 张 JPG/PNG 图片(每张最多 10 MB)或一个 MP4/MOV 视频(最多 50 MB),可用 description 补充外观特征。 |
响应字段
提交后返回任务标识,查询该任务状态以获取生成的视频地址。
| 字段 | 类型 | 用法 |
|---|---|---|
| code | integer | 响应代码,0 或 200 表示本次接口操作成功。 |
| data.task_id | string | 提交后返回的任务标识,用于查询同一个任务。 |
| data.status | string | 取值为 not_started、running、finished 或 failed。提交成功后继续查询生成状态。 |
| data.created_time | string | 服务返回的任务创建时间。 |
| data.files | array | 任务完成后返回的生成媒体条目。 |
| data.files[].file_type | string | 生成视频对应 file_type=video 的条目。 |
| data.files[].file_url | string | 用于播放或下载的视频地址。 |
| data.error_message | string | null | status=failed 时查看具体错误信息。 |
任务生命周期
保存返回的 task_id,持续查询直到 finished 或 failed。
not_started请求已接收并等待处理,保存 task_id 以继续查询。
running视频正在生成,继续查询当前任务。
finished生成已完成,从 files 中读取视频条目。
failed生成以错误结束,请先查看 error_message,再调整请求并重新提交。
错误处理
- 提交前检查时长多镜头设置 sound=true,确认各分镜时长之和为 3–15 秒。
- 确保素材地址可访问使用可公开访问的 HTTP(S) 素材地址,并在任务处理期间保持可访问。
- 恢复中断的状态查询状态查询失败时,使用原 task_id 继续查询;需要生成另一个片段时再提交新请求。
- 查看返回的错误信息任务失败时先查看 error_message,调整对应输入后再重试。
规格说明
| 规格 | 取值 | 说明 |
|---|---|---|
| 输入方式 | Image to Video | 首帧与动作描述,可选尾帧。 |
| 分辨率 | 1080p | 当前档位输出1080p视频。 |
| 单次时长 | 3–15 秒 | 使用整数秒,分镜序列中的每个镜头为 1–12 秒。 |
| 音频 | sound | true 生成音频,静音单镜头使用 false。 |
| 模型标识 | kwaivgi/kling-v3.0-pro/image-to-video | 本次请求使用的公开 model 值。 |
相关模型
Kling 3.0 Pro Image to Video API 常见问题
Kling 3.0 Pro Image to Video API 是什么?
Kling 3.0 Pro Image to Video 是快手用于静态图片动画化的模型。它生成1080p视频,结合原生音频与参考帧引导。图像条件引导开场构图,元素参考为重复主体提供外观依据。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Kling 3.0 Pro Image to Video 如何使用尾帧?
在 image_urls[0] 填开场图,在 image_urls[1] 填目标收尾图。多镜头使用一张首帧;单镜头可同时使用首帧与尾帧。在提示词中描述连接两幅构图的动作。
Kling 3.0 Pro Image to Video 如何使用角色参考?
在首帧之外添加具名元素,选择 2–4 张 JPG/PNG 参考图(每张最多 10 MB),或一个 MP4/MOV 参考视频(最多 50 MB)。在动作提示词中以 @element_name 点名,让动作对应目标角色。
Kling 3.0 Pro Image to Video 如何从一张图片编排连续镜头?
提供一张首帧,开启 multi_shots 与 sound,再为后续镜头分别填写提示词。每镜为 1–12 秒,duration 填合计的 3–15 秒,并在序列中沿用一致的主体描述。
Kling 3.0 Pro Image to Video 如何生成音频?
设置 sound=true,并结合画面动作描述对白、环境声或音效。单镜头可设置 sound=false 生成静音视频,多镜头设置 sound=true。
Kling 3.0 Pro Image to Video 如何准备产品图片?
选择能清楚展示产品轮廓与重要表面细节的首帧,让构图符合目标画幅,再为1080p片段描述镜头路径与产品动作。
何时选择 Kling 3.0 Pro 而非 Kling 3.0 Standard?
人物、道具或背景需要1080p输出细节时选择 Pro;Standard 提供720p,适合以较低费用探索场景方向。
Sound 如何影响 Kling 3.0 Pro 计费?
静音单镜头每秒 $0.195,有声视频每秒 $0.245。费用为对应单价乘以总时长,多镜头使用有声单价并按分镜总时长计算。















