Install and first run

Install

pip install h3check

No dependencies. Python 3.9 or newer. That gives you an h3check command; python3 -m h3check does the same thing.

Or vendor it

The package is two files. Copy them side by side into your own project and run the module directly:

git clone https://github.com/dafa6/minimax-h3-spec.git
cp minimax-h3-spec/src/h3check/__init__.py  vendor/h3check.py
cp minimax-h3-spec/src/h3check/h3_spec.json vendor/h3_spec.json
python3 vendor/h3check.py grid

The spec is read from the module's own directory, not the current working directory:

SPEC = json.loads((Path(__file__).with_name("h3_spec.json")).read_text(encoding="utf-8"))

So the two files travel together. Copying one without the other raises FileNotFoundError at import time, not at first use.

Confirm it works

git clone https://github.com/dafa6/minimax-h3-spec.git
cd minimax-h3-spec
python3 test_h3check.py

Eleven assertions, standard library only, no install step — the test file puts src on sys.path itself.

First run: print the frame grid

$ h3check grid
frames = 17n + 5 at 24 fps

  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

whole-second values in 4.0-15.0s: 8.000s (192 frames)

That table is the reason this tool exists. The API accepts any whole number of seconds from 4 to 15, and fifteen of those sixteen values render as a fraction. If you are cutting to music, or stitching clips end to end, eight seconds is the only length that will not drift.

Second run: cost the clip you will actually get

$ h3check cost --duration 10 --resolution 2K
10.0s requested -> 243 frames = 10.125s rendered
2K at $0.13/output second
total: $1.3163

Note which number is priced. Billing is per output second, and the output is 10.125 seconds, so the bill is $1.3163 rather than the $1.30 you would get by multiplying the duration you asked for. The gap is small on one clip and stops being small on a batch.

Third run: validate a request

Write the request you are about to send as JSON:

{
  "mode": "i2va",
  "duration": 8,
  "resolution": "768P",
  "aspect_ratio": "16:9",
  "prompt": "A courier steps out of a lift into a wet loading bay. (S1) Sign here.",
  "references": { "images": ["first-frame.png"] }
}

$ h3check validate request.json
PASS
  note     hosted cost at 768P: $0.6400 for 8.000 rendered seconds
$ echo $?
0

validate also reads from standard input when the path is -, which is how you would wire it into a pipeline that builds requests programmatically:

python3 build_request.py | h3check validate -

Where to go next