zimage-mnn

Run Z-Image-Turbo text-to-image locally with MNN — optimized for Apple Silicon (Metal) with a CPU fallback.

The 12.3B-parameter DiT is quantized to int8 weights and runs the full pipeline (text encoder → 8-step denoiser → VAE) entirely on-device. No cloud calls.

Install & run (one line)

uvx zimage-mnn "a cute cat sitting on a windowsill"

Models (~11 GB) download automatically on first run and are cached in ~/.cache/zimage_mnn.

CLI usage

# basic
uvx zimage-mnn "a red sports car on a coastal highway"

# options
uvx zimage-mnn "a panda eating bamboo" \
    --size 1024x1024 \   # HxW (e.g. 1024x1024); a single number means square
    --steps 8 \          # denoising steps (2-12)
    --seed 42 \          # random seed
    --num-images 2 \     # generate several; each is saved as soon as it finishes
    --output out.png \   # output file (prefix for multiple: out_0.png, out_1.png, ...)
    --backend metal      # auto | metal | cpu

Size notes:

• Official Z-Image range is 512x512 .. 2048x2048 (any aspect ratio), both sides multiples of 16.
• The current released MNN model is exported for 1024x1024; other resolutions require a dynamic-shape model (in progress).

HTTP API

uvx zimage-mnn --api --port 8000

curl -X POST http://127.0.0.1:8000/generate \
     -H "Content-Type: application/json" \
     -d '{"prompt":"a cute cat","size":1024,"steps":8,"seed":42}' \
     -o cat.png

GET /health returns {"status":"ok"}.

Python API

from zimage_mnn import ZImageMNNPipeline

pipe = ZImageMNNPipeline.from_pretrained()          # downloads models
image = pipe("a cute cat", size=1024, steps=8, seed=42)
image.save("cat.png")

images = pipe.generate("a dog", num_images=3, seed=7)

Performance (Apple M5 Pro, 1024×1024, 8 steps)

Quality matches the original PyTorch pipeline (single-step cosine ≈ 0.9996).

Requirements

• Python ≥ 3.9
• macOS with Apple Silicon recommended (Metal). CPU works anywhere but is slower.
• ~16 GB RAM recommended; ~11 GB disk for the models.

License

Apache-2.0. Model weights derive from Tongyi-MAI/Z-Image-Turbo — see its license.