Hub documentation

Spaces como puntos finales de 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 como puntos finales de API

Cada Gradio Space en Hugging Face está disponible automáticamente como un punto de acceso de API. Puedes llamarlo desde Python, JavaScript o cualquier cliente HTTP. Si puedes usar un Space en tu navegador, puedes llamarlo como una API.

Inicio rápido

Instale el cliente de Python y llame a cualquier Space público:

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!"

Ver los puntos finales de API disponibles

Cada Espacio de Gradio tiene un enlace “Use via API” en el pie de página. Haz clic en él para ver:

Todos los puntos de conexión disponibles y sus nombres
Tipos de parámetros y descripciones
Fragmentos de código generados automáticamente para Python y JavaScript
Un grabador de API que genera código a partir de tus interacciones con la interfaz de usuario

Cada Space también expone una especificación OpenAPI en:

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

Por ejemplo: https://huggingface.co/proxy/abidlabs-en2fr.hf.space/gradio_api/openapi.json

Esto es útil para comprender el esquema completo de la API e integrarlo en sus propias aplicaciones.

También puedes inspeccionar los puntos finales de forma programática:

from gradio_client import Client

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

Cliente de Python

Instalación

pip install --upgrade gradio_client

Requiere Python 3.10+.

Conectar a 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")

Obtén tu token de Hugging Face en https://huggingface.co/settings/tokens. Para Spaces privados, necesitas un token con permisos de READ.

Realizar predicciones

Síncrono (bloqueante):

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

Asíncrono (no bloqueante):

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

Gestionar archivos

Use handle_file() para cualquier entrada de archivo:

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")

Monitorizar el estado del trabajo

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()

Endpoints de streaming/generador

Para los puntos finales que producen múltiples salidas:

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

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

Cliente de JavaScript

Instalación

npm i @gradio/client

O úsalo a través de un CDN:

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

Conectar y predecir

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);

Gestionar archivos

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")
]);

Resultados en streaming

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)

También puedes llamar a los Gradio Spaces directamente mediante HTTP, sin ninguna biblioteca de cliente.

API basada en colas (recomendada)

La mayoría de los Spaces utilizan un proceso de dos pasos:

Paso 1: Envía tu solicitud

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

Respuesta:

{"event_id": "abc123"}

Paso 2: Obtener el resultado

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

Respuesta (Eventos enviados por el servidor):

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

La cabecera Authorization es obligatoria para los Spaces privados y ofrece mejores límites de tasa en los Spaces públicos.

Espacios ZeroGPU

Los espacios ZeroGPU tienen cuotas de uso basadas en el tipo de cuenta:

Tipo de cuenta	Cuota diaria de GPU incluida
No autenticado	2 minutos
Cuenta gratuita	5 minutos
Cuenta PRO	40 minutos

Cuando te autenticas con tu token, se consume la cuota de GPU de tu cuenta. Las solicitudes no autenticadas utilizan un pool compartido con límites más estrictos.

Los usuarios PRO, Team y Enterprise pueden superar su cuota diaria incluida mediante créditos prepagados a un precio de 1 USD por 10 minutos de tiempo de GPU.

Puedes suscribirte a PRO para obtener 40 minutos de cuota diaria de GPU, mayor prioridad en la cola y la posibilidad de ampliar tu cuota con créditos.

Patrones comunes

Integración con 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}

Gestión de errores con reintentos

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")

Llamar a Spaces desde otro Space

Al llamar a un Space de ZeroGPU desde tu propia aplicación de Gradio, reenvía la autenticación del usuario:

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()

Encuentra Spaces con búsqueda semántica

Con miles de Gradio Spaces disponibles, a veces quieres encontrar uno para una tarea en particular:

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

Esto devuelve Spaces ordenados por relevancia semántica, con metadatos que incluyen el ID del Space, los “me gusta” y una breve descripción. Utiliza el parámetro sdk=gradio para filtrar los Spaces que exponen una API.

Más información

Update on GitHub

←Spaces como herramientas de agentes Gradio Spaces→