Vidu Commands & Prompt Reference
Request fields, endpoints and model IDs of Vidu's ent/v2 video API, checked against the platform.vidu.com docs as of the 7 October 2026 update notice, which added viduq4-preview. Text, image, start-end and reference-to-video plus task management are covered; image generation, audio, templates and the one-click solution APIs are left out. Generation is asynchronous, and duration, resolution and even prompt length limits change with the model, so check the model row before tuning other fields.
All Commands
Endpoints and authentication (8)
| Command / Syntax | What it does | Notes |
|---|---|---|
| POST /ent/v2/text2video | Create a text-to-video task | Takes text only; the documented models for this route are viduq3-pro, viduq3-turbo, viduq2 and viduq1. |
| POST /ent/v2/img2video | Create an image-to-video task | Animates a single start-frame image; the prompt is optional and is ignored once is_rec is true. |
| POST /ent/v2/start-end2video | Create a start-end frame task | Needs two images of similar resolution: the first opens the clip and the second closes it. |
| POST /ent/v2/reference2video | Create a reference-to-video task | Keeps people or objects from reference images, or from named subjects, consistent through the generated clip. |
| GET /ent/v2/tasks/{id}/creations | Query a task's results | Returns the state, credits spent and output links; video, cover and watermarked links expire after 24 hours. |
| POST /ent/v2/tasks/{id}/cancel | Cancel a task | An empty object means it worked; a task already in the scheduled state gets an error body with code 400. |
| GET /ent/v2/tasks | List recent tasks | Filters by time window, task IDs, states or resolutions and pages through results, at most 100 per page. |
| Authorization: Token {your_api_key} | API key header | Required on generation and task routes alike; the key follows the word Token and a single space. |
Generation parameters (12)
| Command / Syntax | What it does | Notes |
|---|---|---|
| model | Model to run | Required everywhere, and each endpoint page accepts only its own subset of the model IDs listed further down. |
| prompt | Text description of the clip | Length caps run from 2,000 to 20,000 characters by model, and image-to-video drops it when is_rec is true. |
| duration | Clip length in seconds | Usually defaults to 5; viduq4-preview and most Q3 models reach 16 seconds, Q2 models 10, and viduq1 stays at 5. |
| seed | Random seed | Omitting it or sending 0 draws a fresh random value; any other number is used exactly as given. |
| aspect_ratio | Output frame shape | Defaults to 16:9; reference-to-video also takes auto, which derives the ratio from the input images or video. |
| resolution | Output resolution | Mostly 540p to 1080p with 720p as default; viduq4-preview adds 2K and 4K, while viduq1 is fixed at 1080p. |
| audio | Generate sound with the video | When true the clip carries dialogue and effects, and image-to-video then refuses off-peak mode; the default differs by endpoint. |
| images | Input images | One start frame for image-to-video, two for start-end, up to 7 references (15 on viduq4-preview); URL or Base64. |
| is_rec | Use a recommended prompt | Image-to-video field: when true the system writes one prompt itself, and each task costs 10 extra credits. |
| movement_amplitude | Motion strength | Accepted on the Q1 image-to-video and reference-to-video pages, with auto as the default. |
| bgm | Add background music | Q1 reference-to-video field; when true a track from the preset library is fitted to the clip length. |
| voice_id | Voice for dialogue | Read by Q2 and Q1 image-to-video only when audio is true; leave it empty for an automatic pick or pass a cloned voice. |
Reference subjects and media (6)
| Command / Syntax | What it does | Notes |
|---|---|---|
| subjects | Named subject list | Holds up to 7 image or text subjects per task; only viduq2-pro also accepts video subjects. |
| [@name] | Mention a subject in the prompt | Write the name you gave a subject in this form inside the prompt text so the model ties it to that subject. |
| server_id | Saved subject ID | Points a subjects entry at one made with the Create Subject API; without it the subject is temporary and not kept. |
| auto_subjects | Intelligent subject library | A true or false switch on reference-to-video requests that stays off unless you send true. |
| videos | Reference videos | viduq2-pro only: one 8-second clip or two 5-second clips in MP4, AVI or MOV. |
| sounds | Reference voice audio | Up to three MP3 clips of 3-12 seconds each on viduq4-preview and the Q3 mix, ad and drama models. |
Task and delivery (8)
| Command / Syntax | What it does | Notes |
|---|---|---|
| payload | Pass-through data | Comes back unchanged in task responses and callbacks, up to 1,048,576 characters, which makes it handy for tagging jobs. |
| off_peak | Off-peak generation | Cheaper, but the task may take up to 48 hours; unfinished tasks are cancelled and their credits refunded. |
| callback_url | Status webhook URL | Vidu POSTs the query-task body here on each state change, retries failed deliveries three times and signs each request. |
| watermark | Add a watermark | Off by default; the marked file arrives as a separate watermarked_url next to the clean url. |
| wm_position | Watermark corner | Integer from 1 to 4 choosing the corner; reference-to-video puts it bottom right (3) unless told otherwise. |
| wm_url | Custom watermark image | Takes an image URL; without one the default Content generated by AI mark is applied. |
| meta_data | Metadata label | A JSON string with keys such as Label and ContentProducer; Vidu writes its own label when it is left empty. |
| state | Task status field | Response field that moves from created through queueing and processing to either success or failed. |
Model IDs (15)
| Command / Syntax | What it does | Notes |
|---|---|---|
| viduq4-preview | Q4 preview model | Image-to-video and reference-to-video only; takes reference voices, 3-16 second clips and output up to 4K. |
| viduq3-pro | Q3 Pro model | Text, image and start-end frame model with sound and shot changes; 1-16 seconds at 540p to 1080p. |
| viduq3-pro-fast | Q3 Pro Fast model | Image-to-video and start-end variant pitched on speed and cost, with 720p or 1080p output only. |
| viduq3-turbo | Q3 Turbo model | Quicker Q3 variant that covers text, image, start-end and reference tasks at 540p to 1080p. |
| viduq3 | Q3 reference model | Reference-to-video only, aimed at keeping subjects consistent across camera positions in 3-16 second clips. |
| viduq3-mix | Q3 Mix model | Reference-to-video model tuned for overall balance, with sound, scene transitions and 1-7 reference images. |
| viduq3-drama | Q3 Drama model | Reference-to-video model fine-tuned for drama, with an 8-second default length and 1-7 input images. |
| viduq3-ad | Q3 Ad model | Reference-to-video model fine-tuned for advertising; avoid feeding it near-identical input images. |
| viduq2-pro | Q2 Pro model | Image, start-end and reference model, and the only one that accepts reference videos and video subjects. |
| viduq2-pro-fast | Q2 Pro Fast model | Low-cost start-end and image-to-video model, documented as 2-3 times faster than viduq2-turbo. |
| viduq2 | Q2 model | Text-to-video and reference-to-video model with 1-10 second clips at 540p to 1080p. |
| viduq2-turbo | Q2 Turbo model | Quick image-to-video and start-end model; its start-end page also offers 360p output. |
| viduq1 | Q1 model | Produces fixed 5-second, 1080p clips for text, image, start-end and reference tasks. |
| viduq1-classic | Q1 Classic model | Image-to-video and start-end model at 5 seconds and 1080p, with livelier camera work than viduq1. |
| vidu2.0 | Vidu 2.0 model | Older fast model with 4 or 8 second clips at 32fps; the model map lists effect templates for it. |
Frequently Asked Questions
Which Vidu model should I pick?
For text-to-video the choices are viduq3-pro, the quicker viduq3-turbo, viduq2 and the fixed 5-second viduq1. For reference-to-video the Q3 line adds viduq3-mix for overall balance and the fine-tuned viduq3-drama and viduq3-ad, while viduq2-pro is the model that takes reference videos. viduq4-preview, added on 7 October 2026, handles image and reference tasks up to 4K.
How long can a generated video be?
It depends on the model: viduq4-preview and most Q3 models accept up to 16 seconds, Q2 models 1-10 seconds, and viduq1 is fixed at 5. Most default to 5 seconds; viduq3-drama defaults to 8.
How do I get the finished video?
Generation is asynchronous. Set callback_url when creating the task to receive each status change, or query GET /ent/v2/tasks/{id}/creations; the returned links stay valid for 24 hours.
Can off-peak mode be combined with audio?
Not on image-to-video: when audio is true, off-peak mode is not supported. The Q1 and Q2 reference-to-video pages likewise accept off-peak tasks only with audio set to false.
Choosing an endpoint and model
Pick the route by input: POST /ent/v2/text2video for text alone, POST /ent/v2/img2video to animate one start frame, POST /ent/v2/start-end2video to bridge two frames, and POST /ent/v2/reference2video to keep characters or products consistent. Each route accepts only some models: viduq3, viduq3-mix, viduq3-drama and viduq3-ad are reference-only, and viduq4-preview covers image and reference tasks. Duration, resolution and prompt limits follow the model, so a value one model accepts can be rejected by another.
Subjects and the [@name] syntax
On reference-to-video, subjects is a list of named entries, each with up to three images, an optional voice and, for a subject saved through the Create Subject API, a server_id. In the prompt, refer to an entry by writing its name as [@name], for example [@1] and [@2] for two characters. Entries without a saved ID are temporary and are not stored after the task. viduq3-mix cannot be used with subjects for now.
Results, callbacks and off-peak tasks
A new task starts with a state of created. Either set callback_url so Vidu posts each status change to you, or call GET /ent/v2/tasks/{id}/creations until the state is success or failed. Save outputs promptly: the video, cover and watermarked links last 24 hours. off_peak uses fewer credits but may take up to 48 hours, is not available on image-to-video when audio is true, and an off-peak task can still be stopped with POST /ent/v2/tasks/{id}/cancel.
Sources and checks
- Vidu API Docs: Model Map (Vidu Q4 Preview, Q3, Q2, Q1, 2.0) Model IDs and per-model durations, resolutions and capabilities
- Vidu API Docs: Vidu Q3 Text to Video (POST /ent/v2/text2video) Text-to-video fields, Authorization header, viduq3-pro and viduq3-turbo
- Vidu API Docs: Vidu Q3 Image to Video (POST /ent/v2/img2video) Image-to-video fields, audio and prompt rules, viduq3-pro-fast
- Vidu API Docs: Vidu Q3 Reference to Video (POST /ent/v2/reference2video) Subjects and [@name] syntax, watermark and metadata fields, Q3 reference models
- Vidu API Docs: Vidu Q4 Preview Reference to Video viduq4-preview, sounds, 2K and 4K resolution
- Vidu API Docs: Vidu Q2 Reference to Video aspect_ratio auto, reference videos, viduq2 and viduq2-pro
- Vidu API Docs: Query Task Details (GET /ent/v2/tasks/{id}/creations) Task result endpoint and state values
- Vidu API Docs: Cancel Task (POST /ent/v2/tasks/{id}/cancel) Cancel endpoint and its failure response
- Vidu API Docs: Vidu Q1 Image to Video is_rec, voice_id, movement_amplitude, viduq1-classic
- Vidu API Docs: Vidu Q1 Reference to Video bgm and viduq1
- Vidu API Docs: Vidu Q2 Start-End to Video (POST /ent/v2/start-end2video) Start-end endpoint, viduq2-turbo, viduq2-pro-fast
- Vidu API Docs: Query Task List (GET /ent/v2/tasks) Task list endpoint and its filters
Every row on this page was matched to a line in the documentation above on . A command or parameter that could not be found there is not listed.
2 rows from the earlier version of this page were removed in that check: duplicates, and entries the documentation does not list or lists differently.
AI tools change their commands, parameters and model names between releases: the vendor's current documentation and the version you run have the last word. Found a wrong or missing entry? Tell us and it gets checked against the source. How we verify describes the process and its limits.
Related prompt references
Kling AI (54) · MiniMax (Hailuo) (72) · Midjourney (46) · All AI prompt references