Hub documentation
API 엔드포인트로 사용하는 Spaces
API 엔드포인트로 사용하는 Spaces
Hugging Face의 모든 Gradio Space는 자동으로 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 Space에는 푸터에 “Use via API” 링크가 있습니다. 클릭하면 다음을 볼 수 있습니다:
- 사용 가능한 모든 엔드포인트 및 이름
- 파라미터 유형 및 설명
- Python과 JavaScript용 자동 생성된 코드 스니펫
- UI 상호작용에서 코드를 생성하는 API 레코더
각 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 parametersPython 클라이언트
설치
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)
클라이언트 라이브러리 없이 HTTP를 통해 Gradio Spaces를 직접 호출할 수도 있습니다.
큐 기반 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
ZeroGPU Spaces는 계정 유형에 따라 사용 할당이 적용됩니다:
| 계정 유형 | 포함된 일일 GPU 할당량 |
|---|---|
| 인증되지 않음 | 2분 |
| 무료 계정 | 5분 |
| PRO 계정 | 40분 |
토큰으로 인증하면 계정 GPU 할당량이 소모됩니다. 인증되지 않은 요청은 더 엄격한 제한이 적용되는 공유 풀을 사용합니다.
PRO, Team, Enterprise 사용자는 GPU 시간 10분당 $1의 요금으로 선불 크레딧을 사용하여 포함 일일 할당량을 초과하여 사용할 수 있습니다.
40분간의 일일 GPU 할당량, 더 높은 대기열 우선순위, 크레딧을 이용한 할당량 확장 기능을 위해 PRO에 구독할 수 있습니다.
일반적인 패턴
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")다른 Space에서 Space 호출
자체 Gradio 앱에서 ZeroGPU Space를 호출할 때, 사용자의 인증을 전달하세요:
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가 사용 가능한 상황에서, 특정 작업을 위한 Spaces를 찾고 싶을 때가 있습니다:
curl -s "https://huggingface.co/api/spaces/semantic-search?q=text+to+speech&sdk=gradio"이것은 의미적 관련도 순으로 정렬된 Spaces를 Space ID, 좋아요 수, 짧은 설명을 포함한 메타데이터와 함께 반환합니다. API를 노출하는 Spaces로 필터링하려면 sdk=gradio 매개변수를 사용하세요.