If you call open-weight models through Hugging Face Inference Providers, something changed under the hood this week. On 16 November 2026 Hugging Face announced that requests to language models now go through OpenRouter’s router instead of Hugging Face’s own. Each call is sent to the provider with the best mix of price, speed and reliability, and if that provider fails, the request is retried on another one.
Your code keeps working, but there are new options worth using and one breaking change. This guide shows how to call models from Python, choose a routing policy with a model-ID suffix, keep prompt caches warm, and check whether the breaking change affects you.
Sources: the Hugging Face blog post Hugging Face and OpenRouter join forces, the Routing and Providers docs and the Hub changelog.
What changed
- Routing: language-model requests are routed by OpenRouter across the providers that serve the model, based on live measurements.
- Failover: if a provider fails, the request is retried on another provider inside the same call. Before, you got the first provider’s error.
- Policy suffixes: add
:fastest,:cheapestor a provider name to the model ID. - Cache-aware routing: a conversation stays on the provider that holds its prompt cache.
- APIs: the router supports OpenAI’s Chat Completions and Responses APIs and Anthropic’s Messages API for every chat model.
- Pricing: unchanged. You pay the provider’s price on your Hugging Face bill, with no Hugging Face markup.
- Breaking: custom provider API keys no longer work for language models.
Image, video and audio generation are not affected. They still go directly through Inference Providers as before.
Step 1: Get a token and install a client
Create a Hugging Face access token with permission to call Inference Providers, then:
pip install -U openai
export HF_TOKEN="hf_..."
The router speaks the OpenAI API, so the standard openai client works.
Step 2: Your first call
import os
from openai import OpenAI
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.environ["HF_TOKEN"],
)
completion = client.chat.completions.create(
model="deepseek-ai/DeepSeek-V4.1-Flash",
messages=[
{"role": "user", "content": "Explain gradient clipping in three sentences."}
],
)
print(completion.choices[0].message.content)
With no suffix you get default routing. According to the docs, it compares each provider’s effective price (including its real cache-hit rate and the model’s usual input/output mix), its speed (throughput and time to first token) and its reliability (failures, malformed tool calls, capacity rejections). These measurements update in real time.
Step 3: Pick a routing policy with a suffix
Append a suffix to the model ID. Because it is part of the model name, it works even in tools that only let you type a model string.
| Model ID | Routes to |
|---|---|
deepseek-ai/DeepSeek-V4.1-Flash |
Default: best mix of price, speed and reliability |
deepseek-ai/DeepSeek-V4.1-Flash:fastest |
Highest throughput |
deepseek-ai/DeepSeek-V4.1-Flash:cheapest |
Lowest price |
deepseek-ai/DeepSeek-V4.1-Flash:novita |
Only Novita, or an error if it does not serve the model |
A simple pattern is to choose the policy per workload:
MODEL = "deepseek-ai/DeepSeek-V4.1-Flash"
def ask(prompt: str, policy: str | None = None) -> str:
model = f"{MODEL}:{policy}" if policy else MODEL
resp = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": prompt}],
)
return resp.choices[0].message.content
# Interactive chat: latency matters
print(ask("Suggest a name for a churn model.", policy="fastest"))
# Overnight batch labelling: cost matters
labels = [ask(f"Label the sentiment: {t}", policy="cheapest") for t in ["great!", "awful"]]
When to pin a provider
Pinning (:novita and so on) is useful when you need a specific provider for compliance, a particular quantisation or reproducible benchmarks. Note that a pinned provider is never replaced on failure, so you give up automatic failover. Each model page lists which providers can serve it.
Step 4: Keep prompt caches warm
Routing is cache-aware, which matters for long system prompts and multi-turn chats. To make it explicit, send a stable UUID per conversation in the X-HF-Session-Id header:
import uuid
session_id = str(uuid.uuid4()) # one per conversation, reused every turn
history = [{"role": "system", "content": open("system_prompt.txt").read()}]
def chat_turn(user_text: str) -> str:
history.append({"role": "user", "content": user_text})
resp = client.chat.completions.create(
model="deepseek-ai/DeepSeek-V4.1-Flash",
messages=history,
extra_headers={"X-HF-Session-Id": session_id},
)
answer = resp.choices[0].message.content
history.append({"role": "assistant", "content": answer})
return answer
Keeping the conversation on one provider means its cached prefix can be reused, which can lower cost and time to first token. See the Inference Providers prompt caching guide for details.
Step 5: Use it from coding agents
Because the router supports the OpenAI Chat Completions, OpenAI Responses and Anthropic Messages APIs, you can point coding agents at open-weight models with your HF token. The blog lists setup guides for Claude Code, Codex, OpenCode, Pi and Hermes Agent. The model-ID suffix trick is especially handy here, since many agents only expose a model-name field.
Control where requests go
- Turn providers off: in your Inference Providers settings, disable any provider you do not want. The router never sends your requests there, and pinning a disabled provider returns an error.
- Organisations: requests billed to an organisation follow the organisation’s settings, not yours.
- Model pages: a new Providers tab shows each provider’s input and output price, speed and uptime over the last 24 hours, and a Metrics tab shows the best of each.
- Usage: your usage overview now breaks spend down by provider.
The breaking change: custom provider keys
Previously you could pass your own API key for a provider and be billed by that provider directly. For language models, that no longer works: requests go through OpenRouter and are billed to your Hugging Face account or organisation.
What to do:
- Search your code and environment for provider-specific keys used with
router.huggingface.co. - Switch those calls to your HF token.
- If you needed a specific provider, pin it with a suffix instead.
- Custom keys for image and video providers keep working, so leave those alone.
Cost notes
Hugging Face says pricing does not change and there is no markup. PRO users get $2 of monthly credits, and Team and Enterprise organisations get $2 per seat. For cost-sensitive jobs, :cheapest is the obvious lever, but measure quality too: the cheapest provider may serve a different quantisation or have lower limits.
Takeaway
Hugging Face Inference Providers now route language models through OpenRouter, giving you automatic failover and simple :fastest and :cheapest policies without code changes. Add a session header for long chats, pin providers only when you must, and replace any custom provider keys for language models with your HF token.
