Introducing Gradio ClientsJoin us on Thursday, 9am PST

Livestream

New to Gradio? Start here: Getting Started

See the Release History

To install Gradio from main, run the following command:

pip install https://gradio-builds.s3.amazonaws.com/ecbc363ee094a73535f53a612c2f6bd1b2154d83/gradio-4.34.0-py3-none-any.whl

*Note: Setting share=True in launch() will not work.

Client

gradio_client.Client(···)

Description

The main Client class for the Python client. This class is used to connect to a remote Gradio app and call its API endpoints.

Example usage

from gradio_client import Client

client = Client("abidlabs/whisper-large-v2")  # connecting to a Hugging Face Space
client.predict("test.mp4", api_name="/predict")
>> What a nice recording! # returns the result of the remote API call

client = Client("https://bec81a83-5b5c-471e.gradio.live")  # connecting to a temporary Gradio share URL
job = client.submit("hello", api_name="/predict")  # runs the prediction in a background thread
job.result()
>> 49 # returns the result of the remote API call (blocking call)

Initialization

Parameter Description
src

str

required

Either the name of the Hugging Face Space to load, (e.g. "abidlabs/whisper-large-v2") or the full URL (including "http" or "https") of the hosted Gradio app to load (e.g. "http://mydomain.com/app" or "https://bec81a83-5b5c-471e.gradio.live/").

hf_token

str | None

default: None

The Hugging Face token to use to access private Spaces. Automatically fetched if you are logged in via the Hugging Face Hub CLI. Obtain from: https://huggingface.co/settings/token

max_workers

int

default: 40

The maximum number of thread workers that can be used to make requests to the remote Gradio app simultaneously.

verbose

bool

default: True

Whether the client should print statements to the console.

auth

tuple[str, str] | None

default: None

headers

dict[str, str] | None

default: None

Additional headers to send to the remote Gradio app on every request. By default only the HF authorization and user-agent headers are sent. This parameter will override the default headers if they have the same keys.

download_files

str | Path | Literal[False]

default: "/tmp/gradio"

Directory where the client should download output files on the local machine from the remote API. By default, uses the value of the GRADIO_TEMP_DIR environment variable which, if not set by the user, is a temporary directory on your machine. If False, the client does not download files and returns a FileData dataclass object with the filepath on the remote machine instead.

ssl_verify

bool

default: True

If False, skips certificate validation which allows the client to connect to Gradio apps that are using self-signed certificates.

Event Listeners

Description

Event listeners allow you to capture and respond to user interactions with the UI components you've defined in a Gradio Blocks app. When a user interacts with an element, such as changing a slider value or uploading an image, a function is called.

Supported Event Listeners

The Client component supports the following event listeners. Each event listener takes the same parameters, which are listed in the Event Arguments table below.

Listener Description

Client.predict(fn, ···)

Calls the Gradio API and returns the result (this is a blocking call). <br>

Client.submit(fn, ···)

Creates and returns a Job object which calls the Gradio API in a background thread. The job can be used to retrieve the status and result of the remote API call. <br>

Client.view_api(fn, ···)

Prints the usage info for the API. If the Gradio app has multiple API endpoints, the usage info for each endpoint will be printed separately. If return_format="dict" the info is returned in dictionary format, as shown in the example below. <br>

Client.duplicate(fn, ···)

Duplicates a Hugging Face Space under your account and returns a Client object for the new Space. No duplication is created if the Space already exists in your account (to override this, provide a new name for the new Space using to_id). To use this method, you must provide an hf_token or be logged in via the Hugging Face Hub CLI. <br> The new Space will be private by default and use the same hardware as the original Space. This can be changed by using the private and hardware parameters. For hardware upgrades (beyond the basic CPU tier), you may be required to provide billing information on Hugging Face: https://huggingface.co/settings/billing <br>

Client.deploy_discord(fn, ···)

Deploy the upstream app as a discord bot. Currently only supports gr.ChatInterface.

Event Arguments

Parameter Description
args

<class 'inspect._empty'>

required

The arguments to pass to the remote API. The order of the arguments must match the order of the inputs in the Gradio app.

api_name

str | None

default: None

The name of the API endpoint to call starting with a leading slash, e.g. "/predict". Does not need to be provided if the Gradio app has only one named API endpoint.

fn_index

int | None

default: None

As an alternative to api_name, this parameter takes the index of the API endpoint to call, e.g. 0. Both api_name and fn_index can be provided, but if they conflict, api_name will take precedence.