Vidu Reference-to-Video API

Generate subject-consistent video from subjects or reference images/videos. Async task API: submit a request, receive a task_id, then poll the [Query Creations endpoint](./creations) for the result.

Generate subject-consistent video from a subject library or reference images/videos. The same endpoint supports two calling modes:

Subject-based call: Define image/video/text subjects via subjects, reference them in the prompt with @subjectname
Non-subject call: Pass images / videos directly as references

This is an async task-based API: submit a request to receive a task_id, then poll the Query Creations endpoint for the result.

Base URL

https://api.autorouter.top — Production

Authentication

BearerAuth: http (bearer) Authenticate using a Bearer Token. Format: Authorization: Bearer sk-xxxxxx

Endpoints

POST `/vidu/ent/v2/reference2video`

Create Reference-to-Video Task

Subject-Based Call

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	Model name. Available values: `viduq3-turbo`, `viduq3`, `viduq2-pro`, `viduq2`, `viduq1`, `vidu2.0`. `viduq3-mix` does not support subjects
`auto_subjects`	boolean	No	Whether to use the smart subject library, default `false`
`subjects`	array	Yes	Subject list. q3 / q2 / q1 / 2.0: up to 7 image or text subjects; q2-pro: up to 4 image or text subjects, up to 2 video subjects (up to 1 temporary video subject)
`subjects[].name`	string	Yes	Subject ID, referenced in the prompt via `@subjectname`
`subjects[].images`	string[]	No	Subject images; one of `images` or `videos` is required. Up to 3 images; supports URL or Base64; formats png/jpeg/jpg/webp; aspect ratio less than 1:4 or 4:1; ≤ 20 MB after decode
`subjects[].videos`	string[]	No	Subject videos, supported only on `viduq2-pro`. One of `images` or `videos` is required. Images and videos share 3 slots per subject; supports 1 five-second video; formats mp4/avi/mov; pixels ≥ 128×128
`subjects[].voice_id`	string	No	Voice ID. Not effective in q3 reference-to-video models
`subjects[].server_id`	string	No	Subject ID from an existing subject library; required when using an existing subject
`prompt`	string	Yes	Text prompt, up to 5,000 characters. Reference subjects via `@subjectname`
`audio`	boolean	No	Whether to output audio and video together. Default `false`; default `true` for `viduq3` / `viduq3-turbo`
`audio_type`	string	No	Audio type, required when `audio` is `true`, default `all`. Available: `all`, `speech_only`, `sound_effect_only`
`duration`	integer	No	Video duration. `viduq3-turbo` / `viduq3`: default 5, range 3–16; `viduq2-pro`: default 5, range 0–10 (0 means auto-detect); `viduq2`: default 5, range 1–10; `viduq1`: only 5; `vidu2.0`: only 4
`seed`	integer	No	Random seed. Uses a random value if omitted or set to `0`
`aspect_ratio`	string	No	Aspect ratio, default `16:9`. Available: `16:9`, `9:16`, `1:1`. q2 models support arbitrary aspect ratios
`resolution`	string	No	Resolution, default depends on model
`movement_amplitude`	string	No	Motion amplitude, default `auto`. Not effective on q2 and q3
`payload`	string	No	Passthrough parameter, up to 1,048,576 characters
`off_peak`	boolean	No	Off-peak mode. Supported on q3 when `audio=true`; supported on q2 / q1 / 2.0 when `audio=false`
`watermark`	boolean	No	Whether to add a watermark, not added by default
`wm_position`	integer	No	Watermark position: `1` top-left, `2` top-right, `3` bottom-right (default), `4` bottom-left
`wm_url`	string	No	Custom watermark image URL
`meta_data`	string	No	Metadata identifier, JSON format string
`callback_url`	string	No	Callback URL (POST) when task status changes

