Documentation
Installation
DMG Installer
Download the DMG from the releases page (~12 GB, includes model weights). Open it and drag Z-Image.app to your Applications folder.
The CLI tool is embedded in the app bundle:
# Add to your PATH (optional)
ln -s /Applications/Z-Image.app/Contents/MacOS/txt2zimage /usr/local/bin/txt2zimage
Build from Source
git clone https://gitlab.com/mlc0911-group/txt2zimage.git
cd txt2zimage
task build
Requires Go 1.21+, Task, and the MLX libraries (built automatically).
Quick Start — Desktop App
- Launch Z-Image.app
- Type a prompt in the text field
- Pick an aspect ratio (1:1, 4:3, 16:9, …)
- Click Generate
- Watch the step-by-step progress — your image appears in seconds
Tips for better results
- Be descriptive: "a tabby cat sitting on a wooden table, studio lighting, shallow depth of field" works better than "cat"
- Use the seed field to reproduce a result you like
- Start with 9 steps (default) — increase to 12–15 for more detail
- Higher resolutions (1536+) need 24 GB+ RAM
Quick Start — CLI
# Basic generation
txt2zimage -p "a red fox in snow" -o fox.png
# Custom resolution
txt2zimage -p "panoramic mountain view" -w 1920 -h 1080 -o panorama.png
# More steps for higher quality
txt2zimage -p "detailed portrait" -s 15 --seed 42 -o portrait.png
# Use resident server for faster generation
txt2zimage serve & # start server in background
txt2zimage -p "prompt" -o result.png # connects automatically
Models
| Model | Parameters | Size | Steps | Description |
|---|---|---|---|---|
| z-image-turbo | 10.3B | ~12 GB (FP8) | 9 | Default — fast, high quality |
| mlczimage | 10.3B + LoKr | ~12 GB | 9 | Experimental — improved seed diversity |
Models are stored in ~/.txt2zimage/models/ and downloaded automatically
on first use from HuggingFace.
TeaCache
TeaCache is enabled by default. It caches intermediate denoising results
and skips ~4 of 9 steps when possible — roughly 2x speedup with minimal
quality impact. Disable with --no-teacache if you want maximum quality.
PNG Metadata
Every generated image embeds its generation parameters in the PNG tEXt chunks: prompt, seed, steps, resolution, model name, and TeaCache status. This means you can always look up exactly how an image was created and reproduce it.