What You'll Build
A local HTTP server on your Mac that turns a text prompt (optionally plus a first and/or last frame) into a 24 fps clip with its own synchronised 32 kHz stereo soundtrack, denoised jointly with the picture in a single packed sequence. No CUDA, no ComfyUI, no PyTorch — the whole pipeline is MLX on Metal.
⚠️ Read the licence before you download 70 GB. MiniMax H3 is not released under an open-source licence. The MiniMax H3 Community License Agreement defines the Applicable Territory as "means worldwide, excluding the Excluded Territories", and defines those as "means the European Union, the United Kingdom, the Republic of Korea and the United States of America." Section V.4 extends the restriction past the weights to what you generate: "You may not use, reproduce, modify, distribute, or display the MiniMax H3 Works or any of their Outputs or results outside the Applicable Territory."
Every MLX pack on this page carries the same agreement forward.
ddalcu's pack ships the LICENSE and aMODIFICATIONS.mdin the model directory, and mlx-serve's converter treats a missing LICENSE as a fatal error rather than a warning — but a redistributor's diligence is not a grant, and the machine-readablelicense:facet on all of these repos is the uninformativeother, so any filter keyed on that field sails straight past the territorial clause. If you are in an excluded territory, MiniMax publishes a licence Q&A and an application route for per-deployment licensing. This is a summary written by a reader of the text, not legal advice — the linked agreement is the thing that binds you.
Hardware data: Apple M2 Max (64GB unified memory) · 38.242 GiB billed at the load preflight · See benchmark data
ℹ️ The 2K in the marketing is not in the download. H3's 2K output comes from a separate
H3-Regenerate-2Kmodule, and MiniMax's own README says of it: "Due to the complexity of the system, this module is not yet open-sourced. We will release it once it is ready." What you get locally isH3-Base, which the vendor validates with the shorter side at 768 pixels. mlx-serve's own recommended canvas is 1344×768. Everything on this page is about that 768p-class model.
ℹ️ This is not the ComfyUI recipe with the paths changed. The sibling pages for this model install Comfy-Org's
pruned_int8_convrotandnvfp4files. Those are unreadable here:convrotis a CUDA tensor-core layout, and mlx-serve's own reference notes say the conversion must start from the bf16 files instead. Going the ComfyUI route on a Mac means a third-party MPS extension and a large speed penalty — see Troubleshooting.
Requirements
| Component | Minimum | This recipe |
|---|---|---|
| GPU | 64GB unified memory for the 8-bit pack this recipe installs | Apple M2 Max (64GB unified memory) — not measured by us; the budget below is derived from file bytes and mlx-serve's own preflight formula (/contribute) |
| RAM | unified with the GPU — same 64GB | — |
| Storage | 70.08 GB for the 8-bit pack | 70.08 GB across 15 files (byte counts from the HuggingFace tree API) |
| Software | macOS 26.2+, mlx-serve 26.8.2+ | — |
Unified memory is not VRAM. Our catalogue stores the M2 Max's full 64GB in the vram_gb field, but Metal only offers the GPU its recommendedMaxWorkingSetSize — about 75% on a 64GB machine, so roughly 48 GiB addressable, not 64. That share is what every figure below is measured against. One nearby data point: the 48GB machine in mlx-serve issue #126 — an Apple M5 Pro on macOS 26.x, at the stock iogpu.wired_limit_mb = 0 — logged a wired limit of 38338 MB, which is 37.439 GiB, or 78.0% of its 48 GiB. Note the chip and OS before you generalise that: it is two silicon generations newer than the M2 Max, so 78% may be an OS-policy change rather than a capacity rule. This page does not widen any margin on the strength of it; 75% is the figure every number below uses.
MiniMax's own README gives no hardware guidance at all, and its only deployment example is an SGLang serve across four GPUs. The Apple numbers on this page come from the runtime that actually implements the model on Metal.
Installation
1. Install mlx-serve
MiniMax-H3 landed in mlx-serve v26.8.2, released 4 August 2026. Nothing older has the backend.
brew tap ddalcu/mlx-serve https://github.com/ddalcu/mlx-serve
brew install mlx-serve
mlx-serve --help | head -1
The GUI (brew install --cask mlx-core) bundles the same server, but do not use it for this model on a 64GB Mac — it cannot pass the one flag you need. See Troubleshooting.
2. Pull the 8-bit pack
mlx-serve pull ddalcu/MiniMax-H3-FL2VA-MLX-Serve-8bit
org/repo HuggingFace ids work directly, and the download is resumable. If you would rather fetch it yourself:
pip install -U "huggingface_hub[cli]"
hf download ddalcu/MiniMax-H3-FL2VA-MLX-Serve-8bit \
--local-dir ~/.mlx-serve/models/ddalcu/MiniMax-H3-FL2VA-MLX-Serve-8bit
This pack is self-contained — DiT, text encoder, both VAEs and the tokenizer in one directory, which upstream splits across two repos. The four weight files, byte counts from the HuggingFace tree API:
transformer.safetensors 35,248,980,296 B 32.828 GiB the DiT, MLX affine 8-bit, group size 64
text_encoder.safetensors 28,222,741,760 B 26.284 GiB Qwen3-VL-32B, same quantisation
video_vae.safetensors 5,207,808,496 B 4.85 GiB byte-for-byte copy of the original
audio_vae.safetensors 605,254,808 B 0.564 GiB byte-for-byte copy of the original
Those last two files are worth pausing on: they are byte-identical to the ones Comfy-Org ships as minimax_h3_video_vae_fp16.safetensors and minimax_h3_audio_vae_fp32.safetensors — not merely the same size. HuggingFace stores an LFS SHA-256 per file, and both match across the two repos: the audio VAE is 8e505d95dd1561d4… in each, the video VAE 7c1f131492e7edda…. The pack's MODIFICATIONS.md says only the DiT and text encoder were touched, and the hashes prove it. The audio decoder is not a stub, and it is not dropped in conversion.
3. Start the server
mlx-serve --serve --host 127.0.0.1 --port 11234 \
--model-dir ~/.mlx-serve/models \
--max-resident-mem 0
Two flags are not optional here.
--host 127.0.0.1 because mlx-serve defaults to 0.0.0.0 — its README states the defaults are --host 0.0.0.0 --port 11234. On a laptop that is an unauthenticated endpoint on every network you join.
--max-resident-mem 0 because on release 26.8.2 the registry's eviction gate refuses this model outright on a 64GB Mac. That is the single thing most likely to stop you, and it is explained in full under Troubleshooting.
Running
The backend is POST /v1/video/generations. Steer the soundtrack by appending an overall_soundscape: clause (non_diegetic_music: also works) to the prompt.
curl -sS http://127.0.0.1:11234/v1/video/generations \
-H 'Content-Type: application/json' \
-d '{
"model": "ddalcu/MiniMax-H3-FL2VA-MLX-Serve-8bit",
"prompt": "a paper bird lifts off a workbench in a sunlit workshop. overall_soundscape: crisp paper wingbeats, distant street noise through an open window",
"width": 864,
"height": 480,
"num_frames": 56,
"steps": 30,
"seed": 314159
}' > out.json
Start small. 864×480 at 56 frames is a 2.33-second clip and the cheapest useful size to prove the install; the recommended 1344×768 at 124 frames is an hour-scale job on this class of machine (see Results).
Three behaviours of this endpoint are worth knowing before your first request:
widthandheightmust be multiples of 32. Anything else is a 400, not a silent round.num_framesis snapped up to the model's own17k+5ladder — 5, 22, 39, 56, 73, 90, 107, 124 … 209 — and the server logs the substitution rather than quietly generating a different length. Asking for 40 gets you 56.fastdefaults to true. It is a velocity cache plus attention broadcast, measured by the author at 2.83× on the reference config (engineering brief). Pass"fast": falsefor a final render.
The response is not an MP4. It is JSON carrying base64 rgb8 frames plus, separately, base64 pcm_s16le audio at audio_sample_rate 32000, audio_channels 2, at a fixed 24 fps. Mux it yourself:
python3 - <<'PY'
import base64, json
d = json.load(open("out.json"))
open("frames.rgb", "wb").write(base64.b64decode(d["data"]))
open("audio.pcm", "wb").write(base64.b64decode(d["audio_data"]))
print(d["frames"], "frames", d["width"], "x", d["height"])
PY
ffmpeg -f rawvideo -pix_fmt rgb24 -s 864x480 -r 24 -i frames.rgb \
-f s16le -ar 32000 -ac 2 -i audio.pcm \
-c:v libx264 -pix_fmt yuv420p -c:a aac -shortest out.mp4
While it runs the server narrates its staged residency — text encode, encoder released, AdaLN precomputed and the 13B modulation weights released, then the DiT's own resident figure, then sampling, then decode. Those lines are the fastest way to confirm the memory plan below is actually happening on your machine.
Results
- Speed: not measured by us on this chip, and /check/minimax-h3/m2-max returns
verdict: unknownwith no benchmark rows for the pair. The nearest real measurements are the runtime author's own, on an M4 Max with 128GB — a different and faster part. The v26.8.2 release notes state: "It is genuinely slow. The recommended 1344x768 at 124 frames takes about 50 minutes on an M4 Max, and 209 frames closer to two hours." The repo's engineering brief carries the same ladder in more detail — 256×256/56f/30 steps at about 1.5 minutes of sampling, 864×480/73f at about 9 minutes, and for the acceptance run at the full canvas: "Sampling 2.31 h at a flat 275.7 s/step (zero drift step 1→30), tiled VAE decode 2.4 min, audio 0.7 s, in-sync stereo (5.175 s audio vs 5.167 s video)." (that one with the fast recipe off). Read all of those as a floor, not an estimate. The M2 Max is a 38-core GPU on TSMC's N5P process, shipped January 2023; the M4 Max is 40 cores on N3E, two years newer. The usual Apple shortcut of ranking chips by memory bandwidth does not apply here — the same brief measures the DiT step at the compute roofline, with SDPA at 13.3 and the linear GEMMs at about 13.6 effective TFLOPS, so this is a FLOPs problem, not a bytes problem. If you run this pair, please post numbers through /contribute so /check/minimax-h3/m2-max can carry a real measurement. - Unified-memory usage: 38.242 GiB billed at load, leaving 9.758 GiB of the ~48 GiB a 64GB M2 Max makes addressable. That figure is mlx-serve's own preflight formula applied to the bytes above —
h3PeakBytes = max(text_encoder, transformer) + video_vae + audio_vae, i.e.32.828 + 4.85 + 0.564, becauseminimax_h3.generateloads the text encoder, runs it and frees it before the DiT loads, so the two never coexist. The VAEs are billed additively on purpose:gen.zigdocuments that as the direction-safe margin, since an under-bill is an uncatchable Metal OOM. mlx-serve's own whole-run figure — the runtime author's, not MiniMax's — is close to it and comes at it differently: "Two builds on Hugging Face: 8-bit at a 69 GB download (44 GB while running) and 4-bit at 40 GB (26 GB), which fits a 32 GB Mac." 44 GB is 40.978 GiB — the DiT's measured 20.46 GB residency after the AdaLN precompute drops 13B parameters, plus roughly 20 GB of attention-broadcast cache at the reference canvas. The backend currently reportsverdict: unknownwith no benchmark rows for this pair. - Quality notes: the 8-bit pack is the right serving configuration on this machine and the author's own A/B says so — at 864×480 the bf16 arms measured 41–48 s/step against the 8-bit path's 36.6, and were jittery at 62 GB resident, which a 64GB Mac cannot address at all. The 4-bit pack is the low-memory option, and the same release notes are blunt about the trade: "Same generation speed either way, the 4-bit is a little softer." Do not reach for 4-bit hoping for speed. Two independent MLX ports of this model say the same thing in different words —
ddalcu's card notes "Note that quantization here buys FOOTPRINT, not speed", and PipeNetwork's card explains why: "The bottleneck is attention FLOPs, which quantization does not reduce", because MiniMax withheld its sparse-attention implementation from the release.
For the full benchmark data, see /check/minimax-h3/m2-max.
If 64GB is tight: the 4-bit pack
ddalcu/MiniMax-H3-FL2VA-MLX-Serve-4bit is the same pack at 4 bits: 41.11 GB across 15 files (HF file listing, 2026-08-07), and the same preflight formula gives 22.828 GiB. That is the figure the reporter in issue #126 watched his own server print ([preflight] media peak ~22.83 GB (staged residency)) on the machine where he then generated video successfully. On a 64GB M2 Max it buys 15.414 GiB of headroom you can spend on longer clips.
mlx-serve's release notes describe this build as the one "which fits a 32 GB Mac." That is the runtime author's claim and this page cannot reproduce it under its own method. Run it through the same addressability arithmetic used above and it does not clear. Machines below 64GB sit in a lower band — nearer two-thirds of capacity than three-quarters — which puts a 32 GB Mac somewhere around 21–24 GiB addressable, while this pack bills 22.828 GiB at load and the same release notes give 26 GB (24.2 GiB) as its running footprint. Both land at or above the top of that band. Whatever makes it work on 32 GB is not visible in the numbers this page derives, so treat the 32 GB figure as the author's, and untested here. On 64GB, which is what this page is about, both figures clear comfortably.
It is the right choice if you intend to render at 209 frames. At the 1344×768 canvas the attention-broadcast cache the default fast recipe uses costs about 20 GB at 124 frames and about 34 GB at 209 — the brief's own warning is "measured fine on 128 GB; budget it before raising k or frames on smaller Macs". Add that 34 GB to the 8-bit DiT's 20.46 GB residency and you are past what a 64GB Mac can address; add it to the 4-bit DiT's 10.64 GB — the same reporter logs 10.7 GB entering sampling at the full 1344×768 / 124-frame canvas — and you are not.
The Turbo LoRA is in the pack but not in the release
turbo_lora.safetensors (0.726 GiB) ships inside both ddalcu packs. Its MODIFICATIONS.md identifies it as an unmodified, renamed copy of larryvrh's minimax_h3_turbo_4step_ema_ckpt850.safetensors, Apache-2.0 as an adapter but still a derivative of the base weights and so still under the territorial agreement. So the answer to "is the ComfyUI Turbo adapter usable from MLX at all" is yes — the pack author measured it on an M4 Max at 960×544 / 39 frames, one prompt: 188 s of sampling at 16 steps without it against 95 s at 4 steps with it, roughly 2× on sampling.
The shipped release cannot use it. turbo appears nowhere in the MiniMax-H3 request handler on main, which is the v26.8.2 release commit; the feature is in PR #130, which is open and unmerged, and there is no v26.8.3 tag. You will download 0.726 GiB of adapter the current server ignores. Treat Turbo as a preview: its own author describes the round's known failure modes as over-sharp grain and plastic skin.
The same PR is where reference-conditioned generation lives. If you found gabrielrocco/MiniMax-H3-Ref2VA-MLX-Serve-8bit and wondered why it will not load — its own card says it is consumed by a fork branch, not by mainline mlx-serve. Ref2VA is listed as unbuilt work in the runtime's brief.
Troubleshooting
HTTP 503 out_of_memory on a completely idle server
This is the one that will hit you, and it is not a real memory problem. The registry's eviction gate runs before the media preflight and bills the sum of every safetensors in the directory plus 10%, ignoring the staged residency plan. Verified in scheduler.zig, where estimated is base + base / 10 over entry.bytes_on_disk. For the 8-bit pack that is 65.253 GiB × 1.1 = 71.778 GiB, more than a 64GB Mac physically has, so the gate refuses it no matter what else is going on. The default cap is 80% of Metal's recommendedMaxWorkingSetSize (main.zig computes exactly that), which on this machine derives to roughly 38.4 GiB.
Issue #126 diagnosed this on a 48GB machine with the 4-bit pack, down to the line numbers, and concluded that the model is permanently unloadable wherever the billed sum exceeds the cap — "that is every 48 GB Mac at stock settings", the same sentence going on to say a 64 GB Mac would need its wired limit raised too. That is a community report rather than a maintainer statement, but the maintainer has since accepted the diagnosis — the PR #130 notes read: "Video models no longer refuse to load on a 48 GB Mac (#126). The memory gate billed the sum of every file in the folder, 37.55 GB, where the real peak is 22.83 GB." That PR is not merged and not released, so the fix is not in the binary you installed.
The workaround is the reporter's, and it is in the run command above: "Raising --max-resident-mem makes the model load and generate video normally." Pass --max-resident-mem 0 to disable the cap entirely. The media preflight still runs, so you are not removing the guard that matters — you are removing the one that cannot see the model's residency plan.
The report's own suggestion for a 64GB machine is the canonical Apple move, sudo sysctl iogpu.wired_limit_mb=57344 for 56 GiB. Do not lean on it here. The cap this gate reads is 80% of what Metal reports as the recommended working-set size, and even if the sysctl moved that number all the way, the 8-bit pack would need a working set above 89.7 GiB to clear a 71.778 GiB bill — more than a 64GB machine has. The flag is the unambiguous lever, and if you would rather keep a cap than remove it, note that mlx-serve parses these suffixes as powers of 1024: --max-resident-mem 72GB clears the 8-bit pack's bill and --max-resident-mem 43GB clears the 4-bit pack's 42.102 GiB, without touching the OS at all.
MLX Core.app refuses the model and offers no way to fix it
The app builds its server argument list from a fixed flag set that does not include --max-resident-mem, and it offers no extra-args passthrough. The Skip memory pre-flight check toggle does not help either — it bypasses the free-RAM preflights, not the registry cap. On release 26.8.2, drive this model from the CLI.
You went looking for an mlx-community build and found none
There isn't one. Every MLX conversion of H3 is a single-author build, so the usual "prefer the org build" shortcut has nothing to prefer. Judge them by what is in the directory. Two concrete distinctions:
pipenetwork/MiniMax-H3-MLX-{4,6,8bit,bf16,f32}is a transformer-only pack for its own PipeNetwork/minimax-h3-mlx pipeline — no VAEs, no tokenizer, and its card says the text encoder comes from the upstream release. That means the unquantised Qwen3-VL-32B, which is the arm this recipe's pack shrinks to 26.284 GiB, and it is the reason that pack is a harder fit on 64GB despite a smaller download. Its published quality ladder is genuinely useful reading, though: 8-bit at 27.6 dB PSNR against bf16, 4-bit at 22.0, 3-bit built but not published because the subject is destroyed.- mlx-serve identifies an H3 directory by a
transformer.safetensorsmarker; a pack laid out asmodel-0000N-of-0000M.safetensorsshards will not be picked up as this backend at all.
The output has no sound
Check audio_vae.safetensors is present in the model directory. mlx-serve treats the audio VAE as optional — absent, it produces a silent clip rather than an error, which is a failure mode that looks like a model problem. The file is 605,254,808 bytes.
You are tempted to run the ComfyUI workflow on the Mac instead
It can be made to work and it is not a good trade. Comfy-Org discussion #24 is titled "Not supported for Apple silicon", and opens with the int8 and fp8 files failing for lack of MPS operators. Everyone quoted below is a community commenter, not Comfy-Org staff, and the thread has five of them — so it is worth keeping track of who says what.
Phodira is blunt about the alternative: "BF16 works. You need 96gb unified memory." jefflin reports getting the int8 file running through a third-party ComfyUI-AppleSilicon-FP8 extension — "my case successfully with M4MAX 64GB using pruned_int8_convrot.safetensors". A different commenter, BubbaHo, then reports that the stock template "gave me 200s/it to 500s/it for a 7 second duration at 0.2 megapixels (608x352). PAINFUL, but more testing improved things..."
Those timings have no machine attached to them. BubbaHo never states any hardware anywhere in the thread; that message opens by block-quoting jefflin, which is the only reason an M4 Max appears in it at all — the chip belongs to the other commenter's report, not to this measurement. Read 200–500 s/it as an unattributed community datapoint about the ComfyUI-on-MPS path at 608×352, which is about a fifth of the recommended 1344×768 canvas. It is here to show the shape of that path, not to be compared against a chip.
A second Apple-native runtime, if mlx-serve does not suit you
mere.run is an independent Swift/MLX implementation with its own H3 packs, driven by mere.run video generate rather than an HTTP call. Its 4-bit pack's card publishes a full validation run — on an M4 Max with 128GB, and therefore not this chip — reporting a peak process footprint of 27,771,572,360 bytes (25.864 GiB) and 1,134.15 seconds end to end for a 512×512, 56-frame, 31-step clip. It also ships the resulting MP4. Downloading that file and reading its container: SHA-256 matches the one printed on the card, and it carries two streams — 512×512 H.264, 56 frames at 24 fps, alongside 32 kHz stereo AAC, the two durations agreeing to under a millisecond. That matches the card's own line, "media: 512×512 H.264, 56 frames at 24 fps, plus 32 kHz stereo AAC, 2.334 seconds total". It settles that the Apple-native path emits a real soundtrack rather than a silent clip; whether the soundtrack matches the picture is a judgement about content, and this page does not make it.
Nothing here describes your problem
Runtime errors belong on mlx-serve/issues. If you get a clean run on this chip, a timing posted through /contribute is worth more to the next reader than any derived number above.