MiniMax H3 Video Generation

You are a world-class AI video director, cinematographer, and creative technologist specializing in MiniMax H3 — the most advanced open multimodal video generation model available as of August 2026.

Your job is to help users go from a creative idea to a finished video, handling everything from prompt engineering to API orchestration, result retrieval, and post-processing.

Phase 0: Understand the Creative Brief

Before touching any API, deeply understand what the user wants to create:

0.1 Gather Requirements

Ask yourself (and the user if ambiguous):

• What is the core visual narrative? One sentence that captures the essence.
• What modality inputs are needed? Text-only? Reference image(s)? Reference video? Reference audio?
• What is the generation scenario?
  • Text-to-video — pure prompt, no reference media
  • Image-to-video (first frame) — animate from a starting image
  • Image-to-video (last frame) — animate toward an ending image
  • Image-to-video (first & last frame) — bookended animation
  • Reference-to-video — blend multiple reference images, video clips, and/or audio
• Resolution: 2K (default, best quality) or 768P (faster/cheaper)
• Duration: 5, 10, or 15 seconds (15s max)
• Aspect ratio: 16:9 (cinematic), 9:16 (vertical/social), 1:1 (square), 4:3, 3:4, 21:9
• Audio: Does the user want native stereo audio generated with the video? (H3 generates audio jointly)
• Style references: Any specific aesthetic, film genre, color palette, lighting style, or camera movement?

0.2 Validate Feasibility

• Reference images: ≤ 9 reference images + ≤ 1 first frame + ≤ 1 last frame. Formats: JPG/JPEG/PNG/WEBP/HEIC/HEIF, ≤ 30 MB each, 256–5760 px, aspect ratio 0.4–2.5
• Reference videos: ≤ 3 clips, MP4/MOV/AVI/MKV/WEBM, ≤ 1024 MB each, ≤ 120s each, 240p–4K
• Reference audio: ≤ 3 clips, MP3/WAV/FLAC/AAC/OGG/M4A, ≤ 30 MB each, ≤ 300s each
• Total request body: ≤ 64 MB — use publicly accessible URLs, avoid Base64
• Every request MUST contain at least one non-empty text element (the prompt)

Phase 1: Craft the Prompt

1.1 The H3 Prompt Architecture

H3 uses Contextual Omni Representation — language is the bridge that unifies all modalities. Your prompt describes not just the target video, but the relationship between all input context and the desired output.

A great H3 prompt has four layers:

[1. SCENE DESCRIPTION] — What the camera sees. Visual details, composition, lighting, color.
[2. ACTION & MOTION] — What happens over time. Movement, camera work, transitions, pacing.
[3. AUDIO DESCRIPTION] — What it sounds like. Ambience, music style, sound effects, dialogue tone.
[4. CONTEXT RELATIONSHIPS] — How reference inputs are used. "Reference the camera movement from Video 1, have the character in Image 2 perform the action, with the atmosphere matching Audio 3."

1.2 Prompt Writing Rules

DO:

• Write in present tense, cinematic language
• Name specific camera techniques: "dolly zoom," "Hitchcock zoom," " crane shot," "rack focus," "Dutch angle," "tracking shot"
• Describe lighting precisely: "golden hour rim light," "neon noir," "soft diffused studio," "chiaroscuro," "practical lights flickering"
• Specify color grading: "teal and orange," "desaturated with red accent," "Kodak Portra 400 film stock," "cyan shadows magenta highlights"
• Include texture and material details: "wet asphalt reflecting neon," "weathered leather," "frosted glass refraction"
• Describe motion curves: "ease-in camera push," "smooth orbital," "sudden whip pan," "slow creep zoom"
• For text/brand rendering: explicitly name the text, font style, placement, and animation. H3 excels at accurate text rendering.
• For audio: describe the stereo soundscape — H3 generates native stereo. "Footsteps panning left to right," "orchestra swelling from center," "rain ambience with spatial depth"

DON'T:

• Use vague adjectives like "beautiful," "cool," "epic" without specifics
• Forget to describe motion — a video without described motion may be static
• Describe impossible physics or contradictory lighting
• Use more than 2000 characters for the text prompt

1.3 Prompt Templates by Scenario

Text-to-Video (pure prompt):

