Hub documentation

Spaces в качестве конечных точек 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 в качестве конечных точек API

Каждое Gradio Space на Hugging Face автоматически доступно как API-эндпоинт. Вы можете вызывать его из Python, JavaScript или любого HTTP-клиента. Если вы можете использовать Space в браузере, вы можете вызывать его как API.

Быстрый старт

Установите Python-клиент и вызовите любое публичное Space:

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

Просмотр доступных конечных точек API

Каждое пространство Gradio содержит ссылку «Use via API» в подвале страницы. Нажмите на неё, чтобы увидеть:

Все доступные конечные точки и их имена
Типы и описания параметров
Автоматически сгенерированные фрагменты кода на Python и JavaScript
API Recorder, генерирующий код на основе ваших действий в интерфейсе

Каждый Space также предоставляет спецификацию OpenAPI по адресу:

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

Например: https://abidlabs-en2fr.hf.space/gradio_api/openapi.json

Это полезно для понимания полной схемы API и её интеграции в собственные приложения.

Вы также можете программно проверять конечные точки:

from gradio_client import Client

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

Python-клиент

Установка

pip install --upgrade gradio_client

Требуется Python 3.10+.

Подключение к 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")

Получите токен Hugging Face по адресу https://huggingface.co/settings/tokens. Для частных Spaces потребуется токен с правами READ.

Создание предсказаний

Синхронный (блокирующий):

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

Асинхронный (неблокирующий):

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

Работа с файлами

Используйте handle_file() для любых файловых входных данных:

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

Мониторинг статуса задания

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

Эндпоинты потоковой передачи/генераторов

Для конечных точек, возвращающих несколько выходов:

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

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

JavaScript-клиент

Установка

npm i @gradio/client

Или используйте через CDN:

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

Подключение и предсказание

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

Работа с файлами

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

Потоковая передача результатов

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

REST API (curl)

Вы также можете вызывать Gradio Spaces напрямую через HTTP без использования клиентской библиотеки.

Очередная API (рекомендуется)

Большинство Spaces используют двухэтапный процесс:

Шаг 1: Отправьте запрос

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

Ответ:

{"event_id": "abc123"}

Шаг 2: Получите результат

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

Ответ (события, отправляемые сервером):

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

Заголовок Authorization обязателен для частных Spaces и обеспечивает более высокие лимиты запросов для публичных Spaces.

ZeroGPU Spaces

Spaces на ZeroGPU имеют квоты на использование в зависимости от типа вашего аккаунта:

Тип аккаунта	Включенный суточный лимит GPU
Неаутентифицированный	2 минуты
Бесплатный аккаунт	5 минут
PRO-аккаунт	40 минут

При аутентификации с использованием токена расходуется квота на GPU вашего аккаунта. Запросы без аутентификации используют общий пул с более строгими ограничениями.

Пользователи тарифов PRO, Team и Enterprise могут превысить включённый в подписку суточный лимит, используя предоплаченные кредиты по ставке 1 доллар за 10 минут времени GPU.

Вы можете подписаться на PRO, чтобы получить 40 минут ежедневной квоты GPU, более высокий приоритет в очереди и возможность расширить квоту с помощью кредитов.

Частые паттерны

Интеграция с 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}

Обработка ошибок с повторными попытками

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

Вызов Spaces из другого Space

При вызове ZeroGPU Space из собственного приложения Gradio передавайте аутентификацию пользователя:

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

Поиск Spaces с помощью семантического поиска

Среди тысяч доступных Gradio Spaces иногда хочется найти подходящий для конкретной задачи:

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

Этот запрос возвращает Spaces, отсортированные по семантической релевантности, с метаданными, включая идентификатор Space, количество лайков и краткое описание. Используйте параметр sdk=gradio, чтобы отфильтровать Spaces, предоставляющие API.

Подробнее

Update on GitHub

←Spaces в качестве инструментов агентов Gradio Spaces→