Build Anything with gr.Workflow

Published August 25, 2026

Many AI applications are pipelines. An image can be generated, have its background removed, and then be transformed into something else. A script can be turned into a voiceover, or the voice can be replaced while keeping the script unchanged. These steps are commonly connected in Python, with debugging often requiring developers to inspect intermediate values manually.

gr.Workflow, built into Gradio, makes the pipeline itself the interface. Workflows are defined as graphs of typed nodes, and Gradio provides a drag-and-drop canvas where each node can be run independently and every intermediate result is visible. The same graph can also serve as a REST API and be deployed to Hugging Face Spaces with one command.

The following examples demonstrate how workflows can be used. Each is available as a live Hugging Face Space that can be opened, run, and duplicated.

Edit an image

Users upload an image and provide an instruction, such as “turn it into a snowy winter scene,” “add sunglasses,” or “make the car red.” The application returns the edited image. The complete app is a single node that calls Qwen-Image-Edit through Hugging Face Inference Providers.

Try the Image Editor Pipeline.

Chain models into a media studio

A single graph can contain three pipelines. A prompt first generates an image with FLUX, then sends that image to a background-removal Gradio Space to create a sticker. The same topic is converted into a voiceover through a text-to-speech Gradio Space, while an LLM generates an episode title.

The workflow uses two model calls through Hugging Face Inference Providers and two calls to Gradio Spaces. Each output also receives its own REST endpoint: /sticker, /voiceover, and /episode_title. These endpoints can be called directly from code without opening the user interface.

Try the AI Media Studio.

Generate images in parallel

A single idea can produce several pieces of artwork at once: a base image from FLUX, a soft watercolor reinterpretation, a neon cyberpunk version, and a gallery title written by an LLM.

Each image is generated directly from the prompt by a model node using Inference Providers. The title is produced by an fn node that calls an LLM. This demonstrates a fan-out pattern, where one input feeds multiple operators that run in parallel.

Try the Generative Art Lab.

Profile a Hugging Face dataset

A user can enter a Hugging Face dataset ID, such as stanfordnlp/imdb or mteb/tweet_sentiment_extraction. One input then fans out to four operator nodes, which analyze the dataset through the Datasets Server API.

The results include an overview card, a preview of the first rows, statistics for each column, and a distribution chart. These results are computed independently and in parallel.

Try Data Detective.

Run a model on your own GPU

Although the preceding examples call Hugging Face services, an fn node is simply Python and can also run a model inside the Space on a GPU.

A bound function can be decorated with @spaces.GPU. When the node runs, ZeroGPU allocates a GPU for the call, runs the model, and releases the resource afterward. This allows workflows to use a local model rather than relying only on Inference Providers or existing Gradio Spaces.

One demonstration animates a still image with Lightricks/LTX-Video, loaded through Diffusers and run entirely within one node. gr.Workflow does not need details about the GPU configuration because it simply calls the bound function.

Try the ZeroGPU Animator.

How it works

Every workflow is a graph containing three types of nodes:

References: Inputs supplied to the workflow.
Operators: Steps that perform work.
Subjects: Outputs produced by the workflow.

An operator can be a custom Python function, a model accessed through Hugging Face Inference Providers, another Gradio Space, or a row from a Hub dataset. Nodes are connected by dragging between typed ports. After selecting Run, each result appears at its corresponding location in the graph.

Call a workflow from code

Every workflow is also an API. Each output becomes a REST endpoint named after its label, and the endpoint can be called from Python with the Gradio client.

The following example calls a multi-endpoint demo Space without a token:

from gradio_client import Client

client = Client("ysharma/gr-workflow-multi-endpoint-API")

print(client.predict("hello there friend", api_name="/word_count"))  # -> 3
print(client.predict(20, api_name="/fahrenheit"))                    # -> 68.0

Endpoints that call a model or another Space run with a Hugging Face token. Pass the token when creating the client:

from gradio_client import Client, handle_file

client = Client("ysharma/gr-workflow-image-editor", token="hf_...")

edited = client.predict(
    handle_file("dog.jpg"),
    "turn it into a snowy winter scene",
    api_name="/edited_image",
)

The endpoints can also be accessed over HTTP with curl:

curl -s https://ysharma-gr-workflow-multi-endpoint-API.hf.space/gradio_api/call/word_count \
  -H "Content-Type: application/json" -d '{"data": ["hello there friend"]}'

Build your own workflow

One way to get started is to open a demo, select Duplicate, and modify the graph. A basic workflow can also be created directly from Python:

import gradio as gr

def your_function(text: str) -> str:
  pass

gr.Workflow(bind=[your_function]).launch()

The full gr.Workflow guide covers the operator types, JSON schema, and reusable workflow patterns. More complex applications, including AUTOMATIC1111, can also be built with gr.Workflow.

Build Anything with gr.Workflow