Gradio Client

2.4.0 · active · verified Thu Apr 09

Gradio Client is a Python library designed for programmatically interacting with deployed Gradio applications. It allows developers to make API calls to Gradio-hosted machine learning models or other Gradio apps without needing the UI. The current stable version is 2.4.0. It's actively developed as part of the broader Gradio ecosystem, with frequent updates corresponding to Gradio's release cycle.

Warnings

breaking The `gradio.client` module was deprecated and removed in Gradio v3.14. Functionality was moved to the separate `gradio-client` package. If you were using `gradio.client.Client` directly, you must now install `gradio-client` and import `Client` from there.
Fix: Install `gradio-client` via `pip install gradio-client` and update your imports from `from gradio.client import Client` to `from gradio_client import Client`.
gotcha Distinction between `client.predict()` and `client.submit()`: `predict()` is a synchronous, blocking call that returns the result directly. `submit()` returns a `Job` object, allowing for asynchronous execution, polling for results, and handling streaming outputs. Using `predict()` for long-running tasks or when streaming is expected will block your program.
Fix: For long-running tasks or when expecting streaming data, use `job = client.submit(...)` and then retrieve results via `job.result()` or `job.outputs()`. For real-time updates, you might need `job.listen()`.
gotcha File inputs/outputs are handled automatically but can be unintuitive. When providing a local file path as input, `gradio-client` uploads it. When receiving a file output, `predict()` returns a temporary file path on the local machine.
Fix: Ensure the local file path provided as input exists and is accessible. When processing file outputs, remember they are temporary. If you need to persist them, copy or move the file from the temporary path after the call returns.
gotcha Authentication for private Hugging Face Spaces requires an `hf_token`. Forgetting to provide this token will result in authentication errors when trying to access private models.
Fix: Pass your Hugging Face API token using the `hf_token` parameter when initializing `Client`, e.g., `Client('repo_id', hf_token='hf_xxxxxxxxxxxxxxxxxxxxx')`, or set the `HF_TOKEN` environment variable, which `gradio-client` will pick up automatically.

Install

pip install gradio-client Install latest version

Imports

Client
```
from gradio_client import Client
```
The Client class was moved to its own `gradio-client` package in Gradio v3.14. Direct import from `gradio` no longer works for newer versions.

Quickstart

This quickstart demonstrates how to instantiate a `Client` for a Gradio application and make synchronous API calls using `client.predict()` and `client.submit().result()`. It includes basic error handling and shows how to pass a Hugging Face token for private spaces using an environment variable.

import os
from gradio_client import Client

# Replace with your Gradio app URL or Hugging Face Space ID
# For private Spaces, set the HF_TOKEN environment variable or pass hf_token directly.
SPACE_URL = os.environ.get('GRADIO_SPACE_URL', 'https://hf.space/gradio/calculator')
HF_TOKEN = os.environ.get('HF_TOKEN', '') # Optional: for private Hugging Face Spaces

client = Client(SPACE_URL, hf_token=HF_TOKEN)

# Example for a simple calculator app with 'add' function taking two numbers
try:
    # Use client.predict for synchronous calls
    result = client.predict(2, 3, api_name='/add')
    print(f"Result of 2 + 3: {result}")

    # Use client.submit for asynchronous calls or streaming output (not shown here)
    job = client.submit(10, 5, api_name='/subtract')
    print(f"Result of 10 - 5 (via job): {job.result()}")
except Exception as e:
    print(f"Error interacting with Gradio app: {e}")
    print("Please ensure the Gradio app is running and the API name is correct.")

view raw JSON →