Card: pin runner doc links to the tested commit

7d7f785 verified 2 days ago

8.25 kB

---
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](https://huggingface.co/VisualInference/MiniMax-H3-Image-MLX-bf16)
(the MLX port of [MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image)). It runs with the same runner,
[felix-ab/minimax-h3-image-mlx](https://github.com/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](https://huggingface.co/cguldogan/MiniMax-H3-Image-MLX-8bit).

## Usage

Accept the licence on this page, then:

```bash
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):

```python
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](https://github.com/cguldogan/minimax-h3-image-mlx) (`pip install git+https://github.com/cguldogan/minimax-h3-image-mlx@31cc9a9173d8013f14f22024b056f64e27fd763c`) and archived by [Software Heritage](https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/felix-ab/minimax-h3-image-mlx).

The model expects long, detailed English prompts. See the runner's
[examples](https://github.com/felix-ab/minimax-h3-image-mlx/tree/31cc9a9173d8013f14f22024b056f64e27fd763c/examples/prompts).

## Quality checks

The method follows the port's own [validation](https://github.com/felix-ab/minimax-h3-image-mlx/blob/31cc9a9173d8013f14f22024b056f64e27fd763c/docs/VALIDATION.md).
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.

![bf16, 8-bit and 4-bit side by side](assets/comparison.jpg)

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`](https://huggingface.co/VisualInference/MiniMax-H3-Image-MLX-bf16/tree/c4c5623a8605ae23dcb711a8715603df9bf426cf),
  which comes from [`MiniMaxAI/MiniMax-H3-Image@492fd8c`](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/tree/492fd8c4eca666f1085f57e30738c1e0d86b3439).

See [NOTICE](NOTICE).

## Credits

- **MiniMax**: the model, [MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image).
- **Felix Brener** ([felix-ab](https://github.com/felix-ab), [VisualInference](https://huggingface.co/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](LICENSE), 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.

	---
	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](https://huggingface.co/VisualInference/MiniMax-H3-Image-MLX-bf16)
	(the MLX port of [MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image)). It runs with the same runner,
	[felix-ab/minimax-h3-image-mlx](https://github.com/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](https://huggingface.co/cguldogan/MiniMax-H3-Image-MLX-8bit).

	## Usage

	Accept the licence on this page, then:

	```bash
	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):

	```python
	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](https://github.com/cguldogan/minimax-h3-image-mlx) (`pip install git+https://github.com/cguldogan/minimax-h3-image-mlx@31cc9a9173d8013f14f22024b056f64e27fd763c`) and archived by [Software Heritage](https://archive.softwareheritage.org/browse/origin/?origin_url=https://github.com/felix-ab/minimax-h3-image-mlx).

	The model expects long, detailed English prompts. See the runner's
	[examples](https://github.com/felix-ab/minimax-h3-image-mlx/tree/31cc9a9173d8013f14f22024b056f64e27fd763c/examples/prompts).

	## Quality checks

	The method follows the port's own [validation](https://github.com/felix-ab/minimax-h3-image-mlx/blob/31cc9a9173d8013f14f22024b056f64e27fd763c/docs/VALIDATION.md).
	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.

	![bf16, 8-bit and 4-bit side by side](assets/comparison.jpg)

	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`](https://huggingface.co/VisualInference/MiniMax-H3-Image-MLX-bf16/tree/c4c5623a8605ae23dcb711a8715603df9bf426cf),
	which comes from [`MiniMaxAI/MiniMax-H3-Image@492fd8c`](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/tree/492fd8c4eca666f1085f57e30738c1e0d86b3439).

	See [NOTICE](NOTICE).

	## Credits

	- MiniMax: the model, [MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image).
	- Felix Brener ([felix-ab](https://github.com/felix-ab), [VisualInference](https://huggingface.co/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](LICENSE), 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.