⌘K

Vidu Q4 Preview - Image to Video

viduq4_preview_img2video

Generate videos from a single first-frame image, with synchronized audio-video output and prompt recommendations, 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_img2video

images array<string> required

First-frame image used as the starting frame of the generated video
Accepts exactly 1 image
Supports accessible image URLs or Base64 data URIs with a MIME prefix
Supported formats: png, jpeg, jpg, webp
Each image must not exceed 50MB
The HTTP POST body must not exceed 20MB
Base64 example: data:image/png;base64,{base64_encode}

prompt string

Text description of the video to generate
Maximum length: 20000 characters

is_rec boolean

Whether to use a recommended prompt
true: Automatically recommend a prompt and use it to generate the video
false: Use the provided prompt

Default: true

Options: true, false

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

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_img2video",
  "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