Skip to main content

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 the X-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.
string
required
The model ID: viduq4-preview.
string[]
required
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.
string
The scene, up to 20,000 characters. Required on reference2video. Optional on img2video.
integer
default:"5"
The clip length in whole seconds, 3 to 16. You are billed per second of output.
string
default:"720p"
The output tier: 540p, 720p, 1080p, 2K or 4K. A higher tier costs more per second.
boolean
default:"true"
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.
string
default:"16:9"
The output shape on reference2video: 16:9, 9:16, 1:1, 4:3 or 3:4. On img2video, the clip follows the image.
boolean
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.
integer
default:"0"
The random seed. 0 picks a random seed.
string
Free text, up to 4,096 characters, that Vidu stores with the task and does not read.

Response

Submit

A 200 status means that Vidu accepted the task. It does not mean that the clip is ready.
string
required
The task ID. Poll GET /v1/vidu/video/{task_id} with it. It works for 7 days.
string
The task state when it was accepted, such as created.

Poll

string
required
processing while the task runs. success or failed when it ends. Poll until you read one of the two terminal values.
string
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.
integer
The Vidu credits that the task used. Present once the task is billed.
object
Present when state is failed. error.message explains why. Read it before you resubmit.
The poll also echoes model, capability, duration and resolution.

Example

Submit, poll, download. The submit path names the task, and the poll path takes the task ID.
To carry subjects into a new scene, submit to /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: false unless 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 with state 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.