> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nativeport.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nativeport.ai/_mcp/server.

# Hugging Face

Fronts [Hugging Face](https://huggingface.co/docs/inference-providers)'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.

| Endpoint                                        | Notes                                                                                   |
| ----------------------------------------------- | --------------------------------------------------------------------------------------- |
| `POST v1/chat/completions`                      | The 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

#### Chat Completions (pinned default provider)

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

#### Chat Completions (explicit provider pin)

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

#### List the catalog

```bash
curl "$GATEWAY/huggingface/v1/models" \
  -H "Authorization: Bearer $TOKEN"
```

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](https://huggingface.co/docs/inference-providers).