参考生视频

文档版本：v1.0.0 | 最后更新：2026-06-11
本平台已完整适配 Vidu 系列官方视频生成接口，请求与响应均为透传，参数语义与官方一致。

以参考图片/视频的主体一致性生成视频，支持主体库功能。该接口包含两种调用方式：使用主体调用（通过 subjects 参数）和非主体调用（通过 images/videos 参数）。

POST https://platform.dataeyes.ai/vidu/ent/v2/reference2video

请求参数

请求头

头部	必填	说明
`Content-Type`	是	`application/json`
`Authorization`	是	`Token {API_KEY}`

方式一：使用主体调用

通过 subjects 参数传入主体信息，在提示词中通过 @主体名称 引用。

请求体

参数	子参数	类型	必填	说明
`model`		String	是	模型名称。可选值：`viduq3-turbo`、`viduq3`、`viduq2-pro`、`viduq2`、`viduq1`、`vidu2.0`。 - `viduq3-turbo`：支持智能切镜，音画同出，生成速度最快 - `viduq3`：支持智能切镜，音画同出，多机位一致性更出色 - `viduq2-pro`：支持参考视频，视频编辑，视频替换 - `viduq2`：动态效果好，细节丰富 - `viduq1`：画面清晰，平滑转场，运镜稳定 - `vidu2.0`：生成速度快
`auto_subjects`		Bool	可选	是否使用智能主体库能力。默认 `false`。
`subjects`		Array	是	主体列表。q3/q2/q1/2.0 模型仅支持图片和文字主体（最多 7 个）；q2-pro 可额外使用视频主体（图片/文字最多 4 个，视频最多 2 个）。
	`name`	String	是	主体名称。后续在 prompt 中通过 `@name` 引用。
	`images`	Array[String]	可选	主体图片 URL 或 Base64。最多 3 张。与 `videos` 至少填一个。支持 png、jpeg、jpg、webp 格式，Base64 须含内容类型前缀。
	`videos`	Array[String]	可选	主体视频 URL 或 Base64。与 `images` 至少填一个。仅 `viduq2-pro` 支持，支持 1 个 5 秒视频。支持 mp4、avi、mov 格式。
	`voice_id`	String	可选	音色 ID。为空时系统自动推荐。q3 参考生模型不生效。
	`server_id`	String	可选	通过创建主体 API 获取的主体 ID，使用已有主体时必传。
`prompt`		String	是	文本提示词。字符长度不超过 5000 个字符。使用 subjects 时可通过 `@主体name` 引用，例如：`"@角色A 和 @角色B 在一起吃火锅"`
`audio`		Bool	可选	是否使用音视频直出。viduq3、viduq3-turbo 默认 `true`，其他模型默认 `false`。
`audio_type`		String	可选	音频类型，`audio` 为 `true` 时生效。默认 `all`。可选值：`all`（音效+人声）、`speech_only`（仅人声）、`sound_effect_only`（仅音效）
`duration`		Int	可选	视频时长（秒）： - `viduq3-turbo`、`viduq3`：默认 5，可选 3–16 - `viduq2-pro`：默认 5，可选 0–10（0 为自动判断时长） - `viduq2`：默认 5，可选 1–10 - `viduq1`：默认 5，可选 5 - `vidu2.0`：默认 4，可选 4
`seed`		Int	可选	随机种子。不传或传 0 时使用随机数。
`aspect_ratio`		String	可选	宽高比。默认 `16:9`，可选值：`16:9`、`9:16`、`1:1`。注：q2 模型支持任意宽高比
`resolution`		String	可选	分辨率： - `viduq3-turbo`、`viduq3`（3–16s）：默认 720p，可选 540p、720p、1080p - `viduq2`、`viduq2-pro`：默认 720p，可选 540p、720p、1080p - `viduq1`：默认 1080p，可选 1080p - `vidu2.0`：默认 360p，可选 360p、720p
`movement_amplitude`		String	可选	运动幅度。默认 `auto`。注：q2、q3 模型不生效
`off_peak`		Bool	可选	错峰模式。默认 `false`。注：q3 模型 audio 为 true 时支持错峰；q2/q1/2.0 系列 audio 为 false 时支持错峰
`watermark`		Bool	可选	是否添加水印。默认不加。
`wm_position`		Int	可选	水印位置。`1`：左上，`2`：右上，`3`：右下（默认），`4`：左下
`wm_url`		String	可选	自定义水印图片 URL。
`payload`		String	可选	透传参数。最多 1048576 个字符。
`meta_data`		String	可选	元数据标识，JSON 格式字符串，透传字段。
`callback_url`		String	可选	回调地址。

请求示例（主体调用）

方式二：非主体调用

