OpenRouter 多模型路由使用

⚠️ 待更新·2026-08-29核验 · 更新时间待核验 · 本文信息可能已过期，请以官方文档为准更新时间：2026-08-29 · 核验状态：待更新 · 官方溯源待补

简介

OpenRouter 不只是模型聚合器,还内置了路由能力:可以在单次请求里指定多个模型,主模型失败时自动降级到备用模型,或按权重在多个 provider 间分发请求。这意味着无需自己写 failover 逻辑,网关层就帮你解决了高可用问题。本篇演示三种典型用法。

架构图

场景一:自动降级(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:优先选当前吞吐最高的 provider
lowest_price:优先选最便宜的 provider
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"])

注意 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 时直接命中缓存返回。

🚀 立即开始：免费 API 一键调用

想要无需逐一注册、统一鉴权调用以上全部免费模型？Apishare.cc 提供统一 API Key，一个 Key 调用 100+ 模型，免费模型零成本直连。

👉 立即注册 Apishare.cc → 获取你的统一 API Key

📊 想看更多免费模型排行？查看 2026年9月免费 LLM API 综合实力榜单 →

立即上手：APIShare 免费 API 目录

注册领取免费额度：立即注册 · 登录
浏览全部免费 API：免费 API 目录

免费 API 聚合平台说明

本文涉及的模型均由 APIShare 免费 API 聚合平台统一接入，一份 Key 调用全站模型。

完整模型目录：APIShare 免费 API 目录
注册即送免费额度：注册领取 API Key