⚠️ 待更新·2026-08-29核验 · 更新时间待核验 · 本文信息可能已过期，请以官方文档为准
更新时间：2026-08-29 · 核验状态：待更新 · 官方溯源待补
简介
OpenRouter 不只是模型聚合器,还内置了路由能力:可以在单次请求里指定多个模型,主模型失败时自动降级到备用模型,或按权重在多个 provider 间分发请求。这意味着无需自己写 failover 逻辑,网关层就帮你解决了高可用问题。本篇演示三种典型用法。
架构图
flowchart TD
Req[Request] --> Primary[Primary model]
Primary -->|429/5xx| Fallback1[Fallback model A]
Fallback1 -->|429/5xx| Fallback2[Fallback model B]
Fallback2 -->|fail| Free[Fallback :free model]
Free --> Final[Response]
Primary --> Final
Fallback1 --> Final
Fallback2 --> Final
场景一:自动降级(Fallback)
当主模型限流或宕机时,OpenRouter 会按 models 数组顺序尝试下一个:
curl https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-3.5-sonnet,openai/gpt-4o-mini,meta-llama/llama-3.3-70b-instruct:free",
"messages": [{"role":"user","content":"用一句话解释什么是反向索引"}]
}'
OpenRouter 会先尝试 Claude,失败则切到 GPT-4o-mini,再不行用免费 Llama。响应头 X-Openrouter-Model 标识实际命中的模型,响应体 provider 字段还会标注是哪家 provider 服务了请求。
场景二:按路由偏好分发
OpenRouter 提供三类 routing 偏好:
highest_throughput:优先选当前吞吐最高的 providerlowest_price:优先选最便宜的 providerlowest_latency:优先选延迟最低的 provider
import os, requests
payload = {
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "hi"}],
"routing": "lowest_price"
}
headers = {
"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
"HTTP-Referer": "https://myapp.example.com",
"X-Title": "myapp",
}
r = requests.post(
"https://openrouter.ai/api/v1/chat/completions",
json=payload, headers=headers, timeout=30,
)
print(r.json()["choices"][0]["message"]["content"])
注意 HTTP-Referer 和 X-Title 是可选但推荐的头,能让你的应用在 OpenRouter 排行榜上展示。
场景三:指定 provider 与 ignore
想强制走某家 provider(比如只用 OpenAI 官方而不是 Azure),用 provider.order:
{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "hi"}],
"provider": {
"order": ["OpenAI"],
"allow_fallbacks": false
}
}
反过来,想屏蔽某家:"ignore": ["Together"]。组合使用可精细控制成本与延迟。
进阶:同模型多 provider
同一个模型名(如 openai/gpt-4o-mini)背后可能有多个 provider。设置 provider.allow_fallbacks=true 后,某家 provider 故障会自动切到另一家,无需改代码。响应中的 provider_name 字段告诉你实际走了哪家。
常见问题
- 降级后响应变慢:免费模型排队所致,可把付费模型放前面。
routing 字段被忽略:确认模型确实有多个 provider,否则无意义。- 想固定某家 provider:用
provider.order 字段强制顺序。
- 同模型价格不一:不同 provider 对同一模型定价可能不同,
lowest_price 能自动选最便宜的。
合理组合 fallback + routing + provider 过滤,能在免费层边界内最大化可用性。
路由配置示例
{
"model": "deepseek/deepseek-chat:free",
"fallback": ["meta-llama/llama-3.3-70b:free", "google/gemini-2.0-flash:free"],
"routing": {
"on_429": "fallback",
"on_5xx": "fallback",
"on_timeout": "fail"
}
}
最佳实践
- fallback 链不要超过 3 层：每加一层延迟翻倍，3 层已经接近用户耐心极限。
- 同模型不同 provider：把同模型在 OpenRouter 和原厂（如 DeepSeek 直连）都备一份，避免单家抽风。
- 缓存兜底：相同请求加 Redis 缓存 60 秒，免费层 429 时直接命中缓存返回。
⚠️ Pending Update · 2026-08-29 Verification · Content may be outdated, please refer to official docs
Updated: 2026-08-29 · Status: Pending Verification
Introduction
OpenRouter is more than a model aggregator — it has built-in routing. A single request can list multiple models so the gateway falls back automatically when the primary fails, or it can distribute load across providers by preference. This means you get high availability at the gateway layer without writing your own failover logic. This article shows three patterns.
架构图
flowchart TD
Req[Request] --> Primary[Primary model]
Primary -->|429/5xx| Fallback1[Fallback model A]
Fallback1 -->|429/5xx| Fallback2[Fallback model B]
Fallback2 -->|fail| Free[Fallback :free model]
Free --> Final[Response]
Primary --> Final
Fallback1 --> Final
Fallback2 --> Final
Pattern 1: Automatic Fallback
When the primary model is rate-limited or down, OpenRouter tries the next entry in the models array:
curl https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "anthropic/claude-3.5-sonnet,openai/gpt-4o-mini,meta-llama/llama-3.3-70b-instruct:free",
"messages": [{"role":"user","content":"Explain an inverted index in one sentence."}]
}'
OpenRouter tries Claude first, then GPT-4o-mini, then free Llama. The X-Openrouter-Model response header indicates which model served the request, and the provider field in the body names the actual provider.
Pattern 2: Routing Preferences
OpenRouter exposes three routing preferences:
highest_throughput: prefer the provider with the highest current throughputlowest_price: prefer the cheapest providerlowest_latency: prefer the lowest-latency provider
import os, requests
payload = {
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "hi"}],
"routing": "lowest_price"
}
headers = {
"Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
"HTTP-Referer": "https://myapp.example.com",
"X-Title": "myapp",
}
r = requests.post(
"https://openrouter.ai/api/v1/chat/completions",
json=payload, headers=headers, timeout=30,
)
print(r.json()["choices"][0]["message"]["content"])
Note: HTTP-Referer and X-Title are optional but recommended headers that let your app appear on OpenRouter's leaderboard.
Pattern 3: Pin or Ignore Providers
To force a specific provider (e.g. only OpenAI direct, not Azure), use provider.order:
{
"model": "openai/gpt-4o-mini",
"messages": [{"role": "user", "content": "hi"}],
"provider": {
"order": ["OpenAI"],
"allow_fallbacks": false
}
}
Conversely, to block a provider: "ignore": ["Together"]. Combining the two gives fine-grained control over cost and latency.
Advanced: Multiple Providers for One Model
A single model name (e.g. openai/gpt-4o-mini) may have several providers behind it. Setting provider.allow_fallbacks=true makes OpenRouter switch providers automatically on failure — no code change required. The provider_name field in the response tells you which one served the request.
Troubleshooting
- Slow responses after fallback: caused by free-model queuing. Put a paid model first.
routing field ignored: make sure the model actually has multiple providers; otherwise it has no effect.- Pin a specific provider: use the
provider.order field to force an order.
- Different prices for same model: providers may price the same model differently.
lowest_price picks the cheapest automatically.
Combining fallback, routing, and provider filtering maximizes availability within free-tier limits.
Routing Configuration Example
{
"model": "deepseek/deepseek-chat:free",
"fallback": ["meta-llama/llama-3.3-70b:free", "google/gemini-2.0-flash:free"],
"routing": {
"on_429": "fallback",
"on_5xx": "fallback",
"on_timeout": "fail"
}
}
Best Practices
- Cap fallback chains at 3: each layer doubles latency; 3 layers is near the user-patience limit.
- Same model, multiple providers: back up each model with both OpenRouter and the original (e.g. DeepSeek direct) so one provider outage does not break you.
- Add a cache layer: Redis 60-second cache catches duplicate requests when free tier hits 429.