OpenRouter 怎麼用？從 API Key 到 GPT、Claude、Gemini

一句話導讀：OpenRouter 常被说成「一个 Key 调全家模型」，但第一次上手的人往往在註冊、充值、模型 id 和 SDK 基址之间来回试错。 下文按真实操作顺序写：从账号与 API Key，到用 OpenAI 兼容接口调 GPT、用 Messages 形态调 Claude、再调 Gemini，最后看帳單与常见报错。

OpenRouter 解决什么问题

OpenRouter 是一个聚合多家模型供應商的 API 网关。你向 OpenRouter 发请求，它按你写的 model 字段路由到 OpenAI、Anthropic、Google 等后端，费用记在 OpenRouter 账户上，而不是分别去每家 Console 开帳單。

对个人开发者和小团队，价值通常有三点：一把 Key 试多个模型、目录价透明（可在站内对比输入/输出单价）、失败时可换路由（具体策略以当时文档为准）。它不是模型托管商——权重与推理仍在供應商侧执行。

若你已经在用 Claude Code 接 OpenRouter，那是另一条「Anthropic 兼容基址」路径；本文先讲通用 HTTP / OpenAI SDK，再单独说明 Claude 的差异。

註冊、充值与创建 API Key

1. 打开 openrouter.ai，用邮箱或 OAuth 註冊。
2. 进入 Settings → Credits 充值。新账户往往有少量试用额度；持续调用前建议先设月上限，避免脚本死循环烧额度。
3. 在 Keys 页面创建 API Key。命名建议按用途拆分，例如 local-dev、ci-bot，并为每把 Key 单独设 spending limit。
4. 把 Key 放进環境變數，不要写进仓库：export OPENROUTER_API_KEY="sk-or-…"

模型 id 怎么查、怎么读

OpenRouter 的模型名一般是 供應商/模型，例如 openai/gpt-5.6-sol-medium、anthropic/claude-sonnet-5.5、google/gemini-4-argon-medium。完整列表在站内的 Models 页，也可用 API 拉取：

curl -s https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" | head -c 2000

目录会随供應商上新而变化。写进生产配置时，尽量钉死具体 id，不要只写 latest 别名，否则一次目录更新可能悄悄换价或换上下文长度。本周用量与单价对照可参考 OpenRouter 模型排行。

调用 GPT（OpenAI 兼容）

最常用的入口是 Chat Completions，基址为 https://openrouter.ai/api/v1，认证头为 Authorization: Bearer <OPENROUTER_API_KEY>。建议额外带上 HTTP-Referer 与 X-Title（站点名），便于在 OpenRouter 仪表盘里区分来源。

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "HTTP-Referer: https://your-app.example" \
  -H "X-Title: My Dev App" \
  -d '{
    "model": "openai/gpt-5.6-sol-medium",
    "messages": [{"role": "user", "content": "用三句话解释什么是 OpenRouter"}]
  }'

返回 JSON 结构与 OpenAI 官方类似：choices[0].message.content 为正文，usage 里是分项 token 数，用于对照帳單。

调用 Claude

在 OpenRouter 上，Claude 通常仍走 同一 Chat Completions 端点，只需把 model 换成 anthropic/…。例如：

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet-5.5",
    "messages": [{"role": "user", "content": "列出三个适合代码审查的 checklist 项"}]
  }'

若客户端只支持 Anthropic 原生 Messages API（例如部分终端 Agent），需要把基址改成 https://openrouter.ai/api（注意不要多写 /v1），并按供應商文档使用 Authorization: Bearer。Claude Code 的变量组合见 专门一文。

调用 Gemini

Google 系列在 OpenRouter 上同样用 google/… 前缀。示例：

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-4-argon-medium",
    "messages": [{"role": "user", "content": "把下面这段英文译成简体中文：…"}]
  }'

多模态（图片输入）是否可用，取决于具体模型页的能力标注；不要假设所有 Gemini id 都支持 vision。

在代码里切换 base_url

Python 侧若已安装 openai 官方 SDK，通常只需改基址与 Key：

from openai import OpenAI
import os

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

resp = client.chat.completions.create(
    model="openai/gpt-5.6-sol-medium",
    messages=[{"role": "user", "content": "Hello from OpenRouter"}],
    extra_headers={
        "HTTP-Referer": "https://your-app.example",
        "X-Title": "My Dev App",
    },
)
print(resp.choices[0].message.content)

Node.js 同理：new OpenAI({ baseURL: 'https://openrouter.ai/api/v1', apiKey: process.env.OPENROUTER_API_KEY })。切换模型时只改 model 字符串，其余管道可复用。

费用、限额与 Activity

OpenRouter 按目录 token 单价计费；不同模型输入/输出价可能差几个数量级。理解 token 计量见 token 与价格对照。

• Activity：按 Key、按模型查看每次请求与费用，是排错「为什么今天贵了」的第一站。
• Key 限额：给实验 Key 设硬顶，避免一次批量任务清空余额。
• 缓存与长上下文：部分模型有 cache read 价；长 Agent 会话要同时看模型档与上下文长度，不单看「哪家供應商」。

常见问题

OpenRouter 和直连 OpenAI / Anthropic 帳單能合并吗？ 不能。走 OpenRouter 的请求只扣 OpenRouter 额度；直连各家的 Key 与 OpenRouter Key 相互独立。

401 / 403 怎么查？ 先确认 Authorization: Bearer 拼写、Key 未撤销、账户余额大于零。再确认请求打到 /api/v1 而不是旧文档里的其它路径。

模型返回 404 model not found？ 多数是 id 写错或该模型已下架。用 Models API 或站内搜索核对当前 id。

可以用国内网络直接调吗？ 取决于你本机到 OpenRouter 的连通性。若不稳定，应在应用侧做重试与超时；敏感业务还要评估数据出境与合规要求，本文不构成法律建议。