Kling 3.0 4K Image to Video API
kwaivgi/kling-v3.0-4k/image-to-videoKling 3.0 4K Image to Video 将静态图片生成原生4K视频,结合首尾帧引导与原生音频。设置开场和收尾画面,再通过分镜描述安排中间的动作与运镜。
497/2,500
拖拽文件、粘贴剪贴板素材,或输入 URL。 按顺序添加:第一张作为首帧,第二张作为尾帧(可选)。
1/2 个素材
填写元素对象数组,并在提示词中通过 @element_name 引用;对象内字段会随请求保留。
REST API
快速开始
提交 Kling 3.0 4K 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-4k/image-to-video",
"input": {
"prompt": "镜头缓慢靠近画面主体,柔和日光照亮场景,微风轻拂。",
"duration": 5,
"multi_shots": false,
"sound": true,
"image_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-4k/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-4k/image-to-video",
"input": {
"prompt": "镜头缓慢靠近画面主体,柔和日光照亮场景,微风轻拂。",
"duration": 5,
"multi_shots": false,
"sound": true,
"image_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v3.0-4k/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 生成音频,静音单镜头使用 false,多镜头使用 true。 |
| kling_elements | object[] | 可选 | 不使用时省略 | 与 image_urls 一起提供元素对象,在提示词中用 @element_name 引用具名主体。在 JSON 编辑器中按 4K 文档填写元素对象。 |
响应字段
提交后返回任务标识,查询该任务状态以获取生成的视频地址。
| 字段 | 类型 | 用法 |
|---|---|---|
| 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 | 首帧与动作描述,可选尾帧。 |
| 分辨率 | 4K | 原生4K视频输出。 |
| 单次时长 | 3–15 秒 | 使用整数秒,分镜序列中的每个镜头为 1–12 秒。 |
| 音频 | sound | true 生成音频,静音单镜头使用 false。 |
| 模型标识 | kwaivgi/kling-v3.0-4k/image-to-video | 本次请求使用的公开 model 值。 |
相关模型
Kling 3.0 4K Image to Video API 常见问题
Kling 3.0 4K Image to Video API 是什么?
Kling 3.0 4K Image to Video 是快手用于静态图片动画化的模型。它生成原生4K视频,结合原生音频与参考帧引导。图像条件引导开场构图,元素参考为重复主体提供外观依据。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Kling 3.0 4K Image to Video 的多镜头可以使用尾帧吗?
可以。此4K端点的多镜头请求可在 image_urls[0] 填首帧,并在 image_urls[1] 填可选尾帧。开启 sound 与 multi_shots,再用逐镜提示词和时长描述开场至收尾的过程。
Kling 3.0 4K Image to Video 可以将图片生成原生4K视频吗?
可以,该档位输出原生4K视频。首帧应清晰展示主体及重要细节,再通过动作描述让动画沿着源图的视觉方向展开。
Kling 3.0 4K Image to Video 如何安排镜头过渡时长?
为每个镜头填写提示词和 1–12 整数秒时长,合计须为 3–15 秒,并设置 multi_shots=true 与 sound=true。根据通向收尾画面的动作分配时长,例如镜头拉远或主体转身。
Kling 3.0 4K Image to Video 如何生成音频?
设置 sound=true,并结合画面动作描述对白、环境声或音效。单镜头可设置 sound=false 生成静音视频,多镜头设置 sound=true。
Kling 3.0 4K Image to Video 如何填写元素参考?
与 image_urls 一起提供 kling_elements,元素对象采用 API 文档中的4K结构。在 JSON 中填写对象,并在提示词中用 @element_name 指定具名主体,首帧继续作为开场画面依据。
何时选择 Kling 3.0 4K 而非 Kling 3.0 Pro?
需要原生4K细节或素材将进入4K时间线时选择4K;Pro 以较低每秒费用提供1080p,可按最终交付规格选择。
Sound 如何影响 Kling 3.0 4K 计费?
sound=true 与 sound=false 均为每秒 $0.250。单价乘以视频总时长即为费用,5 秒为 $1.250,多镜头保持 sound=true。















