One uninterrupted three-second low side-view shot inside a dry ancient lava tube, no active lava. An adult cave explorer in a muted red protective suit and white helmet makes one careful short step across a shallow narrow groove on the basalt floor. The attached headlamp sweeps naturally across rough dark rock as the body moves; feet land firmly, arms remain stable. Controlled subtle camera tracking, realistic headlamp falloff and deep shadows, detailed basalt. No jumps, extra people, cuts, text or logos.
Kling 3.0 Pro Text to Video API
kwaivgi/kling-v3.0-pro/text-to-videoKling 3.0 Pro Text to Video 将文字生成1080p场景,结合原生音频与逐镜编排。明确每个镜头的动作、景别和光线,引导故事推进与画面衔接。
为每个镜头填写提示词并选择 1–12 秒时长,总时长须为 3–15 秒;Sound 保持开启。
Duration: 3 秒 (3-15)
示例
REST API
快速开始
提交 Kling 3.0 Pro 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-pro/text-to-video",
"input": {
"prompt": "晨光中,一只陶瓷杯放在窗边。镜头缓慢靠近,蒸汽从杯沿升起,伴随安静的室内环境声。",
"duration": 5,
"multi_shots": false,
"sound": true,
"aspect_ratio": "16:9"
}
}
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/text-to-video",
"input": {
"prompt": "晨光中,一只陶瓷杯放在窗边。镜头缓慢靠近,蒸汽从杯沿升起,伴随安静的室内环境声。",
"duration": 5,
"multi_shots": false,
"sound": true,
"aspect_ratio": "16:9"
}
}
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 | true 生成音频,静音单镜头使用 false,多镜头使用 true。 |
| aspect_ratio | string | 可选 | 1:1 | 选择 1:1、16:9 或 9:16,分别构建方形、横屏或竖屏场景。 |
响应字段
提交后返回任务标识,查询该任务状态以获取生成的视频地址。
| 字段 | 类型 | 用法 |
|---|---|---|
| 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 | 单条场景提示词,或各自带时长的分镜提示词。 |
| 分辨率 | 1080p | 当前档位输出1080p视频。 |
| 单次时长 | 3–15 秒 | 使用整数秒,分镜序列中的每个镜头为 1–12 秒。 |
| 音频 | sound | true 生成音频,静音单镜头使用 false。 |
| 模型标识 | kwaivgi/kling-v3.0-pro/text-to-video | 本次请求使用的公开 model 值。 |
相关模型
Kling 3.0 Pro Text to Video API 常见问题
Kling 3.0 Pro Text to Video API 是什么?
Kling 3.0 Pro Text to Video 是快手用于文字生成视频场景的模型。它生成1080p视频,结合原生音频与逐镜时长编排。音画联合生成让声音与场景共同展开,分镜提示词引导动作和场景衔接。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Kling 3.0 Pro Text to Video 如何编排对话场景?
为每位说话者给出清晰描述,并把对白写在对应人物的动作旁。开启 sound=true 后,可用多镜头请求分别安排开场、回应与反应镜头,合计为 3–15 秒。
Kling 3.0 Pro Text to Video 如何生成音频?
设置 sound=true,并结合画面动作描述对白、环境声或音效。单镜头可设置 sound=false 生成静音视频,多镜头设置 sound=true。
Kling 3.0 Pro Text to Video 如何描述特写?
先明确脸部或产品表面等关注对象,再写明景别、光线和动作。Pro 生成1080p视频,选择能够清晰展示重点的构图,让关键细节位于画面主体区域。
Kling 3.0 Pro Text to Video 如何引导场景连续性?
各分镜沿用相同的人物特征、服装、环境和光线描述,再有目的地改变动作或机位,让后续镜头承接前一镜头。
Kling 3.0 Pro Text to Video 如何通过分镜时长安排节奏?
每个分镜为 1–12 整数秒,总计为 3–15 秒。为对白、动作和反应分别分配时长,将 duration 设为各镜头之和,并保持 sound=true。
何时选择 Kling 3.0 Pro 而非 Kling 3.0 Standard?
人物、道具或背景需要1080p输出细节时选择 Pro;Standard 提供720p,适合以较低费用探索场景方向。
Sound 如何影响 Kling 3.0 Pro 计费?
静音单镜头每秒 $0.195,有声视频每秒 $0.245。费用为对应单价乘以总时长,多镜头使用有声单价并按分镜总时长计算。