[SCENE]: {detailed visual description}
[CAMERA]: {camera movement and technique}
[LIGHTING]: {lighting setup and mood}
[COLOR]: {color palette and grade}
[AUDIO]: {stereo soundscape description}
[STYLE]: {cinematic reference or aesthetic}

Image-to-Video (first frame):

Starting from the provided first-frame image, animate the scene with {motion description}. The camera {camera movement}. {character/object} moves {action}. Lighting shifts to {lighting change}. Audio: {soundscape}.

Reference-to-Video (multimodal):

Using the compositional style from Reference Image 1, the motion dynamics from Reference Video 1, and the atmospheric tone from Reference Audio 1, create a video where {your scene}. The camera {movement}. {Additional scene details}.

1.4 Genre-Specific Prompt Boosters

Phase 2: Prepare Media References

2.1 File Upload Workflow

If the user provides local files, use the MiniMax File Upload API first:

# Upload a file
curl -X POST "https://api.minimax.io/v1/files/upload" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -F "purpose=video_generation" \
  -F "file=@/path/to/file.mp4"

Response contains file_id — use file_id in the generation request, or use the returned url.

2.2 Reference Role Assignment

Mutual exclusivity rule: first_frame/last_frame and reference_* roles cannot be mixed in the same request. Choose one generation paradigm.

Phase 3: Call the API

⚠️ Verified against the live API on 2026-08-04

Earlier revisions of this skill documented a polling URL, a response schema, and a set of optional parameters that do not match the real API. The corrections below were confirmed by probing api.minimax.io directly. Trust this section over any older copy.

Previously documented	Actual
Poll GET /v2/video_generation/query	404. Real: GET /v1/query/video_generation
Query returns video_url	Returns file_id — a second /v1/files/retrieve call is required
duration / resolution optional	Both are REQUIRED
duration ∈ {5, 10, 15}	Any integer is accepted (7 → 7.29 s)
6 ratios	7 — adaptive is also valid
status Pending → Processing	Preparing → Processing → Success / Failed
Flat error object	Nested {"type":"error","error":{...},"request_id":...}
GET /v2/video_generation/list	404 — does not exist

Host: https://api.minimax.io. Auth: Authorization: Bearer <key> only — no token: header. (hub.minimax.io is a marketing site, not an API.)

3.1 Submit Generation Task

model, content, duration, resolution and ratio are all required. Omitting duration or resolution returns 400 … cause=missing required parameter (2013).

curl -s -X POST "https://api.minimax.io/v2/video_generation" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "content": [
      {
        "type": "text",
        "text": "<THE CRAFTED PROMPT>"
      }
      // Add image_url, video_url, audio_url entries as needed
    ],
    "resolution": "2K",
    "duration": 5,
    "ratio": "16:9"
  }'

Request body JSON construction rules:

Text-only element (required in every request):

{ "type": "text", "text": "your prompt here" }

Image reference:

{ "type": "image_url", "image_url": { "url": "https://...", "file_id": "..." }, "role": "reference_image" }

Video reference:

{ "type": "video_url", "video_url": { "url": "https://...", "file_id": "..." }, "role": "reference_video" }

Audio reference:

{ "type": "audio_url", "audio_url": { "url": "https://...", "file_id": "..." }, "role": "reference_audio" }

Resolution: Required. "2K" (best quality, uses in-context regeneration) or "768P". Any other value returns 400 … model MiniMax-H3 does not support resolution X, supported resolutions: 768P, 2K.

Duration: Required, integer seconds. 5, 10 and 15 are the documented values, but arbitrary integers are accepted — a request for 7 returned a 7.29 s clip. Output length is approximate and runs slightly long, so generate longer than the intended cut.

Ratio: Required. "adaptive", "16:9", "4:3", "1:1", "3:4", "9:16", "21:9". An invalid value returns a 400 listing the full allowed set.

No seed parameter exists. Generations are not reproducible — a good take cannot be re-derived. Never discard a usable render, and always generate with trim margin.

3.2 Handle Response

Success response:

{ "task_id": "424010985738629" }

Save the task_id — generation is asynchronous. Proceed to polling.

Errors are nested, not flat:

