PixVerse Commands & Prompt Reference
Request fields, endpoints and model IDs of the PixVerse Platform API v2 (paths under /openapi/v2), checked on 2026-10-10 against the vendor's API reference and guides. Most fields are model-gated: the audio switch needs v5.5 or newer, while the sound effect and lip sync TTS fields stop at v5. Every call carries API-KEY and a fresh Ai-trace-id, and generation calls return only a video_id to poll. Restyle, Swap, Mimic, Modify, Upscale, Avatar and agent endpoints are left out.
All Commands
Generation parameters (11)
| Command / Syntax | What it does | Notes |
|---|---|---|
| prompt | Scene description prompt | Required text field, capped at 5,000 characters, that tells the model what the clip should show. |
| model | Model version to run | Required; the eight IDs run from v3.5 to c1, and the chosen one decides which other fields are honoured. |
| duration | Video length in seconds | Required integer; v6 and c1 take any length from 1 to 15, older models a fixed 5, 8 or 10. |
| quality | Output video quality | Required; at 1080p the 8-second option disappears on v3.5 and the 10-second option on v5.5 and v5.6. |
| aspect_ratio | Frame aspect ratio | Required on text-to-video; v6 and c1 add 2:3, 3:2 and 21:9 to the five ratios older models accept. |
| seed | Random seed | Optional integer up to 2147483647; the image, transition and extend endpoints take the same range. |
| negative_prompt | Content to avoid | Optional, up to 2,048 characters; it appears in the guides' request examples but not in the current reference request schemas. |
| motion_mode | Motion speed mode | Defaults to normal; fast is limited to 5-second clips below 1080p in the older v3.5 to v4.5 parameter table. |
| style | Style preset | Optional preset such as anime, 3d_animation, day, cyberpunk or comic; the guide advises sending it only when needed. |
| camera_movement | Camera movement preset | Shown only as a commented-out line in the reference request examples, with zoom_in as the sample value. |
| generate_multi_clip_switch | Multi-clip output switch | Boolean for v5.5 and v6 only; false keeps the default single-clip mode, true switches to multi-clip generation. |
Audio and lip sync parameters (8)
| Command / Syntax | What it does | Notes |
|---|---|---|
| generate_audio_switch | Generated audio switch | Boolean for v5.5, v5.6, v6 and c1; clips stay silent unless it is set to true. |
| sound_effect_switch | Sound effect switch | Off by default; honoured on v5 and older models, or on any model when a template_id is supplied. |
| sound_effect_content | Sound effect description | Read only when sound_effect_switch is true on v5 or older; an empty value lets the sound be generated automatically. |
| lip_sync_tts_switch | Lip sync speech switch | Off by default and limited to v5 or older; the script and voice come from the two fields that follow. |
| lip_sync_tts_content | Script for the voice | In generation requests, about 140 UTF-8 characters of speech, honoured only by v5 and earlier models. |
| lip_sync_tts_speaker_id | TTS voice ID | Takes an ID from the TTS speaker list; in generation requests it works with v3.5, v4, v4.5 and v5 only. |
| audio_media_id | Uploaded audio track | Lip sync endpoint input from the media upload; send it or a TTS speaker with a script, never both. |
| original_sound_switch | Keep original soundtrack | Sound effect endpoint only; true keeps the source video's own sound when the effect is added. |
Image, video and template inputs (9)
| Command / Syntax | What it does | Notes |
|---|---|---|
| img_id | Uploaded image ID | Required on image-to-video; the integer comes back from the upload image endpoint. |
| img_ids | Image IDs for multi-image effects | Integer array sent instead of img_id when an effect template needs more than one picture. |
| template_id | Effect template ID | Activate the effect first; once it is set, the request's model and prompt values are ignored. |
| first_frame_img | Transition start image | Required on the transition endpoint; an uploaded image ID that the clip opens on. |
| last_frame_img | Transition end image | Required with first_frame_img; the uploaded image the transition finishes on. |
| source_video_id | PixVerse video to reuse | Extend takes the video_id of an earlier PixVerse job here; it cannot be combined with video_media_id. |
| video_media_id | Uploaded video ID | Points extend at a clip uploaded through the media endpoint rather than one PixVerse generated. |
| image_url | Image upload by URL | Upload-image alternative to the multipart image file; JPEG, PNG or WebP links only, octet-stream not accepted. |
| file_url | Video or audio upload by URL | Media upload alternative to sending the file itself; mp4, mov and webm video or mp3, wav, m4a and aac audio. |
Fusion references (5)
| Command / Syntax | What it does | Notes |
|---|---|---|
| image_references | Reference images for Fusion | Each entry pairs an img_id with a subject or background type and a ref_name; Fusion needs v4.5 or newer. |
| ref_name | Reference name | Label of up to 30 characters that the prompt can cite with @; optional from v5.5 onward. |
| @ref_name | Mention a reference in prompts | Follow the name with a space, as in @cat plays, and spell it exactly as the matching ref_name. |
| reference_mode | Fusion reference mode | The documented value is omni; on v6 it unlocks video references, an auto aspect ratio and up to 10 images. |
| video_references | Reference videos for Fusion | Up to two clips totalling 15 seconds; duration must then be 0, and output length follows the longest one. |
Endpoints and required headers (16)
| Command / Syntax | What it does | Notes |
|---|---|---|
| API-KEY | API key header | Carries the platform key on every call, uploads and status checks included. |
| Ai-trace-id | Per-request trace ID header | Needs a new UUID each time; repeating one returns the earlier result and starts no new video. |
| Content-Type | Request body type header | Set to application/json on the generation requests, whose bodies are JSON objects. |
| POST /openapi/v2/video/text/generate | Start text-to-video job | Returns only a video_id; the finished clip is fetched later through the status endpoint. |
| POST /openapi/v2/video/img/generate | Start image-to-video job | Needs an img_id from the image upload; the same path runs effect templates when template_id is set. |
| POST /openapi/v2/video/transition/generate | Start first-last frame job | Builds a clip that moves from first_frame_img to last_frame_img, with the usual prompt and model fields. |
| POST /openapi/v2/video/fusion/generate | Start reference-to-video job | Composes subjects and backgrounds from image_references, which the prompt names with @ mentions. |
| POST /openapi/v2/video/extend/generate | Continue an existing video | Its model field accepts v3.5 up to v6 but not v5.6 or c1. |
| POST /openapi/v2/video/lip_sync/generate | Start lip sync job | Combines one video source with either an uploaded audio track or a TTS speaker plus script. |
| POST /openapi/v2/video/sound_effect/generate | Add sound effects to a video | Works on an existing clip; without sound_effect_content the effect is derived from what the video shows. |
| GET /openapi/v2/video/result/{id} | Check generation status | Status 1 means ready with a url, 5 still generating, 7 blocked by moderation and 8 failed. |
| POST /openapi/v2/image/upload | Upload an image | Takes PNG, WebP or JPEG files under 20MB and 10000 pixels and returns the img_id used by later calls. |
| POST /openapi/v2/media/upload | Upload video or audio | Returns a media_id; limits vary by feature, from 30-second clips for extend to 300 seconds for lip sync. |
| GET /openapi/v2/video/tts_speaker | List TTS voices | Optional speaker_type filter selects system, custom or all voices; page_size accepts 10, 20, 50 or 100. |
| GET /openapi/v2/account/balance | Check credit balance | Reports monthly credits and purchased package credits as separate numbers, plus the account ID. |
| GET /openapi/v2/video/effects/templates/list | List effect templates | A type of 1 returns video templates and 2 image templates; leaving it out returns both. |
Model IDs (8)
| Command / Syntax | What it does | Notes |
|---|---|---|
| c1 | Cinematic generation model | Recommended for cinematic and reference-driven work across text, image, transition and Fusion jobs, without extension. |
| v6 | General-purpose generation model | The model the docs point to for extending videos; it also covers text, image, transition and Fusion jobs. |
| v5.6 | Version 5.6 model | Supports generate_audio_switch but not the multi-clip switch, and caps clips at 10 seconds, or 8 at 1080p. |
| v5.5 | Version 5.5 model | Oldest model with both the audio and multi-clip switches; durations are 5, 8 or 10 seconds. |
| v5 | Version 5 model | Newest model that still reads the sound effect and lip sync TTS fields; clips run 5 or 8 seconds. |
| v4.5 | Version 4.5 model | Oldest model Fusion accepts; there it allows up to three reference images and 5 or 8 second clips. |
| v4 | Version 4 model | Legacy option limited to 5 or 8 second clips, with audio only through the sound effect and lip sync fields. |
| v3.5 | Version 3.5 model | Earliest listed model; a 1080p clip on it cannot use the 8-second duration. |
Frequently Asked Questions
Why is a parameter being ignored in my PixVerse request?
Most parameters are model-gated. Audio and multi-clip switches are supported on the newer models, while sound effects and lip sync fields apply to v5 and below. Check the model version against the parameter before debugging further.
What duration and quality can I ask for?
It depends on the model: older versions accept 5 or 8 seconds, v5.5 and v5.6 add 10 (not at 1080p), and v6/c1 accept 1 to 15. Quality options are 360p, 540p, 720p, and 1080p.
What headers does the API require?
API-KEY with your platform key, and Ai-trace-id containing a UUID that must be unique for each request.
Sources and checks
- PixVerse Platform API v2 reference — Text-to-Video generation Text-to-video request fields, headers, model and duration rules; model IDs
- PixVerse Platform API v2 reference — Image-to-Video generation Image-to-video endpoint, img_id, sound effect and TTS speaker fields
- PixVerse Platform API v2 reference — Template video generation Effect templates: template_id and img_ids
- PixVerse Platform API v2 reference — Transition (first-last frame) generation Transition endpoint and frame image fields
- PixVerse Platform API v2 reference — Speech (lip sync) generation Lip sync endpoint and audio_media_id
- PixVerse Platform API v2 reference — Get speech (lip sync) TTS list TTS voice list endpoint
- PixVerse Platform API v2 reference — Fusion (reference to video) generation Fusion endpoint, ref_name, @ref_name prompt syntax, reference_mode, v4.5
- PixVerse Platform API v2 reference — Sound effect generation Sound effect endpoint and original_sound_switch
- PixVerse Platform API v2 reference — Extend generation Extend endpoint, source_video_id and video_media_id
- PixVerse Platform API v2 reference — Get video generation status Status endpoint and status codes
- PixVerse Platform API v2 reference — Upload image Image upload endpoint and image_url
- PixVerse Platform API v2 reference — Upload video and audio Media upload endpoint and file_url
- PixVerse Platform Docs — Model overview C1 and V6 model rows
- PixVerse Platform Docs — PixVerse-api-llm.txt (updated 2026-04-24) Required headers; image_references
- PixVerse Platform API v2 reference — Get user credit balance Balance endpoint
- PixVerse Platform Docs — Extend guide (parameter details) negative_prompt, motion_mode and style
- PixVerse Platform Docs — Fusion V6 video reference integration guide video_references
- PixVerse Platform API v2 reference — Get template list Effect template list endpoint
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.
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) · Vidu (49) · MiniMax (Hailuo) (72) · All AI prompt references