Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 37 ยท Sharing and Deployment

The Gradio API and Python Client

Every Gradio app is also an API. Learn api_name, the Python and JavaScript clients, the two-step HTTP call protocol, file inputs and Server-Sent Events, with a runnable mock server.

Every Gradio app you build is also a web service. The buttons in the browser are just one client; a script, another app or a cron job can call the same functions over HTTP. This is why a Space can be used as a backend: you build a demo once and get an API for free.

The real server and client are not available on this site, so their code is read-only. The runnable blocks build a mock of the protocol in plain Python (JSON in, events out), labelled as a stand-in, to make the request and response shapes concrete.

Naming your endpoints

Each event handler becomes an endpoint with a name. For an Interface it is /predict. In Blocks, set it explicitly so it stays stable:

Python
import gradio as gr

def shout(text, times):
    return (text.upper() + "! ") * int(times)

with gr.Blocks() as demo:
    t = gr.Textbox(label="Text")
    n = gr.Slider(1, 5, value=2, step=1, label="Repeat")
    out = gr.Textbox(label="Result")
    gr.Button("Go").click(shout, [t, n], out, api_name="shout")

demo.launch()

At the bottom of the page, a "Use via API" link opens a panel listing every endpoint with its parameters, return types and ready-made code in Python, JavaScript and cURL. Check it first: it shows the exact names your client must use. Set api_name=False on a handler to hide it from the API, for example internal helpers, and show_api=False in launch() to remove the panel entirely.

The Python client

Install it separately (pip install gradio_client). Point it at a local URL or a Space:

Python
from gradio_client import Client

client = Client("http://127.0.0.1:7860/")        # or Client("user/space-name")
result = client.predict("hello", 2, api_name="/shout")
print(result)                                     # HELLO! HELLO!

Parameters go in the same order as the components in inputs. A call blocks until the result is ready. For long jobs use submit, which returns a job immediately:

Python
job = client.submit("hello", 3, api_name="/shout")
print(job.status())      # queued, running...
print(job.result())      # waits for the final value

Jobs can also be cancelled (job.cancel()) or iterated for generator endpoints (for partial in job:). Files are passed with handle_file("path/or/url"), and files in results are downloaded to a temp folder and returned as paths. For private Spaces pass Client("user/space", token=os.environ["HF_TOKEN"]). client.view_api() prints the endpoint list. A Space can be cloned for private use with Client.duplicate("user/space"), which avoids the shared queue.

The JavaScript client

The @gradio/client package offers the same operations for Node and the browser:

JavaScript
import { Client } from "@gradio/client";

const app = await Client.connect("user/space-name");
const result = await app.predict("/shout", ["hello", 2]);
console.log(result.data);        // ["HELLO! HELLO! "]

Note the difference: results come back as an array under data, because an endpoint can have several outputs.

Raw HTTP: a two-step protocol

Under the clients, calls are plain HTTP. In current Gradio versions (5 and later) a call has two steps:

  1. POST /gradio_api/call/shout with a JSON body {"data": ["hello", 2]}. The reply is {"event_id": "abc123"}: the request is now in the queue.
  2. GET /gradio_api/call/shout/abc123 streams Server-Sent Events. Each event is a pair of lines, event: ... and data: .... The complete event carries the output list, and an error event carries a message.
Terminal
curl -X POST http://127.0.0.1:7860/gradio_api/call/shout \
  -H "Content-Type: application/json" \
  -d '{"data": ["hello", 2]}'
# {"event_id":"..."}

Because the result is delivered by an event stream, long and streaming jobs work without holding the first request open. The "Use via API" panel always shows the up-to-date URLs for your version.

A mock of the protocol

This block fakes the server in memory: post_call queues a job and returns an event id; get_events returns the SSE text; a small parser reads it as a client would.

Python Mock two-step call and SSE parsing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The success case parses to a complete event holding ["HELLO! HELLO! "]; the call with a missing argument yields an error event instead. A real client does the same thing: post, read the stream, stop at complete or error.

A tiny client wrapper

Wrapping the two steps in one function is exactly what Client.predict does for you:

Python predict() built from post and get

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

It prints HI! HI! HI! . Real clients add the queue, the session hash, file upload, retries and streaming on top, but the shape is the same: arguments in, outputs back, endpoints identified by name.

Using an app as a backend: tips

  • Give every public endpoint an api_name and keep it stable, as clients depend on it.
  • The same queue and authentication rules apply to API callers, so a script can be rate-limited or require a token like a browser visitor.
  • For heavy production APIs, call the function from a proper API framework and use Gradio for the UI; the lesson on structuring larger apps shows how to mount both together.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does api_name control?

    An event's api_name becomes the endpoint, such as /shout, that clients call.
  2. 2. How are inputs passed to client.predict?

    Arguments map to inputs by position.
  3. 3. In the HTTP protocol, what does the first POST return?

    The POST queues the call; a GET with the event_id streams the result events.
  4. 4. Which method returns a job object immediately?

    submit returns right away so you can poll status or fetch the result later.

Summary

  • Every event handler is an API endpoint; set api_name for stable names.
  • gradio_client.Client.predict blocks; submit returns a job.
  • Raw HTTP uses a POST that returns an event_id followed by a GET that streams events.
  • The queue and authentication rules apply equally to API clients.

Next: Custom Components: How They Work