OpenRouter 是什么
OpenRouter 是模型聚合网关：用一个 key 调用多家厂商的模型（既有闭源旗舰也有开源托管版），统一用 OpenAI 兼容协议，返回体里带各上游的用量与价格信息，便于快速比价、做试验和临时容灾。代价是引入一层第三方依赖并带来一定溢价，同时各上游的数据使用策略不同——请求实际落到哪家、数据被怎么处理，要按上游逐家确认。关键链路仍建议保留直连厂商的降级通道。
基本信息
| 端点 | openrouter.ai/api/v1/chat/completions |
|---|---|
| 模型命名 | 厂商/模型，如 openai/gpt-4o-mini |
| 鉴权 | Authorization: Bearer <API Key> |
| 能力 | 统一协议、自动路由、备用模型降级、用量统计 |
| 注意 | 各上游数据策略与价格不同，存在平台溢价 |
| 适用 | 多模型比价、快速试验、临时容灾 |
典型使用场景
- 多模型横评：用同一份请求体跑多家模型，省去逐个改造 SDK
- 原型阶段：快速验证不同厂商模型的效果，再决定直连哪家
- 临时容灾：主供应商故障时先切到聚合层顶上
- 开源模型试验：不自己部署即可试跑开源托管版
- 成本观察：借聚合层的用量字段快速对比不同模型的单次开销
最小调用与自检
最小调用与自检
# 密钥走环境变量
export OPENROUTER_API_KEY=你的密钥
cat > payload.json <<'EOF'
{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"用一句话解释向量检索"}]}
EOF
curl -s https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer $OPENROUTER_API_KEY" -H "Content-Type: application/json" -d @payload.json
# 排查顺序：401 密钥 / 402 余额 / 404 模型标识写错或已下线 / 429 上游限流模型标识后缀要注意
| 后缀形态 | 含义 | 影响 |
|---|---|---|
| 基础形态 | 厂商/模型名 | 按上游约定路由 |
| 免费变体 | 带 free 之类后缀 | 配额低、限流严，仅适合试验 |
| 高速变体 | 带性能优先后缀 | 价格更高，路由到的上游可能变化 |
| 自动路由 | 通用自动选择标识 | 上游可变，输出稳定性弱于固定模型 |
把聚合层当唯一通道风险集中：它故障或改策略时全线受影响。生产上建议主链路直连厂商，聚合层作为试验与降级通道。
模型标识后缀会改变路由与配额，测试通过的标识要原样写进配置；靠「大致相似的写法」在聚合层很容易落到另一个上游。