Generate images from text prompts directly in your terminal. Uses the Z-Image-Turbo model with a terminal-native workflow: generate → view inline → vary → save. Works in Ghostty and other terminals supporting the Kitty graphics protocol.

Quick Start

Bash

# 1. Install dependencies
uv sync

# 2. Download the model from Hugging Face (~32GB)
HF_XET_HIGH_PERFORMANCE=1 hf download Tongyi-MAI/Z-Image-Turbo

# 3. Start generating
uv run python src/cli.py

Features

Terminal Viewer - Generate and view images inline with instant hotkeys
Auto-save - Images saved to ~/Pictures/Autogen automatically
Variations - Same prompt, different seeds with one keypress
Web UI - Gradio-based interface with resolution controls
Optimized for Mac - Apple Silicon (MPS) and CUDA support

Requirements

Python 3.12+
Mac with Apple Silicon (M1/M2/M3/M4) or NVIDIA GPU
~32GB disk space for model download
16GB+ RAM recommended

Usage

Terminal Viewer (Recommended)

Bash

uv run python src/cli.py                    # 640x480 (fast)
uv run python src/cli.py -W 1024 -H 1024    # 1024x1024 (high quality)
uv run python src/cli.py -s 6               # Fewer steps (faster)

Interactive hotkeys:

[c] Copy to clipboard
[d] Delete image
[u] Upscale (2x resolution, same seed, max 1024)
[v] Variation (new seed)
[r] Reproduce (same seed)
[m] Show memory usage
[n] New prompt
[q] Quit

The UI shows generation time, RAM usage, and GPU memory with a visual bar. Images auto-save to ~/Pictures/Autogen/ with prompt-based filenames.

Web UI

Bash

uv run python src/ui.py           # Standard UI
uv run python src/ui_optimized.py # With optimization options

Performance

Apple Silicon (M4 Max)

Based on benchmarking with 1024x1024 images, 9 steps:

Standard: ~100s (1.00x)
Torch Compile: ~162s (0.62x)
Int8 Quantization: ~126s (0.80x)
Compile + Quantization: ~97s (1.03x)

Key Findings: torch.compile is NOT optimized for MPS yet (adds overhead). Model is already well-optimized for Apple Silicon. For faster generation: reduce resolution or decrease steps.

CUDA GPUs

RTX 4090: 5-15s per image
H100: Sub-5s per image
torch.compile provides 2-3x speedup on CUDA
bfloat16 recommended for best quality/speed balance

Project Structure

text

turbo-term/
├── src/
│   ├── cli.py               # Terminal viewer with Kitty graphics
│   ├── generate.py          # Simple generation script
│   ├── ui.py                # Gradio web UI
│   └── ui_optimized.py      # Web UI with optimization options
├── scripts/
│   ├── debug_model.py       # Device/dtype testing
│   └── optimize_benchmark.py # Performance benchmarking
├── pyproject.toml
└── README.md

Dependencies

diffusers - Image generation pipeline
torch - Deep learning framework
torchao - Quantization library
gradio - Web UI framework
transformers - Model utilities
accelerate - Training/inference optimization

Model Information

Z-Image-Turbo by Tongyi-MAI:

Optimized for fast inference (8-9 steps)
1024x1024 native resolution
Fits in 16GB VRAM
~32GB model size on disk

License

MIT License. The Z-Image-Turbo model has its own license - see the model card for details.