Tools

Hugging Face

The Inference Providers router — one chat-completions endpoint, provider-pinned pricing

View as Markdown

Fronts Hugging Face’s Inference Providers router. It is the leanest of the model-inference routes here: the admitted surface is stateless chat completion only, and — like the OpenAI, Anthropic and Grok routes — it’s policed, not a transparent pass-through.

GET  /huggingface/v1/models[/<owner>/<repo>]   → answered locally by the gateway
POST /huggingface/v1/chat/completions          → https://router.huggingface.co/v1/chat/completions

This route ships behind a kill switch that defaults to off, plus a per-account pilot allowlist — the same current-availability caveat as the other model-inference routes. A request can 404 here even with a funded, valid key until this route is enabled for your deployment.

Endpoints

Exactly two forms are admitted; anything else under /huggingface is refused with the gateway’s own 404 and never reaches the router.

EndpointNotes
POST v1/chat/completionsThe only admitted POST — no files, batches, or fine-tuning surface exists here at all
GET v1/models, GET v1/models/{owner}/{repo}Answered locally, in the same shape as the live router’s own model-list response

The provider pin

Hugging Face’s router serves each model through several competing backing providers whose prices differ, and nothing in a routed response identifies which one served it. So the gateway’s catalog pins every admitted model to a specific (model, provider) pair with its own verified rate:

  • A bare model id (e.g. openai/gpt-oss-120b) resolves to its pinned default provider.
  • An explicit model:provider suffix (e.g. openai/gpt-oss-120b:together) is honored only if that exact pairing is cataloged.
  • The router’s own :fastest, :cheapest, and :preferred routing-policy suffixes are rejected — they would make the price paid unpredictable, since nothing confirms which provider actually served the request.

Request policy

  • Overwritten unconditionally: the Authorization: Bearer header, replaced with the gateway’s own Hugging Face token.
  • Always removed: the X-HF-Bill-To header — it’s a client-suppliable org-billing redirect header with our token attached, a channel no other upstream on this gateway has.
  • Function-only: each tools[] entry must have type: "function", validated structurally; any other type is rejected.
  • No forced per-tenant identity field — Hugging Face documents no user/attribution field on chat completions, so this route (uniquely among the four) doesn’t force one.

Billing

Metered per token from the response’s prompt_tokens/completion_tokens, at the pinned (model, provider) pair’s rate — a pass-through of the provider’s own list price, no Hugging Face markup. An account can register its own Hugging Face token; while that’s active, calls bill to that token directly (bringing along that account’s own Hugging Face credits) instead of metering through the gateway balance.

Examples

$curl -X POST "$GATEWAY/huggingface/v1/chat/completions" \
>  -H "Authorization: Bearer $TOKEN" \
>  -H "Content-Type: application/json" \
>  -d '{
>    "model": "openai/gpt-oss-120b",
>    "messages": [{"role": "user", "content": "Summarize this page in one sentence."}]
>  }'

Responses arrive as the router’s JSON, untouched once a request clears the checks above. Field-level request and response detail lives in Hugging Face’s documentation.