Hugging Face API: Access, Rate Limits & SDKs 2026
Hugging Face's Inference Providers API is OpenAI-compatible with one HF token, routing across many open models and providers. Non-chat tasks use the native clients.
Hugging Face API verdict
Hugging Face's Inference Providers API authenticates with one fine-grained HF token.
Carrying the 'Make calls to Inference Providers' permission, and is OpenAI-compatible at https://router.huggingface.co/v1. You can reuse the OpenAI SDK by swapping the base URL, or use the native huggingface_hub Python and @huggingface/inference JS clients that cover all tasks.
Build on Inference Providers when you want one API and one token over many open models and providers. Keep your OpenAI SDK, point base_url at https://router.huggingface.co/v1 with an HF token, and call POST /v1/chat/completions with a model like openai/gpt-oss-120b:fastest to let HF pick the provider. For image, embeddings or speech, switch to the huggingface_hub or @huggingface/inference clients, which expose those tasks on the same token. Use :cheapest to optimize cost, pin a provider for consistency, and GET /v1/models to discover what is available and at what price. For teams, attribute spend with X-HF-Bill-To and set limits. The trade-off is that the OpenAI-compatible path is chat-only and quality is the underlying open model's. This is the right call when provider flexibility and open-model breadth matter more than a single vendor's proprietary frontier model.
- The OpenAI-compatible endpoint handles chat completions only. For text-to-image, embeddings or speech, use the huggingface_hub or huggingface.js clients.
- This is an access and routing layer, so model quality is the open model you choose, like gpt-oss, DeepSeek or Llama, not a Hugging Face proprietary model.
- Per-token rates are the provider's, since HF adds no markup, and they vary by model and provider, so check GET /v1/models for live pricing rather than a single number.
- Free monthly credits are small, from $0.10 to $2 a seat. Production workloads move to pay-as-you-go and should set org spend limits.
- Auth
- Bearer HF token (fine-grained)
- Base URL
- router.huggingface.co/v1
- Compat
- OpenAI SDK drop-in (chat)
- Clients
- huggingface_hub, huggingface.js
- Models
- 200+ across 19 providers
Build with the Hugging Face API
import os
from huggingface_hub import InferenceClient
client = InferenceClient()
completion = client.chat.completions.create(
model="openai/gpt-oss-120b",
messages=[{"role": "user", "content": "How many G in huggingface?"}],
)
print(completion.choices[0].message){
"choices": [{
"message": { "role": "assistant", "content": "There are 2 letter \"g\"s in ..." },
"finish_reason": "stop"
}]
}- Cost levers: :cheapest provider policy (lowest output price); pay-as-you-go at provider rates (no HF markup); X-HF-Bill-To org billing + spend limits.
- Handle: 401 (invalid or under-scoped HF token), 402 (monthly credits exhausted (purchase credits)).
Real Hugging Face code from the official docs. The raw cURL hello-world is the code block above; full limits and endpoints are in the tables on this page.
Your first Hugging Face API request
curl https://router.huggingface.co/v1/chat/completions \
-H "Authorization: Bearer $HF_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model": "openai/gpt-oss-120b:fastest",
"messages": [{"role": "user", "content": "How many G in huggingface?"}],
"stream": false
}'How to authenticate with the Hugging Face API
| Aspect | Detail | Notes |
|---|---|---|
| Auth | Bearer HF token (fine-grained) | Needs 'Make calls to Inference Providers' permission |
| Base URL | https://router.huggingface.co/v1 | OpenAI-compatible chat completions endpoint |
| Python SDK | huggingface_hub (InferenceClient) | pip install huggingface_hub; all tasks |
| JS/TS SDK | @huggingface/inference (InferenceClient) | npm install @huggingface/inference; TypeScript support |
| OpenAI compat | OpenAI SDK with base_url swap | Chat completions only; minimal change |
| Provider selection | provider="auto" (default) + :fastest/:cheapest/:preferred | Append suffix or pin model:provider |
| Models | 200+ open models, e.g. openai/gpt-oss-120b, DeepSeek-V3, FLUX | 19 partner providers |
Core endpoints and tasks
| Capability | How | Purpose |
|---|---|---|
| Chat completions | POST /v1/chat/completions | Text generation, OpenAI-compatible (router or clients) |
| Model listing | GET /v1/models | Models across providers with pricing, context, latency, throughput |
| Text-to-image | client.text_to_image(...) | Diffusion image generation (e.g. FLUX.1) via clients |
| Feature extraction | client.feature_extraction(...) | Embeddings for semantic search, RAG, recommendations |
| Text-to-video / speech | client text_to_video, speech tasks | Video generation and speech-to-text across capable providers |
| Function calling | tools[] (guide) | Tool use with the chat completion surface |
| Structured outputs | JSON schema (guide) | Schema-conforming JSON from LLMs |
| Responses API | Responses API (beta) | OpenAI Responses-style surface, in beta |
Credits, billing and rules
| Aspect | Detail | Notes |
|---|---|---|
| Free credits | $0.10 free, $2.00 PRO, $2.00/seat Team/Enterprise | Monthly; subject to change |
| Pay-as-you-go | Provider rates, no HF markup | Purchase credits after free tier |
| Billing modes | Routed by HF vs Custom Provider Key | Credits apply only to routed requests |
| Org billing | X-HF-Bill-To: org-name or resource-group-id | Centralize and attribute spend |
| Failover | provider="auto" reroutes if a provider is down | Built-in reliability |
| Chat-only compat | OpenAI-compatible endpoint = chat completions | Other tasks via clients |
| hf-inference scope | Mostly CPU / smaller models since July 2025 | Compute-time billing (time x hardware price) |
SDKs, snippets and developer fit
| Aspect | Detail | Notes |
|---|---|---|
| SDKs | huggingface_hub (Python), @huggingface/inference (JS/TS), OpenAI SDK | Plus raw requests/fetch |
| Python tiers | huggingface_hub, openai, or requests | High-level convenience to low-level control |
| Code snippets | View Code Snippets on any model page | Generated Python / TypeScript |
| Playground | huggingface.co/playground | Test models and providers before code |
| Token setup | export HF_TOKEN=...; hf auth login | Read token from env var |
| Free experimentation | Generous free tier + extra PRO/Team credits | Get started without paid setup |
| Org consolidation | Shared org credits + usage breakdown | Per-model/provider usage in settings |
Hugging Face API FAQ
How do I authenticate with the Hugging Face Inference Providers API?
Create a fine-grained Hugging Face token with the 'Make calls to Inference Providers' permission in your token settings, then send it as a bearer token, as export HF_TOKEN=.... The simplest path is the huggingface_hub InferenceClient in Python or @huggingface/inference in JS, which read the token automatically. Because the API is OpenAI-compatible at https://router.huggingface.co/v1, you can also use the OpenAI SDK by swapping its base URL and key.
Is the Hugging Face API OpenAI-compatible?
Yes, for chat completions. There is a drop-in OpenAI-compatible endpoint at https://router.huggingface.co/v1, so existing OpenAI chat code works by changing the base URL to the router and the key to your HF token. It handles provider selection on the server side, defaulting to :fastest. For non-chat tasks like text-to-image, embeddings or speech, you use the Hugging Face inference clients rather than the OpenAI-compatible endpoint.
What can the API do beyond chat completions?
Through the inference clients it covers text-to-image, such as FLUX.1, feature extraction for embeddings in search and RAG, text-to-video and speech-to-text, plus function calling, structured JSON outputs and a beta Responses API. GET /v1/models lists every available model across providers with per-provider pricing, context length, latency and throughput, so you can discover and compare options programmatically.
How do I control which provider serves my request?
By default provider='auto' selects the fastest available provider and fails over if one is unavailable. Append a policy suffix to the model id to change it: :cheapest for lowest output price or :preferred for your settings order. You can also pin a provider explicitly by appending its name, as in openai/gpt-oss-120b:sambanova. The official clients format the request for whichever provider is chosen, so your code stays the same.
How much does the API cost?
Hugging Face passes through the provider's rate with no markup, after small monthly credits, $0.10 free, $2 PRO or $2 a seat for Team and Enterprise. Past the free tier you purchase credits and pay as you go, and the built-in hf-inference provider bills by compute time, seconds times hardware price. Because per-token rates vary by model and provider, check GET /v1/models for live pricing, and use X-HF-Bill-To plus spend limits to control team costs.
Sources & verification
| Source | What was checked | Last checked |
|---|---|---|
| Hugging Face Official | Official product page | July 10, 2026 |
| Hugging Face | Inference Providers | July 10, 2026 |
| Hugging Face | Pricing and plans | July 10, 2026 |
| Hugging Face | Inference Providers First API Call | July 10, 2026 |
Every fact on this Hugging Face page is tied to a named source and a verification date. Freshness-sensitive figures trace to the sources above; verify against the vendor before relying on them.
Explore Hugging Face
Every page on Hugging Face in one place, you are on api.