KaedeTai/HunyuanImage-3.0-mlx-mixed4-8-hymlx

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_proj split 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.