Kling 3.0 4K Text to Video API
kwaivgi/kling-v3.0-4k/text-to-videoKling 3.0 4K Text to Video 将文字生成原生4K画面,支持分镜时长编排与原生音频。描述材质、光线与镜头运动,引导场景细节和叙事节奏。
588/2,500
REST API
快速开始
提交 Kling 3.0 4K Text to Video 请求,再使用返回的任务标识获取视频。
身份验证
在 Authorization 请求头中以 Bearer 格式传入 Vidgo API 密钥。
- 提交地址
- POST
https://api.vidgo.ai/api/generate/submit - 身份验证
- Authorization: Bearer YOUR_API_KEY
提交请求
将模型标识与场景提示词写入 JSON 请求,修改提示词以描述自己的场景。
REQUEST_BODY=$(cat <<'JSON'
{
"model": "kwaivgi/kling-v3.0-4k/text-to-video",
"input": {
"prompt": "晨光中,一只陶瓷杯放在窗边。镜头缓慢靠近,蒸汽从杯沿升起,伴随安静的室内环境声。",
"duration": 5,
"multi_shots": false,
"sound": true
}
}
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/text-to-video",
"input": {
"prompt": "晨光中,一只陶瓷杯放在窗边。镜头缓慢靠近,蒸汽从杯沿升起,伴随安静的室内环境声。",
"duration": 5,
"multi_shots": false,
"sound": true
}
}
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请求参数
选择单条提示词或分镜序列,再填写当前端点的时长与声音设置。
| 字段 | 类型 | 填写条件 | 默认值 | 用法 |
|---|---|---|---|---|
| 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。 |
响应字段
提交后返回任务标识,查询该任务状态以获取生成的视频地址。
| 字段 | 类型 | 用法 |
|---|---|---|
| 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,调整对应输入后再重试。
规格说明
| 规格 | 取值 | 说明 |
|---|---|---|
| 输入方式 | Text to Video | 单条场景提示词,或各自带时长的分镜提示词。 |
| 分辨率 | 4K | 原生4K视频输出。 |
| 单次时长 | 3–15 秒 | 使用整数秒,分镜序列中的每个镜头为 1–12 秒。 |
| 音频 | sound | true 生成音频,静音单镜头使用 false。 |
| 模型标识 | kwaivgi/kling-v3.0-4k/text-to-video | 本次请求使用的公开 model 值。 |
相关模型
Kling 3.0 4K Text to Video API 常见问题
Kling 3.0 4K Text to Video API 是什么?
Kling 3.0 4K Text to Video 是快手用于文字生成视频场景的模型。它生成原生4K视频,结合原生音频与逐镜时长编排。音画联合生成让声音与场景共同展开,分镜提示词引导动作和场景衔接。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Kling 3.0 4K Text to Video 生成的是原生4K吗?
是的,该档位根据场景提示词生成原生4K视频。需要4K交付或剪辑素材时可选择此档位,并描述希望呈现的构图、表面材质与光线。
Kling 3.0 4K Text to Video 如何生成音频?
设置 sound=true,并结合画面动作描述对白、环境声或音效。单镜头可设置 sound=false 生成静音视频,多镜头设置 sound=true。
Kling 3.0 4K Text to Video 如何描述精细场景?
写明前景主体、重要表面细节、光线方向与镜头距离。制作环境镜头时,描述镜头如何逐步展现空间,让画面在运动中始终保持清晰的关注重点。
Kling 3.0 4K Text to Video 如何连接多个镜头?
开启 multi_shots 与 sound,在 multi_prompt 中逐镜填写内容和 1–12 秒时长。各镜头沿用相同主体与环境细节,时长之和等于 duration,总计为 3–15 秒。
Kling 3.0 4K Text to Video 单次视频有多长?
duration 可填写 3–15 的整数秒。制作分镜序列时,将总时长分配给各条提示词,每个镜头为 1–12 秒。
何时选择 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。















