OpenRouter API 怎么接入？一个 key 调 GPT/Claude 等上百个模型

2026-07-07

数据截至 2026-07，价格与限额以各官网为准。

OpenRouter 不是又一个大模型，而是一个聚合层：一个账号、一套 OpenAI 兼容接口，就能调 GPT、Claude、Gemini 加上一大堆开源模型，切换模型只需要改一个字符串，官方还会在某个提供商报错时自动切到下一个可用的——接入本身很简单，真正要花心思的是搞清楚模型名怎么写、免费档的限速规则，以及大陆网络环境下能不能用。

如果你已经分别接过 OpenAI 和 Claude 的官方 API，会觉得 OpenRouter 这套东西格外眼熟——因为它走的就是 OpenAI 兼容协议，之前写好的调用代码几乎不用改结构，换个 base_url、换个 model 名字就能跑。但正因为”看起来一样”，反而容易在模型命名、免费额度这些细节上想当然，这篇按实际接入顺序走一遍。

先搞清楚它是什么：聚合入口，不是模型本身

OpenRouter 官方 quickstart 文档里对自己的定位说得很直白：提供一个统一 API，通过单一端点访问上百个模型，同时自动处理故障转移（fallback）并选择性价比更高的选项。换句话说，它自己不训练模型，而是把主流闭源模型（OpenAI GPT 系列、Anthropic Claude 系列、Google Gemini 系列）和大量开源模型（Qwen、DeepSeek、Llama、Gemma 等）统一接进同一套接口里，你用同一个 key 就能在这些模型之间随便切换，不用分别去各家官网注册、分别管理账单。

这也是为什么不少开发者会把 OpenRouter 当成访问 GPT、Claude 这类闭源模型的一条间接路径——尤其是暂时申请不到官方 key、或者想把多家账单统一到一处对账的场景。需要提醒的是，这属于”间接访问”：底层调用的还是各家官方模型，只是账单、鉴权、路由这层由 OpenRouter 统一代理，模型本身的能力、限制和官方那边保持一致，不会因为经过聚合层就变得更强或更弱。

自动故障转移这个特性值得单独说一句：官方原文写的是，当某个模型提供商返回错误时，OpenRouter 会自动切换到下一个可用的提供商，这个过程对用户是透明的，能让生产环境的应用更有韧性。如果你的业务对某个模型有强依赖、又担心单一提供商偶发抖动，这层兜底机制是接入 OpenRouter 而不是直连单一厂商的一个实际理由。

第一步：注册账号，拿到 key

流程和大多数 SaaS 平台差不多：打开 openrouter.ai，用邮箱或第三方账号注册，验证邮箱之后，进入控制台的 Keys 页面就能生成一个 API key。整个过程不涉及复杂的身份审核，标准开发者用途基本上注册完就能拿到 key，不用像申请某些企业级 API 那样等人工审批。

密钥拿到手之后同样是”只显示一次”的老规矩，建议第一时间存进环境变量，不要写死在代码里，也别提交进版本库。这一点跟接 OpenAI、Claude 的 key 是同一套习惯，不需要单独学。

第二步：base_url 与最小调用

OpenRouter 走的是 OpenAI 兼容协议，接口形态跟 OpenAI 的 Chat Completions 几乎一致，区别主要在两处：请求地址换成 OpenRouter 自己的，模型名要带上”命名空间前缀”。

Base URL 是：

https://openrouter.ai/api/v1

对应的 Chat Completions 端点是 https://openrouter.ai/api/v1/chat/completions。

官方 quickstart 里给出的最小示例是直接拼 HTTP 请求：

import requests
import json

response = requests.post(
  url="https://openrouter.ai/api/v1/chat/completions",
  headers={
    "Authorization": "Bearer <OPENROUTER_API_KEY>",
  },
  data=json.dumps({
    "model": "anthropic/claude-opus-4.7",   # 带命名空间前缀，如 openai/xxx、anthropic/xxx、google/xxx
    "messages": [
      {"role": "user", "content": "你好"}
    ]
  })
)

