Hub documentation

Spaces como pontos de extremidade 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 pontos de extremidade de API

Todo Gradio Space no Hugging Face está automaticamente disponível como um endpoint de API. Você pode chamá-lo a partir de Python, JavaScript ou qualquer cliente HTTP. Se você pode usar um Space no seu navegador, pode chamá-lo como uma API.

Início rápido

Instale o cliente Python e chame qualquer 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!"

Visualizar os endpoints de API disponíveis

Todo Espaço Gradio tem um link “Use via API” no rodapé. Clique nele para ver:

Todos os endpoints disponíveis e seus nomes
Tipos e descrições dos parâmetros
Trechos de código gerados automaticamente para Python e JavaScript
Um Gravador de API que gera código a partir das suas interações na interface do usuário

Cada Space também expõe uma especificação OpenAPI em:

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

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

Isso é útil para entender o esquema completo da API e integrá-lo aos seus próprios aplicativos.

Você também pode inspecionar endpoints programaticamente:

from gradio_client import Client

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

Cliente Python

Instalação

pip install --upgrade gradio_client

Requer Python 3.10+.

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

Obtenha seu token do Hugging Face em https://huggingface.co/settings/tokens. Para Spaces privados, você precisa de um token com permissões de READ.

Faça Previsões

Síncrono (bloqueante):

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

Assíncrono (não bloqueante):

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

Gerenciar Arquivos

Use handle_file() para qualquer entrada de arquivo:

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

Monitorar o status do trabalho

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/Generator

Para endpoints que retornam múltiplas saídas:

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

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

Cliente JavaScript

Instalação

npm i @gradio/client

Ou use via CDN:

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

Conectar e Prever

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

Gerenciar Arquivos

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

Você também pode chamar os Gradio Spaces diretamente via HTTP, sem nenhuma biblioteca de cliente.

API baseada em fila (Recomendado)

A maioria dos Spaces usa um processo de duas etapas:

Etapa 1: Envie sua solicitação

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"]}'

Resposta:

{"event_id": "abc123"}

Etapa 2: Obter o resultado

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

Resposta (Server-Sent Events):

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

O cabeçalho Authorization é obrigatório para Spaces privados e oferece limites de taxa melhores em Spaces públicos.

Espaços ZeroGPU

Os Spaces ZeroGPU possuem cotas de uso com base no tipo da sua conta:

Tipo de Conta	Cota Diária de GPU Incluída
Não autenticado	2 minutos
Conta gratuita	5 minutos
Conta PRO	40 minutos

Quando você autentica com seu token, a cota de GPU da sua conta é consumida. Solicitações não autenticadas usam um pool compartilhado com limites mais restritos.

Usuários PRO, Team e Enterprise podem ultrapassar sua cota diária incluída usando créditos pré-pagos na taxa de US$ 1 por 10 minutos de tempo de GPU.

Você pode assinar o PRO para obter 40 minutos de cota diária de GPU, prioridade mais alta na fila e a capacidade de estender sua cota com créditos.

Padrões comuns

Integração com 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}

Tratamento de Erros com Novas Tentativas

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

Chamando Spaces de Outro Space

Ao chamar um Space ZeroGPU do seu próprio app Gradio, encaminhe a autenticação do usuário:

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

Encontre Spaces com busca semântica

Com milhares de Gradio Spaces disponíveis, às vezes você deseja encontrar um para uma tarefa específica:

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

Isso retorna Spaces ranqueados por relevância semântica, com metadados incluindo o ID do Space, curtidas e uma breve descrição. Use o parâmetro sdk=gradio para filtrar Spaces que expõem uma API.

Saiba mais

Update on GitHub

←Spaces como Ferramentas de Agentes Espaços do Gradio→