Create Image-to-Video Task

Vidu image-to-video API guide: animate a first-frame image with a prompt using viduq3 and viduq2 models, with synced audio, off-peak mode, and callback setup.

(Vidu Image-to-Video)

This endpoint lets you upload a first-frame image and combine it with a prompt to generate a coherent, high-quality dynamic video. Supports synchronized audio, custom voices, and off-peak generation mode.

Quick Start

Video generation is asynchronous. The whole flow takes three steps:

1. Submit the task → get a task_id
2. Poll the status → wait for status to become completed and return a public URL

📌 Basics

Endpoint: POST /v1/video/generations
Authentication: Bearer Token (Authorization: Bearer {{YOUR_API_KEY}})
Content type: application/json

📥 Request Parameters (Request Body)

Parameter	Type	Required	Description
model	`string`	Yes	Model name. Options: `viduq3-turbo`, `viduq3-pro`, `viduq2`, `viduq1`.
prompt	`string`	Yes	Video motion description. Up to 5000 characters.
images	`array`	Yes	First-frame image. Only 1 image is supported; pass an image URL or Base64 encoding.
duration	`integer`	No	Duration in seconds. Default 5. Q3 series supports 1-16s, Q2 supports 1-10s.
seed	`integer`	No	Random seed. Default 0 (random).
metadata	`object`	No	Extended configuration object.
└─ audio	`boolean`	No	Whether to enable synchronized audio (sound generated directly with the video). Default true.
└─ audio_type	`string`	No	Audio type: `all` (sound effects + speech), `speech_only`, `sound_effect_only`.
└─ voice_id	`string`	No	Specific voice ID. Any voice can be cloned (not yet supported on the Q3 series).
└─ off_peak	`boolean`	No	Off-peak mode. Generates within 48 hours at a lower credit cost.
└─ callback_url	`string`	Yes	Callback URL for receiving asynchronous task status changes.
└─ is_rec	`boolean`	No	Whether to enable system-recommended prompts (costs 10 extra credits when enabled).

🖼️ Image Requirements

Formats: PNG, JPEG, JPG, WebP.
Size: image file up to 50MB (POST body limited to 20MB).
Aspect ratio: must be between 1:4 and 4:1.

📤 Response

Status code: 200 OK (task submitted)

Field	Type	Description
id	`string`	Task instance ID.
task_id	`string`	Task ID (used for status queries).
status	`string`	Current task status (e.g. `queued`).
progress	`integer`	Generation progress percentage.
created_at	`integer`	Task creation timestamp.

📝 Request Example

{
"model": "viduq3-turbo",
"prompt": "Contemporary dance, the people in the picture are performing contemporary dance.",
"images": [
"https://example.com/dance_start_frame.png"
],
"duration": 7,
"metadata": {
"audio": true,
"audio_type": "all",
"callback_url": "https://your-api.com/callback/vidu-i2v",
"off_peak": false
}
}

💡 Developer Tips

Audio splitting: Fine-grained audio_type splitting (e.g. keeping only sound effects or only speech) is supported on the Q2 and Q1 models only.
Off-peak task management: Off-peak tasks that do not complete within 48 hours are automatically canceled and the credits are refunded; you can also cancel a task manually before it is processed.
Prompt recommendation: If you are unsure about your prompt, enable is_rec: true and the system will automatically optimize it to produce a better video.
Callback signature: Vidu signs its callback pushes; verify the signature on your server for security.

Create Image-to-Video Task

On this page