Hugging Face says its Inference Providers service now uses OpenRouter to route supported language-model requests. Existing Hugging Face tokens and application code are supposed to keep working, but there is a consequential exception: provider keys configured for Hugging Face’s server-side language-model routing no longer work through that route. If your application depends on a provider contract, credits, or capacity attached to one of those keys, inspect that dependency before treating this as a routine backend change. Hugging Face announcement
The change was announced on November 16, 2026. It affects the route behind supported chat, vision-language and agent requests, while image, video and audio generation continue through Hugging Face’s existing provider infrastructure. An image sent to a vision-language chat model and an image produced by an image generator are different tasks here. Embeddings and other tasks also have separate provider integrations. Dedicated Inference Endpoints and models you run locally are separate products. Provider documentation
For an existing HF-billed chat application, the first job is to check its model, eligible providers, credit balance and actual bill. For a team using a custom provider key, the job is larger: identify the affected workloads and decide where their credentials, contracts and billing should live. For everyone, an unchanged API call does not establish an unchanged provider, price, privacy agreement or performance profile.
What Kingy tested, November 16: A signed-in Hugging Face widget initially asked for credits and returned no completion. A later widget call to
openai/gpt-oss-20b, with credits available, returnedREADYand a stop finish. It reported 74 input and 34 output tokens, including 64 cached input tokens, and $0.000003816 in cost; it did not return a provider field. Two direct OpenRouter Llama 3.1 8B calls, one default and one restricted to DeepInfra with fallback disabled, also returnedREADY; each reported DeepInfra, 17 input and two output tokens, and $0.00000042 in cost. The three successful responses reported $0.000004656 in total; we did not independently reconcile an invoice. We also checked Python and JavaScript request construction with mocked inference responses, and retrieved public Hub mapping data for one Python check. These tests do not establish HF API-token continuity, reliability, speed, failover or organization billing.
The new request path
For a supported language-model request, the documented path is your application to Hugging Face’s router, then OpenRouter’s provider selection, then an eligible model provider. Your application continues to use a Hugging Face token and the Hugging Face endpoint. Hugging Face describes the account and billing experience as remaining on its side. Announcement

