⌘K

Vidu Q4 Preview - Reference to Video

viduq4_preview_reference2video

Generate videos with consistent subjects from multiple reference images, with optional reference audio and synchronized audio-video output, from 3 to 16 seconds at resolutions up to 4K

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

Place model at the top level of the request body and the generation parameters below in input[0].params

model string required

Model ID used for this request

Value: viduq4_preview_reference2video

images array<string> required

Reference images used to generate a video with consistent subjects
Accepts 1 to 15 images
Supports accessible image URLs or Base64 data URIs with a MIME prefix
Supported formats: png, jpeg, jpg, webp
The HTTP POST body must not exceed 20MB
Base64 example: data:image/png;base64,{base64_encode}

prompt string required

Text description of the video to generate
Maximum length: 20000 characters
Use [@subjects_name] to refer to subject content

sounds array<string>

Reference audio used to guide the audio in the generated video
Accepts up to 3 audio files, each from 3 to 12 seconds long
Supports mp3 files, each no larger than 50MB
Supports accessible audio URLs or Base64 encoding with a content-type prefix
The HTTP POST body must not exceed 20MB

audio boolean

Whether to generate video with audio
true: Output video with sound, including dialogue and sound effects
false: Output a silent video

Default: true

Options: true, false

duration integer

Video duration in seconds

Default: 5

Range: 3 - 16

aspect_ratio string

Aspect ratio of the generated video

Default: 16:9

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

resolution string

Resolution of the generated video

Default: 720p

Options: 540p, 720p, 1080p, 2K, 4K

seed integer

Random seed. If omitted or set to 0, a random seed is used; otherwise, the specified value is used

Default: 0

payload string

Custom data transmitted without processing
Maximum length: 1048576 characters

callback_url string

Callback URL for task status notifications, set when creating the task
Vidu sends POST requests to this URL using its native task structure and states: processing, success, failed
Callbacks for success or failure are retried 3 times if delivery fails; Vidu uses callback signatures for verification
Retrieve the final platform task status and video results using the polling endpoint below

Polling

Since result generation takes time, you need to poll the task status after creating the task.

The initial response only returns information such as the task ID and initial status. The final result must be obtained by polling the task status endpoint using the task ID.

See the examples on the right for polling requests and responses.

Replace {task_id} in the query URL with the id from the creation response
Continue polling for video results even when the creation response has status: completed
Continue polling while the query status is in_progress; when it is completed with output, read output[].content[].url; when it is failed, read error

Failed response example

{
  "id": "task_id",
  "created_at": 1791763200000,
  "status": "failed",
  "model": "viduq4_preview_reference2video",
  "error": {
    "message": "Video generation failed"
  },
  "output": []
}

Billing

Billed by output resolution tier and video duration, using the platform model pricing configuration
The final cost is reported in usage.cost in the successful query response, in USD

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

content array

List of generated resource content

type string

Resource type

Value: image｜video

url string

Processed resource URL

jobId string

Remote task ID

usage object

Usage statistics, only present when status is completed

cost string

Total cost in USD

discount number

Discount amount

metadata object

Metadata information