MiniMax H3 prompt guide

API version: v1.2.4

Write prompts for H3 and H3 Turbo using text, images, video and audio. See the H3 API guide, Turbo API guide and current input limits for supported inputs and settings.

The examples below use ordinary user prompts with automatic enhancement. You do not need to write the model's internal section headings or dialogue tags yourself.

1. Describe a shot that can happen in the requested time

Describe who is present, where they are, their initial state, what happens in order, what the camera does and what is heard. Use concrete actions and keep the number of events manageable. A short clip is unlikely to fit several scene changes and a long conversation.

In a photography studio, a woman stands beside a table holding a closed camera case.
She places it on the table, opens the lid, then lifts the camera out.
One continuous medium shot. The camera slowly tracks right.
No dialogue or voiceover. Only fabric movement and the case latch clicking. No music.

Distinguish the person's movement from the camera's movement. “The camera moves left” does not mean the person turns left. Say when the person stops, turns back, changes gaze or hands an object to another person. State the object's starting owner and the result of each action.

2. Choose the input mode

A reference portrait supplies an identity; it does not automatically supply every prop, pose or background from the portrait. A scene image supplies a setting; it does not automatically become the opening frame. State which details should carry over.

The API uses duration, resolution_tier and aspect_ratio for H3. Do not copy another model's frame count, sampling steps or FPS settings into an H3 recipe. Check the model guide for current ranges. A fixed video seed does not guarantee identical enhancement text or an identical result across versions.

3. Bind references explicitly

For reference-to-video, number references by their array order:

• reference_image_urls[0] is <Picture 1>; the next entry is <Picture 2>.
• reference_video_urls[0] is <Video 1>.
• reference_audio_urls[0] is <Audio 1> when reference-video audio is not enabled.

Use the API tags in API prompts. Labels such as @Image2 in a creation interface are interface notation; do not assume every API client translates them. Optional reference_image_labels, reference_video_labels and reference_audio_labels must match their respective URL arrays in length and order.

<Picture 1>: the man, identity and clothing only.
<Picture 2>: the woman, identity and clothing only.
<Picture 3>: the camera prop.
<Picture 4>: the photography studio location.
The woman lifts the camera from the table while the man adjusts a light stand.
Keep both people inside the scene. Neither addresses the camera.
No dialogue or voiceover. Keep the studio ambience.

Do not reference a picture, video or audio index that you did not attach. Audio alone does not satisfy the reference-to-video image/video input requirement.

When use_ref_video_audio is enabled, the extracted video soundtracks occupy the first audio positions, ahead of separately supplied audio. For example, one video soundtrack followed by two audio references uses <Audio 1> for the soundtrack and <Audio 2>, <Audio 3> for the separate files. Explicitly identify whether each is a voice reference, ambience or music. Do not assume an audio asset automatically belongs to the person at the same image index.

For first/last-frame generation, the anchor pictures use their own opening/ending roles. Avoid mixing reference arrays and frame anchors unless your model's API guide explicitly supports that combination.

4. Provide actual words when you need dialogue

Give the speaker, language and exact words. Put each utterance on its own line. Quotes make the boundary clear:

The woman from <Picture 2> speaks Mandarin using the voice in <Audio 1>.
The man from <Picture 1> speaks Mandarin using the voice in <Audio 2>.
对白｜女人（普通话）：“先试一下这台相机。”
对白｜男人（普通话）：“好，我来调整灯光。”
The woman speaks first. The man listens, then answers. No overlapping speech.

English is also supported as prompt notation:

Ada says: "Stay here."
Ben says: "I will."

With automatic enhancement, the service compiles supplied words into <d>[Language] ...</d> and assigns stable speaker IDs. Spoken words and punctuation should remain in their original language. Do not put gestures, camera instructions or voice descriptions inside the spoken words.

A bare instruction such as “the host introduces the shoes” does not provide a script. Write the words yourself when they matter; enhancement should not invent words just to satisfy a format check. Explicit unquoted Ada says: Stay here. is also recognized; one line per utterance avoids mixing subsequent action with the words.

Quotes alone do not mean speech. These are visual descriptions:

A sign reads "EXIT".
A character named "Ada" wears a "watercolor" patterned coat.

If a character should read visible writing aloud, state that separately: Ada says: "EXIT".

5. Separate dialogue, voiceover and nonverbal sound

“No dialogue” allows footsteps, room noise and instrumental music when requested. “Complete silence” requests no audio events. “Do not speak to the camera” is a camera/performance constraint; it is not a request to supply dialogue.

6. Keep the camera and timeline consistent

For one take, say “one continuous shot, no cuts” and use a single camera path. For a cut, state the new viewpoint and what happens before and after it. Avoid asking for an unbroken POV and an external view of the same character at the same time.

One continuous shot. Begin behind the woman and slowly move to her right side.
She looks at the camera prop on the table throughout. She does not turn toward the lens.

For multiple shots, keep cuts inside the requested clip duration. Allow time for physical action and speech. Do not require a line to finish after the video ends. For dialogue across a cut, state that the same speaker continues the same line without restarting it. Automatic enhancement handles the model's cut and continuation syntax.

State screen direction or scene-relative direction when “left” could be ambiguous. A person looking behind them while continuing forward does not necessarily reverse travel. References and a clear prompt improve control; they do not guarantee perfect identity, lip synchronization or physical continuity in the generated video.

