JavaScript client

The Gradio JavaScript client makes it easy to use any Gradio app as an API from Node.js or browser environments. You can call Gradio apps hosted on Hugging Face Spaces, your own servers, or anywhere else.

Installation

Install via npm for Node.js projects (requires Node.js 18.0.0 or higher):

npm i @gradio/client

Load directly in your HTML for quick prototyping:

<script type="module">
  import { Client } from "https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js";
  // Your code here
</script>

For production, hardcode a specific version instead of using the latest.

Quick start

Here’s a simple example using the Whisper transcription Space:

import { Client, handle_file } from "@gradio/client";

const response = await fetch(
  "https://github.com/audio-samples/audio-samples.github.io/raw/master/samples/wav/ted_speakers/SalmanKhan/sample-1.wav"
);
const audio_file = await response.blob();

const app = await Client.connect("abidlabs/whisper");
const transcription = await app.predict("/predict", [handle_file(audio_file)]);

console.log(transcription.data);
// ["I said the same phrase 30 times."]

Connecting to apps

Connect to Hugging Face Spaces

Connect to a Gradio app by passing the Space name:

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

const app = await Client.connect("abidlabs/en2fr");

Connect to private Spaces

For private Spaces, pass your Hugging Face token:

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

const app = await Client.connect("abidlabs/my-private-space", { 
  token: "hf_..." 
});

Get your token at https://huggingface.co/settings/tokens.

Connect to custom URLs

If your app is running on your own server:

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

const app = await Client.connect("https://bec81a83-5b5c-471e.gradio.live");

Connect with authentication

If the app requires username and password:

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

const app = await Client.connect(
  "username/space-name",
  { auth: ["username", "password"] }
);

Duplicate a Space for unlimited usage

For unlimited usage without rate limits, duplicate the Space:

import { Client, handle_file } from "@gradio/client";

const response = await fetch(
  "https://audio-samples.github.io/samples/mp3/blizzard_unconditional/sample-0.mp3"
);
const audio_file = await response.blob();

const app = await Client.duplicate("abidlabs/whisper", { 
  token: "hf_..." 
});
const transcription = await app.predict("/predict", [handle_file(audio_file)]);

console.log(transcription.data);

Configure hardware

Customize the hardware and timeout settings:

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

const app = await Client.duplicate("abidlabs/whisper", {
  token: "hf_...",
  timeout: 60,
  hardware: "a10g-small"
});

If the original Space uses GPUs, your duplicated Space will be billed accordingly. Spaces automatically sleep after 5 minutes of inactivity.

Inspect API endpoints

View available endpoints and their parameters:

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

const app = await Client.connect("abidlabs/whisper");
const app_info = await app.view_api();

console.log(app_info);

{
  "named_endpoints": {
    "/predict": {
      "parameters": [
        {
          "label": "text",
          "component": "Textbox",
          "type": "string"
        }
      ],
      "returns": [
        {
          "label": "output",
          "component": "Textbox",
          "type": "string"
        }
      ]
    }
  },
  "unnamed_endpoints": {}
}

You can also click “Use via API” in the app footer to view the API page in your browser.

Make predictions

Basic prediction

Call .predict() with the endpoint name and arguments:

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

const app = await Client.connect("abidlabs/en2fr");
const result = await app.predict("/predict", ["Hello"]);

console.log(result.data);
// ["Bonjour"]

Multiple parameters

Pass multiple arguments as an array:

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

const app = await Client.connect("gradio/calculator");
const result = await app.predict("/predict", [4, "add", 5]);

console.log(result.data);
// [9.0]

File inputs

For file inputs, pass a Buffer, Blob, or File:

import { Client, handle_file } from "@gradio/client";

const response = await fetch(
  "https://audio-samples.github.io/samples/mp3/blizzard_unconditional/sample-0.mp3"
);
const audio_file = await response.blob();

const app = await Client.connect("abidlabs/whisper");
const result = await app.predict("/predict", [handle_file(audio_file)]);

