minimax-h3-spec

A machine-readable spec sheet for MiniMax H3 (the video model MiniMax also ships as Hailuo 3), plus a small validator that catches the request errors the API only tells you about after it has charged you.

Every field in h3_spec.json carries the source it came from. If a number here disagrees with something you read elsewhere, open an issue — several of the highest-ranking pages about this model contradict MiniMax's own API reference, and I would rather be corrected than copied.

pip install h3check

h3check grid
h3check cost --duration 8 --resolution 2K
h3check validate request.json

No dependencies, at runtime or for the tests. Python 3.9+. python3 -m h3check ... works too, and the package is two files — copy src/h3check/__init__.py and src/h3check/h3_spec.json side by side into another project if you would rather vendor it than depend on it.

Full documentation, including every validation message with its cause and fix, is at minimax-h3-spec.readthedocs.io.

The thing that surprised me: the duration you ask for is not the duration you get

H3 renders on a frame-block grid. Frame count follows 17n + 5, and the output is 24 fps, so most durations land on a fraction of a second:

  n  frames   seconds
  6     107     4.458
  7     124     5.167
  8     141     5.875
  9     158     6.583
 10     175     7.292
 11     192     8.000  <- whole second
 12     209     8.708
 13     226     9.417
 14     243    10.125
 15     260    10.833
 16     277    11.542
 17     294    12.250
 18     311    12.958
 19     328    13.667
 20     345    14.375

Ask for 5 seconds and you get 5.167. Ask for 10 and you get 10.125.

Exactly one value in the 4–15 second range lands on a whole second. Solve (17n + 5) mod 24 = 0, i.e. 17n ≡ 19 (mod 24). Since 17 is its own inverse mod 24, n ≡ 11 (mod 24), and only n = 11 falls in range: 192 frames, exactly 8.000 seconds.

Anyone can check that with a calculator, which is why I was surprised not to find it documented anywhere. If you are cutting to music, or stitching clips end to end, 8 seconds is the only length that will not drift.

Three more things the validator catches

The reference-file caps do not add up the way they look. Nine images, three clips and three audio files is 15, and 15 is the number several write-ups print. The API caps the total at 12. h3check.py validate fails the request before you upload 40 MB of assets.

There is no 1080p and no 4K. Output is 768P or 2K, with nothing in between and nothing above. A request for 1080p is rejected, not downgraded. The 2K path is also not an upscale — the 768P result is fed back through the model together with your original context and generated again, which is why small on-screen text survives it.

Audio is not optional. Picture and 32 kHz stereo come out of the same forward pass. There is no on/off switch and no separate line on the bill, because there is no separate step. If your code sets generate_audio: false, it is being ignored.

Example

$ cat request.json
{
  "mode": "ref2va",
  "duration": 10,
  "resolution": "2K",
  "aspect_ratio": "9:16",
  "references": {
    "images": ["a.png", "b.png", "c.png", "d.png", "e.png",
               "f.png", "g.png", "h.png", "i.png"],
    "videos": [{"url": "clip.mp4", "seconds": 6}],
    "audio":  [{"url": "vo1.wav",  "seconds": 5},
               {"url": "vo2.wav",  "seconds": 5},
               {"url": "room.wav", "seconds": 5}]
  }
}

$ h3check validate request.json
FAIL
  ERROR    13 reference files exceeds the total cap of 12 - the per-type caps add up to 15, but the total is 12
  note     duration 10s renders as 243 frames = 10.125s (n=14). The only whole second in range is 8.000s (192 frames).
  note     hosted cost at 2K: $1.3163 for 10.125 rendered seconds

Each of those three inputs is legal on its own — nine images is the image cap, one clip is under the clip cap, three audio files is the audio cap. It is the total that fails.

What is actually open

H3 is three stages, and only the middle one was published:

So downloading the weights gets you the middle stage. It is also worth saying "open weights" rather than "open source": the MiniMax H3 Community License fails two of the OSI's ten criteria, and Hugging Face's own tag for it is other. The territory restriction is the part most summaries stop short of — §V.4 extends it to the outputs, not just the weights.

Sources and further reading

The spec tables this repo is generated from, with each row linked to its primary source and dated, live at minimax-h3ai.video — that site is also a browser-based MiniMax H3 video generator if you want to check a claim against a real render rather than take my word for it. The first clip runs without an account.

Two pages there go deeper than this README does:

• The reference-to-video caps in full, including per-file size and aspect-ratio bounds
• A clause-by-clause reading of the H3 licence, including the output clause

Primary sources for everything else: MiniMax's API reference and pricing page at platform.minimax.io, the MiniMaxAI/MiniMax-H3 model card on Hugging Face, and the Comfy-Org/ComfyUI release notes for the node-level behaviour.

Disclosure: I maintain minimax-h3ai.video. It is an independent third-party interface and is not affiliated with MiniMax. This repo is MIT-licensed and takes corrections.

Contributing

Found a number that is wrong, or a constraint the validator misses? Open an issue with the source and I will update h3_spec.json. Tests live in test_h3check.py and need no install:

python3 test_h3check.py

Last verified against the API reference: 2026-08-24.