license: other
license_name: minimax-h3-image-community-license-agreement
license_link: LICENSE
library_name: mlx
pipeline_tag: text-to-image
base_model: MiniMaxAI/MiniMax-H3-Image
base_model_relation: quantized
tags:
- mlx
- apple-silicon
- text-to-image
- image-editing
- minimax-h3
- 4bit
extra_gated_heading: MiniMax-H3-Image Community License
extra_gated_description: >-
These weights are a modified distribution of MiniMax-H3-Image, licensed under
the MiniMax-H3-Image Community License Agreement and its Acceptable Use
Policy. The licence excludes the European Union, the United Kingdom, the
Republic of Korea and the United States of America from its territory; use
there requires separate authorization from MiniMax
(https://platform.minimax.io/license). Access is approved automatically.
extra_gated_prompt: >-
By requesting access you agree to the MiniMax-H3-Image Community License
Agreement (LICENSE in this repository) and its Acceptable Use Policy, and you
confirm that you will not use the weights or their outputs outside the
licence's Applicable Territory unless MiniMax has authorized you to.
extra_gated_fields:
I agree to the MiniMax-H3-Image Community License and Acceptable Use Policy: checkbox
extra_gated_button_content: Agree and access
MiniMax-H3-Image for MLX (4-bit)
A 4-bit quantization of VisualInference/MiniMax-H3-Image-MLX-bf16 (the MLX port of MiniMax-H3-Image). It runs with the same runner, felix-ab/minimax-h3-image-mlx, and was made with its own exporter. Text-to-image and image editing, 33B DiT, 6 steps. Unofficial; not affiliated with MiniMax or with the port's author. Powered by MiniMax-H3-Image.
Compact, not faithful. 4-bit drifts from the float32 result 1.1–6.4× further than bf16 does at 2048×2048, and 5–8× at 512×384. In practice the composition can change (pose, framing, small objects), much like a different seed. Every image in the tests below stayed clean, with correct text, and showed no grain or banding. Use it if disk space matters most. Use 8-bit if you want bf16-level fidelity.
| bf16 (source) | 4-bit (this repo) | |
|---|---|---|
| Download | 94 GB | 31.4 GB |
| Memory and time, weights streamed from disk | 3.4 GB, 185 s | 2.8 GB, 235 s |
| Memory and time, weights kept in memory | 40.4 GB, 197 s | 13.5 GB, 204 s |
All timings are for one 2048×2048 image on an M4 Pro (64 GB), with the weights on an external PCIe SSD. Quantized matmuls are a little slower than bf16 on Apple Silicon, so the gain here is the download size, not speed. The other tier is 8bit.
Usage
Accept the licence on this page, then:
pip install git+https://github.com/felix-ab/minimax-h3-image-mlx@31cc9a9173d8013f14f22024b056f64e27fd763c
hf auth login
minimax-h3-mlx @prompt.txt --size 2048x2048 --seed 42 --weights cguldogan/MiniMax-H3-Image-MLX-4bit -o out.png
minimax-h3-mlx @edit.txt --image ref.png --size 2048x2048 --seed 1234 --weights cguldogan/MiniMax-H3-Image-MLX-4bit -o edit.png
The CLI keeps a quantized tier fully in memory (13.5 GB peak). On a Mac with less memory, stream it from disk instead (same pixels, about 2.8 GB peak):
from minimax_h3_mlx.pipeline import Pipeline
from minimax_h3_mlx.weights import resolve
pipe = Pipeline(resolve("cguldogan/MiniMax-H3-Image-MLX-4bit"), stream=True)
pipe(open("prompt.txt").read(), height=2048, width=2048, seed=42).image.save("out.png")
This commit is the runner version these tiers were tested with. If the original repository is ever unavailable, the same commit is mirrored at cguldogan/minimax-h3-image-mlx (pip install git+https://github.com/cguldogan/minimax-h3-image-mlx@31cc9a9173d8013f14f22024b056f64e27fd763c) and archived by Software Heritage.
The model expects long, detailed English prompts. See the runner's examples.
Quality checks
The method follows the port's own validation. bf16 inference of this model is chaotic: tiny rounding differences grow over the 6 steps, so bf16 itself does not reproduce the float32 image. A quantized tier passes if it stays as close to the float32 result as bf16 does. That float32 result is the MLX port run in float32, which matches PyTorch float32 to 3e-5. "Drift" is ‖latent − float32 latent‖ / ‖float32 latent‖ after the last step (lower is better).
2048×2048, seed 42, drift from float32:
| prompt | bf16 | 8-bit | 4-bit |
|---|---|---|---|
| portrait | 0.123 | 0.076 | 0.247 |
| poster (text) | 0.344 | 0.114 | 0.388 |
| landscape | 0.046 | 0.051 | 0.294 |
512×384, the port's four end-to-end cases, image PSNR against float32 (higher is closer):
| case | bf16 | 8-bit | 4-bit |
|---|---|---|---|
| t2i seed 42 | 25.6 dB | 25.7 dB | 15.1 dB |
| t2i seed 1 | 27.5 dB | 25.8 dB | 14.3 dB |
| t2i seed 2 | 29.6 dB | 29.4 dB | 17.4 dB |
| portrait seed 7 | 30.9 dB | 29.8 dB | 18.0 dB |
The bf16 column reproduces the port's published MLX numbers exactly, which checks the harness.
2048×2048 against bf16, six example prompts and one edit (PSNR, SSIM):
| case | 8-bit | 4-bit |
|---|---|---|
| portrait | 25.7 dB, 0.962 | 18.7 dB, 0.851 |
| poster | 16.0 dB, 0.763 | 13.9 dB, 0.640 |
| landscape | 30.9 dB, 0.979 | 18.8 dB, 0.803 |
| painting | 24.9 dB, 0.894 | 17.8 dB, 0.712 |
| macro | 23.6 dB, 0.914 | 17.6 dB, 0.772 |
| street | 23.1 dB, 0.880 | 16.4 dB, 0.616 |
| edit (reference1.png, seed 1234) | 42.1 dB, 0.994 | 29.4 dB, 0.905 |
For scale, the port measured PyTorch-MPS bf16 against MLX bf16 at 25.2 dB (portrait), 17.1 dB (poster) and 21.5 dB (street) on the same prompts.
Left to right: bf16, 8-bit, 4-bit. Every image is 2048×2048, shown downscaled. The rows are portrait, poster, painting, street and edit. All images are AI-generated.
The uploaded files were checked by running them through the stock CLI. The portrait image came out byte-identical to the image the tables above measured.
Changes from the source
- DiT blocks: the attention (q, k, v, out) and feed-forward weights are 4-bit MLX affine, with group size 64.
- Text encoder layers: the attention and MLP weights are 4-bit, with the same scheme.
- Everything else stays at the source precision: the float32 input, timestep and output layers, the AdaLN tables, norms, token refiner, embedding, vision tower, VAE and tokenizer.
- Source:
VisualInference/MiniMax-H3-Image-MLX-bf16@c4c5623, which comes fromMiniMaxAI/MiniMax-H3-Image@492fd8c.
See NOTICE.
Credits
- MiniMax: the model, MiniMax-H3-Image.
- Felix Brener (felix-ab, VisualInference): the MLX port, the bf16 conversion, the runner and exporter, and the validation method that every quality test here follows. This repository would not exist without his work.
- cguldogan: the 8-bit and 4-bit quantization, the quality tests and the independent verification.
Licence
MiniMax-H3-Image Community License Agreement, including its Acceptable Use Policy and territorial restrictions. Its Applicable Territory excludes the European Union, the United Kingdom, the Republic of Korea and the United States of America. Commercial products or services that use the model must prominently show "MiniMax-H3-Image" in their user interface.