console.log(result.data);

Using events

For endpoints that return results over time or for monitoring job status, use the event interface:

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

function log_result(payload) {
  const { data: [translation] } = payload;
  console.log(`Translation: ${translation}`);
}

const app = await Client.connect("abidlabs/en2fr");
const job = app.submit("/predict", ["Hello"]);

for await (const message of job) {
  log_result(message);
}

Monitor status

Enable status updates by setting the events option:

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

const app = await Client.connect("abidlabs/en2fr", {
  events: ["status", "data"]
});

const job = app.submit("/predict", ["Hello"]);

for await (const message of job) {
  if (message.type === "status") {
    console.log(`Status: ${message.status}`);
  } else if (message.type === "data") {
    console.log(`Result: ${message.data}`);
  }
}

Status objects include:

status: Human-readable status (pending, generating, complete, error)
code: Detailed Gradio status code
position: Position in queue
queue_size: Total queue size
eta: Estimated completion time
success: Whether job completed successfully
time: When status was generated

Cancel jobs

Cancel queued or running jobs:

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

const app = await Client.connect("abidlabs/en2fr");
const job_one = app.submit("/predict", ["Hello"]);
const job_two = app.submit("/predict", ["Friends"]);

job_one.cancel();  // Stops listening for updates
job_two.cancel();  // Cancels if not started yet

Generator endpoints

For endpoints that yield multiple values, iterate over the results:

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

const app = await Client.connect("gradio/count_generator");
const job = app.submit("/count", [9]);

for await (const message of job) {
  console.log(message.data);
}
// 0
// 1
// 2
// ...
// 9

Cancel generator endpoints

Cancel iterative outputs to stop generation:

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

const app = await Client.connect("gradio/count_generator");
const job = app.submit("/count", [9]);

setTimeout(() => {
  job.cancel();
}, 3000);

for await (const message of job) {
  console.log(message.data);
}
// Stops after ~3 seconds

Complete example

Here’s a complete HTML example:

<!DOCTYPE html>
<html lang="en">
<head>
  <title>Gradio Client Example</title>
  <script type="module">
    import { Client } from "https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js";
    
    async function main() {
      const client = await Client.connect("abidlabs/en2fr");
      const result = await client.predict("/predict", {
        text: "My name is Hannah"
      });
      console.log(result);
    }
    
    main();
  </script>
</head>
<body>
  <h1>Check the console for results</h1>
</body>
</html>

Get Started

Core Concepts

Building Interfaces

Building with Blocks

Chatbots

Advanced Features

Custom Components

Clients & Deployment

JavaScript client

Installation

Quick start

Connecting to apps

Connect to Hugging Face Spaces

Connect to private Spaces

Connect to custom URLs

Connect with authentication

Duplicate a Space for unlimited usage

Configure hardware

Inspect API endpoints

Make predictions

Basic prediction

Multiple parameters

File inputs

Using events

Monitor status

Cancel jobs

Generator endpoints

Cancel generator endpoints

Complete example

Next steps

Python client

FastAPI integration

​Installation

​Quick start

​Connecting to apps

​Connect to Hugging Face Spaces

​Connect to private Spaces

​Connect to custom URLs

​Connect with authentication

​Duplicate a Space for unlimited usage

​Configure hardware

​Inspect API endpoints

​Make predictions

​Basic prediction

​Multiple parameters

​File inputs

​Using events

​Monitor status

​Cancel jobs

​Generator endpoints

​Cancel generator endpoints

​Complete example

​Next steps

Python client

FastAPI integration

Installation

Quick start

Connecting to apps

Connect to Hugging Face Spaces

Connect to private Spaces

Connect to custom URLs

Connect with authentication

Duplicate a Space for unlimited usage

Configure hardware

Inspect API endpoints

Make predictions

Basic prediction

Multiple parameters

File inputs

Using events

Monitor status

Cancel jobs

Generator endpoints

Cancel generator endpoints

Complete example

Next steps