README.md

---
license: other
license_name: minimax-h3-community-license-agreement
license_link: LICENSE
base_model:
  - MiniMaxAI/MiniMax-H3
base_model_relation: quantized
library_name: diffusion-single-file
pipeline_tag: image-text-to-video
tags:
  - text-to-video
  - image-to-video
  - text-to-audio-video
  - minimax
  - minimax-h3
  - nvfp4
  - fp4
  - quantized
  - comfyui
  - blackwell
extra_gated_prompt: >-
  MiniMax H3 is released under the MiniMax H3 Community License Agreement. Its open-weight
  license does NOT cover the European Union, the United Kingdom, the Republic of Korea, or
  the United States of America. By requesting access you confirm that you will not use,
  reproduce, modify, distribute, or display these weights or their outputs in those
  territories, and that you accept the Acceptable Use Policy in Exhibit A of the license.
extra_gated_fields:
  I have read the MiniMax H3 Community License Agreement: checkbox
  I am not located in, and will not distribute into, the Excluded Territories: checkbox
---

# MiniMax-H3 (pruned) — NVFP4

NVFP4 (TensorCore block-scaled FP4) **weight-only** quantization of both **pruned MiniMax-H3**
transformers — FL2VA and Ref2VA. MiniMax-H3 is a 33 B omni-modal video model that generates
video **and native stereo audio in a single forward pass**: dialogue, sound effects and score
come out with the picture, not from a separate stage.

**11.67 GiB per transformer instead of 19.53 GiB, and slightly faster** on Blackwell.

