gradio workflow (#89)

- Convert app to gr.Workflow calling Z-Image-Turbo via HF Inference API (639e5b2674a6fe682cefac3e005abd5dcdb70404)
- Pin gradio 6.20.0 and scope OAuth to inference-api only (3953d49ac5e885a01cf75ed42b1d1b0f8927b74e)
- Use Spaces mode: workflow calls mrfakename/Z-Image-Turbo Space (2546607bb3b8fc5b737fa6495b34f3213c157adb)
- Single Space: workflow + @spaces.GPU fn bound via gr.Workflow (8859027f9fdd1583b29818a31734bf0b62cb6291)
- Drop inference-api OAuth scope (1fadc382061acddf691dab33e1171adaf8b51bb7)

README.md

@@ -4,9 +4,80 @@ emoji: 🖼️
 colorFrom: yellow
 colorTo: yellow
 sdk: gradio
-sdk_version: 6.0.1
+sdk_version: 6.20.0
 app_file: app.py
 pinned: true
+hf_oauth: true
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 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
+```

app.py

@@ -1,9 +1,13 @@
-import torch
+import os
+import tempfile
+
 import spaces
+import torch
 import gradio as gr
 from diffusers import DiffusionPipeline
 
-# Load the pipeline once at startup
+# Load the pipeline once at startup. The Space is a ZeroGPU space, so the
+# model weights stay resident and `@spaces.GPU` allocates a worker per call.
 print("Loading Z-Image-Turbo pipeline...")
 pipe = DiffusionPipeline.from_pretrained(
     "Tongyi-MAI/Z-Image-Turbo",
@@ -11,19 +15,50 @@ pipe = DiffusionPipeline.from_pretrained(
     low_cpu_mem_usage=False,
 )
 pipe.to("cuda")
+print("Pipeline loaded!")
 
-# ======== AoTI compilation + FA3 ========
-# pipe.transformer.layers._repeated_blocks = ["ZImageTransformerBlock"]
-# spaces.aoti_blocks_load(pipe.transformer.layers, "zerogpu-aoti/Z-Image", variant="fa3")
 
-print("Pipeline loaded!")
+def _save_image(image) -> dict:
+    """Mirror of `gradio.workflow._save_tmp`: serialize a PIL.Image as a JSON
+    pointer the canvas can render. `Workflow.launch()` already adds the
+    tempdir to `allowed_paths`, so the /gradio_api/file=… URL resolves."""
+    path = os.path.join(
+        tempfile.gettempdir(), f"zimage_{os.urandom(8).hex()}.png"
+    )
+    image.save(path)
+    return {
+        "path": path,
+        "url": f"/gradio_api/file={path}",
+        "orig_name": "zimage.png",
+        "mime_type": "image/png",
+    }
+
 
 @spaces.GPU
-def generate_image(prompt, height, width, num_inference_steps, seed, randomize_seed, progress=gr.Progress(track_tqdm=True)):
-    """Generate an image from the given prompt."""
+def generate_image(
+    prompt: str,
+    height: int,
+    width: int,
+    num_inference_steps: int,
+    seed: int,
+    randomize_seed: bool,
+):
+    """Generate an image from a prompt using Z-Image-Turbo on ZeroGPU.
+
+    Bound to the workflow canvas as a `fn` operator node — the workflow
+    calls this Python function directly server-side, so the entire pipeline
+    (frontend + ZeroGPU) lives in a single Space.
+
+    Returns (image_dict, seed_used). The image is serialized to a /gradio_api
+    file URL so JSON serialization across the fn bridge succeeds; the executor's
+    `fromGradioOutput` turns the dict back into an image port value.
+    """
+    if not prompt or not prompt.strip():
+        raise gr.Error("Please enter a prompt.")
+
     if randomize_seed:
         seed = torch.randint(0, 2**32 - 1, (1,)).item()
-    
+
     generator = torch.Generator("cuda").manual_seed(int(seed))
     image = pipe(
         prompt=prompt,
@@ -33,228 +68,20 @@ def generate_image(prompt, height, width, num_inference_steps, seed, randomize_s
         guidance_scale=0.0,
         generator=generator,
     ).images[0]
-    
-    return image, seed
 
-# Example prompts
-examples = [
-    ["Young Chinese woman in red Hanfu, intricate embroidery. Impeccable makeup, red floral forehead pattern. Elaborate high bun, golden phoenix headdress, red flowers, beads. Holds round folding fan with lady, trees, bird. Neon lightning-bolt lamp, bright yellow glow, above extended left palm. Soft-lit outdoor night background, silhouetted tiered pagoda, blurred colorful distant lights."],
-    ["A majestic dragon soaring through clouds at sunset, scales shimmering with iridescent colors, detailed fantasy art style"],
-    ["Cozy coffee shop interior, warm lighting, rain on windows, plants on shelves, vintage aesthetic, photorealistic"],
-    ["Astronaut riding a horse on Mars, cinematic lighting, sci-fi concept art, highly detailed"],
-    ["Portrait of a wise old wizard with a long white beard, holding a glowing crystal staff, magical forest background"],
-]
+    return _save_image(image), int(seed)
 
-# Custom theme with modern aesthetics (Gradio 6)
-custom_theme = gr.themes.Soft(
-    primary_hue="yellow",
-    secondary_hue="amber",
-    neutral_hue="slate",
-    font=gr.themes.GoogleFont("Inter"),
-    text_size="lg",
-    spacing_size="md",
-    radius_size="lg"
-).set(
-    button_primary_background_fill="*primary_500",
-    button_primary_background_fill_hover="*primary_600",
-    block_title_text_weight="600",
-)
 
-# Build the Gradio interface
-with gr.Blocks(fill_height=True) as demo:
-    # Header
-    gr.Markdown(
-        """
-        # 🎨 Z-Image-Turbo
-        **Ultra-fast AI image generation** • Generate stunning images in just 8 steps
-        """,
-        elem_classes="header-text"
-    )
-    
-    with gr.Row(equal_height=False):
-        # Left column - Input controls
-        with gr.Column(scale=1, min_width=320):
-            prompt = gr.Textbox(
-                label="✨ Your Prompt",
-                placeholder="Describe the image you want to create...",
-                lines=5,
-                max_lines=10,
-                autofocus=True,
-            )
-            
-            with gr.Accordion("⚙️ Advanced Settings", open=False):
-                with gr.Row():
-                    height = gr.Slider(
-                        minimum=512,
-                        maximum=2048,
-                        value=1024,
-                        step=64,
-                        label="Height",
-                        info="Image height in pixels"
-                    )
-                    width = gr.Slider(
-                        minimum=512,
-                        maximum=2048,
-                        value=1024,
-                        step=64,
-                        label="Width",
-                        info="Image width in pixels"
-                    )
-                
-                num_inference_steps = gr.Slider(
-                    minimum=1,
-                    maximum=20,
-                    value=9,
-                    step=1,
-                    label="Inference Steps",
-                    info="9 steps = 8 DiT forwards (recommended)"
-                )
-                
-                with gr.Row():
-                    randomize_seed = gr.Checkbox(
-                        label="🎲 Random Seed",
-                        value=True,
-                    )
-                    seed = gr.Number(
-                        label="Seed",
-                        value=42,
-                        precision=0,
-                        visible=False,
-                    )
-                
-                def toggle_seed(randomize):
-                    return gr.Number(visible=not randomize)
-                
-                randomize_seed.change(
-                    toggle_seed,
-                    inputs=[randomize_seed],
-                    outputs=[seed]
-                )
-            
-            generate_btn = gr.Button(
-                "🚀 Generate Image",
-                variant="primary",
-                size="lg",
-                scale=1
-            )
-            
-            # Example prompts
-            gr.Examples(
-                examples=examples,
-                inputs=[prompt],
-                label="💡 Try these prompts",
-                examples_per_page=5,
-            )
-        
-        # Right column - Output
-        with gr.Column(scale=1, min_width=320):
-            output_image = gr.Image(
-                label="Generated Image",
-                type="pil",
-                format="png",
-                show_label=False,
-                height=600,
-                buttons=["download", "share"],
-            )
-            
-            used_seed = gr.Number(
-                label="🎲 Seed Used",
-                interactive=False,
-                container=True,
-            )
-    
-    # Footer credits
-    gr.Markdown(
-        """
-        ---
-        <div style="text-align: center; opacity: 0.7; font-size: 0.9em; margin-top: 1rem;">
-        <strong>Model:</strong> <a href="https://huggingface.co/Tongyi-MAI/Z-Image-Turbo" target="_blank">Tongyi-MAI/Z-Image-Turbo</a> (Apache 2.0 License) • 
-        <strong>Demo by:</strong> <a href="https://x.com/realmrfakename" target="_blank">@mrfakename</a> • 
-        <strong>Redesign by:</strong> AnyCoder • 
-        <strong>Optimizations:</strong> <a href="https://huggingface.co/multimodalart" target="_blank">@multimodalart</a> (FA3 + AoTI)
-        </div>
-        """,
-        elem_classes="footer-text"
-    )
-    
-    # Connect the generate button
-    generate_btn.click(
-        fn=generate_image,
-        inputs=[prompt, height, width, num_inference_steps, seed, randomize_seed],
-        outputs=[output_image, used_seed],
-    )
-    
-    # Also allow generating by pressing Enter in the prompt box
-    prompt.submit(
-        fn=generate_image,
-        inputs=[prompt, height, width, num_inference_steps, seed, randomize_seed],
-        outputs=[output_image, used_seed],
-    )
+# The workflow (workflow.json) wires this function as a `fn` operator:
+#   Prompt, Height, Width, Inference Steps, Seed, Randomize Seed ─▶
+#   generate_image (fn operator, kind="fn") ─▶ Output Image, Seed Used
+#
+# On a Space with `hf_oauth: true`, visiting the canvas runs this function
+# under a ZeroGPU worker using each visitor's own HF token.
+demo = gr.Workflow(
+    graph="workflow.json",
+    bind={"generate_image": generate_image},
+)
 
 if __name__ == "__main__":
-    demo.launch(
-        theme=custom_theme,
-        css="""
-        .header-text h1 {
-            font-size: 2.5rem !important;
-            font-weight: 700 !important;
-            margin-bottom: 0.5rem !important;
-            background: linear-gradient(135deg, #fbbf24 0%, #f59e0b 100%);
-            -webkit-background-clip: text;
-            -webkit-text-fill-color: transparent;
-            background-clip: text;
-        }
-        
-        .header-text p {
-            font-size: 1.1rem !important;
-            color: #64748b !important;
-            margin-top: 0 !important;
-        }
-        
-        .footer-text {
-            padding: 1rem 0;
-        }
-        
-        .footer-text a {
-            color: #f59e0b !important;
-            text-decoration: none !important;
-            font-weight: 500;
-        }
-        
-        .footer-text a:hover {
-            text-decoration: underline !important;
-        }
-        
-        /* Mobile optimizations */
-        @media (max-width: 768px) {
-            .header-text h1 {
-                font-size: 1.8rem !important;
-            }
-            
-            .header-text p {
-                font-size: 1rem !important;
-            }
-        }
-        
-        /* Smooth transitions */
-        button, .gr-button {
-            transition: all 0.2s ease !important;
-        }
-        
-        button:hover, .gr-button:hover {
-            transform: translateY(-1px);
-            box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15) !important;
-        }
-        
-        /* Better spacing */
-        .gradio-container {
-            max-width: 1400px !important;
-            margin: 0 auto !important;
-        }
-        """,
-        footer_links=[
-            "api",
-            "gradio"
-        ],
-        mcp_server=True
-    )
+    demo.launch()

requirements.txt

@@ -1,5 +1,6 @@
-gradio
+gradio>=6.20.0
 git+https://github.com/huggingface/diffusers
 transformers
 kernels
-gradio[mcp]
+spaces
+gradio[mcp]

workflow.json

@@ -0,0 +1,154 @@
+{
+  "schema_version": "2",
+  "name": "Z-Image-Turbo",
+  "description": "Ultra-fast AI image generation with Z-Image-Turbo on ZeroGPU, driven by a gr.Workflow fn-bound @spaces.GPU function. Single Space: the workflow frontend and the GPU worker share one process.",
+  "runtime": { "default": "client" },
+  "view": { "default": "canvas" },
+  "references": [
+    {
+      "id": "ref_prompt",
+      "label": "Prompt",
+      "role": "reference",
+      "asset_type": "text",
+      "inputs": [{ "id": "in", "label": "Prompt", "type": "text" }],
+      "outputs": [{ "id": "out", "label": "Prompt", "type": "text" }],
+      "x": 60,
+      "y": 160,
+      "width": 240,
+      "height": 120,
+      "data": {
+        "out": "Astronaut in a jungle, cold color palette, muted colors, detailed, 8k"
+      }
+    },
+    {
+      "id": "ref_height",
+      "label": "Height",
+      "role": "reference",
+      "asset_type": "number",
+      "inputs": [{ "id": "in", "label": "Height", "type": "number" }],
+      "outputs": [{ "id": "out", "label": "Height", "type": "number" }],
+      "x": 60,
+      "y": 300,
+      "width": 200,
+      "height": 90,
+      "data": { "out": 1024 }
+    },
+    {
+      "id": "ref_width",
+      "label": "Width",
+      "role": "reference",
+      "asset_type": "number",
+      "inputs": [{ "id": "in", "label": "Width", "type": "number" }],
+      "outputs": [{ "id": "out", "label": "Width", "type": "number" }],
+      "x": 60,
+      "y": 410,
+      "width": 200,
+      "height": 90,
+      "data": { "out": 1024 }
+    },
+    {
+      "id": "ref_steps",
+      "label": "Inference Steps",
+      "role": "reference",
+      "asset_type": "number",
+      "inputs": [{ "id": "in", "label": "Steps", "type": "number" }],
+      "outputs": [{ "id": "out", "label": "Steps", "type": "number" }],
+      "x": 60,
+      "y": 520,
+      "width": 200,
+      "height": 90,
+      "data": { "out": 9 }
+    },
+    {
+      "id": "ref_seed",
+      "label": "Seed",
+      "role": "reference",
+      "asset_type": "number",
+      "inputs": [{ "id": "in", "label": "Seed", "type": "number" }],
+      "outputs": [{ "id": "out", "label": "Seed", "type": "number" }],
+      "x": 60,
+      "y": 630,
+      "width": 200,
+      "height": 90,
+      "data": { "out": 42 }
+    },
+    {
+      "id": "ref_randomize",
+      "label": "Randomize Seed",
+      "role": "reference",
+      "asset_type": "boolean",
+      "inputs": [{ "id": "in", "label": "Randomize", "type": "boolean" }],
+      "outputs": [{ "id": "out", "label": "Randomize", "type": "boolean" }],
+      "x": 60,
+      "y": 740,
+      "width": 200,
+      "height": 90,
+      "data": { "out": true }
+    }
+  ],
+  "operators": [
+    {
+      "id": "op_generate",
+      "label": "generate_image",
+      "role": "operator",
+      "kind": "fn",
+      "source": "fn",
+      "fn": "generate_image",
+      "inputs": [
+        { "id": "in_0", "label": "prompt", "type": "text", "required": true },
+        { "id": "in_1", "label": "height", "type": "number" },
+        { "id": "in_2", "label": "width", "type": "number" },
+        { "id": "in_3", "label": "num_inference_steps", "type": "number" },
+        { "id": "in_4", "label": "seed", "type": "number" },
+        { "id": "in_5", "label": "randomize_seed", "type": "boolean" }
+      ],
+      "outputs": [
+        { "id": "out_0", "label": "image", "type": "image", "output_index": 0 },
+        { "id": "out_1", "label": "seed_used", "type": "number", "output_index": 1 }
+      ],
+      "x": 420,
+      "y": 320,
+      "width": 280,
+      "height": 220,
+      "data": {}
+    }
+  ],
+  "subjects": [
+    {
+      "id": "sub_image",
+      "label": "Output Image",
+      "role": "subject",
+      "asset_type": "image",
+      "inputs": [{ "id": "in", "label": "Image", "type": "image" }],
+      "outputs": [{ "id": "out", "label": "Image", "type": "image" }],
+      "x": 820,
+      "y": 280,
+      "width": 240,
+      "height": 130,
+      "data": {}
+    },
+    {
+      "id": "sub_seed",
+      "label": "Seed Used",
+      "role": "subject",
+      "asset_type": "number",
+      "inputs": [{ "id": "in", "label": "Seed", "type": "number" }],
+      "outputs": [{ "id": "out", "label": "Seed", "type": "number" }],
+      "x": 820,
+      "y": 460,
+      "width": 240,
+      "height": 100,
+      "data": {}
+    }
+  ],
+  "edges": [
+    { "id": "e_prompt",     "from_node_id": "ref_prompt",     "from_port_id": "out", "to_node_id": "op_generate", "to_port_id": "in_0", "type": "text" },
+    { "id": "e_height",     "from_node_id": "ref_height",     "from_port_id": "out", "to_node_id": "op_generate", "to_port_id": "in_1", "type": "number" },
+    { "id": "e_width",      "from_node_id": "ref_width",      "from_port_id": "out", "to_node_id": "op_generate", "to_port_id": "in_2", "type": "number" },
+    { "id": "e_steps",      "from_node_id": "ref_steps",      "from_port_id": "out", "to_node_id": "op_generate", "to_port_id": "in_3", "type": "number" },
+    { "id": "e_seed",       "from_node_id": "ref_seed",       "from_port_id": "out", "to_node_id": "op_generate", "to_port_id": "in_4", "type": "number" },
+    { "id": "e_randomize",  "from_node_id": "ref_randomize",  "from_port_id": "out", "to_node_id": "op_generate", "to_port_id": "in_5", "type": "boolean" },
+    { "id": "e_image_out",  "from_node_id": "op_generate",    "from_port_id": "out_0", "to_node_id": "sub_image", "to_port_id": "in", "type": "image" },
+    { "id": "e_seed_out",   "from_node_id": "op_generate",    "from_port_id": "out_1", "to_node_id": "sub_seed",  "to_port_id": "in", "type": "number" }
+  ]
+}