How to write MiniMax H3 prompts
Model page: MiniMax H3 API — pricing, specs and the playground
MiniMax H3 does not read a free-form wish list directly. In MiniMax's own pipeline, a step called H3-Context-IR first turns whatever you typed, plus your reference images, videos and audio, into a structured description, and only then does the video model generate. MiniMax calls that step "critical to the quality of the final output" and publishes the structure so you can write it yourself.
Writing it yourself buys control. You decide when each cut happens, which character says which line, and what the audience hears, instead of leaving it to an automatic rewrite. A plain one-line description still produces a clip; the structure matters when timing, dialogue and sound have to land exactly.
Everything below follows MiniMax's official H3 prompt-writing guide in the MiniMax-AI/MiniMax-H3 repository. The example prompts are our own.
The three fields of an H3 prompt
A text-only H3 prompt has exactly three fields, in this order. Everything visible or audible on screen goes into the first; the other two only cover sound.
| Field | What goes in it | Rule of thumb |
|---|---|---|
| integrated_multimodal_description | The timeline: style and framing, subjects, actions, camera moves, cuts, speakers and dialogue, sounds tied to the action | Starts with [Shot 1] and the overall style, e.g. Live-action, cinematic |
| overall_soundscape | Ambience, physical action sounds and non-verbal human sounds across the whole clip | 1–4 sentences in one paragraph; never repeat dialogue here |
| non_diegetic_music | Background music only the audience hears | 1–3 sentences on instruments, tempo and dynamics; N/A if none |
Shots, cut times and camera moves
Number the shots in order. The first shot gets no timestamp; every later shot opens with a cut time in minutes:seconds, strictly increasing and inside the clip length: "[Shot 2] At 00:05.000, the camera cuts to …". A cut should bring something new, a new subject, place, viewpoint or moment. If you only want to get closer or shift the angle a little, move the camera instead of cutting.
Describe a camera move with up to three parts: the move itself, its amplitude and its speed, written as a normal sentence inside the shot rather than as tags: "The camera pushes in with small amplitude at slow speed toward the letter in her hands." Leave amplitude and speed out when medium and normal is what you want.
| Write | What the camera does |
|---|---|
| Push In / Pull Out | The camera physically moves toward or away from the subject |
| Zoom In / Zoom Out | Only the focal length changes; the camera stays put |
| Pan Left / Right, Tilt Up / Down | The camera pivots in place, horizontally or vertically |
| Truck Left / Right, Pedestal Up / Down | The whole camera slides sideways or rises and lowers |
| Arc Shot, Tracking Shot | Circles the subject, or follows a moving subject |
| Static Shot, POV | Holds still, or shows the subject's point of view |
| Shake Slightly / Strongly, Roll Clockwise / Counterclockwise | Handheld shake, or a roll around the lens axis |
| with small / large amplitude, at slow / fast speed | How far and how fast the move goes |
Dialogue, voiceover and on-screen text
Give every character who speaks or sings a stable ID, (S1), (S2), and keep it across shots; characters who never make a sound get none. Describe the speaker outside the dialogue tag (age, voice, delivery), and put only the language and the exact line inside it: The baker with a raspy voice (S1) says: <d>[English] First batch of the morning.</d>. The language goes in square brackets; MiniMax's own examples use [English]. Lines are kept verbatim in their original language, never translated.
For voiceover, use the exact phrase "says in an off-screen voiceover" and state right after the line that the on-screen character's lips stay closed. Any sign, label, subtitle or neon text that should appear in the frame goes in double quotes, verbatim: A neon sign reading "OPEN" glows above the door.
A complete example: 8 seconds, two shots, one line
Below is a text-only prompt written to the official structure: a night-shift ramen cook, a push-in, one line of dialogue in Chinese, a cut at the 5-second mark and a sign on the wall. Send it with duration 8 so the cut time sits inside the clip.
integrated_multimodal_description: [Shot 1] Live-action, cinematic, a medium shot frames a narrow late-night ramen bar where a cook in his fifties wipes the wooden counter as steam rises from the pots behind him. The camera pushes in with small amplitude at slow speed as the cook, a man with a low, gravelly voice (S1), looks up toward the door and says: <d>[Chinese] 最后一碗,给你留着呢。</d> [Shot 2] At 00:05.000, the camera cuts to a close-up of a bowl of ramen set down on the counter, chopsticks resting across the rim, with a handwritten sign reading "营业到两点" on the wall behind it. overall_soundscape: Broth bubbles in the pots under a low kitchen hum. The ceramic bowl clinks against the wood, and rain patters faintly outside the door. non_diegetic_music: N/A
In a real request the three fields are separated by blank lines, as in the code below.
When you also send images, video or audio
H3 has five input modes, and the first line of the prompt changes with each. With a first frame, the prompt opens with a fixed sentence pinning Picture 1 to 0.00 seconds, then describes what happens next from that image. With a first and last frame, it describes the path between them, usually as a single shot. With references (people, products, a camera move to copy, a voice), MiniMax's guide labels each asset <Subject N>, <Picture N>, <Video N> or <Audio N>, keeps each label's meaning the same everywhere in the prompt, and says exactly where in the timeline each reference appears.
On apimodels.app each mode maps to a model id and its fields. Arrays are sent in the order you give them, and that order is how you refer to them in the prompt.
| What you have | Official mode | Model id and fields |
|---|---|---|
| Text only | T2VA | Any of minimax-h3, minimax-h3-lite, minimax-h3-max-turbo, minimax-h3-rh-enhanced |
| A first frame | I2VA | minimax-h3-max-turbo or minimax-h3-rh-enhanced, first_frame_url |
| A first and a last frame | FL2VA | minimax-h3-max-turbo, minimax-h3-rh-enhanced or minimax-h3-lite, first_frame_url + last_frame_url |
| Reference images, video or audio | Ref2VA | minimax-h3: images (up to 9), video_list (up to 3), audio_list (up to 3); minimax-h3-rh-enhanced: reference_image_urls (up to 9), reference_video_urls (up to 3); minimax-h3-lite: images + audio_list |
Mistakes that quietly ruin an H3 clip
A plot summary instead of shots. "A lonely chef finds hope" gives the model nothing to film. Write what the camera sees and hears, shot by shot.
Cut times that do not fit the clip. A cut at 00:09.000 in a 6-second video, or two cuts out of order. Set duration first (5 to 15 whole seconds on minimax-h3), then place the cuts inside it.
Sound in the wrong field. Dialogue belongs in the timeline, not in overall_soundscape. A radio playing in the room is part of the scene; only music the characters cannot hear goes in non_diegetic_music.
Translated dialogue. If the line is in Chinese, keep it in Chinese inside <d>; the rest of the prompt is written in English.
Reference labels that drift. If <Subject 1> is the woman from your first image, it stays that woman everywhere in the prompt.
When you do not need any of this
If you are sketching ideas, a single natural sentence is enough, and minimax-h3-max-turbo can expand a short prompt for you with prompt_expansion_mode set to quality. For finished prompts to copy, start from the MiniMax H3 prompt library and edit the action, camera and line you need.
Quick start
cURL
# 8 seconds, 768p, text only. In JSON the blank line between fields is \n\n.
curl -X POST https://api.apimodels.app/v1/video/generations \
-H "Authorization: Bearer $APIMODELS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-h3",
"duration": 8,
"resolution": "768p",
"ratio": "16:9",
"prompt": "integrated_multimodal_description: [Shot 1] Live-action, cinematic, a medium shot frames a narrow late-night ramen bar where a cook in his fifties wipes the wooden counter as steam rises from the pots behind him. The camera pushes in with small amplitude at slow speed as the cook, a man with a low, gravelly voice (S1), looks up toward the door and says: <d>[Chinese] 最后一碗,给你留着呢。</d> [Shot 2] At 00:05.000, the camera cuts to a close-up of a bowl of ramen set down on the counter, chopsticks resting across the rim, with a handwritten sign reading \"营业到两点\" on the wall behind it.\n\noverall_soundscape: Broth bubbles in the pots under a low kitchen hum. The ceramic bowl clinks against the wood, and rain patters faintly outside the door.\n\nnon_diegetic_music: N/A"
}'
# → { "code": 200, "data": { "taskId": "...", "state": "pending" } }; poll GET /v1/video/generations?task_id=...Python
import os, requests
prompt = """integrated_multimodal_description: [Shot 1] Live-action, cinematic, a medium shot frames a narrow late-night ramen bar where a cook in his fifties wipes the wooden counter as steam rises from the pots behind him. The camera pushes in with small amplitude at slow speed as the cook, a man with a low, gravelly voice (S1), looks up toward the door and says: <d>[Chinese] 最后一碗,给你留着呢。</d> [Shot 2] At 00:05.000, the camera cuts to a close-up of a bowl of ramen set down on the counter, chopsticks resting across the rim, with a handwritten sign reading "营业到两点" on the wall behind it.
overall_soundscape: Broth bubbles in the pots under a low kitchen hum. The ceramic bowl clinks against the wood, and rain patters faintly outside the door.
non_diegetic_music: N/A"""
r = requests.post(
"https://api.apimodels.app/v1/video/generations",
headers={"Authorization": f"Bearer {os.environ['APIMODELS_API_KEY']}"},
json={"model": "minimax-h3", "duration": 8, "resolution": "768p", "ratio": "16:9", "prompt": prompt},
)
print(r.json()) # then poll GET /v1/video/generations?task_id=...FAQ
Should MiniMax H3 prompts be written in English?
MiniMax's guide writes the structured prompt in English, but keeps dialogue, lyrics and any text visible in the frame in their original language. So a Chinese line stays Chinese inside <d>, and a Chinese sign stays Chinese inside double quotes.
How do I set when a shot changes?
Start each shot after the first with its cut time, for example "[Shot 2] At 00:05.000, the camera cuts to …". The first shot has no timestamp, cut times must increase, and all of them must fall inside the duration you request.
How do I make a character say a specific line?
Give the character a speaker ID and wrap only the language tag and the exact words in <d>: The woman (S1) says: <d>[English] I get off at the next station.</d>. Describe voice and delivery outside the tag, and keep the same ID for that character in every shot.
Do I have to use this structure on apimodels.app?
No. A plain description works on every H3 model id. The structure is for when you need exact timing, dialogue and sound. If you want a short prompt expanded for you, minimax-h3-max-turbo has prompt_expansion_mode.
Where is the official MiniMax H3 prompt guide?
In the MiniMax-AI/MiniMax-H3 repository on GitHub, under the h3-prompt-writing skill: one guide for text and keyframe modes and one for full-reference mode. This page summarises both and adds how each mode maps to apimodels.app.
Related
- MiniMax H3 prompt library: copy-ready prompts with sample clips
- MiniMax H3 API docs: fields, reference limits and pricing
- MiniMax H3 API pricing, compared
