| --- |
| title: Z-Image / Z-Image-Turbo |
| emoji: ⚡ |
| colorFrom: indigo |
| colorTo: pink |
| sdk: gradio |
| sdk_version: "6.20.0" |
| app_file: app.py |
| pinned: false |
| license: apache-2.0 |
| short_description: Text-to-image generation |
| --- |
| |
| # Z-Image / Z-Image-Turbo Gradio demo |
|
|
| A single-file Gradio app for Tongyi-MAI's Z-Image models: |
|
|
| - [Tongyi-MAI/Z-Image](https://huggingface.co/Tongyi-MAI/Z-Image) — full, undistilled base model. Supports CFG and negative prompts, 28–50 steps. |
| - [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo) — distilled for speed, 8 steps, no CFG. |
|
|
| Both load through the same `diffusers` `ZImagePipeline` class, so `app.py` works for either model — which one loads is controlled by the `MODEL_ID` constant at the top of the file. |
|
|
| ## Deploying |
|
|
| 1. Create a new Space at [huggingface.co/new-space](https://huggingface.co/new-space), SDK = **Gradio**. |
| 2. Upload `app.py`, `requirements.txt`, and this `README.md`. |
| 3. Under **Settings → Hardware**, select a GPU. For a free public demo, choose **ZeroGPU** (requires a PRO / Team / Enterprise account to enable it, but is free to run once enabled); otherwise pick a dedicated GPU tier with at least ~16 GB VRAM. |
| 4. To serve the base model instead of Turbo, either edit the `MODEL_ID` line in `app.py` to `"Tongyi-MAI/Z-Image"`, or add a Space **Variable** named `MODEL_ID` with that value and leave the code untouched. Deploying the same repo twice with different `MODEL_ID`s (mirroring the two official demo Spaces) is the simplest way to offer both. |
|
|
| ## Notes |
|
|
| - `low_cpu_mem_usage=False` and installing `diffusers` from Git (not PyPI) are both required per the model cards as of this writing. |
| - The Turbo model disables the steps and CFG controls in the UI since deviating from its distilled 8-step schedule tends to hurt quality; the base model leaves them adjustable. |
| - ZeroGPU currently backs onto H200 GPUs with ~70GB VRAM per workload, so if you'd rather have one Space that lets people switch between both models live (instead of deploying two Spaces), that's very feasible memory-wise — ask and this file can be adapted to load both and add a model-select dropdown. |
| - This is a minimal starting point. The [official Z-Image-Turbo Space](https://huggingface.co/spaces/Tongyi-MAI/Z-Image-Turbo) additionally layers on prompt enhancement, an NSFW safety checker, and ahead-of-time (AoTI) compilation for extra speed, none of which are included here to keep things simple to read and deploy. |
