Hub documentation

Spaces en tant que points de terminaison d'API

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Spaces en tant que points de terminaison d'API

Chaque Gradio Space sur Hugging Face est automatiquement disponible en tant que point de terminaison d'API. Vous pouvez l'appeler depuis Python, JavaScript ou tout client HTTP. Si vous pouvez utiliser un Space dans votre navigateur, vous pouvez l'appeler en tant qu'API.

Démarrage rapide

Installez le client Python et appelez n'importe quel Space public :

pip install --upgrade gradio_client

from gradio_client import Client

client = Client("abidlabs/en2fr", token="hf_...")
result = client.predict("Hello, world!", api_name="/predict")
print(result)  # "Bonjour, le monde!"

Afficher les points de terminaison d'API disponibles

Chaque Espace Gradio possède un lien « Utiliser via l’API » dans le pied de page. Cliquez dessus pour afficher :

Toutes les extrémités disponibles et leurs noms
Types et descriptions des paramètres
Extraits de code générés automatiquement pour Python et JavaScript
Un enregistreur d'API qui génère du code à partir de vos interactions avec l'interface utilisateur

Chaque Space expose également une spécification OpenAPI à l'adresse suivante :

https://<space-subdomain>.hf.space/gradio_api/openapi.json

Par exemple : https://abidlabs-en2fr.hf.space/gradio_api/openapi.json

Cela est utile pour comprendre le schéma d'API complet et l'intégrer dans vos propres applications.

Vous pouvez également inspecter les points de terminaison de manière programmatique :

from gradio_client import Client

client = Client("abidlabs/whisper", token="hf_...")
client.view_api()  # Prints all endpoints with parameters

Client Python

Installation

pip install --upgrade gradio_client

Nécessite Python 3.10 ou supérieur.

Se connecter à un Space

from gradio_client import Client

# Public Space
client = Client("username/space-name")

# Private Space (requires token)
client = Client("username/private-space", token="hf_xxxxx")

Obtenez votre jeton Hugging Face sur https://huggingface.co/settings/tokens. Pour les Spaces privés, vous avez besoin d'un jeton avec les autorisations READ.

Faire des prédictions

Synchrone (bloquant) :

result = client.predict("Hello", api_name="/predict")

Asynchrone (non bloquant) :

job = client.submit("Hello", api_name="/predict")
# Do other work...
result = job.result()  # Get result when ready

Gérer les fichiers

Utilisez handle_file() pour toute entrée de fichier :

from gradio_client import Client, handle_file

client = Client("abidlabs/whisper", token="hf_...")

# From local file
result = client.predict(audio=handle_file("audio.wav"), api_name="/predict")

# From URL
result = client.predict(audio=handle_file("https://example.com/audio.wav"), api_name="/predict")

Suivre l'état du travail

job = client.submit("Hello", api_name="/predict")

# Check status
status = job.status()
print(f"Queue position: {status.rank}, ETA: {status.eta}")

# Check if complete
if job.done():
    result = job.result()

# Cancel a pending job
job.cancel()

Points de terminaison de streaming/générateur

Pour les points de terminaison qui produisent plusieurs sorties :

job = client.submit(prompt="Write a story", api_name="/generate")

# Iterate over streaming outputs
for output in job:
    print(output)

Client JavaScript

Installation

npm i @gradio/client

Ou utilisez-le via CDN :

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

Connecter et prédire

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

const app = await Client.connect("abidlabs/en2fr", { token: "hf_..." });
const result = await app.predict("/predict", ["Hello"]);
console.log(result.data);

Gérer les fichiers

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

const app = await Client.connect("abidlabs/whisper", { token: "hf_..." });
const result = await app.predict("/predict", [
  handle_file("https://example.com/audio.wav")
]);

Résultats en flux

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

for await (const message of job) {
  if (message.type === "data") {
    console.log("Result:", message.data);
  }
  if (message.type === "status") {
    console.log("Queue position:", message.position);
  }
}

API REST (curl)

Vous pouvez également appeler les Gradio Spaces directement via HTTP, sans aucune bibliothèque client.

API basée sur une file d’attente (recommandée)

La plupart des Spaces utilisent un processus en deux étapes :

Étape 1 : Soumettez votre demande

curl -X POST "https://abidlabs-en2fr.hf.space/gradio_api/call/predict" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $HF_TOKEN" \
  -d '{"data": ["Hello, world"]}'

Réponse :

{"event_id": "abc123"}

Étape 2 : Obtenir le résultat

curl -N "https://abidlabs-en2fr.hf.space/gradio_api/call/predict/abc123" \
  -H "Authorization: Bearer $HF_TOKEN"

Réponse (Server-Sent Events) :

event: complete
data: ["Bonjour, le monde!"]

L'en-tête Authorization est requis pour les Spaces privés et offre de meilleures limites de débit sur les Spaces publics.

Espaces ZeroGPU

Les Spaces ZeroGPU disposent de quotas d'utilisation basés sur le type de votre compte :

Type de compte	Quota quotidien de GPU inclus
Non authentifié	2 minutes
Compte gratuit	5 minutes
Compte PRO	40 minutes

Lorsque vous vous authentifiez avec votre jeton, le quota de GPU de votre compte est consommé. Les requêtes non authentifiées utilisent un pool partagé avec des limites plus strictes.

Les utilisateurs PRO, Team et Enterprise peuvent dépasser leur quota quotidien inclus en utilisant des crédits prépayés au tarif de 1 $ pour 10 minutes de temps GPU.

Vous pouvez vous abonner à PRO pour bénéficier de 40 minutes de quota GPU par jour, d'une priorité de file d'attente plus élevée et de la possibilité d'étendre votre quota avec des crédits.

Modèles courants

Intégration FastAPI

from fastapi import FastAPI
from gradio_client import Client, handle_file

app = FastAPI()
client = Client("abidlabs/whisper", token="hf_...")

@app.post("/transcribe/")
async def transcribe(file_url: str):
    result = client.predict(audio=handle_file(file_url), api_name="/predict")
    return {"transcription": result}

Gestion des erreurs avec des tentatives

import time
from gradio_client import Client

def predict_with_retry(client, *args, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            return client.predict(*args, **kwargs)
        except Exception as e:
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
            else:
                raise

client = Client("username/space", token="hf_...")
result = predict_with_retry(client, "input", api_name="/predict")

Appeler des Spaces depuis un autre Space

Lors de l’appel d’un Space ZeroGPU depuis votre propre application Gradio, transmettez l’authentification de l’utilisateur :

import gradio as gr
from gradio_client import Client

def process(prompt, request: gr.Request):
    x_ip_token = request.headers.get('x-ip-token', '')
    client = Client("owner/zerogpu-space", headers={"x-ip-token": x_ip_token})
    return client.predict(prompt, api_name="/predict")

demo = gr.Interface(fn=process, inputs="text", outputs="text")
demo.launch()

Trouver des Spaces avec la recherche sémantique

Avec des milliers de Gradio Spaces disponibles, vous souhaitez parfois en trouver un pour une tâche particulière :

curl -s "https://huggingface.co/api/spaces/semantic-search?q=text+to+speech&sdk=gradio"

Cela renvoie des Spaces classés par pertinence sémantique, avec des métadonnées incluant l’ID du Space, les likes et une courte description. Utilisez le paramètre sdk=gradio pour filtrer les Spaces qui exposent une API.

En savoir plus

Update on GitHub

←Les Spaces en tant qu'outils d'agent Gradio Spaces→