Vidu Q2 - 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_reference2video

subjects `array` required

Subject information from reference images, supports 1 - 7 subjects, total 1 - 7 images

id string required

Subject ID, can be referenced later using @subject_id format

images array required

Image URLs for this subject, each subject supports up to 3 images

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

voice_id string

Voice ID to determine the voice timbre in the video, when empty, the system will automatically recommend, refer to the available voice list for options

prompt `string` required

Text description for video generation, maximum 2000 characters

When using subjects parameter, you can use @subject_id to represent 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, uses audio-video direct output capability; when false, does not use audio-video direct output capability

Options: true, false

Default: false

duration `integer`

Video duration in seconds

Options: 1 - 10

Default: 5

seed `integer`

Random seed, when not provided or set to 0, uses a random number instead, manual setting uses the specified seed

aspect_ratio `string`

Aspect ratio

Note: Supports any aspect ratio

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

Default: 16:9

resolution `string`

Resolution parameter

Options: 540p, 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 points. Tasks submitted in off-peak mode will be generated within 48 hours. Tasks that cannot be completed will be automatically canceled and points will be refunded

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

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

Options: true, false

Default: false

watermark `boolean`

Whether to add a watermark. When true, a watermark is added; when false, no watermark is added

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

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, provided as an image URL, when not provided, the default AI-generated watermark content is used

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 through polling the task status endpoint

aspect_ratio `string`

Output video aspect ratio

Options: 16:9, 9:16, 3:4, 4:3, 1:1

Default: 16:9

off_peak `boolean`

Note: Temporarily unavailable

Off-peak mode. Off-peak mode consumes fewer points, please refer to detailed pricing information. Tasks submitted during off-peak hours will be generated within 48 hours. Unfinished tasks will be automatically cancelled and their points refunded. We also support canceling off-peak tasks

When audio parameter is true, off-peak mode will not take effect

Options: true, false

Default: false

Response Format

error `object`

Error information. Only present when status is failed.

code integer

Error code

error_message string

Detailed error message

output `array`

Generation results. Only present when status is completed.

content array

List of generated content

type string

Resource type

Value: video

url string

Generated content 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.

Error Codes

Error Code	Description
008017098	Generation failed
008017099	Service unavailable

curl --location \ 'https://cloud.vtrix.ai/model/v1/generation' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer YOUR_API_KEY' \ --data ' { "model": "viduq2_reference2video", "input": [ { "params": { "prompt": "example_prompt", "subjects": [ { "id": "example_id", "images": [ "example_images" ] } ], "audio": true, "duration": 5 } } ] } '

{ "id": "d5u5obte8783ap44qtj0", "created_at": 1769757744021, "status": "completed", "model": "viduq2_reference2video", "output": [ { "content": [ { "type": "video", "url": "https://example.com/generated-video.mp4", "duration": 5, "jobId": "remote_job_id_12345" } ] } ], "usage": { "cost": "0.000500", "discount": 0, "input_tokens": null, "output_tokens": null, "quantity": 1, "time_per_unit": 0, "total_tokens": null, "unit_price": "0.000500", "user_discount": 1 }, "metadata": { "completed_at": 120.5, "in_queue_at": 0, "upload_at": 1.2, "usage": { "input_tokens": 20, "input_tokens_details": { "text_tokens": 20 }, "output_tokens": 0, "total_tokens": 20 } } }

Vidu Q2 - Reference to Video

Authentication

authorization `string` required

Parameters

model `string` required

subjects `array` required

id `string` required

images `array` required

voice_id `string`

prompt `string` required

audio `boolean`

duration `integer`

seed `integer`

aspect_ratio `string`

resolution `string`

payload `string`

off_peak `boolean`

watermark `boolean`

wm_position `integer`

wm_url `string`

callback_url `string`

Polling

aspect_ratio `string`

off_peak `boolean`

Response Format

error `object`

code `integer`

error_message `string`

output `array`

content `array`

type `string`

url `string`

usage `object`

cost `string`

discount `number`

metadata `object`

Error Codes

Authentication

authorization string required

Parameters

model string required

subjects array required

id string required

images array required

voice_id string

prompt string required

audio boolean

duration integer

seed integer

aspect_ratio string

resolution string

payload string

off_peak boolean

watermark boolean

wm_position integer

wm_url string

callback_url string

Polling

aspect_ratio string

off_peak boolean

Response Format

error object

code integer

error_message string

output array

content array

type string

url string

usage object

cost string

discount number

metadata object

Error Codes

authorization `string` required

model `string` required

subjects `array` required

id `string` required

images `array` required

voice_id `string`

prompt `string` required

audio `boolean`

duration `integer`

seed `integer`

aspect_ratio `string`

resolution `string`

payload `string`

off_peak `boolean`

watermark `boolean`

wm_position `integer`

wm_url `string`

callback_url `string`

aspect_ratio `string`

off_peak `boolean`

error `object`

code `integer`

error_message `string`

output `array`

content `array`

type `string`

url `string`

usage `object`

cost `string`

discount `number`

metadata `object`