OpenRouter 保姆级教程：从0到1接入 GPT / Claude / Gemini 全模型

如果你正在为每个大模型厂商单独注册账号、维护多套 SDK 和账单，OpenRouter 可能是 2026 年最省事的解法——一个 API Key + 一个 OpenAI 兼容 Endpoint，即可调用 GPT-4o、Claude 3.5 Sonnet、Gemini 2.5 Pro、DeepSeek、Qwen 等 400+ 模型。本文面向 AI 应用开发者与技术决策者，覆盖双路由机制、五大核心优势、与直连 API 的对比决策、3 步接入流程，以及 curl / Python / Node.js / OpenAI SDK 全套代码与 Fallback 容灾配置。结论先行：中小体量多模型场景选 OpenRouter 迁移成本几乎为零；超大体量、极致延迟或严格数据驻留仍应直连官方 API。

SECTION 01 多模型接入时，开发者最常踩的四类坑

• 账号与 Key 碎片化：OpenAI、Anthropic、Google、Meta、DeepSeek 各需独立注册、计费与 SDK 适配，运维成本随模型数量线性增长。
• 单点故障无容错：某一厂商限流或宕机时，业务侧需自行实现重试、切换供应商与 circuit breaker，代码复杂度陡增。
• 账单对账困难：五个后台五个账单，无法在一个 Dashboard 统一查看 token 消耗、延迟（TTFT）与吞吐量。
• 模型切换成本高：换模型往往意味着重写请求适配层；与DeepSeek V4 API 迁移或Kimi K3 多模型对比场景叠加时，适配层维护成为瓶颈。

SECTION 02 OpenRouter 是什么？双路由机制一次讲清

一句话定义：OpenRouter 是统一 LLM API 网关 / 聚合层——用一个 API Key和OpenAI 兼容 Endpoint https://openrouter.ai/api/v1/chat/completions，调用来自 70+ 供应商、400+ 模型的能力，无需为每个厂商单独注册、接入 SDK、管理账单。认证方式：Authorization: Bearer $OPENROUTER_API_KEY。模型命名规则为 供应商/模型名，例如 openai/gpt-4o、anthropic/claude-3.5-sonnet、google/gemini-2.5-pro、deepseek/deepseek-chat。

已有 OpenAI SDK 代码基本不用改，只需替换 base_url 和 api_key，请求体、消息格式与流式处理逻辑完全不变。

此外：免费模型有 25+ 个（部分 Llama、Gemma、DeepSeek 免费档），未充值约 50 次/天，账户充值 ≥$10 后提升至 1000 次/天（20 次/分钟）。定价机制：OpenRouter 不在 token 单价上加价，按供应商原价透传；仅在充值购买 Credits 时收取 5.5% 手续费（最低 $0.80），加密货币支付另收 5%。BYOK（自带供应商 Key）模式下，每月前 100 万次请求免费，超出后对等值部分收 5% 服务费。

SECTION 03 OpenRouter 和直接调用 OpenAI / Anthropic API 有什么区别

五大核心优势：① 一个 Key 打通所有模型，迁移成本几乎为零；② 跨供应商自动 Failover；③ 统一账单与用量分析；④ 无 token 加价，定价对用户友好；⑤ 适合多模型对比、Agent 框架统一跑遍市面模型。

什么时候不该用 OpenRouter（建立信任的平衡视角）：

• 单一模型、超大体量（月消费数万美元以上），5.5% 充值手续费已值得自建供应商直连
• 需要 Anthropic Prompt Caching 计费优化、OpenAI Batch API / Assistants API、Google Vertex AI 专属工具链
• 对延迟极度敏感（网关额外 10–80ms 跳数不可接受）
• 数据合规 / 数据驻留要求，不允许流量经过美国第三方中间层

OpenRouter 不是要取代 OpenAI/Anthropic 官方 SDK，而是在「多模型场景」和「官方直连」之间提供折中方案。

SECTION 04 实战教程：3 步接入 OpenRouter API + 全套代码示例