Non-Subject Call (Video Generation)

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	Model name. Available values: `viduq3-mix`, `viduq3-turbo`, `viduq3`, `viduq2-pro`, `viduq2`, `viduq1`, `vidu2.0`
`images`	string[]	Yes	Image references, 1–7 images. `viduq2-pro` supports 1–7 images if no video is uploaded, or 1–4 if a video is uploaded. Formats png/jpeg/jpg/webp; pixels ≥ 128×128; aspect ratio less than 1:4 or 4:1; size ≤ 50 MB; request body ≤ 20 MB
`videos`	string[]	No	Video references, supported only on `viduq2-pro`. Up to 1 eight-second video or 2 five-second videos; formats mp4/avi/mov; size ≤ 100 MB
`prompt`	string	Yes	Text prompt, up to 2,000 characters
`audio`	boolean	No	Whether to output audio and video together, default `true`. Supported only on q3 series for non-subject calls
`bgm`	boolean	No	Whether to add BGM, default `false`. Not effective on q2 when duration is 9 or 10 seconds; not effective on q3
`duration`	integer	No	Video duration. `viduq3-mix` / `viduq3-turbo` / `viduq3`: default 5, range 3–16; others same as subject-based call
`seed`	integer	No	Random seed
`aspect_ratio`	string	No	Aspect ratio, default `16:9`. Available: `16:9`, `9:16`, `4:3`, `3:4`, `1:1`. `4:3` and `3:4` supported only on q2 series
`resolution`	string	No	Resolution, default depends on model
`movement_amplitude`	string	No	Motion amplitude, default `auto`. Not effective on q2 and q3
`payload`	string	No	Passthrough parameter
`off_peak`	boolean	No	Off-peak mode. `viduq3-mix` does not support off-peak
`watermark`	boolean	No	Whether to add a watermark
`wm_position`	integer	No	Watermark position
`wm_url`	string	No	Custom watermark image URL
`meta_data`	string	No	Metadata identifier
`callback_url`	string	No	Callback URL

Responses

200: Task created successfully

Content-Type: application/json

400: Bad request / invalid parameters

Content-Type: application/json

429: Rate limit exceeded

Content-Type: application/json

Request Example

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"
}'

Response Example

{
  "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"
}

Response fields:

Name	Type	Description
`task_id`	string	Task ID
`state`	string	Processing status: `created`, `queueing`, `processing`, `success`, `failed`
`model`	string	Model name
`prompt`	string	Prompt
`images`	string[]	Image parameters
`videos`	string[]	Video parameters (non-subject call)
`duration`	integer	Video duration
`seed`	integer	Random seed
`aspect_ratio`	string	Aspect ratio
`resolution`	string	Resolution
`bgm`	boolean	Whether BGM was used
`audio`	boolean	Whether audio and video were output together
`audio_type`	string	Audio type
`movement_amplitude`	string	Motion amplitude
`payload`	string	Passthrough parameter
`off_peak`	boolean	Whether off-peak mode was used
`credits`	integer	Credits consumed
`watermark`	boolean	Whether a watermark was added
`created_at`	string	Creation time

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

Query Creations

See the Query Creations endpoint for details.

Request Example

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

Error Handling

HTTP 400 Parameter Errors (pre-submit validation, no billing)

Scenario	Response
Missing `prompt`	`{"code":"InvalidParameter","message":"...","request_id":"..."}`
Subject call missing `subjects` / non-subject call missing `images`	`{"code":"InvalidParameter","message":"...","request_id":"..."}`
Unknown model	`{"code":"InvalidParameter","message":"unknown model: ...","request_id":"..."}`

HTTP 401 / 403 Auth Errors

401 Unauthorized: API Key invalid or expired
403 Forbidden: API Key has no access to this model

HTTP 402 Insufficient Balance

Returns insufficient user quota. Top up at the AutoRouter console.

Task `failed` Status

See err_code when the task fails. When a task enters failed, AutoRouter automatically refunds the billed quota.

Reference-to-Video

On this page