Skip to main content
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

​
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>

​
Next steps

Python client

Use Gradio apps as APIs from Python

FastAPI integration

Integrate Gradio client with FastAPI