Vidu Q4
Vidu Q4 preview is Vidu’s newest video model. It animates a still image, or it carries the subjects of up to 15 reference images into a new scene. It generates dialogue and sound effects with the picture, and it can switch camera angles within one clip. Each task has its own submit path. Generation is asynchronous. You submit a task, poll it until the state is terminal, then download the clip. The route mirrors Vidu’s own API, so the request and response shapes are the provider’s.Best for
- Animating a still. The image becomes the first frame, and the prompt drives the motion.
- Consistent subjects. Up to 15 reference images keep characters and objects the same across the clip.
- Clips with sound. Speech and sound effects come out with the video in one request.
- Resolution range. From 540p drafts to 4K finals.
Models
Durations are whole seconds. Both tasks send
viduq4-preview as the model value. Text-to-video is not offered on this model: a submit to text2video returns 400.
Endpoints
{capability} is img2video or reference2video. The poll path is the same for both.
Request
Send your API key in theX-API-Key header. See Authentication. Set Content-Type: application/json. The examples also send a User-Agent header that names your application.
The route accepts only the fields below. A body with any other top-level field, such as Vidu’s sounds or callback_url, returns 400 before any charge.
The images. On
img2video, exactly one: the first frame. On reference2video, 1 to 15 reference images. Each item is a public https URL or a base64 data:image/... URI. Vidu takes PNG, JPEG, JPG and WEBP up to 50 MB each. The whole request body must stay under 20 MB, so pass large images by URL.The output tier:
540p, 720p, 1080p, 2K or 4K. A higher tier costs more per second.Whether the clip carries generated sound: dialogue and sound effects. It defaults to on, and sound adds a surcharge to the task. Send
false for a silent clip.The output shape on
reference2video: 16:9, 9:16, 1:1, 4:3 or 3:4. On img2video, the clip follows the image.On
img2video, true lets Vidu write its own prompt and ignore yours. When you send a prompt and leave is_rec out, Nunchux sends false, so your prompt is used.Response
Submit
A 200 status means that Vidu accepted the task. It does not mean that the clip is ready.Poll
processing while the task runs. success or failed when it ends. Poll until you read one of the two terminal values.The URL of the clip, in
creations[0].url. Present only when state is success. The URL is time-limited. Download the clip as soon as the task succeeds. A later poll returns a fresh URL.model, capability, duration and resolution.
Example
Submit, poll, download. The submit path names the task, and the poll path takes the task ID./v1/vidu/video/reference2video instead, with up to 15 images and a prompt. The body below replaces the submit body in the example. It leaves audio out, so the clip has sound and the surcharge applies.
Reference-to-video
Tips
- Send
audio: falseunless you want sound. Sound is on by default and costs extra on every task. - Draft at 540p or 720p. 2K and 4K cost several times more per second, so settle the prompt at a lower tier first.
- Name each subject in the prompt by the image that shows it, and keep the reference images consistent in style.
- Poll every 5 seconds at first, then back off to 30 seconds. Polls are free and never use a concurrency slot.
Errors and limits
A 200 status on submit means that Vidu accepted the task. It does not mean that the task succeeded. A task that fails later ends withstate set to failed, and error.message explains why. Read it before you resubmit.
A failed submit returns an HTTP error status. See Error codes. These request shapes are rejected with 400 before any charge:
A 5xx status or a timeout on submit does not tell you whether the task was created. Never resubmit blindly. If the submit returned a
task_id, poll it. If it returned nothing, check your credits before you try again.
Vidu bills per second of output at the chosen resolution. Sound adds a fixed surcharge per task on both image-to-video and reference-to-video. Nunchux holds the charge at submit, with the surcharge unless you sent audio: false, and settles it to the credits that Vidu reports when the task ends. A failed task is refunded. See the pricing page for the rates.
Every submit counts toward the simultaneous-jobs cap of your plan for six minutes, however fast the task finishes. A task that ends sooner does not give its slot back early, so a burst of short tasks can return 429 concurrent_limit_exceeded. Wait and retry with backoff. Separately, at most five Vidu tasks per account can be in progress at once. A sixth returns 429 with the code too_many_open_tasks. A task stops counting toward the five when Nunchux settles it, which can be a few seconds after the poll first shows a terminal status, so a submit sent at once can still return 429. See Rate limits, Credits & pricing and the Partner models overview.