⚠️ **This repo holds the two transformers only.** Grab the text encoder and both VAEs from
[`Comfy-Org/MiniMax-H3`](https://huggingface.co/Comfy-Org/MiniMax-H3) — you need
`text_encoders/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors` (14.61 GiB),
`vae/minimax_h3_video_vae_fp16.safetensors` (4.85 GiB) and
`vae/minimax_h3_audio_vae_fp32.safetensors` (0.56 GiB). Four files, 31.7 GiB on disk.

📝 **Full write-up, benchmarks & the gotchas in detail:**
[Running MiniMax-H3 on one RTX 5090](https://ai-muninn.com/en/blog/minimax-h3-nvfp4-rtx5090)
· [繁體中文版](https://ai-muninn.com/zh-TW/blog/minimax-h3-nvfp4-rtx5090)

## What this is

- **Format:** NVFP4 weight-only. 200 linear layers are packed FP4 (4-bit) with per-block FP8
  (E4M3) scales and per-tensor FP32 global scales — the standard NVFP4 layout. Norms,
  embeddings, biases and the pruned model's `adaln_t_table` stay at their original precision.
  (Header dtype profile: 1,132 tensors — 200 U8 packed-FP4 + 200 F8_E4M3 block scales +
  200 F32 global scales, alongside 219 BF16 / 51 F16 / 4 F32 left untouched.)
- **Base:** the **pruned** Comfy-Org repack of
  [`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3). The pruned checkpoint
  matters here: most of its ~13 B-parameter AdaLN projection has been replaced by an
  equivalent timestep lookup table (13,039,369,728 → 43,642,368 parameters, ~299×; reduced
  `adaln_proj` tensors remain rather than being removed outright), so quantization never
  touches it. MiniMax document this themselves — the model card notes the AdaLN modulation
  outputs can be precomputed and cached and "do not need to be loaded for inference-only
  deployment". AdaLN emits the
  scale/shift applied to every residual stream and its error compounds across every block and
  every sampling step — the pruned base removes that risk instead of trying to survive it.
- **Size:** 11.67 GiB per transformer, down from 19.53 GiB. The two transformers are
  alternative task checkpoints and are never loaded together, so what has to fit is one
  transformer plus the text encoder: measured peak is 26,914 MiB on a 32 GB card.

## Honest caveats (read these)

**1. Blackwell only. On anything older this is a size play with no speed.**
NVFP4 has tensor-core support only on sm_120+. On Turing/Ampere/Ada, ComfyUI lists `nvfp4`
under `emulated ops`: the file loads and runs, but weights are expanded before the matmul, so
you get the smaller download and none of the benefit. For those cards, use INT8-ConvRot or a
W4A4-ConvRot build instead.

**2. A different quantization does not give you the same clip faster — it gives you a
different clip.**
Quantization changes the numerics, the denoising trajectory diverges, and a fixed seed lands
somewhere else. `samples/nvfp4_vs_int8_sidebyside.mp4` shows NVFP4 next to INT8-ConvRot from
the same seed and prompt: both are coherent — materials, lighting and the carved Chinese
characters hold up in each — but the framing, the bird's position and how much of the
inscription is legible are simply not the same shot. Neither is broken; they are two valid
solutions to the same prompt. If you have a seed you like on INT8, expect to re-roll after
switching.

**3. The timings below are thermally limited, so read them with the ambient in mind.**
Those runs were made at about 35 °C room temperature with a 500 W power limit. The card sat
roughly 2 °C under its throttle point and held only 84–87% of its maximum SM clock. On a cooler
machine both formats will be faster and the gap between them may shift. Treat the absolute
seconds as this machine on that day; the ratio is the part that transfers.

**4. Prompting is not optional here.**
H3 accepts a keyword list and quietly gives you something worse. It expects a structured
context — see the prompting section below.

## Files

| File | Size | Purpose |
|---|---|---|
| `diffusion_models/minimax_h3_fl2va_pruned_nvfp4.safetensors` | 11.67 GiB | `t2va` (text→video) and `fl2va` (first and/or last frame→video) |
| `diffusion_models/minimax_h3_ref2va_pruned_nvfp4.safetensors` | 11.67 GiB | `ref2va` — up to 9 reference images, 3 videos, 3 audio clips; keeps a character, style or voice consistent |
| `text_encoders/qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors` | 14.61 GiB | Qwen3-VL-32B text encoder (NVFP4-AWQ, from Comfy-Org) |
| `vae/minimax_h3_video_vae_fp16.safetensors` | 4.85 GiB | Video VAE |
| `vae/minimax_h3_audio_vae_fp32.safetensors` | 0.56 GiB | Audio VAE |

The repo mirrors ComfyUI's `models/` tree, so one command puts everything where it belongs:

```bash
# everything, ~43 GiB
hf download coolthor/MiniMax-H3-pruned-NVFP4 --local-dir ComfyUI/models

# text-to-video and keyframe work only, ~32 GiB
hf download coolthor/MiniMax-H3-pruned-NVFP4 --local-dir ComfyUI/models \
  --include "diffusion_models/minimax_h3_fl2va*" "text_encoders/*" "vae/*"
```

## Usage (ComfyUI)

Requires **ComfyUI ≥ 0.30.0**. No special launch flags are needed.

| | |
|---|---|
| Loader | `UNETLoader` → the `.safetensors` above, `weight_dtype: default` |
| Text encoder | `CLIPLoader` → `qwen3vl_32b_minimax_h3_nvfp4_awq.safetensors`, **type `minimax`** |
| Sampler | `KSamplerSelect` → `res_multistep` |
| Scheduler | `BasicScheduler` → `simple`, **steps 10**, denoise 1.0 |
| Guider | `BasicGuider` — the weights are CFG-distilled, so there is no negative prompt and no CFG value |
| Video | `CreateVideo` → 24 fps, audio connected from `VAEDecodeAudio` |

**Steps: start at 10, not 20.** The ComfyUI template ships 20, but MiniMax publishes no
recommended step count — their reproducible request scripts contain no step parameter at all,
and the released weights are CFG-distilled. 10 steps showed no visible quality loss on a
10-second clip while cutting time roughly in half (324 s → 172 s, same resolution and seed).

Frame math:

- Frame counts sit on a **17k+5** grid at 24 fps (5, 22, … 124, … 243 …); the stock template
  computes this for you.
- Trained range is **124–362 frames** (5.17–15.08 s).
- Native canvas is a 768 px short edge, capped at 768×1344, rounded to a multiple of 32.

With `--use-sage-attention`, this file ran **7% faster** on the 5090 (172 s vs 185 s), and the
output was effectively unchanged — only 4 bytes differed in a 1.97 MB file. That is far from the
"roughly double" figure quoted elsewhere; the installed package was SageAttention 1.0.6, and
that claim refers to 2.x.

## Measured performance

RTX 5090 · ComfyUI 0.30.1 · torch 2.11.0+cu128 · 500 W power limit · SageAttention off

Both runs used the same job; only the quantization differed: **fl2va**, 864×480, 243 frames
(10.125 s), 10 steps, seed 16, `res_multistep` + `simple`, with the same text encoder and VAEs.

| | **NVFP4 (this repo)** | INT8-ConvRot |
|---|---|---|
| File size | **11.67 GiB** | 19.53 GiB |
| Generation time | **175 s** | 185 s |
| Peak VRAM | **26,914 MiB** | 28,581 MiB |
| Mean SM clock | **2,696 MHz** | 2,585 MHz |
| Peak GPU temp | 82 °C | 80 °C |

**≈5% faster, 40% smaller, 1.6 GB less VRAM.** Ref2va was not benchmarked separately; it is the
same architecture at the same size, so expect the same order of magnitude plus whatever your
reference images cost to encode.

## Prompting

H3 expects a structured context, not a keyword list. Text-only generation (the T2VA task)
uses three fields, in this order. Image-conditioned tasks (I2VA / FL2VA / L2VA) additionally
need an alignment instruction as the very first line, followed by a blank line.

```text
integrated_multimodal_description: [Shot 1] <style>, <framing>, <what happens> …
[Shot 2] At 00:06.000, the camera cuts to …

overall_soundscape: <ambience, action sounds, non-verbal human sounds>

non_diegetic_music: <instruments, tempo, rhythm, dynamics — no mood words>
```

Easy things to get wrong:

- Shot 1 carries **no** timestamp; later shots need strictly increasing cut times within the
  clip's duration.
- Camera motion is motion type + amplitude + speed, written as a natural sentence
  (medium amplitude and normal speed are usually omitted):
  `The camera pushes in with small amplitude at slow speed toward …`
- Dialogue: everything except the language tag and the verbatim line goes **outside** the tag —
  `The man, with a low, restrained voice (S1), says: <d>[Chinese] …</d>`
- All three fields are always present; what is mutually exclusive is which sound goes where.
  Dialogue and diegetic music belong in the description, ambience in `overall_soundscape`, and
  only audience-side score in `non_diegetic_music`. Write `N/A` when a field has nothing —
  though `overall_soundscape` takes `N/A` only when total silence was explicitly requested.
- On-screen text goes in English double quotes, verbatim, untranslated.
- **Describe what is visible, not what is absent.** Diffusion models cannot render absence, and
  they follow geometry far better than words like "left": `enters from the left edge of the
  frame` works where `his left hand` does not.

MiniMax ships the full specification as two prompt-writing guides with the base model.

## Samples

Generated with the files in this repo at the settings above, each with the complete prompt that
produced it. Audio is native — dialogue, ambience and score come out of the same forward pass as
the picture.

| File | What it is |
|---|---|
| [`samples/yangguo_nvfp4.mp4`](samples/yangguo_nvfp4.mp4) | NVFP4 (this repo) — 175 s |
| [`samples/yangguo_int8_convrot.mp4`](samples/yangguo_int8_convrot.mp4) | INT8-ConvRot, for comparison — 185 s |
| [`samples/nvfp4_vs_int8_sidebyside.mp4`](samples/nvfp4_vs_int8_sidebyside.mp4) | The two above side by side, NVFP4 left, INT8 right |
| [`samples/yangguo_prompt.txt`](samples/yangguo_prompt.txt) | The exact prompt, verbatim |

[`samples/README.md`](samples/README.md) covers what the clip exercises — two shots in one
generation, dialogue across the cut, carved characters, a one-armed character — and why each of
those is hard.

## Credits

- **Base model:** [`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3) — 33 B
  omni-modal video + native audio.
- **ComfyUI repack (pruned base, text encoder, VAEs):**
  [`Comfy-Org/MiniMax-H3`](https://huggingface.co/Comfy-Org/MiniMax-H3).
- **NVFP4 approach:** [`lilcheaty/MiniMax-H3-NVFP4`](https://huggingface.co/lilcheaty/MiniMax-H3-NVFP4).
- Quantization, packaging and benchmarks by **coolthor**.

This is a **modified** redistribution: the transformer weights have been quantized to NVFP4 and
are not the originals published by MiniMax.

## License

Distributed under the **MiniMax H3 Community License Agreement**, Copyright © 2026 MiniMax.
All Rights Reserved. A complete copy is in `LICENSE` and the required notice is in `NOTICE`.

Key points carried over:

- **The open-weight license excludes the European Union, the United Kingdom, the Republic of
  Korea, and the United States of America.** Section V.4 prohibits use, reproduction,
  modification, distribution and display of the works *or their outputs* outside the Applicable
  Territory — which is why this repo is gated. If you are in an excluded territory, MiniMax
  accepts license applications; see their
  [Q&A](https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/docs/QA-about-License.md).
- Any derivative must ship with a complete copy of the Agreement, and modified files must carry
  a notice that they were changed (done above).
- Section V.2: before giving anyone access you must bind them to enforceable terms **at least
  as protective as the use restrictions in Section V and Exhibit A**, and tell them those
  restrictions apply. Section V.5 additionally requires safeguards if you expose generation to
  third parties.
- Section IV.2: a commercial product or service built on this must display "MiniMax H3"
  prominently in its user interface.
- Commercial products or services above **USD $20,000,000** in yearly revenue need separate
  written authorization from MiniMax.

---

☕ If this saved you GPU hours, you can [buy me a coffee](https://buymeacoffee.com/thorlin).