| # 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](https://docs.astral.sh/uv/getting-started/installation/) |
| and authenticate with Hugging Face as shown below. |
|
|
| ```bash |
| 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](docs/TECHNICAL.md). |
|
|
| 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 |
|
|
| ```bash |
| 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: |
|
|
| ```bash |
| --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 |
|
|
| ```bash |
| 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](RELEASE.md). |
|
|
