PARAS MADAN
All writing

Latest in AI

Hugging Face OpenRouter Migration: Provider Keys, Billing and Fallbacks

The API can keep working while the billing and provider-selection assumptions underneath it change.

Hugging Face moved language-model requests in Inference Providers to OpenRouter on November 16. Existing application code can stay the same, but custom provider API keys no longer work for those models. Requests are now billed to your Hugging Face account or organization.

That is the migration detail I would check before comparing speed claims. An application returning a good answer tells you very little about whether the right account paid for it or whether the request went to an approved provider.

Which requests changed

The Hugging Face announcement separates language models from other generation tasks. Image, video and audio generation continue through Hugging Face's existing provider path rather than OpenRouter. Custom keys for image and video providers still work.

Start by listing the tasks your application calls. A product with a chat assistant and an image generator may now have two different billing assumptions, even when both features use the same Hugging Face integration. Do not replace every credential because one part of the application changed.

Connecting an existing OpenRouter account to Hugging Face is listed as future work. Do not assume an OpenRouter balance already pays for requests sent through the Hugging Face endpoint.

Check who receives the bill

The current pricing documentation says Hugging Face passes through provider prices without a markup. PRO includes $2 in monthly compute credits; Team and Enterprise organizations receive $2 per seat. These credits cover several Hugging Face compute services, so they are not an inference-only allowance. Free accounts need purchased credits.

Organization billing must be selected explicitly. For HTTP requests, the documented header is X-HF-Bill-To: my-org-name. Requests billed to an organization use its provider settings rather than the user's personal settings; explicitly choosing a provider disabled by that organization returns an error.

Suppose a developer tests with personal billing and then deploys under company billing. The model name can be unchanged while the permitted provider set changes. When a request fails only in production, compare the billed organization and its settings before changing the prompt or model.

Decide whether fallback is allowed

The routing guide documents four useful choices:

Model suffixWhat you are choosing
No suffixA balance of price, speed and reliability
:fastestHighest throughput
:cheapestLowest price
:novitaNovita only, when it serves the model

Default routing can retry another provider when the first one fails. A pinned provider is never replaced. Disabled providers are excluded, and attempting to pin one produces an error.

Provider pinning is a reliability trade-off. It makes the destination explicit, but gives up cross-provider recovery. For an internal prototype, automatic fallback may be useful. For a workflow with an approved-provider list, establish that list first and test recovery within it. A successful fallback to an unacceptable destination would still be a failed deployment.

Preserve the conversation's cache identity

Hugging Face's prompt-caching guide documents X-HF-Session-Id for raw HTTP clients. Send a stable UUID for each conversation; other values are ignored. This helps keep turns on the same provider, where the cached prefix lives. The Hugging Face Python and JavaScript clients handle caching automatically.

Keep stable instructions and tool definitions before changing user input. A fresh timestamp at the beginning of every prompt can defeat prefix reuse even if the session identifier is correct. Check usage.prompt_tokens_details.cached_tokens rather than treating a successful response as evidence of a cache hit.

For a document assistant, use one UUID throughout a conversation and a different one for a new conversation. Recreating the UUID on every turn defeats the purpose of stable session identity. This is a configuration example, not a claim that every request will receive discounted cached tokens.

Test the migration with synthetic data first

Before sending production material, run a small acceptance check using a made-up support document. Verify the billed account, provider, response format and token usage. If the application depends on tool calls or structured output, test those exact paths rather than stopping after a plain-text greeting succeeds.

Then compare a normal request, a second turn with the same session ID and a deliberately restricted provider configuration. Record what should succeed and what should fail before running the checks. Keep credentials out of logs, and do not broaden provider access merely to make a test pass.

This guide is based on the published announcement and documentation, not a live integration test. The useful measure of this migration is whether your application keeps its billing, routing and output requirements intact. Keeping the same API shape is only one part of that.

I’m Paras. I work at the intersection of AI, engineering and distribution.

I help developer-tool teams turn migrations and technical changes into guides their users can actually follow.

Book a 30-minute call