7. Preview automatic enhancement

POST /api/v1/inference/prompt/enhance accepts a prompt and model, with the same duration and reference context you plan to submit. Authenticate with X-API-Key. It returns text only and does not create a video job.

curl --fail-with-body https://phosor.ai/api/v1/inference/prompt/enhance \
  -H "X-API-Key: $PHOSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/h3/text-to-video",
    "prompt": "A woman opens a camera case in a studio. One continuous medium shot. No dialogue or voiceover. Only the latch clicking and room ambience.",
    "duration": 5
  }'

Check enhanced and reason, then review prompt. HTTP 200 with enhanced: false is an enhancement failure, not successful preparation. If submitting a reviewed structured prompt, set enhance_prompt: false and enable_prompt_expansion: false to avoid another rewrite. Preserve the same references and duration.

Normal H3 submission enables automatic enhancement unless explicitly disabled or the prompt is already recognized as structured. When required enhancement fails, submission stops rather than silently sending the rejected original. A failure after a credit deduction follows the refund path. Preview success confirms text preparation; it does not certify the quality of a generated video.

Manually structured prompts require the full model format. Base generation uses integrated_multimodal_description, overall_soundscape, non_diegetic_music; reference generation uses subject_definitions, summary, retention_analysis, detailed_description, overall_soundscape, non_diegetic_music. Dialogue containers are for actual spoken words. Use automatic enhancement unless you maintain this format yourself.

8. Troubleshoot and manage results

Preserve your original prompt, model, reference order, duration, settings, enhanced text if previewed and request_id. Retrieve completed outputs using result and download the video if you need a durable copy; do not use an expiring result URL as your only archive. Use history to find prior requests. For support, share the request ID and error, without sharing API keys.

9. A compact recipe checklist

Before submitting, choose the exact H3 or H3 Turbo model ID and supply the inputs required by that mode. H3 uses duration (4–15 seconds), resolution_tier (480p or 768p) and aspect_ratio; it does not support negative_prompt. See the linked model guide and current limits before combining references.

• One continuous shot: give one camera path and a short action sequence.
• Visible dialogue: identify the speaker and supply exact words.
• Generated narration: identify the narrator, exact words and voiceover mode.
• Narration added later in an editor: do not supply it as an utterance to generate. State that this request contains no spoken words. Check the enhanced text for unwanted <d> containers before submission.
• Reference inputs: bind each image, video and audio by its actual array order. A picture number never implies a matching voice number.

Enhancement can fail or misunderstand intent. In particular, quoted labels, softly spoken lines and post-production narration need careful preview review. If no video audio is requested, an unwanted spoken line in a preview is an error, even if enhanced is true. Do not approve that preview just because it passed automatic checks.

10. A complete reference request

This example uses two images and one voice reference. Replace all placeholder media URLs with your own accessible assets. It creates a paid video request; use only after reviewing the references, prompt and estimate.

curl --fail-with-body https://phosor.ai/api/v1/inference/submit \
  -H "X-API-Key: $PHOSOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax/h3/reference-to-video/turbo",
    "prompt": "<Picture 1> supplies the identity and clothing of Ada. <Picture 2> supplies the studio setting. Use <Audio 1> as Ada voice timbre. Ada says: \"Hello.\" One continuous medium shot. No other dialogue, music or subtitles.",
    "reference_image_urls": ["https://your-public-host.example/person.jpg", "https://your-public-host.example/studio.jpg"],
    "reference_image_labels": ["Ada identity and clothing", "studio setting"],
    "reference_audio_urls": ["https://your-public-host.example/voice.mp3"],
    "reference_audio_labels": ["Ada voice timbre"],
    "duration": 4,
    "resolution_tier": "480p",
    "aspect_ratio": "16:9",
    "enhance_prompt": true
  }'

For a silent reference request, remove the audio arrays and replace the spoken sentence with explicit action and ambience. Do not attach an unused voice reference and expect it to mute speech.

11. Review a preview before adopting it

A successful preview has the following shape; the actual text is longer and depends on your input:

{
  "original_prompt": "Your original description",
  "prompt": "The generated structured execution prompt",
  "enhanced": true,
  "reason": "The enhancement result or failure explanation",
  "disable_vendor_expansion": true
}

Check all of the following before accepting it:

1. Every required action remains in the original order.
2. Only your intended spoken words appear in <d>; visual text and asset labels do not.
3. Speaker, voiceover mode and reference bindings are correct.
4. The shot plan fits the requested duration and camera constraints.
5. No new spoken lines were introduced.

When adopting this plain preview workflow, use the returned prompt as the submit prompt, preserve the original model, duration, frame anchors and reference arrays, and set enhance_prompt and enable_prompt_expansion to false. Do not submit a preview with enhanced: false. If your endpoint uses an additional reviewed-adaptation receipt, follow that endpoint contract rather than inventing or editing receipt fields.

Previewing and a later automatic submit enhancement are separate calls and can produce different text. To verify exactly the reviewed text, adopt it explicitly as above. Passing enhancement is not proof of video quality; inspect the actual output and its audio.

12. Short scenario templates

These are starting points, not guaranteed outputs. Keep dialogue short enough to finish naturally, and check the generated video for missing actions, extra speech, wrong voices or broken continuity.