h3

Native MiniMax-H3 video and audio inference CLI for Apple Silicon

TLDR

Inspect a local MiniMax-H3 checkpoint and the selected Metal device

$ h3 --info -d [./MiniMax-H3]

Generate a short video from a prompt (balanced quality defaults)

$ h3 -d [./MiniMax-H3] -p "[A red fox walks through snow]" --width 512 --height 512 --frames 22 --steps 20 --layers 45 --reuse 2 -o [outputs/fox.mp4]

Start an interactive session that keeps the model resident between prompts

$ h3 -d [./MiniMax-H3] --width 512 --height 512 --steps 6

Condition on first and last frames

$ h3 -d [./MiniMax-H3] -p "[Continue the scene]" --first-frame [start.png] --last-frame [end.png] -o [out.mp4]

Use an ordered image reference (Ref2VA path)

$ h3 -d [./MiniMax-H3] -p "[Use the subject in Picture 1]" --ref-image [person.png] -o [out.mp4]

Profile Metal timing and peak memory

$ h3 --profile -d [./MiniMax-H3] -p "[prompt]" --width 512 --height 512 -o [out.mp4]

SYNOPSIS

h3 -d MODELDIR [**-p** PROMPT] [**-o** OUTPUT] [options_]h3 -d MODELDIR_ --info

h3 (project name h3-metal / repository h3.c) is Salvatore Sanfilippo's native MiniMax-H3 inference engine for Apple Silicon. It loads a local Hugging Face-style MiniMax-H3 checkpoint, runs the DiT and VAEs on Metal, and writes synchronized H.264 video plus AAC audio (via ffmpeg / ffprobe on PATH).Without -p, the binary starts an interactive session: type prompts to generate numbered videos while BF16 prompt conditioning and decoders stay resident. Session bang-commands such as !seed, !first, !last, !ref-image, and !help control generation without restarting.With -p, generation is one-shot. Quality and speed are controlled by independent knobs: --steps (denoising passes), --layers (active DiT blocks), --reuse or --core-reuse (how often the full denoiser runs), optional --token-reduction, and optional lower --render-width / --render-height with upscale to the final canvas. First/last-frame flags select the FL2VA path; --ref-image, --ref-video, and related flags select the ordered Ref2VA path.The tool targets Mac GPUs with large unified memory (M3/M5 class). It is not a portable Linux GPU runtime; build with make on macOS against the local model tree.

PARAMETERS

-d, --model-dir PATH

Local MiniMax-H3 checkpoint directory (required).

-p, --prompt TEXT

Generation prompt. Omit to enter the interactive session.

-o, --output PATH

Output MP4 path (default outputs/h3.mp4). Empty string disables encoding.

--width N, --height N

Output canvas size (multiples of 32; product limited). Defaults depend on release (commonly 864×480).

--render-width N, --render-height N

Smaller internal DiT/VAE canvas (same aspect), then upscale to output size.

--frames N | --seconds N

Requested length. H3 aligns frames to its temporal grid at 24 fps. Mutually exclusive.

--steps N

Number of denoising passes (default 20). Low budgets (for example 4–7) are for previews.

--reuse N

Whole-denoiser reuse interval: 1 close, 2 fast, 3 aggressive. Mutually exclusive with --core-reuse.

--layers N

Active DiT blocks: 50 exact, 45 fast, 40 aggressive.

--core-reuse N

Refresh expensive core less often while keeping patch/head work fresh.

--token-reduction

Pair horizontal video tokens in middle DiT blocks (faster; may change composition).

--seed N

RNG seed (default 42).

--first-frame PATH, --last-frame PATH

FL2VA conditioning images.

--ref-image PATH, --ref-video PATH, --ref-silent-video PATH, --ref-audio PATH, --ref-video-audio VIDEO AUDIO

Ordered Ref2VA references (repeatable; order preserved).

--show

Display progressive previews in Kitty/iTerm2-class graphical terminals.

--profile

Print per-phase Metal timing and allocation stats.

--info

Inspect model layout and Metal device without mapping all weights.

-h, --help

Show the full option list for this build.

INSTALLATION

Build from source on macOS (Apple Silicon). Requires make, a C/ObjC toolchain, and FFmpeg on PATH:

$ git clone https://github.com/antirez/h3.c.git
cd h3.c
make -j8
./h3 --help

Download a MiniMax-H3 weight tree (for example into ./MiniMax-H3) before generating media. There is no distro package for this project; packages named h3 or libh3-bin are Uber's geospatial library, not this tool.

CAVEATS

Requires Apple Silicon with Metal, a full MiniMax-H3 weight tree (tens of GiB), and ffmpeg/ffprobe. Peak unified-memory use is large; aggressive presets trade fidelity for speed and can alter composition.--reuse and --core-reuse cannot be combined. Do not stack the most aggressive layer, reuse, and token-reduction settings without validating quality. Name collision: other ecosystems ship unrelated h3 binaries (for example geospatial H3 tooling).

HISTORY

h3-metal is a 2026 C/Metal project by Salvatore Sanfilippo (antirez), built as successive vertical slices (host metadata, Metal block parity, prompt-to-video/audio, FL2VA and Ref2VA). It targets native MiniMax-H3 inference on Mac without a Python ML stack.

RESOURCES

Source code

h3