Kling 4.0 Reference to Video API
kwaivgi/kling-v4.0/reference-to-videoKling 4.0 Reference to Video 将参考图片、参考视频和可复用元素转化为 3–30 秒、720p 或 1080p 的带立体声视频,并在提示词中以 @Image1、@Video1 或 @Element1 引用每个参考。它让角色、产品与场景与参考保持一致,同时把它们放进你描述的新画面中。
拖拽文件、粘贴剪贴板素材,或输入 URL。 可选起始帧:1 张 JPEG、PNG 或 WebP。
拖拽文件、粘贴剪贴板素材,或输入 URL。 最多 10 张图片,在提示词中以 @Image1、@Image2… 引用。
2/10 个素材
拖拽文件、粘贴剪贴板素材,或输入 URL。 最多 5 个视频,每个 3–30 秒,合计 30 秒以内,以 @Video1… 引用;按输入视频计费。
切换到 JSON 可添加 kling_elements 或使用 multi_prompt 编写分镜。
REST API
快速开始
三步完成第一次 Kling 4.0 Reference to Video 调用。示例以 @Image1 和 @Image2 引用人物与工作室图片,并返回 task_id。
连接 Vidgo API
创建 API Key,将它安全保存在服务端,并通过 Authorization 请求头以 Bearer Token 发送。
- 接口地址
- POST
https://api.vidgo.ai/api/generate/submit - 认证方式
- Authorization: Bearer VIDGO_API_KEY
提交一个生成任务
运行短示例,提供 prompt 并至少包含一种参考输入。
curl --request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "kwaivgi/kling-v4.0/reference-to-video",
"input": {
"prompt": "@Image1 is the character: a young violin maker with round glasses and a green work apron. @Image2 is the workshop: wooden benches, hanging violin bodies, a dusty window. In one continuous 8-second shot, she lifts a finished violin, tightens a peg, and plays a short bright phrase while the camera circles slowly around the bench. Keep her face, glasses and apron consistent with @Image1. Audio: the short violin phrase, a creaking floorboard, quiet street noise outside. No text, no logos, no watermark.",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v4.0/reference-to-video/v1/01/input-01.webp",
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v4.0/reference-to-video/v1/01/input-02.webp"
]
}
}'等待并获取结果
使用返回的 task_id 查询同一个任务,直到状态变为 finished 或 failed;成功后读取 data.files[].file_url。
查询状态
GET https://api.vidgo.ai/api/generate/status/{task_id}当状态为 not_started 或 running 时,建议每隔数秒查询一次;到达 finished 或 failed 后停止。成功时从 data.files[].file_url 读取视频地址;生成较长视频时可逐步拉长间隔,也可在提交请求根层添加 callback_url 异步接收结果。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "WV8ZE7C44UA7J6U4",
"status": "not_started",
"created_time": "2026-11-05T07:05:17"
}
}{
"code": 200,
"data": {
"task_id": "WV8ZE7C44UA7J6U4",
"status": "finished",
"files": [
{
"file_url": "https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v4.0/reference-to-video/v2/01/output-01.mp4",
"file_type": "video"
}
],
"created_time": "2026-11-05T07:05:17",
"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-v4.0/reference-to-video",
"input": {
"prompt": "@Image1 is the character: a young violin maker with round glasses and a green work apron. @Image2 is the workshop: wooden benches, hanging violin bodies, a dusty window. In one continuous 8-second shot, she lifts a finished violin, tightens a peg, and plays a short bright phrase while the camera circles slowly around the bench. Keep her face, glasses and apron consistent with @Image1. Audio: the short violin phrase, a creaking floorboard, quiet street noise outside. No text, no logos, no watermark.",
"duration": 8,
"resolution": "720p",
"aspect_ratio": "16:9",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v4.0/reference-to-video/v1/01/input-01.webp",
"https://cdn.vidgo.ai/apis/models/kwaivgi/kling-v4.0/reference-to-video/v1/01/input-02.webp"
]
}
}
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')
if [ -z "$TASK_ID" ]; then
printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
exit 1
fi
while true; do
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')
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 2
;;
*)
printf 'Unexpected task status: %s
' "$STATUS" >&2
exit 1
;;
esac
done请求参数
model 和 callback_url 位于请求根层;生成参数位于 input。
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| model | string | 是 | — | 固定为 kwaivgi/kling-v4.0/reference-to-video。 |
| callback_url | string (URL) | 否 | — | 用于接收任务结果的公开 HTTP(S) 地址,任务结束时推送。 |
| input | object | 是 | — | 生成参数:至少一种参考输入与 prompt 或 multi_prompt,以及可选的起始帧、duration、resolution 与 aspect_ratio。 |
| input.prompt | string | 否 | — | 单条提示词,1–26,000 个字符;与 multi_prompt 二选一。 |
| input.multi_prompt | object[] | 否 | — | 分镜 {prompt, duration?},合计 3–30 秒;同时发送 duration 时须等于合计值。 |
| input.reference_image_urls | string[] | 否 | — | ≤10 个图片 URL(@Image1…)。 |
| input.reference_video_urls | string[] | 否 | — | ≤5 个视频 URL(@Video1…),每个 3–30 秒;按输入视频计费。 |
| input.kling_elements | object[] | 否 | — | ≤7 个元素,其中视频元素 ≤3。每个:element_input_urls(2–4)或 element_input_video_urls(1)。 |
| input.image_urls | string[] | 否 | — | ≤1 个起始帧 URL。 |
| input.duration | integer | 否 | 5 | 3–30 秒。 |
| input.resolution | string | 否 | 720p | 720p 或 1080p。 |
| input.aspect_ratio | string | 否 | auto | auto、16:9、9:16、1:1、21:9。 |
响应字段
提交响应会立即返回任务标识;随着任务推进,状态响应会补充进度、输出文件或失败信息。
| 字段 | 类型 | 说明 |
|---|---|---|
| code | integer | 应用层结果码,成功响应使用 0 或 200。 |
| message | string | 存在时返回便于阅读的响应或错误信息。 |
| data.task_id | string | 任务标识,用于拼接状态查询地址。 |
| data.status | string | 当前状态:not_started、running、finished 或 failed。 |
| data.created_time | string | 任务创建时间,采用日期时间格式。 |
| data.progress | number | 上游提供进度时返回的完成百分比。 |
| data.files[] | array | 任务成功后返回的生成文件列表。 |
| data.files[].file_url | string | 生成视频的公开访问地址。 |
| data.files[].file_type | string | 生成文件类型,例如 video。 |
| data.files[].watermark_url | string | null | 存在水印版本时返回对应地址。 |
| data.error_message | string | null | status 为 failed 时的失败详情。 |
任务生命周期
not_started 与 running 属于非终态;finished 与 failed 是两种终态,收到任意终态后都应停止轮询。
not_started任务已被接受,正在等待排队开始。
running视频正在生成中,请保持轮询查询。
finished任务完成,从 data.files[].file_url 读取视频地址。
failed生成失败,读取 data.error_message 了解原因并停止轮询。
轮询与错误处理
- 认证失败401 表示 Bearer API Key 缺失或无效,请在控制台确认密钥后重试。
- 参数校验400 表示请求字段不合法或属于其他端点,请检查参考数量(图片 10、视频 5、元素 7、合计 15)及输入视频时长。
- 轮询间隔任务运行期间建议每隔数秒查询一次;生成较长视频时可逐步拉长间隔。
- 终态处理仅在 not_started 或 running 时继续轮询;收到 finished 或 failed 即停止。
- 回调方式在请求根层添加 callback_url,即可在任务结束时接收结果推送,无需持续轮询。
模型规格
| 规格 | 取值 | 说明 |
|---|---|---|
| 模型 | kwaivgi/kling-v4.0/reference-to-video | 参考引导视频生成的模型标识。 |
| 时长 | 3–30 | 整数秒,默认 5 秒。 |
| 分辨率 | 720p | 1080p | 默认 720p。 |
| 画幅比例 | auto | 16:9 | 9:16 | 1:1 | 21:9 | 默认 auto。 |
| 价格 | 28.5 / 42.5 · 17 / 25.5 credits/s | 仅图片参考:720p / 1080p 每输出秒。含参考视频或视频元素:按输入视频费率与计费秒数。 |
相关模型
Kling 4.0 Reference to Video API 常见问题
Kling 4.0 Reference to Video API 是什么?
Kling 4.0 Reference to Video 是快手用于参考素材引导视频生成的模型,由可灵 AI 于 2026 年 10 月发布。它将最多 10 张图片、5 个参考视频和 7 个元素转化为 3–30 秒、720p 或 1080p 的带立体声视频。Omni Reference 输入允许在提示词中以 @Image1、@Video1 或 @Element1 引用每个素材,让身份、场景与动作来自你选择的参考。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Kling 4.0 Reference to Video 提示词中如何引用参考?
按素材在各自列表中的顺序引用:@Image1 表示第一张参考图,@Video2 表示第二个参考视频,@Element1 表示第一个元素。并写明各自的作用,例如“@Image1 是角色,@Video1 是舞蹈动作”。
Kling 4.0 Reference to Video 的参考视频如何计费?
包含参考视频或视频元素时,按更低的费率(720p 每秒 17 点数、1080p 每秒 25.5 点数)乘以计费秒数收费:输出秒数加上输出秒数与输入视频总时长(向上取整)中的较大者。10 秒 720p 视频配 3 秒参考视频,计费 20 秒,共 340 点数($1.70)。
Kling 4.0 Reference to Video 中的元素是什么?
元素是可复用的主体:用 element_input_urls 提供同一角色或物体的 2–4 张图片,或用 element_input_video_urls 提供 1 个视频。一次请求最多 7 个元素,其中视频元素最多 3 个。
Kling 4.0 Reference to Video 最多能用多少参考?
素材合计最多 15 个:图片(含可选起始帧)最多 10 张、参考视频 5 个、元素 7 个。每个输入视频 3–30 秒,合计不超过 30 秒。
Kling 4.0 Reference to Video 仅用图片参考时如何计费?
仅使用图片和图片元素时,计费与文生视频相同:720p 每输出秒 28.5 点数,1080p 每秒 42.5 点数。8 秒 720p 视频为 228 点数($1.14)。
Kling 4.0 Reference to Video 能从指定画面开场吗?
可以。在 image_urls 中放入一张图片作为开场画面,与参考素材一起使用;它计入 10 张图片的上限。















