OpenRouter 保姆级教程：从0到1用一个 Key 调用 GPT、Claude、Gemini 全模型

OpenRouter 能做什么——统一调用 GPT / Claude / Gemini / DeepSeek

OpenRouter 是一个统一 LLM API 网关：用一个 API Key + 一个 OpenAI 兼容 Endpoint（https://openrouter.ai/api/v1/chat/completions），即可调用 GPT、Claude、Gemini、Llama、DeepSeek、Qwen、Mistral 等来自 70+ 家供应商的 400+ 模型，而不需要为每个厂商单独注册、接入 SDK、管理账单。

• 认证方式：Authorization: Bearer $OPENROUTER_API_KEY
• 兼容协议：OpenAI Chat Completions 格式——已有 OpenAI SDK 代码基本不用改，只需换 base_url 和 api_key
• 模型命名：供应商/模型名，例如 openai/gpt-4o、anthropic/claude-3.5-sonnet、google/gemini-2.5-pro、deepseek/deepseek-chat

OpenRouter 内部做两层独立路由决策，这是理解它行为的关键：

如果主力供应商限流或报错，OpenRouter 会自动切换到下一个可用供应商或备选模型（models 数组），业务侧通常不会收到 500——这套容错逻辑内置在网关层，不需要你在业务代码里手写 circuit breaker。

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

OpenRouter 不是要取代官方 SDK，而是在「多模型场景」和「官方直连」之间提供折中。下面这张表帮你快速判断差异 👇

OpenRouter 的 5 个核心优势（含什么时候不该用）

优势一：一个 Key 打通所有模型，迁移成本几乎为零。换模型 = 改一个 model 字符串，不需要重写业务逻辑或为每个厂商写适配层。

优势二：跨供应商自动故障转移。可以显式配置 fallback 链，主力挂了自动依次尝试备选模型，业务代码无需额外重试逻辑。

优势三：统一账单和用量分析。一个 Dashboard 看所有模型的消耗、成本、延迟（TTFT）、吞吐量。

优势四：定价对用户友好——无 token 加价。OpenRouter 官方 FAQ 明确不在 token 单价上加价，只在充值环节收 5.5% 手续费。中大体量用户可用 BYOK（自带供应商 Key）模式：每月前 100 万次请求免费，超出后对等值部分收 5% 服务费。

优势五：场景定位清晰。适合快速原型验证、多模型 A/B 测试、中小体量应用（月消费几千美元以内）、需要多模型 fallback 提升可用性的场景，以及用同一套 Prompt / Agent 框架跑遍市面所有模型。

实战教程——6 步接入 OpenRouter API

下面是从注册到发出第一次请求的完整路径。建议在一台干净的 macOS 开发机上操作——避免 Python 版本冲突和旧 SDK 残留干扰排查。

1. 注册 OpenRouter 账号：访问 openrouter.ai，用 GitHub 或邮箱注册。
2. 创建 API Key：在 Dashboard → Keys 页面生成密钥，存入环境变量 OPENROUTER_API_KEY，不要硬编码进仓库。
3. （可选）充值 Credits：调用付费模型需要账户有余额；充值时收取 5.5% 手续费（最低 $0.80）。未充值也可使用 25+ 免费模型，但有频率限制。
4. 查询可用模型：用 GET /api/v1/models 确认目标模型 ID 和当前定价。
5. 发出第一次请求：用 curl 或 SDK 调用 /v1/chat/completions，指定 model 参数。
6. 验证流式与 Fallback：在生产接入前，分别测试 stream: true 和 models 数组的容灾链路，确认业务侧能正确处理。

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

代码示例——curl / Python / Node.js / OpenAI SDK 兼容写法

以下四种写法覆盖最常见的接入场景。OpenRouter 建议携带 HTTP-Referer 和 X-Title 请求头，用于排行榜统计。

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://your-app-domain.com",
        "X-Title": "My App",
    },
)
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 completion = await openai.chat.completions.create({
  model: "deepseek/deepseek-chat",
  messages: [{ role: "user", content: "Explain OpenRouter in one sentence" }],
});

console.log(completion.choices[0].message.content);

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);
}

{
  "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 会按顺序自动尝试列表里的下一个模型，业务侧无需额外重试逻辑。

进阶用法——免费模型、Fallback 容灾与成本控制

• 免费模型：OpenRouter 提供 25+ 免费模型（如部分 Llama、Gemma、DeepSeek 免费档）。未充值账户约 50 次/天；账户充值 ≥$10 后提升到 1000 次/天、20 次/分钟。
• BYOK 模式：自带各厂商 API Key，每月前 100 万次请求免 OpenRouter 服务费，超出后对等值部分收 5%。适合已有大量官方 Key 的中大体量用户。
• 定价机制：Token 按供应商原价透传，无 markup；仅在充值购买 Credits 时收 5.5% 手续费（最低 $0.80），加密货币支付另收 5%。
• 成本监控：在 Dashboard 按模型查看 prompt / completion 单价和实际消耗，避免多模型 A/B 测试时账单失控。

定价档位、免费模型列表和限流规则可能随时间调整——请以官方文档为准，而不是本文转述。

OpenRouter 官方文档

OpenRouter 官方 FAQ（定价与 BYOK 说明）

OpenRouter 官方 —— Provider Routing 机制说明

常见问题 FAQ

OpenRouter 解决的是「多模型 API 统一接入」的问题，但它管不了你的本地开发环境：Python 虚拟环境冲突、Node.js 版本不匹配、Agent 框架写到一半把主力机搞脏——这些摩擦点在多模型实验阶段尤其常见。一台可以随时清空、按天起租的真实 Apple Silicon Mac mini，用来跑 OpenRouter 接入脚本、Next.js 原型或长期挂着的 Agent 进程，比共用笔记本更可控。我们在 Kimi K3 模型测试指南和 Xcode CI Runner 搭建指南里写过类似的「干净机器」思路——OpenRouter 多模型联调同样适用。