直接传入参考图片/视频，模型自动提取主体一致性生成视频。

请求体

参数	类型	必填	说明
`model`	String	是	模型名称。可选值：`viduq3-mix`、`viduq3-turbo`、`viduq3`、`viduq2-pro`、`viduq2`、`viduq1`、`vidu2.0`。 - `viduq3-mix`：画面质感强，智能切镜，音画同出，均衡性最强
`images`	Array[String]	是	参考图片。支持 1–7 张图片（URL 或 Base64）。注：`viduq2-pro` 模型上传视频时最多 1–4 张图支持 png、jpeg、jpg、webp 格式，像素不小于 128×128
`videos`	Array[String]	可选	参考视频。仅 `viduq2-pro` 支持。最多 1 个 8 秒视频或 2 个 5 秒视频。支持 mp4、avi、mov 格式，大小不超过 100M
`prompt`	String	是	文本提示词。字符长度不超过 2000 个字符。
`audio`	Bool	可选	是否使用音视频直出。非主体调用时仅 q3 模型支持，默认 `true`。
`bgm`	Bool	可选	是否添加背景音乐。默认 `false`。注：q2 系列 duration 为 9s/10s 时不生效；q3 系列不生效
`duration`	Int	可选	视频时长（秒）： - `viduq3-turbo`、`viduq3-mix`：默认 5，可选 3–16 - `viduq3`：默认 5，可选 3–16 - `viduq2-pro`：默认 5，可选 0–10（0 为自动判断时长） - `viduq2`：默认 5，可选 1–10 - `viduq1`：默认 5，可选 5 - `vidu2.0`：默认 4，可选 4
`seed`	Int	可选	随机种子。
`aspect_ratio`	String	可选	宽高比。默认 `16:9`，可选值：`16:9`、`9:16`、`4:3`、`3:4`、`1:1`。注：`4:3`、`3:4` 仅支持 q2 系列模型
`resolution`	String	可选	分辨率： - `viduq3-mix`（3–16s）：默认 720p，可选 720p、1080p - `viduq3-turbo`（3–16s）：默认 720p，可选 540p、720p、1080p - `viduq3`（3–16s）：默认 720p，可选 540p、720p、1080p - `viduq2`、`viduq2-pro`：默认 720p，可选 540p、720p、1080p - `viduq1`：默认 1080p，可选 1080p - `vidu2.0`：默认 360p，可选 360p、720p
`movement_amplitude`	String	可选	运动幅度。默认 `auto`。注：q2、q3 系列不生效
`off_peak`	Bool	可选	错峰模式。默认 `false`。注：viduq3-mix 不支持错峰
`watermark`	Bool	可选	是否添加水印。
`wm_position`	Int	可选	水印位置。
`wm_url`	String	可选	自定义水印图片 URL。
`payload`	String	可选	透传参数。
`meta_data`	String	可选	元数据标识。
`callback_url`	String	可选	回调地址。

请求示例（非主体调用）

响应参数

字段	类型	说明
`task_id`	String	任务 ID
`state`	String	处理状态：`created`、`queueing`、`processing`、`success`、`failed`
`model`	String	本次调用的模型名称
`prompt`	String	提示词
`images`	Array[String]	图像参数
`videos`	Array[String]	视频参数（非主体调用 viduq2-pro 时返回）
`duration`	Int	视频时长
`seed`	Int	随机种子
`aspect_ratio`	String	宽高比
`resolution`	String	分辨率
`bgm`	Bool	是否添加背景音乐
`audio`	Bool	是否开启音视频直出
`audio_type`	String	音频类型
`movement_amplitude`	String	运动幅度
`payload`	String	透传参数
`off_peak`	Bool	是否使用错峰模式
`credits`	Int	本次调用消耗的积分数
`watermark`	Bool	是否使用水印
`created_at`	String	任务创建时间

响应示例

{
  "task_id": "{task_id}",
  "state": "created",
  "model": "viduq3-mix",
  "images": ["https://example.com/ref1.png", "https://example.com/ref2.png"],
  "prompt": "Santa Claus and the bear hug by the lakeside.",
  "duration": 5,
  "seed": 123456,
  "aspect_ratio": "3:4",
  "resolution": "720p",
  "credits": 8,
  "created_at": "2025-01-01T15:41:31.968916Z"
}

03-参考生视频

参考生视频#

请求参数#

请求头#

方式一：使用主体调用#

请求体#

请求示例（主体调用）#

方式二：非主体调用#

请求体#

请求示例（非主体调用）#

响应参数#

响应示例#

参考生视频

请求参数

请求头

方式一：使用主体调用

请求体

请求示例（主体调用）

方式二：非主体调用

请求体

请求示例（非主体调用）

响应参数

响应示例