这里最容易被忽略的一个细节是 model 字段的写法：调用哪家的模型，前面就要带上对应厂商的命名空间，比如 Anthropic 的模型写成 anthropic/claude-opus-4.7，OpenAI 的写成 openai/xxx，Google 的写成 google/xxx。忘了加前缀、或者把前缀写错，请求大概率会直接报错找不到模型——这是从单一厂商 API 迁移过来的人最容易踩的第一个坑，因为直连 OpenAI 或 Anthropic 官方 API 时是不需要写命名空间的。

如果你的项目里已经用官方 openai SDK 写好了调用逻辑，不想改动结构，也可以直接把 SDK 的 base_url 指向 OpenRouter，当成”平替”来用：

from openai import OpenAI
client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="<OPENROUTER_API_KEY>",
)

这种写法的好处是迁移成本几乎为零，原来调用 OpenAI 的那套代码结构原封不动，只是把 base_url 和 key 换掉，model 名字照样要带上命名空间前缀。

另外有两个可选请求头可以按需加上：HTTP-Referer（你的站点 URL）和 X-Title（站点名称），官方文档里明确标注这两个都是 Optional，作用是让你的调用出现在 openrouter.ai 的站点排行榜统计里，不传也完全不影响正常调用，纯粹是锦上添花，不用为了”合规”特意去补。

免费模型档：能白嫖，但有限速

OpenRouter 提供一批专门的免费模型路由，官方页面显示大概有 26 个免费变体模型，大多来自 Qwen、DeepSeek、Llama、Gemma 等开源模型开放出来的免费额度，适合拿来跑通流程、做原型验证，不建议指望它扛生产流量。

限速规则分两档：如果账户从来没有购买过 credits，限速是每天 50 次、每分钟 20 次；如果账户历史累计充值达到 10 美元以上，每天的额度会提升到 1000 次，但每分钟 20 次这条限制依然保留。也就是说哪怕升到了更高的日限额，短时间内密集发请求照样会被限速卡住，不是”充够钱就能随便造”。

免费档适合的场景很明确：调试代码逻辑、验证 prompt 效果、教学演示。真要上线跑真实流量，还是老老实实充值用正式模型，别把免费档当成生产环境的免费午餐。

大陆访问的现实情况（诚实说明）

这一段照实说：OpenRouter 是一个境外（美国）托管的服务，它自己以及它底层依赖的 OpenAI、Anthropic、Google 这些模型提供方，在中国大陆网络环境下普遍都需要科学上网或者网络代理才能稳定访问。这不是 OpenRouter 一家的问题，而是这一类海外 AI 聚合平台的共性现实。

需要说明的是，截至目前没有在 openrouter.ai 官方页面上找到关于”中国大陆访问政策”的正式声明，这跟 OpenAI、Anthropic 那种明确写在官方支持地区列表里、白纸黑字排除大陆的情况不完全一样——OpenRouter 更像是”访问需要翻墙的技术现实”，而不是”官方政策层面主动拒绝”。但这个区别不代表访问会更容易，网络层面的门槛照样存在。

至于市面上流传的各种”中转""代理""一键直连”服务，这篇不推荐、不背书，也不列具体渠道名称——原因和接入 OpenAI、Claude 时讲的一样：这类第三方服务的稳定性、账号安全、数据隐私风险都得自己承担，而且渠道变化极快，今天能用明天未必还在，与其推荐一个随时可能失效的具体名字，不如把现实情况讲清楚，怎么选交给你自己判断。如果是企业级场景需要稳定合规接入，建议走正规的出海网络方案，或者直接咨询能合规触达的云服务商。

常见坑 / 注意

model 名必须带命名空间前缀：openai/xxx、anthropic/xxx、google/xxx，漏写或写错前缀会直接找不到模型。
免费档限速卡的是频率，不是总量：哪怕充值满 10 美元升到日限 1000 次，每分钟 20 次的上限依然生效，密集调用照样会被限流。
免费模型不适合生产环境：拿来调试、验证 prompt 没问题，真实业务流量还是要上付费模型。
可选请求头不是必填项：HTTP-Referer、X-Title 不传不影响调用，别为了”凑齐参数”特意加。
大陆访问靠的是翻墙，不是官方政策豁免：没有查到官方关于大陆的正式声明，但网络层面的访问门槛是客观存在的现实。
第三方中转渠道自担风险：本文不推荐具体名字，稳定性和账号安全都需要自己评估。