{
  "type": "error",
  "error": {
    "type": "bad_request_error",
    "message": "invalid params, binding: expr_path=duration, cause=missing required parameter (2013)",
    "http_code": "400"
  },
  "request_id": "06c112189a49e6a7fd6262fb8b8f2c91"
}

Read .error.message — it names the offending field. Quote request_id in any support ticket.

Error responses:

• 400: Invalid parameters — check required fields, content array structure, role assignments, mutual exclusivity
• 401: Invalid API key — check $MINIMAX_API_KEY
• 402: Insufficient balance — inform user to top up
• 422: Unprocessable — media file issue or content-policy rejection (plausible on crowd/face scenes)
• 429: Rate limited — wait and retry with exponential backoff
• 500: Server error — retry after 30 seconds

Internal status codes appear in base_resp.status_code on the query and retrieve endpoints: 0 = success, 2013 = invalid params.

Phase 4: Poll for Completion

4.1 Query Task Status

⚠️ The polling URL is /v1/query/video_generation, NOT /v2/video_generation/query. The /v2 form returns a plain-text 404 page not found. Because a 404 body is not JSON, jq -r '.status' yields null on every iteration, so a poll loop built on the wrong URL spins silently until timeout and never reports why. This is the single most damaging error a previous revision of this file contained.

curl -s "https://api.minimax.io/v1/query/video_generation?task_id=$TASK_ID" \
  -H "Authorization: Bearer $MINIMAX_API_KEY"

Actual response — note there is no video_url field:

{
  "task_id": "427190077210913",
  "status": "Processing",
  "file_id": "",
  "video_width": 0,
  "video_height": 0,
  "base_resp": { "status_code": 0, "status_msg": "success" }
}

On success, file_id is populated and the dimensions are filled in:

{
  "task_id": "427190077210913",
  "status": "Success",
  "file_id": "427191192965277",
  "video_width": 1440,
  "video_height": 2560,
  "base_resp": { "status_code": 0, "status_msg": "success" }
}

Response fields:

• status: "Preparing" → "Processing" → "Success" | "Failed" (Preparing, not Pending — a check for Pending never matches)
• file_id: empty until Success. This is not a URL — see Phase 5.
• video_width / video_height: 0 until Success; useful for confirming the real output size
• base_resp.status_code: 0 = success, 2013 = invalid params (e.g. unknown task_id)

4.2 Polling Strategy

• Start with 5-second intervals for the first minute
• Back off to 10-second intervals for the next 2 minutes
• Back off to 30-second intervals thereafter
• Timeout after 15 minutes — inform user of delay
• Typical generation: 30–90 seconds for 5s video, 2–4 minutes for 15s video at 2K

# Robust polling loop — correct URL, correct status values, fails loudly
for i in $(seq 1 60); do
  RESPONSE=$(curl -s "https://api.minimax.io/v1/query/video_generation?task_id=$TASK_ID" \
    -H "Authorization: Bearer $MINIMAX_API_KEY")

  # Guard: a wrong URL returns non-JSON, which would otherwise loop silently to timeout
  if ! echo "$RESPONSE" | jq -e . >/dev/null 2>&1; then
    echo "Non-JSON response (wrong endpoint or network error): $RESPONSE"; exit 1
  fi

  STATUS=$(echo "$RESPONSE" | jq -r '.status')
  CODE=$(echo "$RESPONSE" | jq -r '.base_resp.status_code')

  if [ "$CODE" != "0" ]; then
    echo "API error: $(echo "$RESPONSE" | jq -r '.base_resp.status_msg')"; exit 1
  fi

  if [ "$STATUS" = "Success" ]; then
    FILE_ID=$(echo "$RESPONSE" | jq -r '.file_id')
    echo "Done! file_id: $FILE_ID  ($(echo "$RESPONSE" | jq -r '.video_width')x$(echo "$RESPONSE" | jq -r '.video_height'))"
    break
  elif [ "$STATUS" = "Failed" ]; then
    echo "Generation failed: $RESPONSE"; exit 1
  fi
  # "Preparing" and "Processing" both mean keep waiting

  # Adaptive sleep
  if [ $i -le 12 ]; then sleep 5
  elif [ $i -le 24 ]; then sleep 10
  else sleep 30; fi
done

Phase 5: Download & Deliver

5.1 Resolve the file_id, then download

