# 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).