# H3 prompting guide
For AI agents writing prompts for users. Full rules, official examples and pitfalls; SKILL.md section 4 has the essentials. Motion swap has its own file: [motion-swap.md](https://minimax.xxt.ai/references/motion-swap.md).
## 0. Sources
From MiniMax's official guides ([base mode](https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/docs/VIDEO_PROMPT_WRITING_GUIDE_base_en.md), [full-reference mode](https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/docs/VIDEO_PROMPT_WRITING_GUIDE_ref_en.md)), the [ComfyUI guide](https://docs.comfy.org/tutorials/video/minimax/minimax-h3-prompt-guide), community reports and tests here. This platform runs the open-source model without MiniMax's prompt rewriter, so one-line prompts that work on MiniMax's app may not work here. Tags: [official], [community] (two or more sources agree), [single source] (worth trying, not a rule), [tested here].
## 1. Two ways to submit a prompt
### 1.1 `describe` (default): write only the scene description
Write "what happens on screen from the first frame on" (section 2). The platform translates Chinese to English (not lines) and wraps it in H3's official structure. **It adds all of the following; never write them yourself:**
- the first-line alignment sentence for first / last frame (last-frame time computed from the real frame count), `[Shot 1]`, and `Live-action, cinematic,` unless your description starts with a style word (`Cinematic`, `Live-action`, `2D-animated`, `3D CG`, `claymation`, `watercolor`, `vintage film`; an animated first frame needs `2D-animated, ` etc.);
- `--dialogue` as speaker `(S1)` plus `[language] original text ` (language from the script: Han → Chinese, kana → Japanese, Hangul → Korean, else English; for other languages use `raw`); lip-sync also gets the "follows `` exactly, every syllable clearly articulated" sentence;
- per reference image, its angle and "keep this face, hairstyle and build in every frame", plus "`` sets scene, composition, clothing and lighting";
- the last-frame landing sentence, `Natural true-to-life skin tone.`, ambient sound (`--sound`, or a generic one if empty) and music `N/A`.
`ref2v` fills the six fields of the full-reference guide [official]: person-angle images form ``, each `other` image becomes its own subject with your note (`a jar of face cream`, `a cozy bedroom`), pictures are numbered from `` (no first frame), and a style sentence is prepended unless you start with a style word.
**With characters (`ref2v`, `i2v`, `lipsync`):**
- Write character names directly; the platform turns them into `` (never write `` yourself) and adds each character's description and reference voice (``, timbre only).
- Lines: submit `--line ":="` (most accurate), or put lines in 「」 in the description with the speaker's name before them; the platform extracts any quoted text (「」“”"" 『』) as lines, untranslated. On-screen text instead goes after `reading` / `写着` in quotes (section 2.4) and stays in the picture. In `lipsync` (one character) quoted text is not extracted; the sung line comes from `--dialogue`.
- Clothing follows your description; photos set face, hairstyle and build only. "Use clothing from photos" (`ref2v` only) makes clothing follow the photos unless your description describes it, so then don't describe that character's clothing.
- `i2v` with 3+ characters, each with `--position` (who and where): everyone is introduced by position, each line names its speaker by position, lines run First/Next/Then/Finally, and after each line the speaker's lips close while the others listen [tested here].
- `ref2v` with lines: an LLM expands a short scene to about 90–150 words and adds a silent closing action, since one- or two-sentence scenes often get burned-in subtitles [tested here]; writing the full scene yourself is safest. `i2v` is not expanded.
- Photo slots: each character gets a front photo first, then others in rotation, up to 8 total including `--ref` images.
**Promo (`promo`):** host ``, then one subject per product, then the scene. Products keep shape, colour, logo and text; worn products are worn by the host. No description → a default shot (host holds the first product beside the face). Lines (≤ 30 units) come from `--line`, `--selling-points` or the description; else the platform writes them.
Notes: English descriptions are safest (each translation can drift); no ``, ``, `` or field names; no line breaks. Voice-over and lines spanning shots need `raw` (2.5).
### 1.2 `raw`: write the complete H3 prompt yourself
Add `--raw`; the prompt goes to the model unchanged, checked only for `integrated_multimodal_description:` (`detailed_description:` for `ref2v`). Use it for exact control of multiple shots, speakers, voice-over and music. Picture numbers must follow the platform's order:
- `` is the first frame; reference images follow from `` in `--ref` order;
- with k reference images, the last frame is ``;
- the lip-sync vocal is ``;
- `ref2v` has no first frame: reference images from ``; six fields in this order: `subject_definitions`, `summary`, `retention_analysis`, `detailed_description`, `overall_soundscape`, `non_diegetic_music` (format in [motion-swap.md](https://minimax.xxt.ai/references/motion-swap.md) section 1, without ``);
- with characters, their photos come before `--ref` images (from `` after a first frame, `` in `ref2v`), grouped per character in `--character` order, each starting with its front photo; every photo at a listed angle counts (check `h3 character show`); `` follows `--character` order; the last frame comes after all.
Structure in section 3. First frame plus reference images is this platform's combination: after the alignment sentence, say in the body which angle of the person each reference image shows.
## 2. How to write the description (applies to both modes)
### 2.1 General principles
- **Every sentence must map to something visible or audible**: the subject's appearance and position, scene and key props, actions and reactions, camera movement, who is speaking, live sound. No filler like "beautiful", "cinematic feel", "amazing" [official].
- **Write in time order.** With a first frame, the recommended order is: anchor the first-frame picture (person, clothing, position, scene) → action begins → continuous development → result or reaction [official].
- **State the shot size**: close-up, medium close-up, medium shot, medium-wide shot, wide shot. Match shot size to the action; don't squeeze face and feet into the same shot [single source].
- **Write only what you want, never what you don't.** The model has no negative prompt; a list of prohibitions tends to bring the prohibited things into the picture [official: ComfyUI]. Tested here: `no tear forms or falls` gave tears in both takes; only `a quiet, grateful smile; her face is calm` came out dry.
- For a still camera, write `The camera holds a static shot`, not `no camera movement`.
- **Spell out key actions step by step, ending in the visible result** [tested here]: `wipes out the writing with his foot` failed in both takes; `drags the sole of his foot back and forth across it twice … when he lifts his foot, the dirt is smooth and blank` worked in both. Give head movements a direction (`a clear left-right shake meaning no; his head never moves up and down`; a bare `shakes his head` nodded), and name the expression (`lowers her eyes, embarrassed`), not just an adverb like `softly`.
- **Length**: 60–150 English words per shot, more for dialogue; too short and the model fills in on its own [community]; too long and "global rules" at the end get ignored, so repeat key requirements in every shot [single source].
### 2.2 Shots and cuts
- **Default to one continuous shot.** H3 tends to cut by default; for a single take, write `in one continuous shot` explicitly [community].
- **Cut only when subject, space, state, viewpoint or time changes**; for small changes in shot size or angle, use camera movement [official].
- **How to write cuts**: no time on the first shot; every later shot is `[Shot 2] At 00:04.000, the camera cuts to ...` [official].
- Times must be strictly increasing and within the duration;
- use single time points, not ranges like `[4s-8s]` [official: ComfyUI];
- cuts land on the written time to the frame [tested here]; still order key actions;
- things written for one shot (e.g. foreground raindrops) can leak into others [tested here];
- a later shot has no first frame to follow, so complex action or continuity there drifts (a smeared frame, a prop flying into a hand): for those, use separate clips with their own first frames [tested here].
- **Shot count guide**: 4–6 s: 1–2 shots; 7–10 s: 2–3; 11–15 s: 3–5; don't cut every second [single source].
- **Dissolves, fades, wipes**: only when the user explicitly asks [official].
### 2.3 Camera movement: type + amplitude + speed [official]
| Movement type | Meaning |
|---|---|
| `zoom in` / `zoom out` | lens zoom, camera body stays |
| `push in` / `pull out` | camera body moves forward / back |
| `pan left` / `pan right` | body stays, lens turns left/right |
| `truck left` / `truck right` | body slides left/right |
| `tilt up` / `tilt down` | body stays, lens turns up/down |
| `pedestal up` / `pedestal down` | whole body rises/lowers |
| `arc shot` | arcs around the subject |
| `tracking shot` | follows a moving subject |
| `static shot` | completely still |
| `shakes slightly` / `shakes strongly` | slight / strong shake |
| `POV` | subject's point of view |
| `rolls clockwise` / `rolls counterclockwise` | rotates around the lens axis |
- **Amplitude** `with small/large amplitude`, **speed** `at slow/fast speed`; medium and normal need not be written.
- Write it as a natural action in the sentence, not tags piled at the end: `The camera pushes in at fast speed toward the folded letter in her hands.`
- Slow moves drag: a short drama cut slow everywhere felt sluggish; default to static and cut [tested here].
### 2.4 People
- **Small faces in wide and full shots blur**: attach a sharp close-up reference image at the angle the person faces in that shot (`front`, `side`, `three_quarter_left` / `three_quarter_right`) and distant faces stay clear [tested here]. Without one, faces only in close shots; backs or empty frames in wide shots [official example + community].
- **If there is only one person throughout, say so explicitly**, e.g. `the same single woman throughout`; when a person walks past the camera, turns, or leaves and re-enters the frame, a second copy of her tends to appear or she suddenly vanishes [single source].
- **Describe movement as a continuous path and action**, not just "walks to somewhere" [single source].
- **With reference images, don't describe appearance in detail in the body** (reference images and the platform lock it); spend the words on action and camera. In close-ups don't describe clothing outside the frame (e.g. trousers, shoes), or the model cuts to a full-body shot to draw them [tested here].
- **To make someone blink**, say at which second [single source].
- **Empty scene**: `no people` fails; write `a completely empty workshop, the workers have all gone home, architecture and objects only` [tested here].
- **On-screen text** (signs, neon lettering): original text verbatim in English double quotes after `reading` / `写着`: `a red neon sign reading "营业中"` [official]. With characters, this is not extracted as a line (section 1).
### 2.5 Speaking and singing
- **Number speakers `(S1)`, `(S2)`**, unchanged across shots. On first appearance say who they are, age, gender and voice quality, e.g. `the young woman with a quiet, breathy voice (S1) says:` [official].
- **Lines go in `[language] original text `**, e.g. `[Chinese] 我下一站就下车。 `.
- Text and punctuation verbatim, not translated [official];
- end the sentence with a period, otherwise the speaker tends to keep mumbling after [single source, confirmed by others];
- no ellipses; they slur pronunciation [official: ComfyUI].
- **Close the mouth after speaking**: write `as her voice stops, her lips close and her jaw stops moving` [official example]. For silent stretches write `silently`, or state the lips are closed [single source]. For someone on screen who never speaks: `X only listens and never speaks; his lips stay closed the whole time.` [tested here].
- **Speaking to the camera**: a static shot or `keeps the medium close-up framing`; `push in` over 11 s cut off the headdress [tested here].
- **Outside the lines, avoid speech words like talk, chat, scold**, or extra voices appear [community].
- **Voiceover**: `says in an off-screen voiceover`, then right after ` ` `while his lips remain completely closed` [official]. Hit-and-miss (lips moved in 2 of 4 takes) [tested here]; make two takes.
- **A line spanning a cut**: write `` at the join on both sides and state the voice continues; if cut off by the end of the clip, write `` [official].
- **In multi-person dialogue, lines drift onto the wrong mouth**, mostly via unrequested close-ups of a listener: two people with `--line` are fine; for three or more in `i2v` add `--position` per character ([characters.md](https://minimax.xxt.ai/references/characters.md) section 6) [tested here].
- **Line length must fit the duration**: Chinese no more than about 7 characters per second; faster and the lips can't keep up [single source]. Real pace is about 4 per second (41 took 10.5 s); add time for the action [tested here].
- **The model sometimes adds or changes words** (an extra phrase at the end, `点` read as `点儿`): transcribe important takes and compare with the script [tested here].
### 2.6 Ambient sound and music [official]
- **Ambient sound** (`overall_soundscape`; filled with `--sound` in `describe`):
- 1–4 English sentences: live ambience, action sounds, and non-speech human sounds like breathing and laughter;
- no lines or singing here;
- write `N/A` only if the user wants complete silence. H3 handles pure silence poorly; concrete sounds reduce noise and mumbling [community].
- **Music** (`non_diegetic_music`; only music the characters can't hear goes here):
- 1–3 English sentences: instruments, tempo, rhythm, dynamics; no mood words;
- music the characters can hear (live performance, radio) goes in the body;
- write `N/A` if none. In `describe` the platform always writes `N/A`.
## 3. Full `raw` structure [official]
### 3.1 First line: picture alignment sentence, followed by a blank line
First frame only:
```text
For the target video, at 0.00 seconds into the target video, (from [Shot 1]) is fully referenced.
```
First + last frame (official wording; the official original has no angle brackets in this sentence):
```text
How the reference pictures align with the target video — Picture 1 (from Shot 1) aligns with the 0.00-second mark of the target video; Picture 2 (from Shot N) aligns with the S.SS-second mark of the target video.
```
- `N` is the number of the last shot.
- `S.SS` is the time the last frame appears, two decimals. This platform's model outputs 24 fps, with frames padded to 17n+5; last-frame time = (frames − 1) ÷ 24. E.g. 8 s is exactly 192 frames, last frame at 7.96 s; 6 s is padded to 158 frames, last frame at 6.54 s.
- On this platform the last frame is numbered after the reference images; replace `Picture 2` in the sentence with the actual number.
### 3.2 Three fields, fixed order, blank line between them
```text
integrated_multimodal_description: [Shot 1] ...
overall_soundscape: ...
non_diegetic_music: ...
```
- `integrated_multimodal_description`: the body, in time order: picture, action, camera, speakers, lines, sung lyrics and sounds audible in the scene. Style goes at the start of `[Shot 1]`, e.g. `[Shot 1] Live-action, cinematic, a medium-wide shot frames ...`. Available styles: cinematic, live-action, 2D-animated, 3D CG, claymation, watercolor, vintage film; with a first frame, the style must match it.
- The other two fields: see 2.6.
- **Lip-sync** refers to the vocal as ``, with lines matching the audio word for word, e.g. `The singer (S1) sings : [Chinese] 晚风吹过河岸 , the mouth following the voice exactly.`
### 3.3 Official example: first frame plus one line
From case 2 of the [official base mode guide](https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/docs/VIDEO_PROMPT_WRITING_GUIDE_base_en.md).
```text
For the target video, at 0.00 seconds into the target video, (from [Shot 1]) is fully referenced.
integrated_multimodal_description: [Shot 1] Live-action, cinematic, the young woman shown in remains beside the rain-covered train window, preserving her appearance, clothing, seat position, and the carriage layout. The camera trucks right with small amplitude at slow speed as she lifts her gaze from the folded letter toward the passing city lights. Her reflection moves across the glass while the quiet, breathy young woman (S1) says: [English] I get off at the next station. She folds the letter along its existing crease.
overall_soundscape: The train wheels produce a steady metallic rhythm beneath a low ventilation hum. Rain ticks against the window while paper rustles softly in her hands.
non_diegetic_music: Sustained cello notes at a slow tempo with widely spaced piano tones, gradually decreasing in volume.
```
### 3.4 Official example: first + last frame, one 8 s shot
Same source, case 3. The body doesn't describe each image separately; it describes the action path connecting them, and the last sentence lands on the last frame.
```text
How the reference pictures align with the target video — Picture 1 (from Shot 1) aligns with the 0.00-second mark of the target video; Picture 2 (from Shot 1) aligns with the 8.00-second mark of the target video.
integrated_multimodal_description: [Shot 1] Live-action, cinematic, a rain-soaked cyclist begins in the position and framing established by Picture 1, holding a closed black umbrella beside a silver bicycle. The camera pulls out with small amplitude at slow speed as she releases the bicycle handle, raises the umbrella above her shoulder, and presses the runner upward until the canopy opens. Water rolls from the expanding fabric while she steps beneath it, rotates the handle into the final angle, and settles into the pose, spacing, and composition established by Picture 2 at the end of the shot.
overall_soundscape: Rain falls steadily on the pavement, followed by the metallic click of the umbrella runner and the soft snap of the canopy opening. Water drips from the bicycle frame as distant traffic passes.
non_diegetic_music: N/A
```
To submit this with `raw` on this platform, change two things:
- the time becomes the platform's computed last-frame time (7.96 for 8 s);
- with reference images, the last-frame number becomes the one after the reference images.
## 4. Per-mode essentials
### Lip-sync (`lipsync`)
- **`--dialogue` must match the vocal word for word**, punctuation included, or the lips go out of sync [community].
- The vocal should ideally be a clean dry vocal; set `--seconds` to the vocal's length.
- **Describe how the person sings and moves** (expression, gestures, camera), not the lyrics.
- For instrumental or non-singing passages, write `keeps relaxed closed lips during instrumental sections and sings only when vocals are audible` [single source].
- **Don't write `restrained`, `subtle`, `minimal`, `almost still` or similar words that hold back the mouth and face** [tested here: same seed, with them the mouth barely moved]. The platform already adds the "every syllable clearly articulated" sentence (see section 1); describe expression, gestures and camera only.
- **Frontal faces and close shots are most stable**; profiles, occlusion, wide shots, multiple people and fast head turns make sync worse [single source: node author]. If the face is too small in the frame, crop the first frame to a closer shot before submitting.
- **Expectation**: H3 generates audio and video together; it is not a forced lip-sync tool, and the lips occasionally mouth something else [single source: node author]. For important shots, generate two takes and pick.
### First frame (`i2v` without a last frame)
- **The first sentence anchors the first frame**: who is where, wearing what, in what scene; then the action that follows.
- Crop the first frame to the target aspect ratio first; if ratios differ, the platform center-crops the excess.
- **After a cut the face drifts**: attach a reference image at that shot's angle [tested here].
- **Starting from the previous clip's last frame (`job:`)**: the new first frame is about 1.5% larger and 5% darker, so the join visibly jumps, even with a dissolve [tested here]. Keep one camera position's action in one clip, or cut to a new angle with its own first frame.
### First + last frame (`i2v` with a last frame)
- **Usually one continuous shot** about the transition, landing on the last frame: `settles into the pose and composition of the final frame at the end of the shot` [official].
- **Keep the two images close**, or the motion stalls midway and then rushes to match at the end [single source].
- **To cut (works in 4 s)**, write `[Shot 2] At 00:02.000, the camera cuts to ...`; the last frame then aligns to Shot 2. Unwritten, the model dissolves or pushes in instead [tested here].
- **Start the last shot in another pose, then move into the last frame** (`still looking down at the cup, then she raises her eyes`), or it freezes on the last frame; a later cut doesn't help [tested here].
- **Same image as first and last frame: describe a closed-loop action** (act, peak, return to the pose), or the picture barely moves [community].
### Text-to-video (`t2v`)
- **There is no image; person, clothing, scene and lighting must all be in the description**, starting from the composition in the first sentence [official: T2VA builds the full timeline from text].
- To keep the same person consistent across several clips, use a free shot, not text-to-video.
### Free shot (`ref2v`)
- **Reference images set appearance; text sets scene, action and camera**; don't describe appearance [official].
- 3–5 sharp close-up person photos, front and side; products, scenes etc. as `other` with a note, each its own subject (`other: a jar of face cream`, `other: a cozy bedroom`).
- With characters too: for several shots in one place attach the same scene image every time (`other: living room`) and just write "living room", so the set stays the same. Scene and prop images use the characters' photo slots; with up to 3 characters, 1–2 is safest.
## 5. Common problems and fixes
| Symptom | Fix | Evidence |
|---|---|---|
| Unwanted cuts or push-ins | Write `in one continuous shot` / a static shot; first + last frame as one shot; if it persists, two takes and pick | [official] [community] [tested here] |
| Hard cuts turn into dissolves, slideshow feel | Write dissolves only when needed; don't write each image as a stop point | [official] [single source] |
| Limbs and clothing break up in fast motion | Lower the speed and amplitude of the action | [community reports] |
| Ghosting on hands | No reliable prompt fix found; generate two takes of important shots and pick | [tested here] |
| Mumbling after speaking, noise at the start | End lines with a period; state lips close after speaking; write concrete ambient sound | [community] |
| Description read aloud as lines, extra voices | Write the description in English; no speech words outside the lines | [community] |
| Subtitles appear in the picture (even with one speaker) | Write the scene fully (shot size, set, lighting, positions, clothing) and add an action after the last line; "no subtitles" doesn't work. Else reroll the seed | [tested here] (same four seeds: short scene 4/4, full scene 0/4) |
| Lines drift onto the wrong mouth | Say who stands where; three people: `raw` pattern, characters.md section 6; two takes | [tested here] |
| Whatever the lines mention appears on screen | Add `the spoken words never add people or objects to the picture` | [single source] |