

Hugging Face's integration with OpenRouter—expanded with an official November 19 developer walkthrough—replaces Hugging Face's custom in-house router for language models with OpenRouter's live multi-provider routing layer across more than 600 models and 80+ providers.
For engineers running open-weight models in production or powering autonomous coding agents, every chat and reasoning call to Hugging Face Inference Providers now routes dynamically based on real-time price, speed, and reliability under your existing HF_TOKEN, with automatic in-call retries when an upstream provider degrades.
API Surface, Suffix Overrides & Coding-Agent Drop-Ins
The unified router exposes OpenAI Chat Completions, OpenAI Responses, and Anthropic Messages endpoints on router.huggingface.co, keeping SDK and harness configurations portable without per-vendor glue code. Hugging Face ships direct setup instructions for Claude Code, Codex, OpenCode, Pi, and Hermes Agent—and OpenRouter reports its updated routing engine cuts capacity errors by 46%, speeds TTFT by 16.9%, and boosts throughput by 16.3%.
# Override default balanced routing using model ID suffixes:
zai-org/GLM-5.3 # Default: live price + speed + reliability mix
zai-org/GLM-5.3:fastest # Optimize for highest tok/s throughput
zai-org/GLM-5.3:cheapest # Optimize for lowest per-token price
zai-org/GLM-5.3:novita # Force traffic exclusively to Novita
Prompt-Cache Stickiness with X-HF-Session-Id
Agent loops re-send long system prompts, tool definitions, and conversation histories on every turn. Because backend prefix caches only hit when consecutive requests land on the same upstream host, Hugging Face's prompt-caching router honors a per-conversation UUID header:
# Send a valid UUID per conversation to stay pinned to one provider's KV cache
# (non-UUID strings are ignored by the router; HF JS/Python SDKs set this automatically)
curl https://router.huggingface.co/v1/chat/completions -H "Authorization: Bearer $HF_TOKEN" -H "X-HF-Session-Id: 3f8c2a1e-6b4d-4e2a-9c1f-7d5b0e8a4c21" -H "Content-Type: application/json" -d '{
"model": "deepseek-ai/DeepSeek-V4.1-Flash-1017:fastest",
"messages": [{"role": "user", "content": "Review this diff for race conditions."}]
}'
Cache hits are reported under usage.prompt_tokens_details.cached_tokens. Avoid injecting per-turn timestamps or random IDs at the top of system prompts, since changing the prefix invalidates provider caches on every iteration.
Breaking Change: Custom Provider Keys vs. Retained Workflows
| Area | Current Behavior | Developer Action Required |
|---|---|---|
| Custom Provider API Keys (LLM BYOK) | Removed for language models; all LLM traffic bills through HF account or organization at raw provider cost (zero Hub markup; $2/mo PRO, $2/seat Team/Enterprise credits) | Switch LLM workflows to your HF_TOKEN billing balance; use model suffixes (:provider) or Settings blocklists to restrict providers |
| Image, Video & Audio Inference | Unchanged on Hugging Face's native Inference Providers router (with LoRA support) | Existing custom keys and media generation endpoints continue working without changes |
| Hosted Routing vs. Local GGUF Weights | Hosted open-weight calls averaged $0.28/M input and $1.62/M output (~4× cheaper than closed baselines) across 59.2T weekly tokens on models like DeepSeek-V4.1-Flash-1017 | Use OpenRouter routing to prototype massive MoE models or absorb burst coding-agent traffic before allocating dedicated local llama.cpp GPU memory—and always check model weights and provider data-retention policies separately |
Next on the roadmap: connecting existing OpenRouter accounts directly to Hugging Face alongside native OpenRouter trace logging into user-owned Hub Storage Buckets.
Updated developer guide incorporating Hugging Face's November 16, 2026 announcement, prompt-caching docs, and November 19, 2026 walkthrough video.


