H3-metal Guide: Run MiniMax-H3 on Apple Silicon

Why H3-metal matters right now

If you’ve tried MiniMax-H3 on a Mac through ComfyUI or MLX ports, you already know the pain: short clips that take fifteen minutes to well over an hour. H3-metal – native MiniMax-H3 inference for Apple Silicon – just dropped from antirez (yes, the Redis author), climbed Hacker News within hours (~200 points on the launch thread, Aug 2026), and changes the wait. Plain C and Metal. No Python. No PyTorch.

ComfyUI/Mac threads still report multi-tens-of-minutes to hour-long gens for a few seconds of video. README timings for h3-metal short presets sit in seconds for denoise, sub-minute for fuller image+audio paths on M5 Max. Same model family. Wildly different overhead.

Get H3-metal running (hands-on)

Apple Silicon, unified memory with real headroom, FFmpeg/ffprobe on PATH, a C toolchain that can make, and disk for the Hugging Face tree. Official end-to-end memory notes (below) assume a 128 GB M5 Max class machine – more on footprint after you build.

1. Clone and build from github.com/antirez/h3.c.
2. Pull the FL2VA snapshot into ./MiniMax-H3 from the official MiniMax-H3 card (text-to-video/audio and first/last-frame path).
3. Sanity-check the Metal device before a full weight map.

git clone https://github.com/antirez/h3.c.git
cd h3.c
make -j8
mkdir -p outputs

# Scoped download example (needs huggingface_hub / hf CLI)
hf download MiniMaxAI/MiniMax-H3 
 --include "model_index.json" "FL2VA/*" 
 --local-dir ./MiniMax-H3

./h3 --info -d ./MiniMax-H3

--info prints the selected Metal device without mapping every weight. Clean device line? Run a short balanced lab clip (22 frames ≈ 0.92 s at 24 fps):

./h3 --profile 
 -d ./MiniMax-H3 
 -p "Night market alley, rain on neon. A courier on an e-bike cuts through steam from a food stall. Handheld 35 mm, eye level, shallow depth. Audio: tire hiss, distant chatter, no score." 
 --width 512 --height 512 
 --frames 22 --steps 20 
 --layers 45 --reuse 2 
 -o outputs/alley-fast.mp4

Denoise for that 45 layers + reuse 2 shape: about 16.69 s on an IT M5 Max per the h3.c README (as of Aug 2026). Same shape with --token-reduction: roughly 12.60 s. First run still pays load + filesystem cache – compare the second. Laptops throttle; desk fans lie.

Interactive session: iterate without reloading

Drop -p. You get a REPL that keeps BF16 prompt conditioning, prepared DiT, and the video decoder resident. That’s the Mac workflow that matters for prompt hunting.

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

h3> !status
h3> !seed random
h3> !seconds 2
h3> Scene: one cyclist on a wet city street at dusk.
Action: slow push-in as the rider turns toward camera.
Camera: 35 mm, handheld micro-shake, eye level.
Look: neon reflections, rain mist, photoreal.
Audio: tire hiss on wet asphalt, distant traffic, no music.
h3> !save outputs/cyclist.mp4

First/last anchors stick: !first opening.png, !last ending.png, then a prompt. Ordered Ref2VA images use !ref-image path and show up as <Picture 1>, <Picture 2> – filenames mean nothing. !refs, !ref-remove N, !refs clear manage the stack.

Pro tip: Write briefs the released path likes – subject, action, setting, camera, look, audio on separate lines. Slogans work; structured lines usually match training better.

CLI twins: --first-frame / --last-frame for FL2VA; --ref-image, --ref-video, --ref-silent-video, --ref-audio for ordered refs (order preserved; standalone audio rides with image or video; 2-15 s each, ≤3 clips, total ≤15 s).

Common pitfalls to avoid with H3-metal

Footguns the happy-path paste jobs skip.

