How to prompt MiniMax H3: the formula isn't in the guide, it's in the API

You want to learn how to prompt MiniMax H3, so you go looking for a page called something like "prompt guide."

The URL exists: /docs/guides/video-prompt. Click it and the heading says H3 Feature Highlights — six use cases in a gallery: brand film, visual creative, vertical drama, e-commerce, UI motion, stylized game footage. Each gives you a prompt, a few reference thumbnails, an output video.

No formula. No table of fields. No list of camera terms.

It's easy to conclude from this that MiniMax simply has no prompting conventions, so anything goes.

That conclusion is wrong, and it costs you about half your available control. MiniMax's conventions absolutely exist — they just aren't in the guides. They're in the API reference. And some of them are strict enough to silently override what you wrote in your prompt.

This article takes all three layers apart: the request structure (the real formula), the prose shape you can reverse-engineer from the six examples, and those fifteen named camera commands.

Image placeholder: "One request, three layers: request structure, prompt prose, camera commands"

Layer one: the real formula is content[]

Here's what an H3 request actually looks like:

{
  "model": "MiniMax-H3",
  "content": [
    { "type": "text",      "text": "..." },
    { "type": "image_url", "image_url": { "url": "..." }, "role": "reference_image" },
    { "type": "video_url", "video_url": { "url": "..." }, "role": "reference_video" },
    { "type": "audio_url", "audio_url": { "url": "..." }, "role": "reference_audio" }
  ],
  "resolution": "2K",
  "duration": 5,
  "ratio": "adaptive"
}

See role? That's the formula.

There are exactly five legal values:

role	Meaning
first_frame	this image is the opening frame
last_frame	this image is the closing frame
reference_image	this image is a reference asset
reference_video	this video is a reference asset
reference_audio	this audio is a reference asset

ByteDance makes you type <Subject_1>@<Image 1> into the prompt, and makes you declare "define the tall man in Video 1 as police officer" before you can refer to him. MiniMax moved that same job into a field. Asset responsibility is carried by role, which is why the prose can just say "the character in Image 2."

The official launch post demonstrates exactly this:

Reference the Hitchcock camera movement from Video 1, have the character in Image 2 sing, with the vocals matching Audio 3.

Three assets, three jobs, one sentence, zero notation. The notation is in the JSON.

So the accurate way to say it is: MiniMax's formula isn't a copywriting format, it's a request structure.

Three hard rules that will bite you

These are in the API schema and nowhere in the guides, but breaking them means an error or a silent no-op.

1. text is always required. Even when you're just handing it a first frame to animate, you must supply text. Omit it and you get a 400:

invalid params, content must include a non-empty text item (prompt is required) (2013)

2. First/last frame and reference assets are mutually exclusive. Straight from the docs:

Image-to-video and reference-to-video are mutually exclusive.

Which means you cannot lock an opening frame and supply a character reference in the same request. Pick one. If your workflow was "reference image locks the character, first frame locks the composition," that path is closed on H3 — you'd generate a still first, then feed that still as the first frame.

3. In image-to-video, aspect ratio comes from the image and your prompt can't change it. The docs say ratio is always adaptive there, and "passing another valid value does not error but is ignored."

So the 16:9 you typed at the top of your prompt is decoration in that mode. Conversely, in pure text-to-video ratio is required and cannot be adaptive.

Layer two: the prose style is decided by role

Here's the part most people miss: H3 prompts have no single voice. What you put in content[] determines how the text should read.

The three official API examples are written in visibly different registers:

Text only — describe a scene:

Epic space-opera theatrical teaser: a female captain stands alone before a massive observation window as the last fleet gathers and jumps away in a blinding flash, the bridge shaking, leaving her behind.

With a first frame — write an edit note:

Pull focus to the people in the background and add more steam to the ramen bowl.

Look carefully: that sentence never describes what's in the frame. The frame is already in the image. Your job is to say what to change — it reads like a note to a compositor.

With references — write dialogue and asset assignments:

Character speaks: Follow the wind, live free. Leave worries behind, enjoy the moment. Voice timbre follows reference audio 1.

Note the ending: the role was already set to reference_audio, and the text still names it again by ordinal. That's MiniMax's own house style — the schema handles binding, the prose says which aspect of the asset you want (here, timbre, not content).

Those six examples: the brief-shaped prompt

The six on the video-prompt page are a third situation — a complete piece. Line them up and a recurring order of sections appears.

To be clear: the six sections below are this article's reading of the official examples, not a formula MiniMax published.

