> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/gradio-app/gradio/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript client

> Use any Gradio app as an API with the @gradio/client JavaScript library

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

<Tabs>
  <Tab title="npm">
    Install via npm for Node.js projects (requires Node.js 18.0.0 or higher):

    ```bash theme={null}
    npm i @gradio/client
    ```
  </Tab>

  <Tab title="CDN">
    Load directly in your HTML for quick prototyping:

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

    <Note>
      For production, hardcode a specific version instead of using the latest.
    </Note>
  </Tab>
</Tabs>

## Quick start

Here's a simple example using the [Whisper transcription Space](https://huggingface.co/spaces/abidlabs/whisper):

```javascript theme={null}
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:

```javascript theme={null}
import { Client } from "@gradio/client";

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

### Connect to private Spaces

For private Spaces, pass your Hugging Face token:

```javascript theme={null}
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](https://huggingface.co/settings/tokens).

### Connect to custom URLs

If your app is running on your own server:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
import { Client } from "@gradio/client";

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

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

## Inspect API endpoints

View available endpoints and their parameters:

```javascript theme={null}
import { Client } from "@gradio/client";

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

console.log(app_info);
```

```json theme={null}
{
  "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:

```javascript theme={null}
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:

```javascript theme={null}
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`:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```html theme={null}
<!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

<CardGroup cols={2}>
  <Card title="Python client" icon="python" href="/clients/python-client">
    Use Gradio apps as APIs from Python
  </Card>

  <Card title="FastAPI integration" icon="bolt" href="https://www.gradio.app/guides/fastapi-app-with-the-gradio-client">
    Integrate Gradio client with FastAPI
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.