Reference-to-Video

Document Version: v1.0.0 | Last Updated: 2026-06-11
This platform fully supports the official Vidu video generation APIs. Requests and responses are transparently proxied with identical parameter semantics.

Generate video with subject consistency from reference images/videos, with support for subject libraries. This endpoint supports two invocation modes: Subject-based invocation (via the subjects parameter) and Non-subject invocation (via the images/videos parameters).

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

Request Parameters

Request Headers

Header	Required	Description
`Content-Type`	Yes	`application/json`
`Authorization`	Yes	`Bearer {API_KEY}`

Mode 1: Subject-Based Invocation

Pass subject information via the subjects parameter and reference them in the prompt using @subject_name.

Request Body

Parameter	Sub-parameter	Type	Required	Description
`model`		String	Yes	Model name. Options: `viduq3-turbo`, `viduq3`, `viduq2-pro`, `viduq2`, `viduq1`, `vidu2.0`. - `viduq3-turbo`: Supports smart scene cutting, audio-video output, fastest generation - `viduq3`: Supports smart scene cutting, audio-video output, superior multi-angle consistency - `viduq2-pro`: Supports reference video, video editing, video replacement - `viduq2`: Good dynamic effects, rich details - `viduq1`: Clear visuals, smooth transitions, stable camera movement - `vidu2.0`: Fast generation speed
`auto_subjects`		Bool	Optional	Whether to use the smart subject library capability. Default `false`.
`subjects`		Array	Yes	Subject list. q3/q2/q1/2.0 models support image and text subjects only (max 7); q2-pro additionally supports video subjects (max 4 images/text, max 2 videos).
	`name`	String	Yes	Subject name. Referenced in the prompt via `@name`.
	`images`	Array[String]	Optional	Subject image URLs or Base64. Max 3 images. At least one of `images` or `videos` must be provided. Supported formats: png, jpeg, jpg, webp. Base64 must include content type prefix.
	`videos`	Array[String]	Optional	Subject video URLs or Base64. At least one of `images` or `videos` must be provided. Only supported by `viduq2-pro`; supports 1 video of 5 seconds. Supported formats: mp4, avi, mov.
	`voice_id`	String	Optional	Voice ID. If empty, the system automatically recommends a voice. Ineffective for q3 reference models.
	`server_id`	String	Optional	Subject ID obtained via the Create Subject API. Required when using an existing subject.
`prompt`		String	Yes	Text prompt. Maximum 5000 characters. When using subjects, reference them via `@subject_name`, e.g.: `"@CharacterA and @CharacterB are having hotpot together"`
`audio`		Bool	Optional	Whether to enable audio-video output. Default `true` for viduq3 and viduq3-turbo, `false` for other models.
`audio_type`		String	Optional	Audio type, effective when `audio` is `true`. Default `all`. Options: `all` (sound effects + voice), `speech_only` (voice only), `sound_effect_only` (sound effects only)
`duration`		Int	Optional	Video duration (seconds): - `viduq3-turbo`, `viduq3`: Default 5, range 3–16 - `viduq2-pro`: Default 5, range 0–10 (0 for automatic duration) - `viduq2`: Default 5, range 1–10 - `viduq1`: Default 5, fixed at 5 - `vidu2.0`: Default 4, fixed at 4
`seed`		Int	Optional	Random seed. If omitted or set to 0, a random value is used.
`aspect_ratio`		String	Optional	Aspect ratio. Default `16:9`. Options: `16:9`, `9:16`, `1:1`. Note: q2 models support arbitrary aspect ratios
`resolution`		String	Optional	Resolution: - `viduq3-turbo`, `viduq3` (3–16s): Default 720p, options 540p, 720p, 1080p - `viduq2`, `viduq2-pro`: Default 720p, options 540p, 720p, 1080p - `viduq1`: Default 1080p, fixed at 1080p - `vidu2.0`: Default 360p, options 360p, 720p
`movement_amplitude`		String	Optional	Movement amplitude. Default `auto`. Note: Ineffective for q2 and q3 models
`off_peak`		Bool	Optional	Off-peak mode. Default `false`. Note: q3 models support off-peak when audio is true; q2/q1/2.0 series support off-peak when audio is false
`watermark`		Bool	Optional	Whether to add a watermark. Default is no watermark.
`wm_position`		Int	Optional	Watermark position. `1`: Top-left, `2`: Top-right, `3`: Bottom-right (default), `4`: Bottom-left
`wm_url`		String	Optional	Custom watermark image URL.
`payload`		String	Optional	Pass-through parameter. Maximum 1048576 characters.
`meta_data`		String	Optional	Metadata identifier, JSON format string, pass-through field.
`callback_url`		String	Optional	Callback URL.

