devin-lai/MiniMax-H3-Image-mlx

MiniMax H3 Image on Apple silicon

Generate and edit images locally with MLX. Choose one weight variant; reuse the shared components.

Measured on M5 Pro / 64 GiB: tuned warm 2048 × 2048 generation took 62.49 s with BF16 or 64.05 s with lossless packed BF16. These are historical tests with cached conditioning and resident weights; see the measurement details.

View the generated showcase and comparisons

The gallery contains AI-generated images from recorded local runs. It uses manual access review under the model license. Prompts, seeds and precision settings are also documented here.

A community port of MiniMax-H3-Image by Devin Lai. Native MLX/Metal inference, all six distilled PDD steps, reference-image editing, lossless BF16 packing and optional Q8/Q4 weights. Model operators run locally on your Mac.

Quick start · Choose weights · Usage · Benchmarks · Collection · Repository map · 简体中文

Start with packed12 on a sufficiently large Mac. It reconstructs the original BF16 weight bits before computation. It is storage compression, not quantization. The tested machine is an M5 Pro with 64 GiB; smaller-memory Macs have not been qualified.

Choose your download

The main repository contains inference code, documentation and comparison records. Generated images are in the separately gated example gallery. Each linked model repository contains one weight choice. The downloader fetches that choice and its required shared files, then reuses the same pinned upstream text encoder across variants.

Variant	Variant weights¹	Choose it for
Lossless packed BF16	27.23 GiB	Recommended exact storage choice; original BF16 payloads
Original BF16	61.73 GiB	Unmodified complete transformer storage
Q8	19.83 GiB	Smaller core; image and detail changes
Q4	10.50 GiB	Smallest core; stronger fidelity tradeoffs

¹ Excludes shared VAE, support tensors, heads and tables, the separate roughly 62 GiB text encoder, Python dependencies and runtime memory. BF16 already includes native support; the downloader omits its redundant shared copy. Download sizes are not RAM requirements. Q8/Q4 quantize main and refiner attention/MLP weights with MLX affine groups of 64; FP32 precision islands stay native. Quantization has not established a generation-speed advantage here.

License and access: model weights retain MiniMax's community agreements, including territory and commercial restrictions; they are not unrestricted open-source weights. Model components use manual access review. Status and license details.

Quick start

Use an Apple silicon Mac, native arm64 Python 3.12 and uv. Request access on the selected model and shared-component pages before downloading weights:

uv venv --python 3.12 .venv
source .venv/bin/activate
uv pip install huggingface-hub==0.36.2
hf auth login

hf download devin-lai/MiniMax-H3-Image-mlx --revision v0.4.1 \
  --include 'h3_mlx/*' config.json pyproject.toml LICENSE NOTICE \
  --local-dir h3-runtime
uv pip install './h3-runtime[native]'
h3-mlx doctor

h3-mlx download --variant packed12 --model-dir models/packed12
h3-mlx generate --model models/packed12 \
  --text-encoder models/packed12/text_encoder \
  'An editorial photograph of a cobalt perfume bottle on pale stone' \
  --width 2048 --height 2048 --seed 731 --output outputs/bottle.png

The first download is large because the native text encoder is separate. Reuse an existing encoder with --text-encoder-path /path/to/text_encoder. Use --variant q8, q4 or bf16 to select another weight repository. Each output includes a JSON record with the prompt, seed, schedule, hardware, precision, timings and memory. Offline use, tuning and Python API.

For reference-image editing, add --image bottle.png and describe the edit using <Picture 1>. The implementation accepts up to sixteen ordered inputs; the recorded edit cohort validates one reference. Detailed English prompts are recommended; the runtime does not silently expand them.

Measured on M5 Pro / 64 GiB

Weight storage	Warm control	Warm tuned	Latency reduction	Max sampled parent footprint¹
BF16	65.83 s	62.49 s	5.07%	40.50 GiB
Lossless packed BF16	66.42 s	64.05 s	3.57%	32.56 GiB

Results are for 2048 × 2048, all six steps, on an M5 Pro with 16 GPU cores, 64 GiB unified memory and MLX 0.32.4. Each time is the geometric mean of product and portrait medians, with three alternating repeats per case. Conditioning was cached and weights resident; startup and downloads are excluded. A fresh CLI process includes loading and should not be expected to match these warm timings.

¹ Maximum sampled parent-process physical footprint over four candidate cases, including one edit; it is not the minimum required RAM. The BF16 and packed figures come from separate campaigns. Every output pixel and saved denoising tensor matched its corresponding MLX control in those four-case suites. These results do not establish CUDA pixel identity or a universal speed claim.

The tuned profiles use compiled blocks and VAE, bounded prefetch, an exact Q/K kernel and an M5-specific matrix tile. The default quick start does not enable all of these options. Copy the tested tuning flags and see the method, raw receipts and limitations. Q8 and Q4 reduce weight storage but change images; their downloadable exports have no established generation-speed advantage.

Inspect, reproduce, contribute

• Original examples and provenance: authentic outputs, prompts, seeds and reference images, clearly identified as AI-generated.
• Native / Q8 / Q4 comparisons: inspect the lettering and detail changes before choosing compact weights.
• Technical guide: precision rules, resident Python pipelines, reference-image processing and experiment reproduction.
• Validation: release software checks and fresh inference.
• Community discussions: share a reproducible issue or result with your variant, prompt, seed, canvas, Mac configuration and generated JSON record.

If the project helps you, like the variant you use and follow devin-lai for future Mac releases. Measured contributions and examples from more Apple silicon configurations are welcome. No hosted inference service is bundled.

Attribution and terms

Independent community MLX adaptation by Devin Lai, based on MiniMax's released weights and the inspected SGLang/Transformers inference contracts. This is not an official MiniMax release or endorsement. Powered by MiniMax-H3-Image.

Runtime code: Apache-2.0. Image weights and derivatives: MiniMax-H3-Image Community License Agreement. Separate text encoder: MiniMax H3 Community License Agreement. The published agreements exclude the EU, UK, Republic of Korea and US absent separate permission and include commercial, redistribution and acceptable-use conditions. Access review does not grant additional rights. Modifications · NOTICE · Pinned source provenance.