Turbo-Term

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

# 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)

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

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

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.