1. 注册 OpenRouter 账号：访问 openrouter.ai，使用 Google/GitHub 或邮箱注册，进入 Dashboard。
2. 创建 API Key：在 Keys 页面生成密钥，存入环境变量 OPENROUTER_API_KEY，切勿提交到版本库。
3. 发起第一次请求：用下方 curl 或 SDK 示例验证连通性与计费。
4. （推荐）配置 HTTP-Referer：OpenRouter 建议携带 HTTP-Referer 与 X-Title，用于排行榜统计与用量归属。
5. 查询可用模型：调用 GET /api/v1/models 获取实时模型列表与定价。
6. 配置 Fallback 链：生产环境建议设置 models 数组，主力模型限流时自动切换备选。
7. 监控用量与成本：在 Dashboard 查看各模型 token 消耗、TTFT 与延迟分布，设置充值告警。

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",
    "messages": [
      { "role": "user", "content": "用一句话解释什么是量子计算" }
    ]
  }'

import requests
import os

response = requests.post(
    url="https://openrouter.ai/api/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['OPENROUTER_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "google/gemini-2.5-pro",
        "messages": [
            {"role": "user", "content": "帮我写一个快速排序的 Python 实现"}
        ],
    },
)

print(response.json()["choices"][0]["message"]["content"])

from openai import OpenAI
import os

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key=os.environ["OPENROUTER_API_KEY"],
)

completion = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_headers={
        "HTTP-Referer": "https://vpsnix.com",
        "X-Title": "VPSNIX Blog Demo",
    },
)
print(completion.choices[0].message.content)

import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});

const stream = await openai.chat.completions.create({
  model: "anthropic/claude-3.5-sonnet",
  messages: [{ role: "user", content: "写一首关于秋天的短诗" }],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) process.stdout.write(content);
}

多模型 Fallback 容灾配置（体现优势二的落地代码）：

{
  "model": "anthropic/claude-3.5-sonnet",
  "models": [
    "anthropic/claude-3.5-sonnet",
    "openai/gpt-4o",
    "google/gemini-2.5-pro"
  ],
  "route": "fallback",
  "messages": [{ "role": "user", "content": "Hello" }]
}

主模型被限流或报错时，OpenRouter 按顺序自动尝试列表中的下一个模型，业务侧无需额外重试逻辑。

查询可用模型列表：

curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

SECTION 05 进阶用法：免费模型、定价机制与可引用硬核数据

可引用硬核数据：

• 模型规模：70+ 供应商、400+ 模型，统一 Endpoint /v1/chat/completions
• 协议兼容：OpenAI Chat Completions 格式，现有 SDK 改两行即可迁移
• 路由层：Model Routing（model 字段）+ Provider Routing（provider 对象，价格倒平方加权）
• Failover：models 数组 + route: "fallback"，主力挂掉自动切换
• 定价：无 token markup；充值 5.5%；BYOK 前 100 万次/月免费
• 免费模型：25+ 个，未充值 50 次/天 → 充值 ≥$10 后 1000 次/天

官方文档与 FAQ（发版后请再次打开链接核对）：

OpenRouter 官方文档

OpenRouter 官方 FAQ — 定价与 BYOK 说明

OpenRouter 模型列表与实时定价页

典型高效组合是：OpenRouter 负责多模型推理与 A/B 对比，VPSNIX M4/M4 Pro 物理节点负责 Xcode 编译、Metal 调试与 AI Agent 7×24 部署——云端 LLM 再强也无法在 Hypervisor 虚拟 macOS 上稳定跑 iOS 证书链；虚拟化方案伴随 EULA 风险与 20–40% 性能损耗。对于需要零损耗原生算力、稳定 iOS CI/CD 与 AI Agent 自动化的生产环境，VPSNIX 的云端物理节点通常是更优解：100% 苹果原装硬件、完整 Root 权限、无 Hypervisor 损耗、按天/周/月弹性下单。报价见定价页；若已在用 OpenRouter 跑Kimi K3或DeepSeek V4做代码推理，更应将编译链锁定在合规物理环境。

SECTION 06 常见问题 FAQ