Hugging Face

Hugging Face Inference Providers + Hub API

Call thousands of open models through one OpenAI-compatible router, pick providers, embed text, make images and search the Hub.

AI & machine learningGuided#llm#open-models#openai-compatible#embeddings#text-to-image#hub

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Hugging Face Inference Providers gives you one API and one token for thousands of open models served by partner providers (Together AI, Fireworks, Novita, DeepInfra, Cerebras, fal, Replicate and others) and by Hugging Face's own HF Inference. Chat models are reachable through an OpenAI-compatible endpoint, so existing OpenAI client code works by changing the base URL. The Hub API lets you search and inspect models and datasets, including which providers serve a model. This guided collection covers both.

Get a token

  1. Sign in or sign up at huggingface.co.
  2. Open Settings > Access Tokens > New token (this link preselects the right options).
  3. Choose Fine-grained, give it a name, and tick Make calls to Inference Providers. Add read access to repos if you also want private models or datasets in the Hub calls.
  4. Create the token (it starts with hf_) and paste it into the hfToken variable, which is marked secret.
  5. Inference is pay-as-you-go: free accounts must buy credits first; PRO and Team/Enterprise plans include monthly compute credits. See pricing.

Authentication and base URLs

Every request sends Authorization: Bearer <hfToken> (set at collection level).

HostUse
https://router.huggingface.co/v1OpenAI-compatible chat completions and model list (routerUrl).
https://router.huggingface.co/hf-inferenceHF Inference tasks such as embeddings and text-to-image (hfInferenceUrl).
https://huggingface.co/apiHub API: account, models, datasets (hubUrl).

Choosing a provider

Put the model's Hub ID in model. With no suffix the router picks a provider by price, speed and reliability, and fails over automatically. Add a suffix to change that: :fastest (highest throughput), :cheapest (lowest price) or a provider name such as :novita or :together to pin one provider (no failover). You can switch providers off in your Inference Providers settings. Team and Enterprise users can bill an organization by adding the X-HF-Bill-To: <org> header.

Using this collection

  1. Fill hfToken and run 1. Start here to check the token and see which chat models are live.
  2. Folder 2 sends chat completions (plain, streaming, routing policies, structured output). Change chatModel to any model from the list.
  3. Folder 3 runs embeddings and text-to-image on HF Inference.
  4. Folder 4 searches the Hub; Search models fills modelId for the info request.

Limits and pricing

You pay each provider's own rate with no Hugging Face markup; usage and spend are shown in your billing settings. Hub API calls are rate-limited per window: responses carry RateLimit and RateLimit-Policy headers. See rate limits.

Common errors

StatusMeaningWhat to do
400Invalid body, or a parameter the chosen provider does not supportRemove the parameter or pick another provider.
401Token missing or invalidCheck hfToken.
403Token lacks the Inference Providers permission, or a gated repo you have not acceptedEdit the token permissions; accept the model's terms on its page.
404Model not found or not served by any (or the pinned) providerCheck the ID; use Get model providers.
429Rate limitedBack off and retry; see the RateLimit headers.
Billing errorNo credits leftBuy credits in billing settings.

Docs: Inference Providers, routing, chat completion, Hub API for providers, Hub API reference.

Endpoints 16

1. Start here

  • GETWho am I (check the token){{hubUrl}}/whoami-v2Returns the account the token belongs to and what the token may do. When: first, to confirm hfToken is valid and has the right permissions. What comes back:…
  • GETList chat models (router){{routerUrl}}/modelsLists every chat model currently served through the OpenAI-compatible router, with per-provider details. When: choosing a chatModel, or comparing providers.…
  • GETGet one chat model (router){{routerUrl}}/models/{{chatModel}}Same data as the list, for a single model: {{chatModel}}. When: to check which providers serve your model, their prices and whether they support tools or…

