Hub documentation

Spaces sebagai endpoint 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 sebagai endpoint API

Setiap Gradio Space di Hugging Face secara otomatis tersedia sebagai endpoint API. Anda dapat memanggilnya dari Python, JavaScript, atau klien HTTP apa pun. Jika Anda dapat menggunakan Space di browser, Anda dapat memanggilnya sebagai API.

Mulai cepat

Instal klien Python dan panggil Space publik mana pun:

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

Lihat endpoint API yang tersedia

Setiap Gradio Space memiliki tautan “Use via API” di bagian footer. Klik tautan tersebut untuk melihat:

Semua endpoint yang tersedia beserta nama mereka
Jenis dan deskripsi parameter
Potongan kode yang dibuat otomatis untuk Python dan JavaScript
Perekam API yang menghasilkan kode dari interaksi UI Anda

Setiap Space juga mengekspos spesifikasi OpenAPI di:

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

Sebagai contoh: https://huggingface.co/proxy/abidlabs-en2fr.hf.space/gradio_api/openapi.json

Hal ini berguna untuk memahami skema API secara lengkap dan mengintegrasikannya ke dalam aplikasi Anda sendiri.

Anda juga dapat memeriksa endpoint secara programatik:

from gradio_client import Client

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

Klien Python

Instalasi

pip install --upgrade gradio_client

Memerlukan Python 3.10+.

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

Dapatkan token Hugging Face Anda di https://huggingface.co/settings/tokens. Untuk Spaces privat, Anda memerlukan token dengan izin READ.

Lakukan Prediksi

Sinkron (blocking):

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

Asinkron (non-blocking):

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

Mengelola File

Gunakan handle_file() untuk semua input 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")

Pantau Status Pekerjaan

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

Endpoint Streaming/Generator

Untuk endpoint yang menghasilkan beberapa output:

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

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

Klien JavaScript

Instalasi

npm i @gradio/client

Atau gunakan via CDN:

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

Hubungkan dan Prediksi

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

Mengelola File

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

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

REST API (curl)

Anda juga dapat memanggil Gradio Spaces secara langsung melalui HTTP tanpa pustaka klien apa pun.

API Berbasis Antrean (Disarankan)

Sebagian besar Spaces menggunakan proses dua langkah:

Langkah 1: Kirim permintaan Anda

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

Respons:

{"event_id": "abc123"}

Langkah 2: Dapatkan hasilnya

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

Respons (Server-Sent Events):

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

Header Authorization diperlukan untuk Spaces privat dan memberikan batas laju (rate limit) yang lebih baik pada Spaces publik.

ZeroGPU Spaces

Spaces ZeroGPU memiliki kuota penggunaan berdasarkan tipe akun Anda:

Jenis Akun	Kuota GPU Harian yang Disertakan
Tidak terautentikasi	2 menit
Akun gratis	5 menit
Akun PRO	40 menit

Saat Anda melakukan autentikasi dengan token Anda, kuota GPU akun Anda akan terpakai. Permintaan tanpa autentikasi menggunakan pool bersama dengan batasan yang lebih ketat.

Pengguna PRO, Team, dan Enterprise dapat melampaui kuota harian yang disertakan dengan menggunakan kredit prabayar dengan tarif $1 per 10 menit waktu GPU.

Anda dapat berlangganan PRO untuk kuota GPU harian 40 menit, prioritas antrean yang lebih tinggi, dan kemampuan untuk memperpanjang kuota Anda dengan kredit.

Pola umum

Integrasi 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}

Penanganan Kesalahan dengan Percobaan Ulang

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

Memanggil Spaces dari Spaces Lain

Saat memanggil ZeroGPU Space dari aplikasi Gradio Anda sendiri, teruskan autentikasi pengguna:

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

Cari Spaces dengan pencarian semantik

Dengan ribuan Gradio Spaces yang tersedia, terkadang Anda ingin menemukan satu untuk tugas tertentu:

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

Ini mengembalikan Spaces yang diurutkan berdasarkan relevansi semantik, dengan metadata yang mencakup ID Space, jumlah suka, dan deskripsi singkat. Gunakan parameter sdk=gradio untuk memfilter Spaces yang mengekspos API.

Pelajari lebih lanjut

Update on GitHub

←Spaces sebagai Alat Agen Gradio Spaces→