该接口可以根据图片或视频主体参考生成视频。

请求信息

请求 URL

POST /hub/vidu/v2/reference2video

请求头

Header	必填	示例值
Authorization	是	Bearer sk-xxxxx
Content-Type	是	application/json; charset=utf-8

主体调用请求体

字段	类型	必填	说明
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	object[]	是	主体信息数组。支持 1-7 个主体
name	string	是	主体名称，可在 prompt 中用 @name 引用
images	string[]	否	主体图片。与 videos 至少传一个；单主体图片和视频共享槽位，通常最多 3 个
videos	string[]	否	主体视频。仅部分模型支持，通常最多 1 个 5 秒视频
voice_id	string	否	主体音色 ID
server_id	string	否	通过创建主体 API 获取的主体 ID，使用已有主体时必传该参数
prompt	string	是	文本提示词，最长 2000 字符。可通过 @主体名 引用主体
audio	bool	否	是否启用音视频直出，默认 false
audio_type	string	否	音频类型。audio=true 时使用，常见值：all、speech_only、sound_effect_only
duration	int	否	视频时长。不同模型支持不同；viduq2-pro 常见可选 0-10，其中 0 表示自动判断
seed	int	否	随机种子。传 0 或不传时自动生成
aspect_ratio	string	否	画面比例，默认 16:9。常见值：16:9、9:16、1:1
resolution	string	否	输出分辨率，常见值：360p、540p、720p、1080p
movement_amplitude	string	否	运动幅度，默认 auto。常见值：auto、small、medium、large
payload	string	否	透传字段，最长 1048576 字符
off_peak	bool	否	是否启用错峰模式。音视频直出通常不支持
watermark	bool	否	是否添加水印
wm_position	int	否	水印位置。可选值：1、2、3、4；默认 3
wm_url	string	否	自定义水印图片地址
meta_data	string	否	元数据标识，JSON 字符串，透传使用
callback_url	string	否	任务状态回调地址，具体规范请参考 回调签名与验签规范

非主体调用请求体

字段	类型	必填	说明
model	string	是	模型名称。常见可选值：viduq2-pro、viduq2、viduq1、vidu2.0
images	string[]	是	参考图片。常见支持 1-7 张；部分模型在同时上传视频时上限更低
videos	string[]	是	参考视频。仅部分模型支持，常见支持 1 个 8 秒视频或 2 个 5 秒视频
prompt	string	是	文本提示词，最长 2000 字符
audio	bool	否	是否使用音视频直出能力，默认为 true，使用
bgm	bool	否	是否添加背景音乐，默认 false
duration	int	否	视频时长，默认值与模型有关
seed	int	否	随机种子。传 0 或不传时自动生成
aspect_ratio	string	否	画面比例，默认 16:9。常见值：16:9、9:16、4:3、3:4、1:1
resolution	string	否	输出分辨率，常见值：360p、540p、720p、1080p
movement_amplitude	string	否	运动幅度，默认 auto
payload	string	否	透传字段，最长 1048576 字符
off_peak	bool	否	是否启用错峰模式
watermark	bool	否	是否添加水印
wm_position	int	否	水印位置。可选值：1、2、3、4；默认 3
wm_url	string	否	自定义水印图片地址
meta_data	string	否	元数据标识，JSON 字符串，透传使用
callback_url	string	否	任务状态回调地址，具体规范请参考 回调签名与验签规范

主体调用请求示例

json{
  "model": "viduq2",
  "subjects": [
    {
      "name": "hero",
      "images": [
        "https://example.com/hero-1.png",
        "https://example.com/hero-2.png"
      ],
      "voice_id": "voice_hero"
    }
  ],
  "prompt": "@hero 在餐厅里向镜头微笑并开口讲话。",
  "audio": true,
  "audio_type": "all",
  "duration": 8,
  "resolution": "720p"
}

非主体调用请求示例

json{
  "model": "viduq2-pro",
  "images": [
    "https://example.com/ref-1.png",
    "https://example.com/ref-2.png"
  ],
  "videos": [
    "https://example.com/ref-video.mp4"
  ],
  "prompt": "圣诞老人和棕熊在湖边相拥。",
  "duration": 5,
  "aspect_ratio": "3:4",
  "resolution": "540p"
}

响应信息

响应体

字段	类型	说明
task_id	string	任务 ID
state	string	任务状态。常见值：created、queueing、processing、success、failed
model	string	模型名称
prompt	string	提示词
images	string[]	输入图片
videos	string[]	输入视频
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	string	消耗量
created_at	string	创建时间

响应示例

json{
  "task_id": "tsk_1234567893",
  "state": "created",
  "model": "viduq2-pro",
  "prompt": "圣诞老人和棕熊在湖边相拥。",
  "images": [
    "https://example.com/ref-1.png",
    "https://example.com/ref-2.png"
  ],
  "videos": [
    "https://example.com/ref-video.mp4"
  ],
  "duration": 5,
  "seed": 22334455,
  "aspect_ratio": "3:4",
  "resolution": "540p",
  "bgm": false,
  "audio": false,
  "movement_amplitude": "auto",
  "payload": "",
  "off_peak": false,
  "credits": "20.000000",
  "created_at": "2026-04-16T09:33:00Z"
}

错误码

完整列表请参考客户端 API 错误码。