Section	What it does	Official wording
Spec	duration and ratio	15s, 16:9.
Asset roles	what each reference covers	Image 1: mood, setting, film grain. Image 2: character. Image 3: bag. Image 4: ending logo.
Core story	the whole thing, uncut	Core story: on a desert highway beside a vintage car, the woman takes a black bag from the trunk, shares a brief quiet moment with the man, then leaves.
Tone	how it should feel	Tone premium and cool
Edit feel	pace, cut density	edit agile and fashion-forward
Sound	what you should hear	Sound: kitchen ambience plus the creature's soft electronic hums.

This isn't a description of a shot. It's a brief. And there's a counterexample — the sixth, game-oriented prompt has neither spec line nor asset roles, just one continuous first-person camera description. So these are a common shape, not required fields.

A few things worth internalising:

Give every asset a stated job. Image 1: mood, setting, film grain. Image 2: character. — one line each. role tells the model that it's a reference; the prose tells it which aspect to take. You need both layers.

Tell the core story in one pass. No "Shot 1," no timeline — because the H3 launch post lists Native multi-shot modeling among its pretraining properties, and the API has no shot field at all. The cuts are its call.

Name a tone coordinate everyone already knows. ReelShort / DramaBox feel: dark romance, danger, destiny. That line is worth stealing: it names a category rather than describing pixels, and beats stacking "cinematic, dreamy, epic, hyperreal" — those four fight each other.

Edit feel is your one remaining pacing lever. You don't write shots, but "slow, few cuts" versus "tight, high-impact rhythm" changes the model's segmentation for half a sentence of effort.

Write the sound, because it's making sound regardless. H3's audio is native stereo generated jointly with picture, and voice, effects and music are modelled together with no separation. Skip it and you still get audio — just whatever it guessed.

Layer three: fifteen named camera commands

This is the most buried thing in the whole documentation set.

The API reference contains a closed list, stated verbatim as Supported 15 camera commands:

Type	Commands
Truck	[Truck left], [Truck right]
Pan	[Pan left], [Pan right]
Push	[Push in], [Pull out]
Pedestal	[Pedestal up], [Pedestal down]
Tilt	[Tilt up], [Tilt down]
Zoom	[Zoom in], [Zoom out]
Shake	[Shake]
Follow	[Tracking shot]
Static	[Static shot]

The usage rules are equally explicit:

• Combined: multiple commands inside one [] take effect simultaneously, e.g. [Pan left,Pedestal up]. Recommended maximum: 3.
• Sequential: commands apply in the order they appear, e.g. "...[Push in], then...[Push out]".
• Natural language works too, but the docs say plainly — explicit commands yield more accurate results.

The official example prompt, verbatim:

A man picks up a book [Pedestal up], then reads [Static shot].

This is stricter than ByteDance. Seedance's camera section uses such as — examples, not an enumeration. MiniMax hands you a closed list of fifteen plus combination rules and a recommended cap.

The honest caveat, which you need

That table is documented under MiniMax-Hailuo-2.3, MiniMax-Hailuo-2.3-Fast, MiniMax-Hailuo-02, T2V-01-Director and I2V-01-Director — not H3.

The H3 guide says only:

add camera motion instructions (e.g., [pan], [zoom], [static]) directly after key descriptions to guide the camera work.

Lowercase, e.g., three examples — a different notation from the Title Case table.

So the honest reading is: bracket camera syntax is a MiniMax house convention across generations, and the full vocabulary is documented on the Director/Hailuo line. Whether H3 honours all fifteen is not stated. Worth trying. Not a guarantee.

A historical clue: H3 removed the prompt optimizer

Dig through the older endpoints and you'll find a parameter H3 no longer has: prompt_optimizer.

Whether to automatically optimize the prompt. Defaults to true. Set to false for more precise control.

Default true. On the older models, your prompt was rewritten by an optimizer unless you opted out. Those models also capped prompts at 2,000 characters.

The H3 v2 endpoint has no such parameter, and the cap rises to 7,000 characters per text item.

That clue ties the whole product position together. MiniMax moved from "write whatever, I'll rewrite it" to "say it properly, I won't touch your words." The launch post's describe their intent directly in natural language only reads as substantive once you notice the rewriting layer was actually removed.

What you're working with

