USAGE.md

Install and use

Use Apple silicon, native arm64 Python 3.12, and a compatible macOS Metal installation. The measured environment is M5 Pro / 64 GiB, macOS 27.0.1, MLX 0.32.4 and Transformers 4.57.6. Smaller Macs have not been qualified.

Release installation

Request access on the selected variant and shared model pages and read their licenses. Install uv and authenticate with Hugging Face as shown below.

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 release catalog records immutable component revisions. It rejects unpublished or unpinned weights. For local development use uv pip install -e '.[native]' and the original checkpoint paths, as in the technical guide.

The native extra supplies PyTorch for the original CPU noise stream. Model operators still run in MLX on Metal. Without that extra, --rng mlx uses a different random stream and does not reproduce the same seeded images.

Select another variant or reuse existing weights

h3-mlx download --variant q8 --model-dir models/q8 \
  --text-encoder-path /path/to/MiniMax-H3/text_encoder
h3-mlx generate --model models/q8 --text-encoder models/q8/text_encoder \
  'A detailed scene description' --output outputs/q8.png

Use q4, bf16 or packed12 in the same way. Use a separate assembly directory for each variant. Shared files and the encoder are cached once; no other variant is fetched. The release selects quantization automatically, so do not add --quantize or --quantized-core to published variants.

To fetch the image model without the encoder, use --skip-text-encoder and pass your encoder path directly to generation. --local-files-only avoids network access when all required files already exist in the Hub cache.

Measured exact tuning

On the tested M5 Pro / 64 GiB, add:

--compile-blocks --eval-every 0 --prefetch-blocks 4 \
--compile-vae --vae-batch 4 --kernel metal-qk-exact --tune-matmul

Optional --wired-gb 32 (packed12) or --wired-gb 42 (BF16) were tested on this 64 GiB Mac. The runtime checks Metal's limit. They are not universal settings for other machines. Q8/Q4 are storage and memory tradeoffs and have not established a generation-speed advantage. Frozen modulation tables require MLX 0.32.4 and MLX_ENABLE_TF32=0; original checkpoints remain an alternative when regenerating tables in another supported environment.

Reference-image editing

h3-mlx generate --model models/packed12 \
  --text-encoder models/packed12/text_encoder \
  'Change the bottle in <Picture 1> to emerald glass while preserving its label' \
  --image bottle.png --seed 42 --output outputs/edit.png

The implementation accepts up to sixteen ordered references. The recorded image-edit cohort covers one reference. This does not establish quality for every multi-image composition. Use detailed English prompts. Prompt expansion is not automatic. The default 2048-square canvas is within the model's usual 4–20 MP working range. Smaller requested images are generated on an enlarged canvas and resized; development overrides are documented in the technical guide.

Each output has a JSON record with precision, seeds, schedule, timings, memory and environment. Add --save-trace for numerical audits. Report issues with that record, your command, chip, memory, macOS and package versions.

Licenses and access

The image weights and derivatives retain the MiniMax-H3-Image Community License Agreement, including its territory, commercial, redistribution and acceptable-use conditions. The text encoder has its own MiniMax H3 agreement. The published agreements exclude the EU, UK, Republic of Korea and US absent separate permission. A manual Hub gate supports access review; it does not grant rights outside those agreements. See LICENSE-model, LICENSE-text-encoder, NOTICE and release status.