Vidu Q4 API

The Preview model is exposed under the id viduq4-preview. Official docs split it into two jobs: image-to-video and reference-to-video. viduq4.app is not the official API console. It is a product UI that submits the same model through authorized channels and charges workspace credits. The composer shows the credit amount before you submit; 10 credits = $1. Per-second list rates are on pricing.

If you only need a clip, skip HTTP and run a job in the homepage composer. If you are wiring your own backend, use the official platform routes below and keep secrets on the server.

Model id and launch

Use viduq4-preview as the model name on official calls. The Preview launched on 7 October 2026 with web and API access together. This site does not expose a separate “GA” id yet. Capabilities the docs attach to this id: audio–video sync, optional native sound, and automatic camera switching inside a take. Field lists change on the vendor’s pages — treat those pages as source of truth when a parameter is in doubt.

Official auth

Official calls use:

Authorization: Token <your key>

against https://api.vidu.com. Issue keys on the vendor’s platform, not in this app’s settings. This site never asks you to paste that key into the composer; it uses its own provider credentials and bills credits instead.

Keep keys in server environment variables. Do not commit them. Do not send them from a public frontend. Rotate a key if it leaked into a client bundle or a chat log.

Image-to-video

Official create route:

POST https://api.vidu.com/ent/v2/img2video

What the body is for:

• model — viduq4-preview (required).
• images — exactly one start frame. URL or Base64. png / jpeg / jpg / webp. Image ≤ 50MB. HTTP body ≤ 20MB. Base64 must include a content-type prefix such as data:image/png;base64,....
• prompt — motion and camera (optional on the official field list; maximum length is documented as 20,000 characters). The still is the first frame; the prompt should describe what happens next.
• is_rec — whether to use the platform’s recommended prompt (true / false, default true in official docs). If you wrote a careful prompt, set this to false so the system does not replace it.
• duration — integer 3–16, default 5.
• resolution — 540p / 720p / 1080p / 2K / 4K, default 720p.
• audio — true for native sound (dialogue and effects), false for a silent plate. Default true.
• seed — integer. Omit or 0 for a random seed; set a value when you are chasing a take.
• payload — passthrough string (documented max 1,048,576 characters). Echoed back on the task so you can attach your own job id.
• callback_url — HTTPS endpoint the platform POSTs when state changes.

Create returns a task_id and a state (created, then queueing / processing / success / failed). You do not get the MP4 in that first response.

Minimal shape (replace the image URL and key):

POST https://api.vidu.com/ent/v2/img2video
Authorization: Token YOUR_KEY
Content-Type: application/json

{
  "model": "viduq4-preview",
  "images": ["https://example.com/start-frame.png"],
  "prompt": "The astronaut waved and the camera moved up.",
  "is_rec": false,
  "duration": 5,
  "resolution": "720p",
  "audio": true
}

On this site the matching composer entry is Vidu Q4. You upload the still, type the prompt, and submit. No JSON.

Reference-to-video

Official create route:

POST https://api.vidu.com/ent/v2/reference2video

What the body is for:

• model — viduq4-preview.
• prompt — required on this route. Official examples bind stills with [@reference_image_1] (and so on) and voices with [reference_audio_1]. Stay under 20,000 characters.
• images — 1–15 stills, same format and size limits as image-to-video. This is the consistency pack: character, product, style, set.
• sounds — optional, 0–3 MP3 files, each about 3–12 seconds, each ≤ 50MB. Used to keep a voice consistent. Not a music bed.
• audio — generate native soundtrack or not (default true).
• duration — 3–16 seconds (default 5). Some marketing pages mention 1–16; this composer still uses 3–16.
• aspect_ratio — 16:9 / 9:16 / 1:1 / 3:4 / 4:3 (default 16:9).
• resolution — same ladder as image-to-video.
• seed, payload, callback_url — same roles as image-to-video.

Official notes: the Preview does not currently support the older “subject invocation” method. Pass images (and optional sounds) on the job. Do not expect a stored character id from a previous product generation to work here.

On this site the matching composer entry is Vidu Q4 Refs. Drop 1–15 stills in the reference well. The homepage UI does not currently collect the three voice files; if you need voice references, use the official route or wait for that control to land.

Query creations (polling)

Official query route:

GET https://api.vidu.com/ent/v2/tasks/{id}/creations

Header: Authorization: Token <your key> (some doc pages also show Bearer — use the scheme your key was issued with).

When state is success, creations[] includes:

• url — result video
• cover_url — poster
• watermarked_url — watermarked copy

Official docs say those URLs are valid for 24 hours. Copy them to your own storage if you need them longer. On failed, read err_code. Credits on the official response are the vendor’s units, not this site’s workspace credits.

A simple poll loop: wait 2–5 seconds, GET the task, stop on success or failed, cap the wait (minutes, not hours). Image-to-video at 4K takes longer than 540p; do not time out at 15 seconds.

Callbacks instead of polling

Set callback_url on create. The platform POSTs the same shape as the query response when the task moves. Documented states in the callback: processing, success, failed. Failed deliveries retry a small number of times. Verify the callback signature using the vendor’s signing docs — do not trust a raw POST body on an open URL.

Use callbacks when you have a public HTTPS endpoint and many in-flight jobs. Use polling when you are debugging a single curl.

Limits that actually bite

• One image on image-to-video; 1–15 on reference-to-video.
• Image formats: png, jpeg, jpg, webp. Voice: mp3.
• 50MB per image or voice file; 20MB HTTP body. Base64 inflates size — prefer HTTPS URLs for large stills.
• Prompt length: 20,000 characters. That is a ceiling, not a target. Short motion instructions outperform novels.
• Result URLs expire in 24 hours on the official query payload.
• No text-to-video on this model id.

If a create call 400s, check body size, content-type on data URIs, and that images is an array even for one still.

Using this site instead of JSON

The homepage composer uploads stills, builds the job, charges workspace credits from the vendor estimate, and polls until the MP4 is ready. You never paste a vendor key. You never stand up callback_url. Failed auth on this site means “sign in,” not “missing Token header.”

Site-side flow, at a glance:

1. Sign in.
2. POST the composer generate endpoint with model, prompt, reference URLs, duration, resolution, aspect, audio.
3. Poll the task endpoint until success or failed.
4. Download from the result URL the UI shows.

That path is for product use. It is not a documented public REST contract for third-party apps. If you are shipping your own app, call api.vidu.com with your own key and your own storage.

Credits, list rates, and the promo window are explained on pricing without a second formula. The amount shown in the composer before submit is the amount that will be deducted if the job starts.

Errors and retries

• created / queueing / processing — wait.
• success — copy files before the 24-hour URL window.
• failed — do not retry blindly at 4K. Inspect the still (face size, format), shorten the prompt, drop duration, then retry at 720p.
• 401 / 403 on official routes — bad or missing key.
• Insufficient credits on this site — the composer will say so; buy a pack or subscribe on /pricing.

Idempotency: official payload is how you round-trip your own id. This site’s composer creates a new task per submit.

Official field lists

• Image-to-video
• Reference-to-video
• Product overview: vidu.com/vidu-q4

For what the Preview will and will not generate, stay on the Preview guide. To try a shot without standing up polling, generate on the homepage.