MiniMax H3 Video Generation
Direct access to MiniMax's flagship video model MiniMax-H3 (launched 2026-07-31, successor to the Hailuo line) using the user's own API key. Open-weight, multimodal, native stereo sound. Ranked #1 video editing / #2 text-to-video / #3 image-to-video (Artificial Analysis). Specs: up to 15s at native 2K, native stereo audio in one pass.
When to use this vs siblings
- MiniMax H3 (this skill): native 2K + stereo sound in one pass, reference-to-video (feed subject images/video/audio), first+last-frame morphs. Strong cinematic motion.
- fal-ai-generation: broader model catalog (Veo, Kling, Sora), image gen, LoRA. Note: fal balance was exhausted as of 2026-07 — confirm before routing there.
- higgsfield-generate: separate general-creative slate, credits/MCP. Do NOT inject Cheonma palette into video prompts unless the user names the brand.
- Built-in bfl_flux3_ tools:* first-party Flux 3 (runtime-native). H3 is a separate, parallel option — pick per brief.
Auth
MINIMAX_API_KEY is set in ~/.hermes/profiles/creative/.env (the active profile's env — this is where the user put it). The script also falls back to ~/.hermes/.env and the shell env. Bearer auth.
Region matters — key and host MUST match or you get invalid api key:
- Global: host
https://api.minimax.io (key from minimax.io platform)
- Mainland China: host
https://api.minimaxi.com (key from minimaxi.com)
Default to global. Get a key: https://platform.minimax.io → user-center → interface-key. New accounts get starter credits.
Call pattern (async, like fal.ai's queue)
POST {BASE}/v2/video_generation with JSON {model:"MiniMax-H3", content:[...], duration, resolution, ratio?} → returns task_id.- Poll
GET {BASE}/v2/query/video_generation/{task_id} every ~10s. task.status: succeeded → task.content.url is the direct download URL; terminal fails are failed/cancelled/expired.
- Download the mp4 to
~/Downloads/ (user convention: VisualOutput→SaveToDownloads).
The content[] structure (multimodal)
Each element has a type and optional role:
{"type":"text","text":"..."} — required; defines content + motion.{"type":"image_url","image_url":{"url":"..."},"role":"first_frame"} — opening frame (i2v).{"type":"image_url","image_url":{"url":"..."},"role":"last_frame"} — ending frame.{"type":"image_url","image_url":{"url":"..."},"role":"reference_image"} — subject reference (also reference_video / reference_audio).
The four modes
| Mode |
content[] |
ratio |
| text-to-video (t2va) |
text only |
required, not 'adaptive' (e.g. "16:9") |
| image-to-video (i2va) |
text + first_frame |
adaptive — omit ratio (set by image) |
| first+last frame |
text + first_frame + last_frame |
adaptive — omit ratio |
| reference-to-video (r2va) |
text + reference_image(s) |
adaptive — omit ratio |
Params
duration: 4–15 (seconds).resolution: "2K" (the public tier). "768P" exists but is closed beta — contact sales; don't default to it.ratio: only for t2v. e.g. "16:9", "9:16", "1:1".
Pricing (pay-as-you-go, 2K)
- Video: $0.13/sec (5s ≈ $0.65, 15s ≈ $1.95). 768P would be $0.09/sec but is beta.
- Input audio: free. Input images: first 5 free, then $0.04 each. Input video: billed at output resolution rate.
Usage
python3 scripts/minimax_video.py --mode t2v --prompt "..." --ratio 16:9 --duration 5 --out ~/Downloads/h3.mp4
python3 scripts/minimax_video.py --mode i2v --prompt "..." --image https://.../frame.png --duration 5
python3 scripts/minimax_video.py --mode flf --prompt "..." --image https://.../first.png --last-image https://.../last.png
python3 scripts/minimax_video.py --mode ref --prompt "..." --ref https://.../subject.png --ref https://.../style.png
Runs submit→poll→download. Poll interval 10s; generation takes minutes — run via background terminal with notify_on_complete for long clips.
Pitfalls
- Image inputs must be public URLs in v1 — the API's
image_url wants a URL, not a local path. Host local frames somewhere public first (or use MiniMax's file-upload endpoint — not yet wired into the script). Text-only t2v needs no images.
- ratio is mandatory for t2v and forbidden ('adaptive') for the image modes. Getting this wrong → 400.
- Region mismatch =
invalid api key — it's almost always host/key region, not a bad key.
- Don't burn retries on a failed task — read
task.error; content-policy rejections won't succeed on retry.
- Generation is slow (minutes). Poll, don't hammer; 10s interval is the documented recommendation.
Support files
scripts/minimax_video.py — CLI: submit→poll→download for all four modes. Reads MINIMAX_API_KEY from ~/.hermes/.env.
Related skills
fal-ai-generation (catalog/LoRA/images), higgsfield-generate (credits slate), ai-video-editing + ai-video-generation (assembly/pacing — the user directs edits himself; defer to his eye), comfyui (local pipelines; H3 open-weights may run locally later).
1---2name: minimax-video-generation3description: Use when generating video with MiniMax H3.4---5
6# MiniMax H3 Video Generation
7
8Direct access to MiniMax's flagship video model **MiniMax-H3** (launched 2026-07-31, successor to the Hailuo line) using the user's own API key. Open-weight, multimodal, native stereo sound. Ranked #1 video editing / #2 text-to-video / #3 image-to-video (Artificial Analysis). Specs: up to 15s at native 2K, native stereo audio in one pass.
9
10## When to use this vs siblings
11- **MiniMax H3 (this skill):** native 2K + stereo sound in one pass, reference-to-video (feed subject images/video/audio), first+last-frame morphs. Strong cinematic motion.
12- **fal-ai-generation:** broader model catalog (Veo, Kling, Sora), image gen, LoRA. Note: fal balance was exhausted as of 2026-07 — confirm before routing there.
13- **higgsfield-generate:** separate general-creative slate, credits/MCP. Do NOT inject Cheonma palette into video prompts unless the user names the brand.
14- **Built-in bfl_flux3_* tools:** first-party Flux 3 (runtime-native). H3 is a separate, parallel option — pick per brief.
15
16## Auth
17`MINIMAX_API_KEY` is set in `~/.hermes/profiles/creative/.env` (the active profile's env — this is where the user put it). The script also falls back to `~/.hermes/.env` and the shell env. Bearer auth.
18**Region matters — key and host MUST match or you get `invalid api key`:**
19- Global: host `https://api.minimax.io` (key from minimax.io platform)
20- Mainland China: host `https://api.minimaxi.com` (key from minimaxi.com)
21Default to global. Get a key: https://platform.minimax.io → user-center → interface-key. New accounts get starter credits.
22
23## Call pattern (async, like fal.ai's queue)
241. `POST {BASE}/v2/video_generation` with JSON `{model:"MiniMax-H3", content:[...], duration, resolution, ratio?}` → returns `task_id`.
252. Poll `GET {BASE}/v2/query/video_generation/{task_id}` every ~10s. `task.status`: `succeeded` → `task.content.url` is the direct download URL; terminal fails are `failed`/`cancelled`/`expired`.
263. Download the mp4 to `~/Downloads/` (user convention: VisualOutput→SaveToDownloads).
27
28### The `content[]` structure (multimodal)
29Each element has a `type` and optional `role`:
30- `{"type":"text","text":"..."}` — required; defines content + motion.
31- `{"type":"image_url","image_url":{"url":"..."},"role":"first_frame"}` — opening frame (i2v).
32- `{"type":"image_url","image_url":{"url":"..."},"role":"last_frame"}` — ending frame.
33- `{"type":"image_url","image_url":{"url":"..."},"role":"reference_image"}` — subject reference (also `reference_video` / `reference_audio`).
34
35### The four modes
36| Mode | content[] | ratio |
37|------|-----------|-------|
38| text-to-video (t2va) | text only | **required**, not 'adaptive' (e.g. "16:9") |
39| image-to-video (i2va) | text + first_frame | adaptive — omit ratio (set by image) |
40| first+last frame | text + first_frame + last_frame | adaptive — omit ratio |
41| reference-to-video (r2va) | text + reference_image(s) | adaptive — omit ratio |
42
43### Params
44- `duration`: 4–15 (seconds).
45- `resolution`: `"2K"` (the public tier). `"768P"` exists but is **closed beta** — contact sales; don't default to it.
46- `ratio`: only for t2v. e.g. "16:9", "9:16", "1:1".
47
48## Pricing (pay-as-you-go, 2K)
49- Video: **$0.13/sec** (5s ≈ $0.65, 15s ≈ $1.95). 768P would be $0.09/sec but is beta.
50- Input audio: free. Input images: first 5 free, then $0.04 each. Input video: billed at output resolution rate.
51
52## Usage
53```bash
54python3 scripts/minimax_video.py --mode t2v --prompt "..." --ratio 16:9 --duration 5 --out ~/Downloads/h3.mp4
55python3 scripts/minimax_video.py --mode i2v --prompt "..." --image https://.../frame.png --duration 5
56python3 scripts/minimax_video.py --mode flf --prompt "..." --image https://.../first.png --last-image https://.../last.png
57python3 scripts/minimax_video.py --mode ref --prompt "..." --ref https://.../subject.png --ref https://.../style.png
58```
59Runs submit→poll→download. Poll interval 10s; generation takes minutes — run via background terminal with notify_on_complete for long clips.
60
61## Pitfalls
62- **Image inputs must be public URLs** in v1 — the API's `image_url` wants a URL, not a local path. Host local frames somewhere public first (or use MiniMax's file-upload endpoint — not yet wired into the script). Text-only t2v needs no images.
63- **ratio is mandatory for t2v and forbidden ('adaptive') for the image modes.** Getting this wrong → 400.
64- **Region mismatch = `invalid api key`** — it's almost always host/key region, not a bad key.
65- Don't burn retries on a failed task — read `task.error`; content-policy rejections won't succeed on retry.
66- Generation is slow (minutes). Poll, don't hammer; 10s interval is the documented recommendation.
67
68## Support files
69- `scripts/minimax_video.py` — CLI: submit→poll→download for all four modes. Reads MINIMAX_API_KEY from ~/.hermes/.env.
70
71## Related skills
72`fal-ai-generation` (catalog/LoRA/images), `higgsfield-generate` (credits slate), `ai-video-editing` + `ai-video-generation` (assembly/pacing — the user directs edits himself; defer to his eye), `comfyui` (local pipelines; H3 open-weights may run locally later).
theheavenlyd3mon