Vidu参考生视频API-主体参考一致性视频-AutoRouter

基于主体或参考图/视频生成主体一致的视频。异步任务接口，提交后返回 task_id，需轮询生成物接口获取结果。

基于主体库或参考图/视频生成主体一致的视频。同一接口支持两种调用方式：

使用主体调用：通过 subjects 定义图片/视频/文字主体，提示词中用 @主体name 引用
非主体调用：直接传入 images / videos 作为参考

异步任务型接口：提交后立即返回 task_id，需轮询查询生成物接口获取结果。

Base URL

https://api.autorouter.top — Production

Authentication

BearerAuth: http (bearer) 使用 Bearer Token 认证。格式: Authorization: Bearer sk-xxxxxx

Endpoints

POST `/vidu/ent/v2/reference2video`

创建参考生视频任务

使用主体调用

Example:

{
  "model": "viduq3",
  "subjects": [
    {
      "name": "your_subject1_name",
      "images": ["your_image_url1", "your_image_url2", "your_image_url3"],
      "voice_id": ""
    },
    {
      "name": "your_subject2_name",
      "images": ["your_image_url4", "your_image_url5", "your_image_url6"],
      "voice_id": ""
    }
  ],
  "prompt": "@your_subject1_name 和 @your_subject2_name 在一起吃火锅，并且旁白音说火锅大家都爱吃。",
  "duration": 8,
  "audio": true
}

Properties:

Name	Type	Required	Description
`model`	string	Yes	模型名称。可选值：`viduq3-turbo`、`viduq3`、`viduq2-pro`、`viduq2`、`viduq1`、`vidu2.0`。`viduq3-mix` 暂不支持使用主体
`auto_subjects`	boolean	No	是否使用智能主体库，默认 `false`
`subjects`	array	Yes	主体列表。q3 / q2 / q1 / 2.0：图片或文字主体最多 7 个；q2-pro：图片或文字主体最多 4 个，视频主体最多 2 个（临时视频主体最多 1 个）
`subjects[].name`	string	Yes	主体 ID，提示词中通过 `@主体name` 引用
`subjects[].images`	string[]	No	主体图片，与 `videos` 必填其一。最多 3 张；支持 URL 或 Base64；格式 png/jpeg/jpg/webp；比例小于 1:4 或 4:1；decode 后 ≤ 20 MB
`subjects[].videos`	string[]	No	主体视频，仅 `viduq2-pro` 支持。与 `images` 必填其一。每个主体图片与视频共享 3 个槽位；支持 1 个 5 秒视频；格式 mp4/avi/mov；像素 ≥ 128×128
`subjects[].voice_id`	string	No	音色 ID。q3 参考生模型中不生效
`subjects[].server_id`	string	No	已有主体库中的主体 ID，使用已有主体时必传
`prompt`	string	Yes	文本提示词，不超过 5000 字符。可通过 `@主体name` 引用主体
`audio`	boolean	No	是否音视频直出。默认 `false`；`viduq3` / `viduq3-turbo` 默认 `true`
`audio_type`	string	No	音频类型，`audio` 为 `true` 时必填，默认 `all`。可选：`all`、`speech_only`、`sound_effect_only`
`duration`	integer	No	视频时长。`viduq3-turbo` / `viduq3`：默认 5，可选 3–16；`viduq2-pro`：默认 5，可选 0–10（0 为自动判断）；`viduq2`：默认 5，可选 1–10；`viduq1`：仅 5；`vidu2.0`：仅 4
`seed`	integer	No	随机种子。不传或传 `0` 时使用随机数
`aspect_ratio`	string	No	比例，默认 `16:9`。可选：`16:9`、`9:16`、`1:1`。q2 模型支持任意宽高比
`resolution`	string	No	分辨率，默认值依模型而定
`movement_amplitude`	string	No	运动幅度，默认 `auto`。q2、q3 不生效
`payload`	string	No	透传参数，最多 1048576 个字符
`off_peak`	boolean	No	错峰模式。q3 在 `audio=true` 时支持；q2 / q1 / 2.0 在 `audio=false` 时支持
`watermark`	boolean	No	是否添加水印，默认不加
`wm_position`	integer	No	水印位置：`1` 左上、`2` 右上、`3` 右下（默认）、`4` 左下
`wm_url`	string	No	自定义水印图片 URL
`meta_data`	string	No	元数据标识，JSON 格式字符串
`callback_url`	string	No	任务状态变化时的回调地址（POST）

非主体调用（视频生成）

Example:

{
  "model": "viduq3-mix",
  "images": [
    "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-1.png",
    "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-2.png",
    "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-3.png"
  ],
  "prompt": "Santa Claus and the bear hug by the lakeside.",
  "duration": 5,
  "seed": 0,
  "aspect_ratio": "3:4",
  "resolution": "720p"
}

Properties:

