参考生视频

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

POST https://platform.shuyanai.com/vidu/ent/v2/reference2video

请求头

头部	必填	说明
`Content-Type`	是	`application/json`
`Authorization`	是	`Bearer sk-xxx`

方式一：使用主体调用

通过 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 个字符。可通过 `@主体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–16 秒）：默认 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` 上传视频时最多 4 张图支持 png、jpeg、jpg、webp 格式，像素不小于 128×128
`videos`	Array[String]	否	参考视频，仅 `viduq2-pro` 支持。最多 1 个 8 秒视频或 2 个 5 秒视频，格式 mp4、avi、mov，大小不超过 100 MB
`prompt`	String	是	文本提示词，不超过 2000 个字符
`audio`	Bool	否	是否使用音视频直出。非主体调用时仅 q3 模型支持，默认 `true`
`bgm`	Bool	否	是否添加背景音乐，默认 `false`。注：q2 系列 duration 为 9 秒或 10 秒时不生效；q3 系列不生效
`duration`	Int	否	视频时长（秒）： - `viduq3-turbo`、`viduq3-mix`、`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–16 秒）：默认 720p，可选 720p、1080p - `viduq3-turbo`、`viduq3`（3–16 秒）：默认 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	本次调用消耗的 Vidu 积分数
`watermark`	Bool	是否使用水印
`created_at`	String	任务创建时间

响应示例

{
  "task_id": "{task_id}",
  "state": "created",
  "model": "viduq3-turbo",
  "images": ["https://example.com/ref1.png", "https://example.com/ref2.png"],
  "prompt": "圣诞老人和小熊在湖边拥抱",
  "duration": 5,
  "seed": 123456,
  "aspect_ratio": "16:9",
  "resolution": "720p",
  "credits": 8,
  "created_at": "2025-01-01T15:41:31.968916Z"
}

任务创建后，使用查询任务接口获取生成结果。

03-参考生视频

参考生视频#

请求头#

方式一：使用主体调用#

请求体#

请求示例（主体调用）#

方式二：非主体调用#

请求体#

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

响应参数#

响应示例#

参考生视频

请求头

方式一：使用主体调用

请求体

请求示例（主体调用）

方式二：非主体调用

请求体

请求示例（非主体调用）

响应参数

响应示例