Request Example (Subject-Based)

Mode 2: Non-Subject Invocation

Directly pass reference images/videos, and the model automatically extracts subject consistency to generate the video.

Request Body

Parameter	Type	Required	Description
`model`	String	Yes	Model name. Options: `viduq3-mix`, `viduq3-turbo`, `viduq3`, `viduq2-pro`, `viduq2`, `viduq1`, `vidu2.0`. - `viduq3-mix`: Strong visual quality, smart scene cutting, audio-video output, best overall balance
`images`	Array[String]	Yes	Reference images. Supports 1–7 images (URL or Base64). Note: `viduq2-pro` model supports max 1–4 images when uploading video Supported formats: png, jpeg, jpg, webp; minimum resolution 128x128
`videos`	Array[String]	Optional	Reference videos. Only supported by `viduq2-pro`. Max 1 video of 8 seconds or 2 videos of 5 seconds. Supported formats: mp4, avi, mov; max size 100M
`prompt`	String	Yes	Text prompt. Maximum 2000 characters.
`audio`	Bool	Optional	Whether to enable audio-video output. Only q3 models support this in non-subject mode; default `true`.
`bgm`	Bool	Optional	Whether to add background music. Default `false`. Note: Ineffective for q2 series when duration is 9s/10s; ineffective for q3 series
`duration`	Int	Optional	Video duration (seconds): - `viduq3-turbo`, `viduq3-mix`: Default 5, range 3–16 - `viduq3`: Default 5, range 3–16 - `viduq2-pro`: Default 5, range 0–10 (0 for automatic duration) - `viduq2`: Default 5, range 1–10 - `viduq1`: Default 5, fixed at 5 - `vidu2.0`: Default 4, fixed at 4
`seed`	Int	Optional	Random seed.
`aspect_ratio`	String	Optional	Aspect ratio. Default `16:9`. Options: `16:9`, `9:16`, `4:3`, `3:4`, `1:1`. Note: `4:3` and `3:4` are only supported by q2 series models
`resolution`	String	Optional	Resolution: - `viduq3-mix` (3–16s): Default 720p, options 720p, 1080p - `viduq3-turbo` (3–16s): Default 720p, options 540p, 720p, 1080p - `viduq3` (3–16s): Default 720p, options 540p, 720p, 1080p - `viduq2`, `viduq2-pro`: Default 720p, options 540p, 720p, 1080p - `viduq1`: Default 1080p, fixed at 1080p - `vidu2.0`: Default 360p, options 360p, 720p
`movement_amplitude`	String	Optional	Movement amplitude. Default `auto`. Note: Ineffective for q2 and q3 series
`off_peak`	Bool	Optional	Off-peak mode. Default `false`. Note: viduq3-mix does not support off-peak mode
`watermark`	Bool	Optional	Whether to add a watermark.
`wm_position`	Int	Optional	Watermark position.
`wm_url`	String	Optional	Custom watermark image URL.
`payload`	String	Optional	Pass-through parameter.
`meta_data`	String	Optional	Metadata identifier.
`callback_url`	String	Optional	Callback URL.

Request Example (Non-Subject)

Response Parameters

Field	Type	Description
`task_id`	String	Task ID
`state`	String	Processing state: `created`, `queueing`, `processing`, `success`, `failed`
`model`	String	Model name used for this call
`prompt`	String	Prompt
`images`	Array[String]	Image parameters
`videos`	Array[String]	Video parameters (returned for non-subject viduq2-pro calls)
`duration`	Int	Video duration
`seed`	Int	Random seed
`aspect_ratio`	String	Aspect ratio
`resolution`	String	Resolution
`bgm`	Bool	Whether background music is added
`audio`	Bool	Whether audio-video output is enabled
`audio_type`	String	Audio type
`movement_amplitude`	String	Movement amplitude
`payload`	String	Pass-through parameter
`off_peak`	Bool	Whether off-peak mode is used
`credits`	Int	Number of credits consumed by this call
`watermark`	Bool	Whether a watermark is used
`created_at`	String	Task creation time

Response Example

{
  "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-Reference-to-Video

Reference-to-Video#

Request Parameters#

Request Headers#

Mode 1: Subject-Based Invocation#

Request Body#

Request Example (Subject-Based)#

Mode 2: Non-Subject Invocation#

Request Body#

Request Example (Non-Subject)#

Response Parameters#

Response Example#

Reference-to-Video

Request Parameters

Request Headers

Mode 1: Subject-Based Invocation

Request Body

Request Example (Subject-Based)

Mode 2: Non-Subject Invocation

Request Body

Request Example (Non-Subject)

Response Parameters

Response Example