Vidu Q4 Reference to Video API
vidu/q4/reference-to-videoVidu Q4 Reference to Video 将提示词与最多 12 张参考图、3 段语音组合,生成最高 4K 的 3–16 秒视频。在提示词中标注各参考素材,让人物、产品和场景保持可辨识,音频生成不额外计费。
拖拽文件、粘贴剪贴板素材,或输入 URL。 必填,1–12 张 JPEG、PNG 或 WebP 图片。
2/12 个素材
拖拽文件、粘贴剪贴板素材,或输入 URL。 可选,最多 3 段 MP3 语音,建议每段 3–12 秒。
REST API
快速开始
三步完成首个 Vidu Q4 参考生视频请求。示例在提示词中标注两张参考图,并返回 task_id。
连接 Vidgo API
创建 API Key,将它安全保存在服务端,并通过 Authorization 请求头以 Bearer Token 发送。
- 接口地址
- POST
https://api.vidgo.ai/api/generate/submit - 认证方式
- Authorization: Bearer VIDGO_API_KEY
提交一个生成任务
使用提示词和至少 1 张参考图运行短示例,语音片段可选。
curl --request POST \
--url "https://api.vidgo.ai/api/generate/submit" \
--header "Authorization: Bearer $VIDGO_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "vidu/q4/reference-to-video",
"input": {
"prompt": "[@reference_image_1] is the shop owner, [@reference_image_2] is her corner bookshop at dusk. She slides the last paperback onto the shelf, flips the hanging sign on the door and smiles at the street outside. Soft rain on the window, a bell rings as the door closes. One continuous medium shot with a slow dolly to the right.",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/vidu/q4/reference-to-video/v1/01/input-01.png",
"https://cdn.vidgo.ai/apis/models/vidu/q4/reference-to-video/v1/01/input-02.png"
],
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"generate_audio": true
}
}'等待并获取结果
使用返回的 task_id 查询同一个任务,直到状态变为 finished 或 failed;成功后读取 data.files[].file_url。
查询状态
GET https://api.vidgo.ai/api/generate/status/{task_id}当状态为 not_started 或 running 时,建议约每 2 秒轮询一次;到达 finished 或 failed 后停止。成功时从 data.files[].file_url 读取视频地址;长任务可逐步延长间隔,也可在提交请求顶层添加 callback_url 异步接收最终结果。
not_startedrunningfinishedfailed{
"code": 200,
"data": {
"task_id": "KJ245166VBTPWOAM",
"status": "not_started",
"created_time": "2026-11-05T07:10:52"
}
}{
"code": 200,
"data": {
"task_id": "KJ245166VBTPWOAM",
"status": "finished",
"files": [
{
"file_url": "https://cdn.vidgo.ai/apis/models/vidu/q4/reference-to-video/v2/01/output-01.mp4",
"file_type": "video"
}
],
"created_time": "2026-11-05T07:10:52",
"error_message": null,
"progress": 100
}
}完整可运行示例
理解上面的三步流程后再展开。这里把提交、轮询、终态处理和结果读取合并在一个脚本中。
set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"
REQUEST_BODY=$(cat <<'JSON'
{
"model": "vidu/q4/reference-to-video",
"input": {
"prompt": "[@reference_image_1] is the shop owner, [@reference_image_2] is her corner bookshop at dusk. She slides the last paperback onto the shelf, flips the hanging sign on the door and smiles at the street outside. Soft rain on the window, a bell rings as the door closes. One continuous medium shot with a slow dolly to the right.",
"reference_image_urls": [
"https://cdn.vidgo.ai/apis/models/vidu/q4/reference-to-video/v1/01/input-01.png",
"https://cdn.vidgo.ai/apis/models/vidu/q4/reference-to-video/v1/01/input-02.png"
],
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"generate_audio": 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')
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 | 是 | — | 固定为 vidu/q4/reference-to-video。 |
| callback_url | string (URL) | 否 | — | 用于接收任务完成通知的公开 HTTP(S) 地址。 |
| input | object | 是 | — | 生成参数:提示词 + 1–12 张参考图,可选语音片段、画幅与音频生成。 |
| input.prompt | string | 是 | — | 场景描述,最多 5,000 个字符且不能为空。可用 [@reference_image_1]、[@reference_audio_1] 等按数组顺序指代素材。 |
| input.reference_image_urls | string[] | 是 | — | 1–12 个公开 HTTP(S) 图片地址,用于人物、产品和场景。 |
| input.reference_audio_urls | string[] | 否 | — | 最多 3 个公开 HTTP(S) 音频地址,作为语音参考。推荐约 3–12 秒、干净的 MP3 片段。 |
| input.duration | integer | 否 | 5 | 输出时长,3–16 的整数秒;也接受 "5" 这样的整数字符串。 |
| input.resolution | string | 否 | 720p | 输出分辨率:540p、720p、1080p、2k 或 4k(不区分大小写),每秒费率随之变化。 |
| input.aspect_ratio | string | 否 | — | 16:9、9:16、4:3、3:4 或 1:1;不传时沿用模型默认值。 |
| input.generate_audio | boolean | 否 | — | 设为 true 生成音轨,价格不变。 |
| input.enable_safety_checker | boolean | 否 | — | 设为 true 或 false 控制内容安全检查;不传时沿用模型默认行为。 |
响应字段
提交响应会立即返回任务标识;随着任务推进,状态响应会补充进度、输出文件或失败信息。
| 字段 | 类型 | 说明 |
|---|---|---|
| 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 表示参数不合法。请检查提示词、1–12 张图片与 0–3 段音频的数量,并确认未发送 image_urls。
- 轮询间隔建议每 2 秒查询一次状态,长任务可按指数退避逐步延长间隔至 5 秒。
- 终态处理仅在 not_started 或 running 时轮询;收到 finished 或 failed 立即终止。
- 回调方式提供 callback_url 可以在生成完成时自动接收推送,无需持续轮询。
模型规格
| 规格 | 取值 | 说明 |
|---|---|---|
| 模型 | vidu/q4/reference-to-video | Vidu Q4 异步参考生视频的模型标识。 |
| 输入方式 | 提示词 + 1–12 张图 + 0–3 段音频 | 提示词中的参考标签按数组顺序编号。 |
| 画幅 | 16:9 | 9:16 | 4:3 | 3:4 | 1:1 | 可选。 |
| 时长 | 3–16 | 整数秒,默认 5 秒。 |
| 分辨率 | 540p | 720p | 1080p | 2k | 4k | 默认 720p。 |
| 价格 | 9 / 19 / 24 / 38 / 78 积分/秒 | 依次对应 540p / 720p / 1080p / 2k / 4k,乘以时长。 |
相关模型
Vidu Q4 Reference to Video API 常见问题
Vidu Q4 Reference to Video API 是什么?
Vidu Q4 Reference to Video 是生数科技用于根据参考素材生成视频的模型。它根据提示词、1–12 张参考图和最多 3 段语音,生成最高 4K 的 3–16 秒视频,支持五种画幅和可选音频生成。提示词标签把每个参考素材绑定到具体角色,让人物、产品和场景在剧情展开时保持可辨识。你可以通过 API 进行程序化调用,也可以在上方体验区直接在线试用。
Vidu Q4 Reference to Video 最多支持多少张参考图?
reference_image_urls 支持 1–12 张图片。为每个人物、产品或地点使用单独图片,并在提示词中按编号指代。
Vidu Q4 Reference to Video 的语音参考怎么用?
在 reference_audio_urls 中添加最多 3 段音频,并在应说话的角色旁写 [@reference_audio_1] 等标签。推荐约 3–12 秒、干净的 MP3 片段。
如何在 Vidu Q4 Reference to Video 提示词中标注参考素材?
在元素应出现或发声的位置写 [@reference_image_1]、[@reference_image_2] 或 [@reference_audio_1],编号与各数组顺序一致。
Vidu Q4 Reference to Video 开启音频会额外收费吗?
不会。generate_audio、参考图和参考音频都不改变费率;积分 = 分辨率费率 × 时长,例如 720p 5 秒为 95 积分。
Vidu Q4 Reference to Video 支持哪些画幅?
通过 aspect_ratio 选择 16:9、9:16、4:3、3:4 或 1:1;不设置时沿用模型默认值。
Vidu Q4 Reference to Video 一次能生成多长?
3–16 个整数秒,默认 5 秒,可选 540p、720p、1080p、2k 或 4k。
什么时候该选 Vidu Q4 Reference to Video 而不是 Image to Video?
当需要多个人物、产品或地点同时出现、需要语音参考或固定画幅时,选择 Reference to Video;Image to Video 从一张确定的画面开始。















