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, :cheapest or 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:

  1. Search your code and environment for provider-specific keys used with router.huggingface.co.
  2. Switch those calls to your HF token.
  3. If you needed a specific provider, pin it with a suffix instead.
  4. 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.