{"guide": {"name": "getting-started-with-the-js-client", "category": "gradio-clients-and-lite", "pretty_category": "Gradio Clients And Lite", "guide_index": 2, "absolute_index": 49, "pretty_name": "Getting Started With The Js Client", "content": "# Getting Started with the Gradio JavaScript Client\n\n\n\nThe Gradio JavaScript Client makes it very easy to use any Gradio app as an API. As an example, consider this [Hugging Face Space that transcribes audio files](https://huggingface.co/spaces/abidlabs/whisper) that are recorded from the microphone.\n\n![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/gradio-guides/whisper-screenshot.jpg)\n\nUsing the `@gradio/client` library, we can easily use the Gradio as an API to transcribe audio files programmatically.\n\nHere's the entire code to do it:\n\n```js\nimport { Client, handle_file } from \"@gradio/client\";\n\nconst response = await fetch(\n\t\"https://github.com/audio-samples/audio-samples.github.io/raw/master/samples/wav/ted_speakers/SalmanKhan/sample-1.wav\"\n);\nconst audio_file = await response.blob();\n\nconst app = await Client.connect(\"abidlabs/whisper\");\nconst transcription = await app.predict(\"/predict\", [handle_file(audio_file)]);\n\nconsole.log(transcription.data);\n// [ \"I said the same phrase 30 times.\" ]\n```\n\nThe Gradio Client works with any hosted Gradio app, whether it be an image generator, a text summarizer, a stateful chatbot, a tax calculator, or anything else! The Gradio Client is mostly used with apps hosted on [Hugging Face Spaces](https://hf.space), but your app can be hosted anywhere, such as your own server.\n\n**Prequisites**: To use the Gradio client, you do _not_ need to know the `gradio` library in great detail. However, it is helpful to have general familiarity with Gradio's concepts of input and output components.\n\n## Installation via npm\n\nInstall the @gradio/client package to interact with Gradio APIs using Node.js version >=18.0.0 or in browser-based projects. Use npm or any compatible package manager:\n\n```bash\nnpm i @gradio/client\n```\n\nThis command adds @gradio/client to your project dependencies, allowing you to import it in your JavaScript or TypeScript files.\n\n## Installation via CDN\n\nFor quick addition to your web project, you can use the jsDelivr CDN to load the latest version of @gradio/client directly into your HTML:\n\n```bash\n\n```\n\nBe sure to add this to the `` of your HTML. This will install the latest version but we advise hardcoding the version in production. You can find all available versions [here](https://www.jsdelivr.com/package/npm/@gradio/client). This approach is ideal for experimental or prototying purposes, though has some limitations.\n\n## Connecting to a running Gradio App\n\nStart by connecting instantiating a `client` instance and connecting it to a Gradio app that is running on Hugging Face Spaces or generally anywhere on the web.\n\n## Connecting to a Hugging Face Space\n\n```js\nimport { Client } from \"@gradio/client\";\n\nconst app = await Client.connect(\"abidlabs/en2fr\"); // a Space that translates from English to French\n```\n\nYou can also connect to private Spaces by passing in your HF token with the `hf_token` property of the options parameter. You can get your HF token here: https://huggingface.co/settings/tokens\n\n```js\nimport { Client } from \"@gradio/client\";\n\nconst app = await Client.connect(\"abidlabs/my-private-space\", { hf_token: \"hf_...\" })\n```\n\n## Duplicating a Space for private use\n\nWhile you can use any public Space as an API, you may get rate limited by Hugging Face if you make too many requests. For unlimited usage of a Space, simply duplicate the Space to create a private Space, and then use it to make as many requests as you'd like! You'll need to pass in your [Hugging Face token](https://huggingface.co/settings/tokens)).\n\n`Client.duplicate` is almost identical to `Client.connect`, the only difference is under the hood:\n\n```js\nimport { Client, handle_file } from \"@gradio/client\";\n\nconst response = await fetch(\n\t\"https://audio-samples.github.io/samples/mp3/blizzard_unconditional/sample-0.mp3\"\n);\nconst audio_file = await response.blob();\n\nconst app = await Client.duplicate(\"abidlabs/whisper\", { hf_token: \"hf_...\" });\nconst transcription = await app.predict(\"/predict\", [handle_file(audio_file)]);\n```\n\nIf you have previously duplicated a Space, re-running `Client.duplicate` will _not_ create a new Space. Instead, the client will attach to the previously-created Space. So it is safe to re-run the `Client.duplicate` method multiple times with the same space.\n\n**Note:** if the original Space uses GPUs, your private Space will as well, and your Hugging Face account will get billed based on the price of the GPU. To minimize charges, your Space will automatically go to sleep after 5 minutes of inactivity. You can also set the hardware using the `hardware` and `timeout` properties of `duplicate`'s options object like this:\n\n```js\nimport { Client } from \"@gradio/client\";\n\nconst app = await Client.duplicate(\"abidlabs/whisper\", {\n\thf_token: \"hf_...\",\n\ttimeout: 60,\n\thardware: \"a10g-small\"\n});\n```\n\n## Connecting a general Gradio app\n\nIf your app is running somewhere else, just provide the full URL instead, including the \"http://\" or \"https://\". Here's an example of making predictions to a Gradio app that is running on a share URL:\n\n```js\nimport { Client } from \"@gradio/client\";\n\nconst app = Client.connect(\"https://bec81a83-5b5c-471e.gradio.live\");\n```\n\n## Connecting to a Gradio app with auth\n\nIf the Gradio application you are connecting to [requires a username and password](/guides/sharing-your-app#authentication), then provide them as a tuple to the `auth` argument of the `Client` class:\n\n```js\nimport { Client } from \"@gradio/client\";\n\nClient.connect(\n space_name,\n { auth: [username, password] }\n)\n```\n\n\n## Inspecting the API endpoints\n\nOnce you have connected to a Gradio app, you can view the APIs that are available to you by calling the `Client`'s `view_api` method.\n\nFor the Whisper Space, we can do this:\n\n```js\nimport { Client } from \"@gradio/client\";\n\nconst app = await Client.connect(\"abidlabs/whisper\");\n\nconst app_info = await app.view_api();\n\nconsole.log(app_info);\n```\n\nAnd we will see the following:\n\n```json\n{\n\t\"named_endpoints\": {\n\t\t\"/predict\": {\n\t\t\t\"parameters\": [\n\t\t\t\t{\n\t\t\t\t\t\"label\": \"text\",\n\t\t\t\t\t\"component\": \"Textbox\",\n\t\t\t\t\t\"type\": \"string\"\n\t\t\t\t}\n\t\t\t],\n\t\t\t\"returns\": [\n\t\t\t\t{\n\t\t\t\t\t\"label\": \"output\",\n\t\t\t\t\t\"component\": \"Textbox\",\n\t\t\t\t\t\"type\": \"string\"\n\t\t\t\t}\n\t\t\t]\n\t\t}\n\t},\n\t\"unnamed_endpoints\": {}\n}\n```\n\nThis shows us that we have 1 API endpoint in this space, and shows us how to use the API endpoint to make a prediction: we should call the `.predict()` method (which we will explore below), providing a parameter `input_audio` of type `string`, which is a url to a file.\n\nWe should also provide the `api_name='/predict'` argument to the `predict()` method. Although this isn't necessary if a Gradio app has only 1 named endpoint, it does allow us to call different endpoints in a single app if they are available. If an app has unnamed API endpoints, these can also be displayed by running `.view_api(all_endpoints=True)`.\n\n## The \"View API\" Page\n\nAs an alternative to running the `.view_api()` method, you can click on the \"Use via API\" link in the footer of the Gradio app, which shows us the same information, along with example usage. \n\n![](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/gradio-guides/view-api.png)\n\nThe View API page also includes an \"API Recorder\" that lets you interact with the Gradio UI normally and converts your interactions into the corresponding code to run with the JS Client.\n\n\n## Making a prediction\n\nThe simplest way to make a prediction is simply to call the `.predict()` method with the appropriate arguments:\n\n```js\nimport { Client } from \"@gradio/client\";\n\nconst app = await Client.connect(\"abidlabs/en2fr\");\nconst result = await app.predict(\"/predict\", [\"Hello\"]);\n```\n\nIf there are multiple parameters, then you should pass them as an array to `.predict()`, like this:\n\n```js\nimport { Client } from \"@gradio/client\";\n\nconst app = await Client.connect(\"gradio/calculator\");\nconst result = await app.predict(\"/predict\", [4, \"add\", 5]);\n```\n\nFor certain inputs, such as images, you should pass in a `Buffer`, `Blob` or `File` depending on what is most convenient. In node, this would be a `Buffer` or `Blob`; in a browser environment, this would be a `Blob` or `File`.\n\n```js\nimport { Client, handle_file } from \"@gradio/client\";\n\nconst response = await fetch(\n\t\"https://audio-samples.github.io/samples/mp3/blizzard_unconditional/sample-0.mp3\"\n);\nconst audio_file = await response.blob();\n\nconst app = await Client.connect(\"abidlabs/whisper\");\nconst result = await app.predict(\"/predict\", [handle_file(audio_file)]);\n```\n\n## Using events\n\nIf the API you are working with can return results over time, or you wish to access information about the status of a job, you can use the iterable interface for more flexibility. This is especially useful for iterative endpoints or generator endpoints that will produce a series of values over time as discrete responses.\n\n```js\nimport { Client } from \"@gradio/client\";\n\nfunction log_result(payload) {\n\tconst {\n\t\tdata: [translation]\n\t} = payload;\n\n\tconsole.log(`The translated result is: ${translation}`);\n}\n\nconst app = await Client.connect(\"abidlabs/en2fr\");\nconst job = app.submit(\"/predict\", [\"Hello\"]);\n\nfor await (const message of job) {\n\tlog_result(message);\n}\n```\n\n## Status\n\nThe event interface also allows you to get the status of the running job by instantiating the client with the `events` options passing `status` and `data` as an array:\n\n\n```ts\nimport { Client } from \"@gradio/client\";\n\nconst app = await Client.connect(\"abidlabs/en2fr\", {\n\tevents: [\"status\", \"data\"]\n});\n```\n\nThis ensures that status messages are also reported to the client.\n\n`status`es are returned as an object with the following attributes: `status` (a human readbale status of the current job, `\"pending\" | \"generating\" | \"complete\" | \"error\"`), `code` (the detailed gradio code for the job), `position` (the current position of this job in the queue), `queue_size` (the total queue size), `eta` (estimated time this job will complete), `success` (a boolean representing whether the job completed successfully), and `time` ( as `Date` object detailing the time that the status was generated).\n\n```js\nimport { Client } from \"@gradio/client\";\n\nfunction log_status(status) {\n\tconsole.log(\n\t\t`The current status for this job is: ${JSON.stringify(status, null, 2)}.`\n\t);\n}\n\nconst app = await Client.connect(\"abidlabs/en2fr\", {\n\tevents: [\"status\", \"data\"]\n});\nconst job = app.submit(\"/predict\", [\"Hello\"]);\n\nfor await (const message of job) {\n\tif (message.type === \"status\") {\n\t\tlog_status(message);\n\t}\n}\n```\n\n## Cancelling Jobs\n\nThe job instance also has a `.cancel()` method that cancels jobs that have been queued but not started. For example, if you run:\n\n```js\nimport { Client } from \"@gradio/client\";\n\nconst app = await Client.connect(\"abidlabs/en2fr\");\nconst job_one = app.submit(\"/predict\", [\"Hello\"]);\nconst job_two = app.submit(\"/predict\", [\"Friends\"]);\n\njob_one.cancel();\njob_two.cancel();\n```\n\nIf the first job has started processing, then it will not be canceled but the client will no longer listen for updates (throwing away the job). If the second job has not yet started, it will be successfully canceled and removed from the queue.\n\n## Generator Endpoints\n\nSome Gradio API endpoints do not return a single value, rather they return a series of values. You can listen for these values in real time using the iterable interface:\n\n```js\nimport { Client } from \"@gradio/client\";\n\nconst app = await Client.connect(\"gradio/count_generator\");\nconst job = app.submit(0, [9]);\n\nfor await (const message of job) {\n\tconsole.log(message.data);\n}\n```\n\nThis will log out the values as they are generated by the endpoint.\n\nYou can also cancel jobs that that have iterative outputs, in which case the job will finish immediately.\n\n```js\nimport { Client } from \"@gradio/client\";\n\nconst app = await Client.connect(\"gradio/count_generator\");\nconst job = app.submit(0, [9]);\n\nfor await (const message of job) {\n\tconsole.log(message.data);\n}\n\nsetTimeout(() => {\n\tjob.cancel();\n}, 3000);\n```\n", "tags": ["CLIENT", "API", "SPACES"], "spaces": [], "url": "/guides/getting-started-with-the-js-client/", "contributor": null}}