README.md

---
title: Z Image Turbo
emoji: 🖼️
colorFrom: yellow
colorTo: yellow
sdk: gradio
sdk_version: 6.20.0
app_file: app.py
pinned: true
hf_oauth: true
---

# Z-Image-Turbo (Gradio Workflow — single Space, ZeroGPU)

A visual, node-based image-generation app built with `gr.Workflow`. The
workflow frontend and the ZeroGPU-powered generation function live in the
**same Space**: the canvas calls a bound `@spaces.GPU` Python function via a
`fn` operator node, so there is no cross-Space round-trip.

## How it works

The workflow is defined in [`workflow.json`](./workflow.json):

| Node | Role | Type |
|---|---|---|
| Prompt · Height · Width · Inference Steps · Seed · Randomize Seed | references (inputs) | text / number / boolean |
| `generate_image` | operator — `kind: "fn"`, bound to `@spaces.GPU generate_image` in `app.py` | calls the local zero-GPU pipeline |
| Output Image · Seed Used | subjects (outputs) | image / number |

`app.py` loads the `Tongyi-MAI/Z-Image-Turbo` pipeline at startup and binds it:

```python
@spaces.GPU
def generate_image(prompt, height, width, num_inference_steps, seed, randomize_seed):
    ...
    return image, seed_used

gr.Workflow(graph="workflow.json", bind={"generate_image": generate_image}).launch()
```

When the canvas hits **Run**, the executor's `fn` branch routes the call to
the local `generate_image`, and `@spaces.GPU` allocates a ZeroGPU worker for
that invocation.

Edit the topology on the canvas (drag nodes, change the prompt, rewire) and
hit **Run**. Changes are saved back to `workflow.json`.

## Running locally

```bash
pip install -r requirements.txt
python app.py
```

GPU access through `@spaces.GPU` only works on Hugging Face Spaces — locally
the decorated call will raise. Otherwise the workflow frontend, node wiring
and grading still work.

Open the **write-access link** printed at launch to edit the workflow; plain
local/share URLs open it read-only.

## Deploying

```bash
gradio deploy
```

`hf_oauth: true` is set so that, on a Space, each visitor signs in with their
own HF account and ZeroGPU allocations run under their own token. The Space
owner can edit and save the workflow; visitors get a read-only view and can
run the pipeline.

## API access

Every Workflow app is a Gradio app, so it exposes a REST endpoint per output
(subject) node — e.g. `/output_image` and `/seed_used`:

```python
from gradio_client import Client

client = Client("your-username/your-space")
client.view_api()  # list endpoints and their parameters
```