README.md

metadata

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:

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:

@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

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

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:

from gradio_client import Client

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