Vidu reference-to-video

Submit a subject-reference video generation task.

POST /vidu/ent/v2/reference2video

Available models

Model	Description
	Q3 flagship; direct audio/video output
	Q2 Pro
	Q2 turbo
	Q2 Pro fast
	Clear visuals, stable camera
	Q1 classic
	Version 2.0

Headers

Name	Type	Required	Description
	string	Yes	Request authentication. Use a Bearer Token, for example: .
	string	Yes	Request content type; must be .

Request body

Name	Type	Required	Description
	string	Yes	Model name. See Available models above.
	array	Yes	Subject array. Multiple subjects supported; each has (subject ID), (image URLs for the subject, up to 3 per subject), and optional (voice ID). Use as the subject ID and reference it later with .
	array	Yes	Subject images. Note 1: Base64 or image URL. Note 2: formats png, jpeg, jpg, webp. Note 3: min 128×128 pixels; aspect ratio must be less extreme than 1:4 or 4:1; max 50 MB. Note 4: HTTP POST body max 20 MB; Base64 encoding must include a content-type prefix, for example: .
	string	No	Voice ID for the video audio. Auto-recommended when empty. Enum values: new voice list, or use the voice-clone API to clone any voice; voice_id values are interchangeable.
	string	No	Text prompt. Text description of the video; reference subjects with . Ignored when recommended prompts are used.
	boolean	No	Direct audio/video output. : video with dialogue and ambient audio; : silent video.
	string	No	Voice ID (global). Determines voice timbre; auto-recommended when empty. Note: ignored for q3 models.
	boolean	No	Whether to use recommended prompts. : system auto-recommends prompts; : generate from the input prompt.
	boolean	No	Background music. : pick suitable music from the preset BGM library; : no BGM.
	integer	No	Video duration in seconds. series: default 5s, range 1–10s.
	integer	No	Random seed. Omit or pass 0 for a random seed; set manually to use a fixed seed.
	string	No	Resolution. Default depends on model and duration. (1–10s): default 720p; options 540p, 720p, 1080p.
	boolean	No	Off-peak mode. : generate during off-peak hours; : generate immediately.
	boolean	No	Whether to add a watermark. : add watermark; : no watermark.
	integer	No	Watermark position. : top-left; : top-right; : bottom-right; : bottom-left.
	string	No	Watermark image URL. Default watermark when omitted: "AI-generated content".
	string	No	Passthrough parameter. Not processed; transmitted as-is.
	string	No	Metadata identifier. JSON string; passthrough field.

Request example

curl -X POST https://octopusx.ai/vidu/ent/v2/reference2video \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '
{
  "model": "viduq3-pro",
  "subjects": [
    {
      "id": "subject_1",
      "images": ["https://example.com/subject.png"],
      "voice_id": "voice_001"
    }
  ],
  "prompt": "Make @subject_1 walk forward and smile",
  "audio": true,
  "is_rec": false,
  "bgm": false,
  "duration": 5,
  "seed": 0,
  "resolution": "720p"
}'

Response example

{
  "task_id": "48038932-0ff5-4251-8b4b-7a76c09fd114",
  "status": "processing",
  "created_at": 1774494511
}

Response fields

Name	Type	Description
	string	Task ID, used to query task status.
	string	Task status. Options: (in progress), (failed), (completed).
	integer	Creation timestamp (Unix timestamp).

Related endpoints

• Vidu video overview
• Video APIs overview
• Error codes