A model is the system you request; a provider is the service running it. Several providers may offer the same model, with different prices, capacity, context limits and feature support. A router chooses among eligible providers under the selected policy. Changing the serving provider can matter even when the model identifier stays the same.
OpenRouter described the launch catalog as 160 models from 38 labs with Hugging Face Hub pages. In a separate catalog request, Kingy observed 164 entries. The figures describe different snapshots, not an inventory to hard-code: availability can change, and a catalog entry does not prove every provider offers every feature your application needs. OpenRouter announcement, Hugging Face catalog API
| Your current setup | First thing to check |
|---|---|
| Hugging Face-managed billing for chat | Model availability, eligible providers, balance, usage and actual cost. |
| A custom provider key configured in Hugging Face | Which language-model workloads relied on the key and its provider contract, credits or capacity. |
| Team or Enterprise billing | The bill-to organization, its provider settings and its pooled compute credits. |
| A pinned provider | Availability and support for your context length, tools and output format; pinning limits alternatives. |
| Image, video or audio generation | Review the existing task-specific integration; the language-model routing announcement does not move all generation tasks. |
| Direct OpenRouter integration | Treat its account, credentials, controls and billing as a separate integration. |
Routing policies and the cost of pinning
Hugging Face documents four choices for language-model routing. Use a model suffix for a pricing or throughput policy, or to name a provider. The native clients also offer a provider setting for automatic or named-provider selection. Check the current provider list and model availability before deploying. Routing and Providers
| Choice | Documented behavior | Practical trade-off |
|---|---|---|
| Default (no model suffix) | Balanced selection considers effective cost, speed and reliability. | You permit the selected provider to vary; balanced does not mean cheapest. |
:fastest |
Selects for output throughput. | Tokens per second is not the same measure as time to first token or total request time. |
:cheapest |
Selects based on price. | The lowest priced eligible choice may not satisfy your latency or feature requirements. |
:provider-name |
Restricts the request to a named provider. | Greater serving control, but that provider is not replaced by another during failover. |
For example, meta-llama/Llama-3.1-8B-Instruct:cheapest requests a pricing policy, while meta-llama/Llama-3.1-8B-Instruct:deepinfra restricts the provider. A provider can be excluded in settings. Hugging Face says an organization-billed request uses the organization’s provider settings, and a request pinned to a provider the organization has disabled returns an error. Membership alone does not make a request organization-billed; the billing target matters. Routing, Hub settings
Routing among providers can give an application more serving options, but it does not make every request recoverable. No eligible provider, a bad token, insufficient credits, an invalid request or an oversized context can still stop a call. We did not induce provider failures or verify failover through Hugging Face. In particular, do not assume a stream that has already emitted text can be restarted invisibly without duplicated output or repeated tool calls.
OpenRouter published its own earlier routing experiment covering a week, 24 million requests and 103 billion input tokens. It reported improvements in time to first token, throughput and capacity errors alongside a 6% increase in cost per request. That is useful evidence of a speed-versus-cost trade-off in its experiment, not a Kingy benchmark or a before-and-after test of this Hugging Face migration. OpenRouter routing study
The provider-key change deserves an inventory
Hugging Face’s announcement says provider keys configured for its server-side language-model route stop working through that route. It also describes account linking as future work. The announcement does not give a precise cutover hour, rollout cohort or grace period, so plan around the documented change rather than assuming a particular deadline. Hugging Face announcement
List each affected application and record the model ID, task, provider, HF account or organization, billing target and current key owner. Then find the dependencies that do not appear in source code: contracted pricing, provider-specific credits, approved regions, data terms, limits, and whether a provider’s capacity is required for an important workflow. A token that still authenticates an HF request is not proof that the old provider key is paying for it.
There are several paths, each with a separate integration decision:
- Use Hugging Face-managed inference billing. Check the model and provider settings, add or allocate HF compute credits as needed, and verify the usage under the correct account.
- Integrate directly with the provider. Review its API, keys, contract and operational controls. This may require code and observability changes.
- Use OpenRouter directly. OpenRouter still documents bring-your-own-key support for its own service. That is a separate host, account and billing relationship; it is not evidence that the provider key remains usable through the HF language-model route. OpenRouter BYOK
Direct OpenRouter BYOK can also fall back to shared capacity and spend OpenRouter credits unless configured to restrict that behavior. Check the provider and fallback settings for each workload. Do not assume an OpenRouter balance, privacy setting or provider configuration transfers to Hugging Face, or that advanced direct OpenRouter controls are available through HF.
Check the catalog before changing code
Hugging Face documents an OpenAI-compatible model catalog at GET https://router.huggingface.co/v1/models and a model-specific form. Its metadata can include provider prices, context limits, tool and structured-output support, and performance fields. These fields are optional and can change. Treat catalog metadata as a discovery aid, then exercise the exact request and inspect its response. Hub API
At minimum, verify the exact model identifier and the eligible providers for it. Then test your largest realistic prompt, expected output size, tool calls and schema requirements. If you use vision, send a representative image using the documented chat request format. A model being listed does not prove that each provider implements the same parameters, context size, tool behavior or structured-output guarantee.
Keep the model ID and routing policy in configuration rather than embedding them throughout an application. Record a known-good version and a rollback target. If you pin a provider to satisfy a contractual requirement, make the resulting availability trade-off explicit to the application owner.
Python: native Hugging Face client
The following example uses the Hugging Face token in a server-side environment variable. Create a token with the required Inference Providers permission, check that the selected model is currently served, and make sure the account has sufficient credits before a real call. Do not put the token in a browser bundle or commit it to source control. Inference Providers documentation
python -m pip install huggingface_hub
export HF_TOKEN='your-hugging-face-token'
import os
from huggingface_hub import InferenceClient
client = InferenceClient(
token=os.environ["HF_TOKEN"],
provider="auto",
)
response = client.chat.completions.create(
model="meta-llama/Llama-3.1-8B-Instruct",
messages=[{"role": "user", "content": "Reply with one short sentence."}],
max_tokens=64,
)
print(response.choices[0].message.content)
The native Python client accepts provider="deepinfra" on the InferenceClient constructor. Do not pass provider to chat_completion() in the installed version we checked: that method rejected the argument. The current upstream client source also places provider selection on the constructor. Explicit constructor selection and a model suffix did not construct the same route in our installed version, as explained below. Python client source
Kingy checked request construction and fixture-response parsing locally with Python 3.14.0 and huggingface_hub 2.4.0. The mocked requests used the HF router URL and included default, :cheapest and :deepinfra model IDs; they did not reach a live model. In an additional check, the same Python SDK retrieved public Hub provider mapping data live; with inference transport mocked, provider="deepinfra" and an HF-shaped fixture token constructed a provider-specific HF URL and the provider’s mapped model ID. With a dummy provider-shaped key, it constructed a direct DeepInfra API URL instead. Neither check used valid credentials or demonstrated successful authentication or inference. The server-side HF key change therefore should not be read as proof that SDKs cannot construct direct provider calls. The Hugging Face JavaScript SDK documentation also describes provider credentials for direct calls. These version numbers describe our check, not minimum supported versions or a promise that older wrappers behave identically.
JavaScript: native Hugging Face client
Install @huggingface/inference and keep your token in a server-side environment variable:
npm install @huggingface/inference
import { InferenceClient } from "@huggingface/inference";
const client = new InferenceClient(process.env.HF_TOKEN);
const response = await client.chatCompletion({
model: "meta-llama/Llama-3.1-8B-Instruct",
provider: "auto",
messages: [{ role: "user", content: "Reply with one short sentence." }],
max_tokens: 64,
});
console.log(response.choices[0].message.content);
With Node 24.16.0 and @huggingface/inference 4.13.33, Kingy used mocked fetch to check auto, explicit DeepInfra, a cheapest suffix and a fixture organization billing header. With an HF-shaped token, the explicit-provider check constructed the general /v1/chat/completions endpoint with :deepinfra on the model ID. No live inference or actual organization charge was tested.
The Python constructor check above instead constructed a provider-specific HF path and a mapped provider model ID. Those observations apply to the tested package versions and request shapes; they are a reason to inspect the actual destination and model ID after an SDK upgrade or wrapper change. Pin the dependency, verify that secrets are sent only to the intended host, and test your own billing and provider controls before rollout.
Python: an OpenAI-compatible client pointed at Hugging Face
If your application already uses the OpenAI Python client for Chat Completions, the documented HF base URL is https://router.huggingface.co/v1. Supply an HF token, not a direct OpenRouter key, for this route. Hugging Face Chat Completion
python -m pip install openai
import os
from openai import OpenAI
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.environ["HF_TOKEN"],
)
response = client.chat.completions.create(
model="meta-llama/Llama-3.1-8B-Instruct:cheapest",
messages=[{"role": "user", "content": "Reply with one short sentence."}],
max_tokens=64,
)
print(response.choices[0].message.content)
We checked the request shape and fixture parsing with openai 3.51.0 using mocked HTTP, not live HF inference. OpenAI-compatible syntax gives you a familiar interface; it does not mean every model and provider implements every OpenAI feature or parameter. Test the behavior your application relies on, including errors and streamed responses.
Hugging Face also documents a Responses API in beta, and its announcement describes Anthropic Messages compatibility for chat models. We did not test either protocol. Check the current endpoint documentation and the specific model’s capabilities before migrating stateful flows, hosted tools or message formats. Do not infer full feature parity from a compatible request shape.
Organization billing is a request setting
Hugging Face documents organization billing using X-HF-Bill-To for HTTP, bill_to in the native Python client and billTo in JavaScript. For an OpenAI-compatible Python client, the organization header can be supplied as a default header:
client = OpenAI(
base_url="https://router.huggingface.co/v1",
api_key=os.environ["HF_TOKEN"],
default_headers={"X-HF-Bill-To": "my-org"},
)
The same native Python constructor can use bill_to="my-org". Replace the example with your real organization, confirm token permissions and membership, and verify the resulting usage in the organization’s billing view. Our mocked requests included a fixture bill-to header; we did not test a real organization or prove its charges. Enterprise resource groups have additional documented requirements. Organization billing
This detail affects provider selection as well as who pays. For organization-billed requests, the organization’s provider settings take precedence over a member’s personal settings. A personal test can therefore succeed while the production organization request is blocked, or route under a different allowed-provider policy. Test using the same billing target and settings as production.
What still costs money
As of the documentation checked on November 16, Hugging Face lists no monthly included compute credits for a Free account, $2 per month for PRO, and $2 per seat per month for Team and Enterprise organizations. Organization credits are pooled. These are shared compute credits, not a separate unlimited inference allowance, and other eligible compute use can consume them. Hugging Face says provider rates are passed through without markup; additional usage requires available credits. Pricing and Billing
That credit distinction mattered in our widget test: the initial attempt asked for credits and produced no completion. A later attempt with credits available succeeded. We did not complete a top-up purchase or independently reconcile an invoice. This does not establish what another account will be charged or whether it has credits available. Check the balance and current billing terms before sending production traffic.
To estimate spend, separate input and output tokens. For a made-up tariff of $0.50 per million input tokens and $2 per million output tokens, a request with 10,000 input tokens and 1,000 output tokens costs:
(10,000 / 1,000,000 × $0.50) + (1,000 / 1,000,000 × $2.00)
= $0.005 + $0.002 = $0.007 per request
At one million identical requests, that example comes to $7,000 before applicable ancillary charges or taxes. It is arithmetic, not a quote for Llama or any other model. Cached tokens, images, reasoning tokens and tools may have their own applicable rates. Multiply by your observed token distributions, not only an average prompt, and leave room for output variance and retries.
Check units before comparing catalogs: HF’s documented provider metadata uses dollars per million tokens. Direct OpenRouter model prices may be expressed per token. A per-token price needs to be multiplied by one million before comparing it with a per-million figure. Our two direct OpenRouter calls each reported $0.00000042, but their token counts and costs say nothing about a larger workload or HF charges.
Direct OpenRouter has its own pricing. Its current pricing page lists a 5.5% credit-purchase fee for Standard and 8% for Business. It also lists a monthly $25,000 list-price inference allowance for Standard and Business BYOK before a 5% platform fee; the provider still bills its inference charges. These direct-service terms should not be added to an HF invoice by assumption. Enterprise terms differ. OpenRouter pricing
For teams, compare projected use with the remaining pooled credits, not the original seat allowance. Hugging Face documents account-level usage views and an Enterprise usage API; it says API data may lag by up to two hours and individual rows can be rounded to cents. Allow for that lag when reconciling a deployment and invoice. Usage breakdown
Streaming, retries and prompt caching
A successful HTTP connection is not the same thing as a complete answer. Consume a stream until its documented completion condition, handle error events and interrupted connections, and distinguish an incomplete answer from a finished one. OpenRouter’s direct-service documentation describes errors that can occur after an HTTP 200 response. We have not verified exactly how those errors are translated through Hugging Face, so log sanitized status and error details from your own integration rather than hard-coding assumptions from a different endpoint. OpenRouter errors
Use bounded retries with backoff for transient failures where retrying is appropriate. Do not repeatedly retry an invalid request, missing permission or exhausted balance as if more attempts will fix it. For tool-using agents, give side effects an idempotency strategy and track whether a tool has already run before replaying a conversation. Surface an incomplete stream to the caller when you cannot safely resume it.
Hugging Face says prompt caching is automatic where supported, and cached input can appear in usage.prompt_tokens_details.cached_tokens. Its documentation describes a stable UUID in X-HF-Session-Id for keeping requests in a conversation with the same provider; invalid UUID values are ignored. Prompt caching
Use a stable, valid session UUID when provider affinity is useful, and inspect actual usage to see whether caching occurred. It is not a guarantee of a cache hit, fixed discount, cache lifetime or server-side conversation state. Your application still needs to manage the messages it sends. If provider availability changes, test what your user sees and whether the request remains eligible under your chosen policy.
Data handling follows the whole request
Hugging Face says it does not store request bodies or responses when routing requests, does not store user data for training purposes, and keeps diagnostic logs for up to 30 days without user data or tokens. It also tells users to review the policies of the external provider. These are vendor statements, not an independent audit of each model provider. Hugging Face security
OpenRouter’s general data policy describes opt-in logging and exceptions involving safety or legal requirements. It also distinguishes upstream provider practices. That general document does not establish every default, contract term, region or retention control for the Hugging Face integration. OpenRouter data collection
Before sending sensitive material, map every party in the request path and obtain the applicable terms for your actual account and selected providers. Ask about region, retention, training use, subprocessors and contractual commitments; verify which controls can be enforced on the HF route. Redact application logs and avoid treating a model-provider label as a complete data-processing agreement. OpenRouter’s separately configured Storage Buckets Broadcast beta is a distinct feature; its announcement does not establish that HF routing automatically archives your prompts. OpenRouter announcement
A practical rollout
Start with a small representative set of requests rather than moving every workload at once. Keep the existing configuration available for rollback where that route remains valid, and assign an owner for cost, security and application behavior.
- Inventory. Record each model ID, HF token owner, task, provider restriction, custom key dependency, organization billing target and required capabilities.
- Inspect settings. Confirm the organization’s permitted providers, current credit balance, spending controls and the account that will receive usage. Resolve any contractual or data-handling requirements.
- Exercise requests. Test normal and maximum-size inputs, tools, structured output, vision where relevant, and both streamed and non-streamed responses. Capture sanitized request IDs and usage.
- Exercise failures. In a safe test environment, check bad credentials, insufficient credits, disallowed or unavailable providers and interrupted streams. Verify your own error handling; do not assume all errors trigger failover.
- Measure your workload. Compare quality, time to first token, total response time, error rate, cached-token usage and cost using a representative sample. Separate model changes from routing changes. Two tiny successful calls are not a performance study.
- Roll out gradually. Route a small share of eligible traffic, check the correct billing account and user-visible outcomes, then expand only when the results meet your own requirements. Keep a tested rollback and revisit estimates after usage data catches up.
- Tested
- Two HF widget attempts: one blocked and one successful. Two successful direct OpenRouter calls; Python and JavaScript inference transport mocked.
- Runner
- Python 3.14.0, huggingface_hub 2.4.0, openai 3.51.0; Node 24.16.0, @huggingface/inference 4.13.33.
- Cloud side
- HF gpt-oss-20b widget returned READY with no provider field; direct OpenRouter Llama 3.1 8B default and pinned calls returned READY.
- Settings
- HF widget used signed-in session; direct pinned call restricted DeepInfra and disabled fallback. No HF API-token inference.
- Cost
- Responses reported $0.000004656 total: $0.000003816 HF widget and $0.00000042 per direct call. Invoice not independently reconciled.
- SDK routes
- Python explicit provider constructed an HF provider path or direct provider URL by fixture key shape; JS HF fixture used the general router path. Inference was mocked.
- Dates
- run 2026-11-16 · checked 2026-11-16
Limits
The announcement and documentation describe intended behavior. Our first HF widget attempt did not produce a completion; a later signed-in widget call succeeded. We did not run inference using an HF API token, so the widget result does not establish existing token or application-code continuity. The Python and JavaScript inference checks used mocked transport and fixture responses; the explicit Python provider check also retrieved public provider mapping data live. The two other successful live calls went directly to OpenRouter, not through Hugging Face; one default selection happened to report DeepInfra, and one explicitly restricted the provider. They do not establish failover, HF provider pin enforcement, HF organization billing, or comparative performance.
We did not verify the HF integration’s failed-attempt charges, exact error translation, advanced OpenRouter control availability, regional routing or retention settings. Check the current documentation and your account terms, then run a bounded test with the exact model, credentials and billing target you intend to deploy.
Follow-up
Kingy has planned four weekly reviews for November 23, November 30, December 7 and December 14, 2026, at 10 a.m. Vancouver time. The review schedule ends after the fourth check.
Sources
- Hugging Face: OpenRouter partnership announcement and official announcement text.
- Hugging Face documentation: routing, providers, pricing and billing, model catalog, Chat Completion, Responses beta, prompt caching and security.
- OpenRouter: partnership announcement, routing experiment, pricing, BYOK, data collection and errors.
