README.md

---
license: other
license_name: minimax-h3-community-license
license_link: https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/LICENSE
base_model: MiniMaxAI/MiniMax-H3
tags:
- mlx
- apple-silicon
- text-to-video
- image-to-video
- audio-video-generation
- diffusion
pipeline_tag: image-text-to-video
library_name: mlx
---

# MiniMax-H3-MLX-bf16

MLX (Apple Silicon) build of the [**MiniMax-H3**](https://huggingface.co/MiniMaxAI/MiniMax-H3) diffusion
transformer. Unquantized, in the release's native **mixed bfloat16/float32** precision.

> Powered by MiniMax H3.

**These files are modified.** The transformer weights have been converted to MLX; they are not MiniMax's originals. Everything else about the model is unchanged.

## What this is

MiniMax-H3 generates **synchronized video and audio** together. It is not a language model: a 33B
diffusion transformer denoises video and audio latents jointly over one packed sequence, conditioned
by a frozen Qwen3-VL-32B encoder, with separate video and audio VAEs. Running it needs the pipeline
code, not just these weights:

```bash
git clone https://github.com/PipeNetwork/minimax-h3-mlx
cd minimax-h3-mlx && pip install -r requirements.txt
python scripts/generate.py "a red fox leaps over a mossy log" -o fox.mp4
```

This repository holds the **transformer only**. The VAEs and the text encoder come from the
[upstream release](https://huggingface.co/MiniMaxAI/MiniMax-H3); the pipeline loads them directly.

## Size

| | |
|---|---|
| on disk | 66.28 GB |
| resident during generation | **40.26 GB** |

The gap is deliberate. ~13B of H3's 33B parameters are the per-block AdaLN projections, whose only
input is the timestep embedding. For a fixed sampler schedule every modulation tensor a run needs is
precomputed once into a small table, and the projections are then dropped — so they are on disk but
never resident. The table scales with step count, not model size: measured at **145 MB for a 9-step
schedule** and 745 MB for 40 steps, against the 26 GB it replaces.

**Nothing here is quantized.** This is the faithful conversion, and it preserves the release's
*mixed* precision rather than flattening it: MiniMax ships the two patch projections, the timestep
MLP and both output heads in **float32** and everything else in bfloat16, and that split is kept
intact. Casting those twelve tensors down to bfloat16 would be a downgrade from the release — the
timestep MLP in particular feeds every block's modulation, so rounding it perturbs all 50 blocks at
every sampling step.

Use this as the quality reference, or as the base for further conversion. If you only want to
generate and have the memory, it is the best output available; if you do not, the
[8-bit build](https://huggingface.co/pipenetwork/MiniMax-H3-MLX-8bit) is 27.6 dB PSNR against it and
roughly half the size.

## How the widths compare

Measured with teacher forcing — one bfloat16 trajectory recorded, each variant re-predicting the
velocity at those same latents, so the difference is quantization error alone rather than trajectory
divergence. 20 paired observations per variant, aggregated with a paired bootstrap.

| bits | video rel-L2 [95% CI] | audio rel-L2 | video cosine |
|---:|---|---:|---:|
| 8 | 0.0329 [0.0277, 0.0381] | 0.0130 | 0.99941 |
| 6 | 0.0611 [0.0501, 0.0728] | 0.0274 | 0.99791 |
| 4 | 0.1649 [0.1324, 0.1971] | 0.1016 | 0.98456 |
| 3 | 0.2842 [0.2362, 0.3358] | 0.2341 | 0.95635 |

Every interval is disjoint from its neighbours, so the ranking is solid. Two things worth noting:
the steepest step is **6 to 4 bits** (2.7x), not at the low end; and audio degrades faster in
relative terms than video (its share of the error climbs from 0.40x at 8-bit to 0.82x at 3-bit),
plausibly because audio is a small fraction of the packed rows and has less redundancy to absorb it.

## Why 8, 6 and 4 bits only

Velocity error ranks the widths but does not say where output stops being usable — the scheduler
integrates velocity, so per-step error compounds along the trajectory. That has to be generated to
be seen. The same prompt, seed and settings were rendered through each checkpoint and compared to
bfloat16:

| build | PSNR vs bf16 | correlation | outcome |
|---|---:|---:|---|
| 8-bit | **27.6 dB** | 0.959 | near-identical |
| 4-bit | 22.0 dB | 0.854 | cooler colour, background artifacting, subject intact |
| 3-bit | 16.3 dB | 0.740 | **subject destroyed** |

At 3 bits the scene is gone — no animal, no log, just a textured field. It is built but **not
published**. Notably it does not degrade by blurring: its per-frame variance *rises* (54.7 against
bfloat16's 37.1) as structure is replaced by high-frequency noise, so a sharpness metric would have
scored it as healthy. 2-bit is not published either; extrapolation puts it near 50% velocity error.

6-bit was not rendered separately — it is bracketed by 8-bit and 4-bit, which both pass.

## Read this before choosing a quant

MiniMax has not released its sparse-attention implementation, so inference runs **dense** attention
over tens of thousands of rows. On an M3 Ultra a single denoising step costs about **8.8 minutes**
for a 5-second clip (37,966 packed rows) and **1.04 hours** for 15 seconds (109,318 rows).

Quantization does not change that. The bottleneck is attention FLOPs, which quantization does not
reduce; the linear layers are ~42% of the work at 5 s and ~20% at 15 s, so a 4-bit build is worth
roughly **1.2-1.4x end to end**. Choose a quant to *fit* H3 on your machine, not to make it quick.

## Licence

Governed by the [MiniMax H3 Community License](https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/LICENSE),
a copy of which is included in this repository. It is **not** an open-source licence. Notably:
redistribution must carry the agreement and mark modified files; commercial products above $20M
yearly revenue need separate authorization from MiniMax; and **the grant is territorially limited**
(worldwide, excluding the Excluded Territories defined in the agreement). By downloading these
weights you accept those terms.

The MLX port code is Apache-2.0 and lives at [https://github.com/PipeNetwork/minimax-h3-mlx](https://github.com/PipeNetwork/minimax-h3-mlx).