MiniMax (Hailuo) Commands & Prompt Reference
Request fields, endpoints and prompt tokens of the MiniMax API, checked on 2026-10-10 against platform.minimax.io: the Video V2 API (OpenAPI 2.0.0) for MiniMax-H3 and MiniMax-H3-Max, the legacy Hailuo 2.3 call with its bracketed camera commands, and the OpenAI-compatible chat endpoint for the M3 and M2.x models. An H3 request always carries one text item in content, and video calls return a task ID to poll. Speech, music, image, the Anthropic-format endpoint and the legacy image-to-video calls are left out.
All Commands
Video task endpoints (6)
| Command / Syntax | What it does | Notes |
|---|---|---|
| POST /v2/video_generation | Create an H3 video task | Asynchronous: the reply carries only a task_id, and the finished clip is collected through the query endpoint. |
| GET /v2/query/video_generation/{task_id} | Query one task | Answers only for tasks from the last 7 days; after success, content.url holds a video link that expires. |
| GET /v2/query/video_generation | List recent tasks | Paged with page_num and page_size, and narrowed with filter.status, filter.model, filter.task_type or filter.task_ids. |
| DELETE /v2/video_generation/{task_id} | Cancel or delete a task | A queued task is cancelled without charge, a succeeded or failed one is deleted, and a running task cannot be stopped. |
| POST /v2/h3_context_ir | Enrich a prompt (H3-Context-IR) | Runs as a task like a video job, but succeeds with an expanded prompt in content.prompt and renders nothing. |
| POST /v2/video_regeneration | Rebuild an H3 clip at 2K | Takes either the source_task_id of a finished task or one base_video item, and only accepts MiniMax-H3 768P output. |
Video generation parameters (9)
| Command / Syntax | What it does | Notes |
|---|---|---|
| model | Video model name | Required; MiniMax-H3 renders 768P or 2K from 4 seconds, while MiniMax-H3-Max stops at 768P and starts at 5 seconds. |
| content | Multimodal input array | Required; it must hold one non-empty text item, and frame images cannot share a request with reference media. |
| resolution | Output resolution | MiniMax-H3 offers 768P or 2K; MiniMax-H3-Max offers 480P or 768P, uses 768P by default and has no 2K. |
| duration | Clip length in seconds | A required whole number: 4 to 15 on MiniMax-H3, 5 to 15 on MiniMax-H3-Max. |
| ratio | Output aspect ratio | Text-only requests must name a fixed ratio; image-to-video always follows the input image, and reference requests default to adaptive. |
| extra | Extra options for H3-Max | Holds only prompt_expansion_mode for now; leaving it out means balanced expansion, and other fields must not be sent. |
| prompt_expansion_mode | Prompt expansion level | Set inside extra: disabled turns expansion off, balanced is the default, and quality favours a richer rewrite. |
| callback_url | Status callback URL | MiniMax first posts a challenge that must be echoed within 3 seconds, then pushes each status change in the query response format. |
| source_task_id | Task to rebuild at 2K | Regeneration endpoint only: needs whitelist access and a succeeded task of your own from the last 7 days, with no content sent. |
Content items and roles (12)
| Command / Syntax | What it does | Notes |
|---|---|---|
| type=text | Prompt text item | One non-empty text item is mandatory in every scenario; its text field takes up to 7000 characters. |
| type=image_url | Image input item | Serves as first or last frame or as one of up to 9 reference images; JPG, PNG, WEBP or HEIC, 30 MB each. |
| type=video_url | Reference video item | Reference requests only: up to 3 MP4 or MOV clips of 2 to 15 seconds, 15 seconds in total. |
| type=audio_url | Reference audio item | Reference requests only: up to 3 WAV or MP3 clips of 2 to 15 seconds, each at most 15 MB. |
| role | Purpose of a content item | Needed when the purpose is not implied; a single image sent without a role is treated as the first frame. |
| role=first_frame | Opening frame image | Image-to-video mode; the clip then takes its aspect ratio from this picture and ignores ratio. |
| role=last_frame | Closing frame image | Sets the picture the clip ends on; add a first_frame item as well for a first-to-last transition. |
| role=reference_image | Reference image | Up to 9 per request; any reference role rules out first_frame and last_frame items in the same call. |
| role=reference_video | Reference video | Lets the prompt borrow motion, camera work or editing rhythm from up to 3 clips. |
| role=reference_audio | Reference audio | Supplies a voice or sound to follow; the vendor example asks for the voice timbre of reference audio 1. |
| role=base_video | Source clip for regeneration | Regeneration endpoint only: the 768P clip to rebuild, sent together with the content that produced it. |
| mm_file://{file_id} | Uploaded file reference | Points an image, video or audio item at a file already on the platform, avoiding Base64 and the 64 MB body cap. |
Model IDs (6)
| Command / Syntax | What it does | Notes |
|---|---|---|
| MiniMax-H3 | H3 video model ID | Text, image and reference input at 768P or 2K, for clips of 4 to 15 seconds in whole-second steps. |
| MiniMax-H3-Max | Fast H3 variant ID | Post-trained by fal.ai for speed; 480P or 768P only, 5 to 15 seconds, and the one model that reads extra. |
| MiniMax-M3.1-Flash-Preview | Preview chat model ID | Reachable through M Plan or MiniMax Code only at present; it always thinks, and reasoning_effort sets how deeply. |
| MiniMax-M3 | M3 chat model ID | Accepts text, image and video input with a 1M context; adaptive thinking can be switched off for direct answers. |
| MiniMax-M2.7 | M2.7 chat model ID | Released on 18 March 2026 with a highspeed twin; thinking cannot be turned off and top_p defaults to 0.9. |
| MiniMax-M2.7-highspeed | Faster M2.7 variant ID | Same quality as M2.7 with noticeably quicker inference, for latency-sensitive calls. |
Chat completions parameters (16)
| Command / Syntax | What it does | Notes |
|---|---|---|
| POST /v1/chat/completions | OpenAI-compatible chat call | Served from https://api.minimax.io and authorised with a Bearer API key in the Authorization header. |
| model | Chat model ID | Required; takes the M3.1 Flash Preview, M3 and M2.x names, including the highspeed variants. |
| service_tier | Admission tier | standard by default; priority costs 1.5 times as much and is admitted ahead of other requests. |
| messages | Conversation history | Roles are system, user, assistant and tool; the M3 models also take image and video parts in content. |
| thinking | Thinking switch | Adaptive by default; disabled makes MiniMax-M3 answer directly, is ignored by M2.x and fails with HTTP 400 on M3.1 Flash Preview. |
| reasoning_effort | Thinking depth | Honoured by MiniMax-M3.1-Flash-Preview alone, from low to max (the default); none is refused and other models ignore it. |
| reasoning_split | Separate reasoning output | true moves thinking into reasoning_content, false leaves it in content inside think tags; thinking itself stays as set. |
| stream | Streaming switch | Off by default; when true the reply arrives piece by piece instead of as one response. |
| stream_options | Streaming options | Object read with streamed requests; its single field, include_usage, adds token counts to the stream. |
| include_usage | Usage in streamed replies | Set inside stream_options; false by default, true reports token usage in the streamed response. |
| max_completion_tokens | Output token limit | M3 models suggest 131072 and allow up to 524288; other models suggest 65536 with a ceiling of 204800. |
| temperature | Sampling temperature | Ranges from 0 to 2 with a default of 1; lower values give more predictable text. |
| top_p | Nucleus sampling | Between 0 and 1; defaults to 0.95 on the M3 models and 0.9 on M2.x. |
| tools | Function tool definitions | Each entry has type function plus a name and a JSON Schema describing its parameters. |
| tool_call_id | Link a tool result | Required on tool-role messages; it repeats the id of the assistant tool call that the result answers. |
| max_tokens | Old output limit | Still accepted but deprecated; the reference names max_completion_tokens as its replacement. |
Legacy Hailuo requests (7)
| Command / Syntax | What it does | Notes |
|---|---|---|
| POST /v1/video_generation | Legacy text-to-video call | The older prompt-string API for the Hailuo models; its callbacks report processing, success or failed. |
| prompt | Legacy prompt string | Up to 2000 characters; with Hailuo 2.3, Hailuo 02 and T2V-01-Director it also reads bracketed camera commands. |
| prompt_optimizer | Automatic prompt rewriting | On by default; switch it off when the prompt should be followed exactly as written. |
| fast_pretreatment | Faster prompt optimisation | Off by default; shortens the optimizer step, and only on Hailuo 2.3 and Hailuo 02. |
| MiniMax-Hailuo-2.3 | Hailuo 2.3 video model ID | Legacy model for text- and image-to-video: 768P at 6 or 10 seconds, or 1080P at 6 seconds. |
| MiniMax-Hailuo-2.3-Fast | Hailuo 2.3 Fast model ID | Image-to-video only, with the same 768P and 1080P length options as Hailuo 2.3. |
| MiniMax-Hailuo-02 | Hailuo 02 video model ID | Older Hailuo model; for image-to-video it adds a 512P option at 6 or 10 seconds. |
Camera movement commands (16)
| Command / Syntax | What it does | Notes |
|---|---|---|
| [Truck left] | Truck camera left | |
| [Truck right] | Truck camera right | |
| [Pan left] | Pan camera left | |
| [Pan right] | Pan camera right | |
| [Push in] | Push the camera in | |
| [Pull out] | Pull the camera out | The listed opposite of [Push in]; the vendor sequence example writes [Push out], which is not on the list. |
| [Pedestal up] | Raise the camera (pedestal) | |
| [Pedestal down] | Lower the camera (pedestal) | |
| [Tilt up] | Tilt camera up | |
| [Tilt down] | Tilt camera down | |
| [Zoom in] | Zoom the lens in | |
| [Zoom out] | Zoom the lens out | |
| [Shake] | Camera shake | |
| [Tracking shot] | Follow the subject | Listed under Follow, the one tracking command among the 15. |
| [Static shot] | Static camera shot | |
| [Pan left,Pedestal up] | Combine camera moves | Moves inside one pair of brackets run together, three at most is advised; separate bracketed commands play in sentence order. |
Recipes
Notes on combining the fields above, checked against the same MiniMax documentation. Each code line uses values from the tables on this page.
Animate a still image
type=image_url → role=first_frame
Send the picture next to the text item; a lone image without a role is read as the first frame anyway. Leave ratio out: image-to-video takes its shape from the picture and ignores any other value. Add a second image with role=last_frame to fix the ending as well.
Steer a clip with reference media
role=reference_video → role=reference_audio
Reference roles and frame roles cannot share a request. Up to 9 images, 3 videos and 3 audio clips are accepted, and the guide caps mixed input at 12 files. The vendor's examples point at inputs by number in the prompt, for example asking for the voice timbre of reference audio 1.
Render at 768P, then rebuild at 2K
MiniMax-H3 → POST /v2/video_regeneration
Pass the finished task as source_task_id, or resend the original content with the clip as a role=base_video item. The endpoint only accepts video that meets the MiniMax-H3 768P output specification; it is not a general upscaler.
Direct the camera in a Hailuo 2.3 prompt
[Pan left,Pedestal up]
Bracketed commands are read in the legacy prompt field of Hailuo 2.3, Hailuo 02 and T2V-01-Director. Moves inside one pair of brackets happen together; separate brackets through the sentence play in order. Plain camera directions also work, but the reference calls the commands more accurate. The Video V2 reference for H3 does not list them.
Separate the thinking from the answer
thinking → reasoning_split
Adaptive thinking is on unless switched off, which only MiniMax-M3 allows. With reasoning_split true the reasoning arrives in reasoning_content; with false it stays in content between think tags. Neither setting turns thinking on or off.
Get told when the render finishes
callback_url
MiniMax first sends a verification request whose challenge value must be returned unchanged within 3 seconds; after that, every status change is pushed in the same shape as the query response, so polling is no longer needed.
Frequently Asked Questions
How do I pass a prompt to MiniMax H3 video generation?
As a content item with type=text, up to 7000 characters. A request without one non-empty text item fails with a parameter error; image, video and audio items are added beside it.
Which video model IDs does the V2 endpoint accept?
MiniMax-H3 (768P or 2K, 4 to 15 seconds) and MiniMax-H3-Max, the faster variant post-trained by fal.ai (480P or 768P, 5 to 15 seconds). The Hailuo 2.3 and 02 models are listed as legacy and use POST /v1/video_generation.
Is video generation synchronous?
No. POST /v2/video_generation returns a task ID; poll GET /v2/query/video_generation/{task_id} or set callback_url. Tasks stay queryable for 7 days and the video URL expires, so download the file promptly.
Do Hailuo camera commands like [Pan left] work with MiniMax H3?
They are documented for the legacy prompt field of MiniMax-Hailuo-2.3, MiniMax-Hailuo-02 and T2V-01-Director. The H3 reference does not list them; describe the camera work in the text item or supply a reference video instead.
Sources and checks
- MiniMax API reference — Create Video Generation Task (Video V2, OpenAPI 2.0.0) H3 request fields, content items, roles, model limits
- MiniMax guide — Video Generation (MiniMax H3 and H3 Max) Model names and specs, input limits, code examples
- MiniMax API reference — Query Task (Video V2) Task query endpoint and status values
- MiniMax API reference — List Tasks (Video V2) Task list endpoint and filters
- MiniMax API reference — Cancel or Delete Task (Video V2) Cancel and delete endpoint
- MiniMax API reference — Create H3-Context-IR Task (Video V2) Prompt enhancement endpoint
- MiniMax API reference — Create Video Regeneration Task (Video V2) 768P to 2K regeneration endpoint, base_video role
- MiniMax API reference — Create Text-to-Video Generation Task (legacy Hailuo models) Legacy endpoint, prompt fields and the 15 camera commands
- MiniMax release notes — APIs (to Oct. 28, 2025) Hailuo 2.3, 2.3 Fast and 02 model IDs
- MiniMax API reference — Chat Completions API (OpenAI-compatible) Chat request fields and chat model IDs
- MiniMax release notes — Models (to Jul. 31, 2026) Release dates of MiniMax H3 and MiniMax-M2.7
- MiniMax guide — Models (language and video model tables) Current and legacy model IDs
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) · DeepSeek (46) · All AI prompt references