• Illegal canvas math. Width and height multiples of 32 (min 32). Product ≤ 768 × 1344. 512×512 is the safest lab size while you lock motion.
• Frame rounding. Duration snaps to 5 + 17n frames. --frames 23 becomes 39. --seconds 10 becomes 243 frames (~10.125 s), not a clean wall-clock 10.0. --seconds and --frames are mutually exclusive.
• Combo that breaks limbs. Do not stack --token-reduction with both --layers 40 and --reuse 3. Validation showed chromatic ringing and ghosted limbs even when latent norms looked fine. --reuse and --core-reuse are also mutually exclusive.
• Preview RAM tax.--show (Kitty/Ghostty/iTerm2-style protocols) loads a resident preview VAE and adds roughly 10 GiB temporary residency. Drop it when memory is tight – runs without --show stay on the lighter path.
• Checkpoint mix-up. First/last anchors select FL2VA. Ordered refs select Ref2VA. They cannot share a session. Point -d at a tree that actually contains the partition you need.

Think of the speed knobs like a three-axis mixer, not one “turbo” switch – twist two aggressively and the third can trash subject fidelity while the profiler still looks cheerful.

Performance knobs (README numbers, Aug 2026)

Four-step denoise on M5 Max: near 3.5 s. Longer reference path in the same notes: ~26.4 s. Full-video SSIM vs a 29-pass oracle sat around 0.55 on the fox/surfer checks in the README – fast is real; it is not pixel-identical to the slow path.

End-to-end image+audio and embedded-video+audio on a 128 GB M5 Max: about 74.6 s and 77.0 s, ~40.1 GB peak physical, zero swaps (h3.c README measurements, Aug 2026). M5 can map the ~37 GiB transformer file-backed/reclaimable and prefers specialized int8 TensorOps paths; older Metal falls back. Phases load and release, so the 33B transformer, Qwen text encoder, and VAEs never fully stack – that’s why peak sits near 40 GB instead of “entire BF16 stack at once.” 64 GB machines are far less documented for the full native BF16 path; community Comfy quant routes are a different trade.

When not to use this

32-48 GB unified memory and a goal of full native BF16 quality at large canvas for 10-15 s clips? Headroom gets ugly fast – skip or expect pain. Need the hosted H3-Context-IR preprocessor or closed H3-Regenerate-2K path? Not in the open weights.

Commercial shipping into excluded territories is the sharp edge: the MiniMax H3 Community License (as published on the model repo) lists the US, EU, UK, and Republic of Korea among excluded territories without separate authorization, and commercial use above roughly $20M yearly revenue needs prior written auth. Read the live LICENSE before you depend on it – terms can move. Batching thousands of clips overnight on CUDA? Multi-GPU NVIDIA or AMD Instinct still wins on raw throughput.

Is a solo MIT Metal engine the long-term default for every Mac video lab – or a bridge until sparse-attention weights and broader quants land? Still open.

FAQ

How much RAM do I really need for H3-metal?

Documented clean end-to-end peaks: ~40.1 GB physical on 128 GB M5 Max, no swap (README, Aug 2026). Leave OS + browser headroom above that.

How is this different from MiniMax-H3 in ComfyUI on Mac?

Comfy graphs (FP8/INT8 nodes, GGUF, etc.) can boot on 64 GB boxes. Timings people post are often 15+ minutes to an hour for short clips. H3-metal is a purpose-built Metal binary aimed at M3/M5 Max with sub-minute short presets in the README. You give up node-graph toys. You get the wait back.

Can I generate a full 15-second 768p clip on day one?

Mechanically the caps allow it: canvas product up to 768×1344, and 362 frames ≈ 15.08 s at 24 fps. Cost scales hard. Don’t start there.

Lock prompt and seed at 512×512 / 22 frames with --layers 45 --reuse 2. Then raise layers, ease reuse toward 1, stretch duration last. Native 256 is a composition preview (auto RoPE adapt). 128 square stays unsupported.

Next action: clone the repo, run ./h3 --info -d ./MiniMax-H3, then one 22-frame 512 clip with --layers 45 --reuse 2 before any aggressive flags.