Instructions to use nativ-community/MiniMax-H3-Image-4bit with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- MLX
How to use nativ-community/MiniMax-H3-Image-4bit with MLX:
# Download the model from the Hub pip install huggingface_hub[hf_xet] hf download nativ-community/MiniMax-H3-Image-4bit --local-dir MiniMax-H3-Image-4bit
- Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- LM Studio
- Atomic Chat
|
Download README.md from nativ-community/MiniMax-H3-Image-4bit: direct link, hf CLI and curl.
- Browser
- Download file 4.91 kB
-
https://huggingface.co/nativ-community/MiniMax-H3-Image-4bit/resolve/main/README.md
- Command line
-
hf download hf://nativ-community/MiniMax-H3-Image-4bit/README.md
-
curl -L -o README.md https://huggingface.co/nativ-community/MiniMax-H3-Image-4bit/resolve/main/README.md
4.91 kB
| library_name: mlx-vlm | |
| pipeline_tag: text-to-image | |
| license: other | |
| license_name: minimax-h3-image-community-license-agreement | |
| license_link: https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/blob/main/LICENSE | |
| base_model: MiniMaxAI/MiniMax-H3-Image | |
| tags: | |
| - mlx | |
| - minimax-h3-image | |
| - image-editing | |
| - 4-bit | |
| - quantized | |
| # MiniMax-H3-Image-4bit | |
| An MLX checkpoint converted directly from the original floating-point | |
| [MiniMaxAI/MiniMax-H3-Image](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image) | |
| weights. It supports text-to-image generation and native image editing with up to | |
| sixteen ordered reference images. Inference uses MLX on Apple silicon, without | |
| PyTorch or Diffusers. | |
| ## Quantization | |
| Eligible linear and embedding layers use **4-bit affine quantization with group | |
| size 64**. Both the diffusion transformer and the Qwen3-VL conditioner are | |
| quantized. The conditioner retains its vision tower for editing. | |
| The VAE, transformer modulation layers, and transformer input/time/output | |
| projections retain their released precision. Normalizations and convolutional | |
| layers also retain their released precision. | |
| | Component | Weight files | Size (GB, decimal) | | |
| | --- | ---: | ---: | | |
| | Qwen3-VL conditioner | 3 | 14.683 | | |
| | Diffusion transformer | 8 | 37.445 | | |
| | Image VAE | 1 | 2.337 | | |
| The full checkpoint occupies approximately **54.5 GB (50.7 GiB)**, including its | |
| tokenizer, configuration files, and weight indexes. No external image-model | |
| components are required. | |
| ## Usage | |
| Requires an `mlx-vlm` version with MiniMax-H3-Image support | |
| ([implementation PR](https://github.com/Neywa-Labs/mlx-vlm/pull/2702)). Until that | |
| support is included in your installed release, install the implementation branch: | |
| ```sh | |
| python -m pip install -U "git+https://github.com/lucasnewman/mlx-vlm.git@minimax-h3-image" | |
| ``` | |
| Replace `/path/to/MiniMax-H3-Image-4bit` with the local checkpoint directory or | |
| this repository's Hugging Face ID after upload. | |
| ```sh | |
| mlx_vlm.generate --output-modality image \ | |
| --model /path/to/MiniMax-H3-Image-4bit \ | |
| --prompt "A red ceramic teapot beside a white cup on a wooden table by a sunny window" \ | |
| --size 4096x4096 --seed 42 --output teapot.png | |
| ``` | |
| ```python | |
| from mlx_vlm.generate import generate_image, load_image_generation_model | |
| model = load_image_generation_model("/path/to/MiniMax-H3-Image-4bit") | |
| result = generate_image( | |
| model, | |
| "A red ceramic teapot beside a white cup by a sunny window", | |
| width=4096, | |
| height=4096, | |
| seed=42, | |
| output_path="teapot.png", | |
| ) | |
| ``` | |
| For editing: | |
| ```sh | |
| mlx_vlm.generate --output-modality image --task edit \ | |
| --model /path/to/MiniMax-H3-Image-4bit \ | |
| --image teapot.png \ | |
| --prompt "Make the teapot in <Picture 1> blue, preserving its shape, the cup, and the lighting" \ | |
| --size 4096x4096 --seed 42 --output blue-teapot.png | |
| ``` | |
| Reference images are ordered as `<Picture 1>`, `<Picture 2>`, and so on. Sampling | |
| is fixed at **six steps and guidance 1**. Small output requests are generated on | |
| at least a 2048x2048-equivalent canvas before resizing. The conditioner is | |
| released before diffusion, and the transformer caches fixed-schedule AdaLN | |
| projections so their large weights can be released. | |
| ## Prompt expansion | |
| Short prompts are expanded by default with the separately downloaded | |
| [MiniMaxAI/MiniMax-H3-Image-PE](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image-PE) | |
| model. Its released NVFP4 weights are separate from this 4-bit image checkpoint. | |
| Prompt templates and request defaults are embedded in the MLX implementation. | |
| For a detailed caption that is ready for the image model, disable expansion: | |
| ```sh | |
| mlx_vlm.generate --output-modality image \ | |
| --model /path/to/MiniMax-H3-Image-4bit \ | |
| --prompt "A realistic still-life photograph of a glossy red ceramic teapot with a curved spout and lid, beside a plain white cup on a warm wooden table next to a sunny window. Soft morning light from the left, detailed glaze and wood grain, a beige wall in the background." \ | |
| --gen-kwargs '{"upsample_prompt":false}' \ | |
| --size 4096x4096 --seed 42 --output teapot.png | |
| ``` | |
| In Python, pass `upsample_prompt=False` when loading or generating. With | |
| expansion disabled, this checkpoint can run fully offline after downloading. | |
| ## Validation | |
| Validated with strict component loading and offline inference on an Apple M5 Max | |
| with 128 GiB unified memory, using MLX 0.32.4. Both checks used seed 42, six steps, | |
| guidance 1, and prompt expansion disabled. The edit used the generated 4K image | |
| as its reference. | |
| | Task | Output resolution | Total elapsed time | | |
| | --- | --- | ---: | | |
| | Generate | 4096×4096 | 180.1 s | | |
| | Edit | 2048×2048 | 88.4 s | | |
| ## License | |
| Weights and prompt templates use the | |
| [MiniMax H3 Image Community License](https://huggingface.co/MiniMaxAI/MiniMax-H3-Image/blob/main/LICENSE). | |
| The reference Diffusers implementation is | |
| [Apache-2.0](https://github.com/huggingface/diffusers/blob/main/LICENSE). | |