Vidu Q2 Pro Fast - Reference to Video

Authentication

authorization string required

All APIs require authentication via Bearer Token.

Get API Key:

Visit API Key Management Page to get your API Key

Usage:

Add to request header:

Authorization: Bearer YOUR_API_KEY

Parameters

model string required

Model ID to use for the request

Value: viduq2_pro_fast_reference2video

---

subjects array required

Subject information, supports 1 - 7 subjects with a total of 1 - 7 images

id string required

Subject ID, can be referenced in prompt using @subject_id

images array required

Image URLs for this subject, up to 3 images per subject

Format Requirements:
Supports Base64 encoding or image URL (ensure accessible)
Supported formats: png, jpeg, jpg, webp
Image pixels must be at least 128×128, aspect ratio less than 1:4 or 4:1, size not exceeding 50MB
Note: HTTP request POST body cannot exceed 20MB, encoding must include appropriate content type string. Example: data:image/png;base64,{base64_encode}

voice_id string

Voice ID to determine the voice tone in the video. When empty, the system will recommend automatically. See Voice List for available options

---

prompt string required

Text description for video generation, character length cannot exceed 2000 characters

When using subjects parameter, you can use @subject_id to reference subject content, for example: “@1 and @2 eating hotpot together, with voiceover saying everyone loves hotpot.”

---

audio boolean

Whether to use audio-video direct output capability

When true, use audio-video direct output capability; when false, do not use audio-video direct output capability

Options: true, false

Default: false

---

duration integer

Video duration in seconds

Options: 1, 2, 3, 4, 5, 6, 7, 8

Default: 5

---

seed integer

Random seed. When not provided or set to 0, a random number will be used. Manual setting will use the specified seed

---

aspect_ratio string

Aspect ratio

Note: q2 models support any width-to-height ratio

Options: 16:9, 9:16, 1:1

Default: 16:9

---

resolution string

Video resolution

Options: 720p, 1080p

Default: 720p

---

payload string

Pass-through parameter, no processing required, only data transmission, maximum 1048576 characters

---

off_peak boolean

Note: Temporarily unavailable

Off-peak mode. Off-peak mode consumes fewer credits. Tasks submitted in off-peak mode will be generated within 48 hours. Tasks not completed will be automatically cancelled and credits refunded

When true, generate video during off-peak hours; when false, generate video immediately

Note: Audio-video direct output does not support off-peak mode

Options: true, false

Default: false

---

watermark boolean

Whether to add watermark. When true, add watermark; when false, do not add watermark

Currently watermark content is fixed and AI-generated, default is no watermark

Options: true, false

Default: false

---

wm_position integer

Watermark position, indicating where the watermark appears on the image

Options: 1 (top-left), 2 (top-right), 3 (bottom-right), 4 (bottom-left)

Default: 3

---

wm_url string

Watermark content, here is the image URL. When not provided, use default watermark: AI-generated content

---

meta_data string

Metadata identifier, JSON format string, pass-through field

You can use custom format or example format. Example below:

{
  "Label": "your_label",
  "ContentProducer": "yourcontentproducer",
  "ContentPropagator": "your_content_propagator",
  "ProduceID": "yourproductid",
  "PropagateID": "your_propagate_id",
  "ReservedCode1": "yourreservedcode1",
  "ReservedCode2": "your_reserved_code2"
}

When this parameter is empty, default to vidu-generated metadata identifier

---

callback_url string

Callback URL

---

Polling

Since video generation takes time, you need to poll the task status after creation

The initial response returns the task ID and initial status. The actual generation results must be obtained by polling the task status endpoint

---

Response Format

error object

Error information. Only present when status is failed.

code string

Error code

message string

Detailed error message.

---

output array

Generation results. Only present when status is completed.

task_id string

Task ID

task_status string

Task status

Options: processing, done, failed

results array

List of generated videos

type string

Resource type

Value: video

url string

Video CDN URL

---

usage object

Usage statistics. Only present when status is completed.

cost string

Total cost in USD.

discount number

Discount amount.

---

metadata object

Metadata information

remote_task_id string

Remote task ID

model string

Model name used

---

Error Codes

Error Code	Description
008017001	When audio=true, subjects parameter is required
008017002	Images or subjects parameter must provide one
008017003	Images parameter must contain 1-7 images
008017095	Internal generation error
008017096	Result parsing error
008017097	HTTP error response
008017098	Status check error
008017099	Task creation error