HunyuanImage-3.0-Instruct — MLX, mixed 4/8-bit
HunyuanImage-3.0-Instruct (80B MoE, 13B active) converted to MLX and quantised for Apple Silicon. Runs text-to-image and reference-image editing on a 128 GB Mac.
Code: https://github.com/KaedeTai/hymlx
git clone https://github.com/KaedeTai/hymlx && cd hymlx
pip install mlx numpy pillow safetensors transformers huggingface_hub torch
huggingface-cli download KaedeTai/HunyuanImage-3.0-mlx-mixed4-8-hymlx \
--local-dir ~/models/hymlx-mix
python3 tools/dream.py "a red fox in fresh snow, natural light" \
--model ~/models/hymlx-mix --steps 14
The model writes its own <think> / <recaption> prompt expansion first, then
generates from it — that expansion is what decides the composition.
Quantisation
Affine group quantisation, group size 64:
| bits | |
|---|---|
| 64 routed experts per layer (91.7% of parameters) | 4 |
attention qkv/o, shared expert, wte, lm_head | 8 |
| all norms, MoE routing gate, patch_embed, final_layer, timestep embedders, VAE, SigLIP2 | bf16, unquantised |
52.5 GiB on disk, 49.7 GiB resident, 69.5 GiB peak during editing.
This split is measured, not guessed. Against a fully 8-bit reference, the model's estimate of the clean latent at sigma=1.0 — the hardest point, where it decides what to draw — correlates:
| configuration | weights | s/step | correlation |
|---|---|---|---|
| 6-bit everywhere | 70.8 GiB | 10.4 | +0.9980 |
| experts 4-bit, rest 8-bit (this repo) | 49.7 GiB | 11.0 | +0.9907 |
| 4-bit everywhere | 48.8 GiB | 10.7 | +0.9650 |
| 4-bit, group size 32 | 58.0 GiB | 9.7 | +0.9622 |
Attention turns out to be the sensitive part, not the experts: keeping it at 8 bits costs 1 GiB over full 4-bit and recovers most of the gap. A finer group size does not help at all. Precision buys memory here, not speed — 9.7 to 11.0 s/step across a 2x range in bit depth, because the path is compute-bound.
Speed
1024x1024, CFG on, M5 Max 128 GB, 14 steps:
| time | |
|---|---|
| text to image | 2.7 min (2.0 reusing a chain-of-thought) |
| reference-image editing | 3.5 min |
| chain-of-thought alone (1100 tokens) | 100 s |
Resolution is fixed by the model: the resolution group has 37 entries, all between 0.85 and 1.05 MP. Only the aspect ratio is adjustable.
Changes from the original
Required by Section 3(b) of the licence:
- Converted from PyTorch bf16 safetensors to MLX safetensors.
- Affine group quantisation applied as described above.
- Tensor layout rearranged for MLX: channels-last convolutions, the packed
gate_and_up_projsplit into separate up and gate halves, per-layer experts stacked into one tensor. - No fine-tuning, distillation or other training. Behaviour is intended to match the original within quantisation error.
Derived from the official bf16 release. tools/requantize.py in the code
repository can convert between precisions in place, so there is no need to
re-download 157 GiB to change the quantisation.
Licence
Tencent Hunyuan is licensed under the Tencent Hunyuan Community License Agreement, Copyright (C) 2025 Tencent. All Rights Reserved.
These weights are a Model Derivative and remain under that agreement — a copy
is included as LICENSE. Before using or redistributing them note in
particular:
- The licence does not apply in the European Union, the United Kingdom or South Korea.
- A separate licence from Tencent is required if your products or services have more than 100 million monthly active users.
- The acceptable-use policy carries its own restrictions.
Powered by Tencent Hunyuan.
The conversion code (hymlx) is separate and MIT licensed.