Instructions to use zimageapp/MiniMax-H3-Image-MLX-Q4 with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- MLX
How to use zimageapp/MiniMax-H3-Image-MLX-Q4 with MLX:
# Download the model from the Hub pip install huggingface_hub[hf_xet] hf download zimageapp/MiniMax-H3-Image-MLX-Q4 --local-dir MiniMax-H3-Image-MLX-Q4
- Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- LM Studio
- Atomic Chat
MiniMax-H3-Image-MLX-Q4
Affine 4-bit / group 64 conversion of MiniMax-H3-Image, published by zimageapp. Includes the Q4 diffusion model, the H3-specific Qwen3-VL32B Q4 text/vision encoder with embedded tokenizer, and the original FP16 Image VAE. Supports the original six-step model, text-to-image and ordered-reference image editing.
Runtime compatibility: packed affine matrices follow the MLX quantization convention, but the checkpoint uses native H3/Locraft tensor names and embedded configuration. The tested end-to-end runtime is Locraft C++/Metal with BF16 compute. A complete Swift/MLX H3 Image implementation is not included or validated. This repository is not a drop-in mlx-lm, MFlux or Diffusers pipeline; the name describes the Q4 weight packaging, not a ready-made loader.
Components
| File | Storage | Size |
|---|---|---|
diffusion_models/minimax_h3_image_int4.safetensors |
Q4/g64, selected original BF16/FP32 tensors retained | 11.39 GB |
text_encoders/qwen3vl_32b_minimax_h3_int4.safetensors |
Q4/g64 text/vision encoder; embedded tokenizer/config | 16.47 GB |
vae/minimax_h3_image_vae_fp16.safetensors |
Original dedicated Image VAE, unchanged | 1.17 GB |
Total weights: 29.02 GB / 27.03 GiB. Exact byte counts, SHA-256 hashes and source URLs are in q4_components.json. The Image VAE has a 24-layer 2D decoder; do not replace it with the H3 video VAE.
The diffusion conversion quantizes 209 matrices. Packed weights are uint32, eight 4-bit values per word, lowest nibble first, with BF16 scales/biases; w = q * scale + bias. The FP32 time basis, patch projection and final PDD-head tensors are preserved. Native tensor names and six original PDD heads are retained. Configuration, tokenizer and reproducible diffusion conversion tools are included. The encoder publication copy removes 864 bytes of inter-tensor padding from the local native file; all 1,602 tensor payloads and metadata are byte-identical and the published file passes standard safetensors validation. Local source weights are not overwritten.
Download
from huggingface_hub import snapshot_download
snapshot_download("zimageapp/MiniMax-H3-Image-MLX-Q4", local_dir="models/MiniMax-H3-Image")
With a Locraft build supporting H3 Image, pass the component paths explicitly (this also supports older catalog entries for the padded encoder):
locraft image generate --model h3-image \
--models-root /absolute/path/models \
--dit /absolute/path/models/MiniMax-H3-Image/diffusion_models/minimax_h3_image_int4.safetensors \
--text-encoder /absolute/path/models/MiniMax-H3-Image/text_encoders/qwen3vl_32b_minimax_h3_int4.safetensors \
--vae /absolute/path/models/MiniMax-H3-Image/vae/minimax_h3_image_vae_fp16.safetensors \
--prompt "A cat reading beside a sunlit window, detailed watercolor illustration." \
--size 2048x1536 --seed 42 --out /absolute/path/new-output --json
For edits, add --ref /absolute/path/input.png (repeat in Picture order, up to nine). References supply image conditioning rather than pinned output frames. Native prompts use Edit <Picture 1>. for edits; Locraft supplies this prefix when absent. The six evaluations use the published seven-point grid in pdd_config.json, guidance 1, no negative prompt, no extra LoRA. The removed experimental two-step adapter is not included. Reducing the step count arbitrarily is unsupported.
The publication encoder also passed a fresh 1024 × 768 six-step smoke in 22.3 s; its output pixels exactly match the historical aligned-encoder result for that prompt/seed. See publication-validation.json.
Local evidence
Apple M5 Pro / 24 GB; native C++/Metal, six evaluations, one food prompt and seed 42:
| Canvas | Total generation time |
|---|---|
| 1024 × 768 | 24.2 s |
| 2048 × 1536 | 60.5 s |
| 3072 × 2304 | 124.0 s |
| 4096 × 3072 | 236.8 s |
These are direct generations, not upscales. Different canvas sizes change noise and composition. Timings are single measured runs, not universal speed or quality guarantees. See benchmarks.json and the exact food prompt.
The local six-step samples show coherent food/material detail, but Q4 is not pixel-identical to the dense model. Image edits can repaint faces and fine geometry. The native CLI does not include the official hosted endpoint's prompt enhancer: exact short input text can differ in style from the hosted API result. A small native Image VAE decoder fixture measured 55.614 dB PSNR against an independent NumPy FP32 reference; that is a decoder check, not full publisher-pipeline parity.
Sources, modifications and license
- Original model: MiniMaxAI/MiniMax-H3-Image.
- Dense diffusion and Image VAE repack: Comfy-Org/MiniMax-H3-Image.
- H3-specific text/vision encoder: Comfy-Org/MiniMax-H3, locally quantized/merged with tokenizer embedded. It is an H3 conditioning encoder, not a generic chat checkpoint.
Modified diffusion and encoder files are quantized derivatives by zimageapp. The Image VAE is unchanged. The original MiniMax-H3-Image Community License Agreement applies; see LICENSE and NOTICE. The shared H3 encoder additionally carries its original LICENSE-H3-TEXT-ENCODER. These licenses contain territory, use and commercial conditions; this conversion does not replace them with an MIT/Apache license. “Powered by MiniMax-H3-Image”.
4-bit
