Command reference

h3check {grid,cost,validate} ...

A subcommand is required. Running h3check with no arguments exits 2 with the argparse usage message.

grid

Print the frame grid the renderer snaps to.

h3check grid [--min MIN] [--max MAX] [--duration DURATION]
Flag Type Default Meaning
--min float 4.0 Lower bound of the printed range, in seconds
--max float 15.0 Upper bound of the printed range, in seconds
--duration float none Also report what this requested duration renders as

--min and --max change what is printed, not what the model supports. They accept floats, so --min 0 --max 30 will show you grid points outside the supported 4–15 second window — useful when you are checking the arithmetic, misleading if you read it as a capability table.

With --duration, one extra line is appended:

$ h3check grid --duration 5
...
asking for 5.0s renders 124 frames = 5.167s (n=7)

Exit code is always 0.

cost

Price one clip at the hosted rate.

h3check cost --duration DURATION [--resolution {768P,2K}]
Flag Type Default Meaning
--duration float required Requested duration in seconds
--resolution choice 768P One of the keys in hostedPricing.perOutputSecond 
$ h3check cost --duration 8 --resolution 2K
8.0s requested -> 192 frames = 8.000s rendered
2K at $0.13/output second
total: $1.0400

The rate is multiplied by the rendered seconds, not the requested ones. Eight seconds is the one duration in range where those two numbers are the same; for every other value the total is higher than the naive multiplication. The choices for --resolution are read from the spec file at parse time, so adding a tier to h3_spec.json adds it to the CLI without touching the code.

Exit code is always 0. cost does not validate — it will happily price a duration the API would reject. Use validate for that.

validate

Check a request document and set the exit code.

h3check validate PATH
Argument Meaning
PATH Path to a JSON file, or - to read from standard input

Output is a verdict line followed by an indented report:

$ 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

When there is nothing at all to say, the report body is the single line (nothing to report).

Exit codes

Code Condition
0 No errors. Warnings and notes do not change this.
1 At least one error.
2 argparse rejected the command line.

Anything that is not valid JSON raises json.JSONDecodeError and exits with a traceback, which is deliberate: a malformed request file is a bug in whatever produced it, not a finding about the render.

Request document shape

Every key is optional as far as the JSON parser is concerned; validate reports the ones it needs.

Key Type Notes
duration integer Required. Whole seconds.
resolution string Required. 768P or 2K.
aspect_ratio string Optional. Checked only when present.
prompt string Optional. Length-checked against the 7000-character ceiling.
mode string Optional. Only ref2va triggers a rule.
generate_audio boolean Optional. Only false triggers a rule.
references.images array Strings or objects.
references.videos array Objects with a numeric seconds participate in budget checks.
references.audio array Same as videos.

Reference entries may be bare strings. Only entries that are objects are inspected for a seconds key, and entries without one are skipped by the budget rules but still counted by the cap rules. In practice that means a list of URLs validates for count but not for duration — if you want the second-budget rules to fire, pass objects.