Name	Type	Required	Description
`model`	string	Yes	模型名称。可选值：`viduq3-mix`、`viduq3-turbo`、`viduq3`、`viduq2-pro`、`viduq2`、`viduq1`、`vidu2.0`
`images`	string[]	Yes	图像参考，1–7 张。`viduq2-pro` 若不上传视频支持 1–7 张，若上传视频则支持 1–4 张。格式 png/jpeg/jpg/webp；像素 ≥ 128×128；比例小于 1:4 或 4:1；大小 ≤ 50 MB；请求体 ≤ 20 MB
`videos`	string[]	No	视频参考，仅 `viduq2-pro` 支持。最多 1 个 8 秒或 2 个 5 秒视频；格式 mp4/avi/mov；大小 ≤ 100 MB
`prompt`	string	Yes	文本提示词，不超过 2000 字符
`audio`	boolean	No	是否音视频直出，默认 `true`。非主体调用时仅 q3 系列支持
`bgm`	boolean	No	是否添加 BGM，默认 `false`。q2 在 duration 为 9 或 10 秒时不生效；q3 不生效
`duration`	integer	No	视频时长。`viduq3-mix` / `viduq3-turbo` / `viduq3`：默认 5，可选 3–16；其余同主体调用
`seed`	integer	No	随机种子
`aspect_ratio`	string	No	比例，默认 `16:9`。可选：`16:9`、`9:16`、`4:3`、`3:4`、`1:1`。`4:3`、`3:4` 仅 q2 系列
`resolution`	string	No	分辨率，默认值依模型而定
`movement_amplitude`	string	No	运动幅度，默认 `auto`。q2、q3 不生效
`payload`	string	No	透传参数
`off_peak`	boolean	No	错峰模式。`viduq3-mix` 不支持错峰
`watermark`	boolean	No	是否添加水印
`wm_position`	integer	No	水印位置
`wm_url`	string	No	自定义水印图片 URL
`meta_data`	string	No	元数据标识
`callback_url`	string	No	回调地址

Responses

200: 成功创建任务

Content-Type: application/json

400: 请求参数错误

Content-Type: application/json

429: 请求频率限制

Content-Type: application/json

请求示例

curl -X POST "https://api.autorouter.top/vidu/ent/v2/reference2video" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "viduq3-mix",
  "images": [
    "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-1.png",
    "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-2.png",
    "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-3.png"
  ],
  "prompt": "Santa Claus and the bear hug by the lakeside.",
  "duration": 5,
  "seed": 0,
  "aspect_ratio": "3:4",
  "resolution": "720p"
}'

响应示例

{
  "task_id": "your_task_id_here",
  "state": "created",
  "model": "viduq3-mix",
  "images": [
    "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-1.png",
    "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-2.png",
    "https://prod-ss-images.s3.cn-northwest-1.amazonaws.com.cn/vidu-maas/template/reference2video-3.png"
  ],
  "prompt": "Santa Claus and the bear hug by the lakeside.",
  "duration": 5,
  "seed": 123456,
  "aspect_ratio": "3:4",
  "resolution": "720p",
  "credits": 4,
  "created_at": "2025-01-01T15:41:31.968916Z"
}

响应字段说明：

Name	Type	Description
`task_id`	string	任务 ID
`state`	string	处理状态：`created`、`queueing`、`processing`、`success`、`failed`
`model`	string	模型名称
`prompt`	string	提示词
`images`	string[]	图像参数
`videos`	string[]	视频参数（非主体调用）
`duration`	integer	视频时长
`seed`	integer	随机种子
`aspect_ratio`	string	画面比例
`resolution`	string	分辨率
`bgm`	boolean	是否 BGM
`audio`	boolean	是否音视频直出
`audio_type`	string	音频类型
`movement_amplitude`	string	运动幅度
`payload`	string	透传参数
`off_peak`	boolean	是否错峰
`credits`	integer	消耗积分
`watermark`	boolean	是否水印
`created_at`	string	创建时间

GET `/vidu/ent/v2/tasks/{id}/creations`

查询生成物

详见查询生成物接口。

请求示例

curl -X GET "https://api.autorouter.top/vidu/ent/v2/tasks/{task_id}/creations" \
  -H "Authorization: Bearer sk-xxxxxx"

错误处理

HTTP 400 参数错误（提交前拦截，不扣费）

场景	响应
未传 `prompt`	`{"code":"InvalidParameter","message":"...","request_id":"..."}`
主体调用未传 `subjects` / 非主体调用未传 `images`	`{"code":"InvalidParameter","message":"...","request_id":"..."}`
未知模型名	`{"code":"InvalidParameter","message":"unknown model: ...","request_id":"..."}`

HTTP 401 / 403 鉴权错误

401 Unauthorized：API Key 无效或已过期
403 Forbidden：API Key 无权访问此模型

HTTP 402 余额不足

返回 insufficient user quota。请前往 AutoRouter 控制台充值。

任务 `failed` 状态

任务失败时见 err_code。失败时 AutoRouter 会自动退款。

参考生视频

目录