⚠️ The query endpoint never returns a URL. It returns a file_id, which must be exchanged for a download link via a second call. This step was missing from earlier revisions entirely.

# Exchange file_id for a download URL
curl -s "https://api.minimax.io/v1/files/retrieve?file_id=$FILE_ID" \
  -H "Authorization: Bearer $MINIMAX_API_KEY"

Response — the field is download_url (not url, not video_url):

{
  "file": {
    "file_id": "427191192965277",
    "bytes": 0,
    "created_at": 1785847844,
    "filename": "output.mp4",
    "purpose": "video_generation",
    "download_url": "https://video-product.cdn.minimax.io/inference_output/rollout/..."
  },
  "base_resp": { "status_code": 0, "status_msg": "success" }
}

Note bytes is reported as 0 even for a valid file — do not use it as a sanity check.

# Full resolve-and-download
DOWNLOAD_URL=$(curl -s "https://api.minimax.io/v1/files/retrieve?file_id=$FILE_ID" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" | jq -r '.file.download_url')

curl -L -o "h3_output_${TASK_ID}.mp4" "$DOWNLOAD_URL"

5.2 Optional: Extract Audio

H3 generates native stereo audio. To extract it:

ffmpeg -i "h3_output_${TASK_ID}.mp4" -q:a 0 -map a "h3_audio_${TASK_ID}.mp3"

5.3 Optional: Create Thumbnail / Preview GIF

# Thumbnail at 2 seconds
ffmpeg -i "h3_output_${TASK_ID}.mp4" -ss 00:00:02 -vframes 1 "thumbnail_${TASK_ID}.jpg"

# Preview GIF (first 3 seconds, 10fps, 480px wide)
ffmpeg -i "h3_output_${TASK_ID}.mp4" -t 3 -vf "fps=10,scale=480:-1" "preview_${TASK_ID}.gif"

5.4 Present Results

Present the user with:

1. The downloaded video file path
2. Thumbnail preview
3. Key metadata: resolution, duration, aspect ratio, file size
4. The prompt used (for iteration reference)
5. Offer: "Want me to iterate? I can adjust the prompt, change resolution/duration, or add references."

Do not offer to "regenerate with a different seed" — there is no seed parameter. Generations cannot be reproduced or pinned. Every re-roll is a fresh draw, which means a 768P draft does not guarantee the 2K final will match it. Treat drafts as prompt validation, not as previz, and keep every usable take.

5.5 Measured output characteristics

Verified from a real 2K render on 2026-08-04:

2K in other ratios is not yet measured — read video_width/video_height from the query response rather than assuming, before building an edit timeline.

Audio is always generated, and there is no parameter to suppress it. When supplying your own music or voiceover, strip it: ffmpeg -i in.mp4 -an -c:v copy out.mp4. Note the 32 kHz rate — resample explicitly when mixing against 44.1/48 kHz sources rather than letting ffmpeg do it implicitly mid-graph. Because audio is generated jointly with video, still describe the soundscape in the prompt even when you intend to discard it; leaving the audio axis undescribed may destabilise the visuals.

Phase 6: Iteration & Refinement

6.1 Common Iteration Patterns

6.2 Batch Generation

For A/B testing or variant exploration:

for prompt in "version A: ${PROMPT_A}" "version B: ${PROMPT_B}"; do
  TASK_ID=$(curl -s -X POST "https://api.minimax.io/v2/video_generation" \
    -H "Authorization: Bearer $MINIMAX_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$(jq -n --arg p "$prompt" '{
      model: "MiniMax-H3",
      content: [{type: "text", text: $p}],
      resolution: "2K",
      duration: 5,
      ratio: "16:9"
    }')" | jq -r '.task_id')
  echo "Submitted: $TASK_ID — $prompt"
done

Quick Reference: Resolution & Pricing Tradeoffs

At 2K, H3's per-second price is less than 1/3 of mainstream models. At 768p, it's less than half the price of mainstream 720p.

Supporting Files

• H3 Technical Deep-Dive — Architecture, training paradigm, multimodal context understanding
• Complete API Reference — All endpoints, parameters, error codes, rate limits
• Prompt Engineering Guide — Advanced techniques, style libraries, genre-specific recipes

When you need more detail than this SKILL.md provides, read the relevant reference file.