2. Chat completions (OpenAI-compatible)

  • POSTCreate a chat completion{{routerUrl}}/chat/completionsSends a conversation and returns the model's reply. The router picks the provider (default routing balances price, speed and reliability) and fails over if…
  • POSTStream a chat completion{{routerUrl}}/chat/completionsSame request with "stream": true: tokens arrive as Server-Sent Events while they are generated. What comes back: text/event-stream. Each data: line is a JSON…
  • POSTRoute to the fastest provider (:fastest){{routerUrl}}/chat/completionsAppends :fastest to the model ID so the router sends the request to the provider with the highest measured throughput (tokens per second). When:…
  • POSTRoute to the cheapest provider (:cheapest){{routerUrl}}/chat/completionsAppends :cheapest, so the router picks the lowest-priced provider for the model. When: offline or bulk work where speed is less important than cost.
  • POSTPin one provider (:provider){{routerUrl}}/chat/completionsAppends a provider name (the provider variable, novita by default) so only that provider is used. There is no failover: if it does not serve the model, is…
  • POSTStructured output (JSON schema){{routerUrl}}/chat/completionsAsks the model to answer with JSON that matches a schema, using response_format with type: json_schema. When: extracting fields into your own data structures.…

3. Embeddings and images (HF Inference)

  • POSTCreate embeddings (feature extraction){{hfInferenceUrl}}/models/{{embeddingModel}}/pipeline/feature-extractionTurns text into vectors for semantic search, RAG and clustering. Uses {{embeddingModel}} (BAAI/bge-small-en-v1.5, served live on HF Inference). What comes…
  • POSTGenerate an image (text-to-image){{hfInferenceUrl}}/models/{{imageModel}}Creates an image from a prompt with {{imageModel}} (stabilityai/stable-diffusion-3-medium-diffusers, live on HF Inference). What comes back: the image as raw…

4. Hub API: models and datasets

  • GETSearch models{{hubUrl}}/modelsSearches the model catalogue. What comes back: an array of models (id, pipeline_tag, downloads, likes, tags, library_name, createdAt). The next page is in the…
  • GETGet model info{{hubUrl}}/models/{{modelId}}Returns one model repository's metadata: {{modelId}}. What comes back: id, author, sha, lastModified, private, gated, pipeline_tag, library_name, tags,…
  • GETGet model providers (inference mapping){{hubUrl}}/models/{{modelId}}Asks the model info endpoint only for which Inference Providers serve the model, using expand[]=inferenceProviderMapping (add expand[]=inference for the warm…
  • GETSearch datasets{{hubUrl}}/datasetsSearches the dataset catalogue. Accepts the same search, author, sort, direction, limit and full parameters as model search, plus tag filters such as…
  • GETGet dataset info{{hubUrl}}/datasets/{{datasetId}}Returns one dataset repository's metadata: {{datasetId}}. What comes back: id, author, sha, lastModified, private, gated, tags, description, downloads, likes,…

API details

Base URL
https://router.huggingface.co/v1
https://router.huggingface.co/hf-inference
https://huggingface.co/api
Authentication
A bearer token in the Authorization header
Operations
16 operations on 16 pathsGET 8POST 8
Main resources
1. Start here 32. Chat completions (OpenAI-compatible) 63. Embeddings and images (HF Inference) 24. Hub API: models and datasets 5
Description format
Swastik Codes guided collection, API version checked against the docs on 2026-11-17

How to test the Hugging Face Inference Providers + Hub API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Hugging Face Inference Providers + Hub API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses A bearer token in the Authorization header. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Who am I (check the token)” (GET {{hubUrl}}/whoami-v2), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Hugging Face Inference Providers + Hub API?

Call thousands of open models through one OpenAI-compatible router, pick providers, embed text, make images and search the Hub. It is listed under AI & machine learning and has 16 endpoints.

Who publishes the Hugging Face Inference Providers + Hub API?

It is listed from Hugging Face's public API description (an OpenAPI document), not published by Hugging Face on Swastik Codes. Anyone who controls huggingface.co can claim the profile by adding a DNS TXT record.

What is the base URL of the Hugging Face Inference Providers + Hub API?

Its description lists 3 base URLs: https://router.huggingface.co/v1, https://router.huggingface.co/hf-inference, https://huggingface.co/api. The first is the usual one; the others are typically sandbox or regional servers.

How do I authenticate with the Hugging Face Inference Providers + Hub API?

With A bearer token in the Authorization header.

How many endpoints does the Hugging Face Inference Providers + Hub API have?

16 operations on 16 paths (8 GET, 8 POST). The largest groups are 1. Start here, 2. Chat completions (OpenAI-compatible), 3. Embeddings and images (HF Inference), 4. Hub API: models and datasets.

Is forking the Hugging Face Inference Providers + Hub API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.