Item	Value
Model	MiniMax-H3 (internally Hailuo-03)
Endpoint	POST /v2/video_generation
Resolution	2K (currently the only value, required)
Duration	required integer, 4–15 s
Ratio	adaptive / 21:9 / 16:9 / 4:3 / 1:1 / 3:4 / 9:16
Prompt length	≤ 7,000 characters per text item
First / last frame	≤ 1 each
Reference images	≤ 9, 256–5760 px, aspect 0.4–2.5
Reference video	≤ 3 clips, 2–15 s each and ≤ 15 s total, MP4 / MOV
Reference audio	≤ 3 clips, WAV / MP3, never sent alone
Asset sources	public URL / mm_file://{file_id} / Base64 data URI
Request body	≤ 64 MB

mm_file://{file_id} deserves its own note: it can point at one of your previous outputs. For continuations, or reusing a generated frame as the next clip's starting point, you don't have to download and re-upload.

One error code to be mentally prepared for — 422:

video description contains sensitive content (1026)

(Last verified 2026-08-01. Specs change between versions; the official docs win.)

A template you can edit

The rainy-night station, in reference mode (reference_image ×2 plus reference_audio ×1):

12s.

Image 1: the lead's appearance — young woman, dark blue raincoat, short black hair, old leather suitcase; take her face and wardrobe. Image 2: the old station platform; take the spatial layout and the balance of cool and warm light. Audio 1: take the ambient texture as a bed for the whole piece, not as dialogue.

Core story: late at night, just after heavy rain, the lead waits behind the yellow line. She hears the train and turns toward the entrance [Pan right]; as it pulls in the wind lifts the hem of her raincoat and she steps back half a pace [Push in]. She does not board.

Tone: realistic cinematic, predominantly cool blue, tungsten platform lamps adding small warm reflections, low saturation; the quiet feel of a Japanese railway film.

Edit: slow, few cuts, let the waiting sit.

Sound: rain, the rails as the train approaches from a distance, indistinct platform announcements. No score.

Notice there's no aspect ratio in there — in reference mode ratio is optional and I'm letting it decide. Switch this to pure text-to-video and ratio becomes required, and cannot be adaptive.

A checklist before you submit

Structure

1. Does content[] contain a non-empty text? (Required — a 400 otherwise.)
2. Did you mix first_frame with reference_image? (Mutually exclusive — it will fail.)
3. Is this text-to-video? Then ratio is required and cannot be adaptive.
4. Is this first-frame image-to-video? Then any ratio you wrote is ignored — don't waste the words.

Prose

1. Does the register match the role? With a first frame, write an edit note, not a fresh scene description.
2. Does every asset say which aspect of it you want?
3. Does the tone have one clear coordinate rather than four adjectives fighting?
4. Did you say anything about pace? If not, the cuts are entirely the model's call.
5. Do you care about the sound? If not, you're accepting whatever it scores.

Where this approach bites

You don't decide the cuts. If your piece has a narrative order that must hold — the phone dies, then she looks up, then the train passes — the model may reorder it or compress all three beats into one movement. And when you regenerate you can't point at "shot 2," because you never defined one.

Seedance solves the same problem with Shot 1 / Shot 2 / Shot 3. The two vendors made opposite trades, which deserves its own piece: see "One idea, two models: Seedance writes structure into the text, MiniMax writes it into the protocol".

There is no constraint layer. Seedance has a whole section on writing "no subtitles, no logo, no watermark," plus a global constraint line specifically for the same character being rendered twice. MiniMax's documentation has no such layer — you can only be thorough in the positive description, and there's no official troubleshooting list when something goes wrong.

Last thing

"The docs don't teach it" and "there are no conventions" are two different statements.

MiniMax's conventions are scattered through API field descriptions — the five values of role, the i2v/r2v exclusion, the three different behaviours of ratio, fifteen named camera commands. These are harder rules than any prompt formula, because they throw errors.

What those six gallery examples teach is a different thing: once the structure is settled, how the remaining paragraph should read. Get that paragraph wrong and no schema will save you.

Official sources

Specs, the content[] structure, role definitions and hard constraints come from MiniMax's v2 API reference; the 15 camera commands come from the prompt field description on the t2v/i2v endpoints (documented for the Hailuo/Director line; not restated for H3); the product position and architecture claims come from the H3 launch post. The six-section shape is this site's reading of six official examples — MiniMax has published no prompt formula as such.

Last verified: 2026-08-01.

• Create Video Generation Task (v2, H3 endpoint, full OpenAPI schema)
• Create Text-to-Video Generation Task (legacy, with the 15-command table)
• Image-to-Video Task (legacy, with the 15-command table)
• Video Generation (MiniMax guide)
• H3 Feature Highlights (at the video-prompt URL)
• MiniMax H3: An Open Model Breaking the Boundaries Between Tasks and Modalities (launch post)