README.md

---
pipeline_tag: image-text-to-video
library_name: diffusers
license: other
license_name: minimax-h3-community-license-agreement
license_link: LICENSE
base_model: MiniMaxAI/MiniMax-H3
tags:
  - orbitquant
  - comfyui
  - w4
  - w4a4
  - native-w4a4-transformer-runtime
  - text-to-video
  - image-text-to-video
  - audio-video-generation
---

# MiniMax H3 — OrbitQuant W4A4 with source FP32 VAEs

OrbitQuant conversion of
[MiniMaxAI/MiniMax-H3](https://huggingface.co/MiniMaxAI/MiniMax-H3), pinned to
source revision
[`73372e6cf53e414edd3ab03e357717fb0602e758`](https://huggingface.co/MiniMaxAI/MiniMax-H3/tree/73372e6cf53e414edd3ab03e357717fb0602e758).

Eligible linear weights in `transformer`, `transformer_ref`, and the Qwen3-VL
`text_encoder` are stored and executed through OrbitQuant's native packed W4A4
path. Non-quantized boundaries use BF16 compute. The visual `vae` and
`audio_vae` are byte-for-byte FP32 source copies and are never quantized.

## Final 608×480 example

<video controls playsinline preload="metadata" width="608" aria-label="MiniMax H3 OrbitQuant balanced ComfyUI proof">
  <source src="https://huggingface.co/WaveCut/MiniMax-H3-OrbitQuant-W4A4/resolve/main/comfyui/examples/hevc/comfyui-balanced-t2va-608x480-crf10.mp4" type="video/mp4; codecs=&quot;hvc1&quot;">
  <source src="https://huggingface.co/WaveCut/MiniMax-H3-OrbitQuant-W4A4/resolve/main/comfyui/examples/h264/comfyui-balanced-t2va-608x480.mp4" type="video/mp4">
  <a href="https://huggingface.co/WaveCut/MiniMax-H3-OrbitQuant-W4A4/resolve/main/comfyui/examples/h264/comfyui-balanced-t2va-608x480.mp4">MiniMax H3 OrbitQuant proof MP4</a>
</video>

[H.265 10-bit CRF 10](comfyui/examples/hevc/comfyui-balanced-t2va-608x480-crf10.mp4)
· [H.264 fallback](comfyui/examples/h264/comfyui-balanced-t2va-608x480.mp4)
· [CRF 1 yuv444p master](comfyui/examples/masters/comfyui-balanced-t2va-608x480-crf1.mp4)
· [16-frame overview](comfyui/examples/timelines/comfyui-balanced-t2va-608x480.jpg)
· [adjacent-frame review](comfyui/examples/review/comfyui-balanced-adjacent-triplets.jpg)
· [audio spectrum](comfyui/examples/review/comfyui-balanced-audio-spectrum.png)

This live ComfyUI run uses 608×480, 124 frames at 24 FPS, seed 42, and 24
sigma points / 23 denoiser forwards. All 300 eligible denoiser linears use the
native packed W4A4 path with no exact INT8 weight cache. Source FP32 tiled visual
decode produced the retained CRF 1 master; the HEVC card copy was derived from
that master at CRF 10. The output contains AAC stereo at 32 kHz.

Full-resolution frames and adjacent triplets were reviewed for face geometry,
eyes, lips, grid artifacts, ghosting, texture breakup, and abrupt section
redraw. The macro-to-face shot remains coherent. The audio spectrum is broadband
without a persistent narrow electronic whistle.

## ComfyUI workflow

Download the ready-to-import
[MiniMax H3 OrbitQuant T2VA workflow](comfyui/workflows/MiniMax-H3-OrbitQuant-T2VA.json).
It is based on Comfy-Org's bundled
[`video_minimax_h3_t2v.json`](https://github.com/Comfy-Org/workflow_templates/blob/7653f1cdef1d92394b6ef9946018c0a8aa4136b8/templates/video_minimax_h3_t2v.json)
and preserves the official preset's readable composition.

![MiniMax H3 OrbitQuant public ComfyUI workflow](comfyui/workflow-export.png)

The PNG above is a 3060×1310 ComfyUI Workflow Image Export, not a browser
screenshot. Its `tEXt` `workflow` chunk contains the same six-node graph with
`balanced`, 608×480, 124 frames, 24 steps, and the detailed example prompt.

Install [ComfyUI-OrbitQuant](https://github.com/iamwavecut/ComfyUI-OrbitQuant)
into `ComfyUI/custom_nodes`, restart ComfyUI, import the workflow, and set
`OrbitQuant Release Loader.model_path` to this downloaded model directory. The
graph uses only the generic public nodes `OrbitQuant Release Loader` and
`OrbitQuant Generate Video`; there are no MiniMax-specific public node classes.

On the RunPod ComfyUI image, launch ComfyUI with:

```bash
python main.py --listen 0.0.0.0 --port 8188 \
  --disable-cuda-malloc \
  --disable-dynamic-vram \
  --disable-async-offload
```

These supported flags let the OrbitQuant subprocess enforce its own allocator
cap instead of competing with ComfyUI's global DynamicVRAM and async-offload
layers.

## Inference profiles

All numbers use CUDA 13, 608×480, 124 frames, 24 sigma points / 23 forwards,
native-auto Torch Flash SDPA, no weight cache, sequential CUDA text conditioning,
and source FP32 VAEs.

| Profile | GPU | Task | Placement | Process peak | Denoise | Generation |
| --- | --- | --- | --- | ---: | ---: | ---: |
| `balanced` (default) | RTX PRO 6000 | T2VA | streamed leaf offload, 12 GiB cap | 6.36 GiB child; 6.90 GiB incl. idle ComfyUI | 46.68 s | — |
| `speed` | RTX PRO 6000 | T2VA | resident transformer | 21.14 GiB | 46.84 s | 51.10 s |
| `minimum_vram` | RTX 4090 | T2VA | low-CPU-memory streamed leaf offload, 8 GiB cap | 4.07 GiB | 154.25 s | 188.70 s |
| `speed` | RTX PRO 6000 | Ref2VA | resident `transformer_ref` | 24.06 GiB | 118.48 s | 155.42 s |

`balanced` is the recommended Pareto recipe. On the tested PRO 6000, streamed
weight movement overlaps denoising closely enough to match the resident path
while cutting the child process's physical CUDA peak by about 70%.
`minimum_vram` is the verified absolute-minimum endpoint. `speed` removes
transformer transfers when VRAM is available.

SageAttention2's available CUDA 13 binary did not include SM120 code for this
PRO 6000, and forced cuDNN attention was slower. Native-auto Torch Flash SDPA is
therefore the shipped supported attention path.

## Install

```bash
pip install "orbitquant[hf,kernels]>=0.9.2,<0.10"
pip install "diffusers @ git+https://github.com/huggingface/diffusers.git@abc5e9bf71fd38f53cd471bc3acaa84bc5ecbfdc"
pip install "transformers>=5.13,<6" accelerate av soundfile
```

Or install all pinned runtime requirements from this repository:

```bash
pip install -r runtime-requirements.txt
```

## Direct runner

The runner writes each scheduler checkpoint atomically and saves the latent
bundle before decode. The examples below keep the prompt in a file to avoid
shell quoting a multi-kilobyte description.

Balanced T2VA:

```bash
python scripts/run_quantized_example.py \
  --release . \
  --output balanced.mp4 \
  --save-latents balanced.latents.pt \
  --prompt "$(cat prompt.txt)" \
  --seed 42 --width 608 --height 480 --num-frames 124 --steps 24 \
  --manual-stage-offload \
  --text-encoder-sequential-offload \
  --transformer-group-offload-type leaf_level \
  --group-offload-use-stream \
  --cuda-memory-cap-gib 12 \
  --transformer-runtime-mode auto_fused \
  --checkpoint-dir checkpoints/balanced
```

Maximum-speed T2VA: remove the group-offload and allocator-cap options while
keeping `--manual-stage-offload --text-encoder-sequential-offload`.

Minimum-VRAM T2VA: use the balanced command with
`--group-offload-low-cpu-mem-usage --cuda-memory-cap-gib 8`.

Ref2VA speed:

```bash
python scripts/run_quantized_example.py \
  --release . \
  --output ref2va.mp4 \
  --save-latents ref2va.latents.pt \
  --prompt "$(cat prompt.txt)" \
  --task ref2va --reference reference.png \
  --seed 42 --width 608 --height 480 --num-frames 124 --steps 24 \
  --manual-stage-offload \
  --text-encoder-sequential-offload \
  --reference-vae-sequential-offload --reference-vae-tile-size 128 \
  --transformer-runtime-mode auto_fused \
  --checkpoint-dir checkpoints/ref2va
```

Decode only after the latent-producing process exits:

```bash
python scripts/decode_h3_latents.py \
  --latents balanced.latents.pt \
  --vae vae \
  --audio-vae audio_vae \
  --output balanced.master-crf1.mp4 \
  --preview-output balanced.mp4
```

The decoder always loads the release's untouched source FP32 visual and audio
VAEs. The visual VAE is tiled and sequentially offloaded; the audio VAE enters
GPU only for the audio stage.

## Component precision and size

| Component | Stored mode | Artifact GiB | Eligible linear coverage | OrbitQuant modules | AdaLN INT4 |
| --- | --- | ---: | ---: | ---: | ---: |
| `transformer` | W4A4 | 17.03 | 97.45% | 300 | 50 |
| `transformer_ref` | W4A4 | 17.03 | 97.45% | 300 | 50 |
| `text_encoder` | W4A4 | 18.55 | 95.80% | 448 | 0 |
| `vae` | source FP32 copy | 9.70 | exact source copy | 0 | 0 |
| `audio_vae` | source FP32 copy | 0.56 | exact source copy | 0 | 0 |

Input/output projections, time/context/refiner boundaries, embeddings, norms,
and language-head boundaries excluded by the pinned H3/Qwen policy remain in
source precision. “Four bit” describes eligible packed linear weights, not
every tensor in the architecture.

## Validation and provenance

- OrbitQuant 0.9.2 revision `cd58b4ecf77f22b8c4116b3d0b7d4af258e16ba3`.
- Diffusers revision `abc5e9bf71fd38f53cd471bc3acaa84bc5ecbfdc`.
- The live ComfyUI workflow reached terminal `pass` through `/prompt` and
  produced the standard `VIDEO` output.
- All 23 denoiser checkpoints and the final latent were persisted before
  source-FP32 decode.
- Visual/audio VAE weight SHA256 values match the pinned source revision; see
  [`validation/source_component_copy_audit.json`](validation/source_component_copy_audit.json).
- Exact artifact hashes are in [`SHA256SUMS`](SHA256SUMS).
- Full machine-readable profile and media evidence is in
  [`comfyui/report.json`](comfyui/report.json).

## License and modifications

The original
[MiniMax H3 Community License Agreement](https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/73372e6cf53e414edd3ab03e357717fb0602e758/LICENSE)
is copied as [`LICENSE`](LICENSE). See [`NOTICE`](NOTICE),
[`MODIFICATIONS.md`](MODIFICATIONS.md), and the upstream
[`QA-about-License`](docs/QA-about-License.md).