Metadata-Version: 2.4
Name: h3check
Version: 0.1.0
Summary: Validate a MiniMax H3 (Hailuo 3) render request before you pay for it, against a spec sheet where every constraint carries its source.
Author: Ray Lin
License-Expression: MIT
Project-URL: Homepage, https://github.com/dafa6/minimax-h3-spec
Project-URL: Documentation, https://minimax-h3-spec.readthedocs.io/en/latest/
Project-URL: Source, https://github.com/dafa6/minimax-h3-spec
Project-URL: Issues, https://github.com/dafa6/minimax-h3-spec/issues
Keywords: minimax,h3,hailuo,video,generative-video,validation,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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`](https://github.com/dafa6/minimax-h3-spec/blob/main/src/h3check/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.

```bash
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](https://minimax-h3-spec.readthedocs.io/en/latest/)**.

---

## 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

```console
$ 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:

| Stage | Published | What it does |
| --- | --- | --- |
| `H3-Context-IR` | no | reads and rewrites your multimodal instruction |
| `H3-Base` | **yes** | renders 768P picture and 32 kHz stereo in one forward pass |
| `H3-Regenerate-2K` | no | feeds the 768P result back through with the original context |

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](https://minimax-h3ai.video)** — that site is also [a browser-based MiniMax H3 video generator](https://minimax-h3ai.video) 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](https://minimax-h3ai.video/reference-to-video), including per-file size and aspect-ratio bounds
- [A clause-by-clause reading of the H3 licence](https://minimax-h3ai.video/blog/minimax-h3-open-weights), 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`](https://github.com/dafa6/minimax-h3-spec/blob/main/test_h3check.py) and need no install:

```bash
python3 test_h3check.py
```

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