用 OpenRouter 做统一 AI 网关：国内调用 Gemini/Claude API 的实战方案

01背景：为什么直连 Gemini API 会失败

前几天在客户端里配 Gemini，踩了一圈坑，过程挺典型，先复盘一下，方便对照自己卡在哪一步。

第一步：模型名填成了展示名

在模型设置里填了 Gemini 3.1 Flash Lite——这是控制台里的展示名称，不是 API 模型 ID。API 要的是全小写、连字符格式，比如 gemini-3.1-flash-lite。填错名字，网关找不到对应模型，直接抛 502。

第二步：改成 API ID 还是 502

把名字改对之后，依然 502。这时候就不是配置问题了——浏览器直接访问 generativelanguage.googleapis.com 显示 404（其实正常，根路径没页面），但客户端里请求 /v1beta/openai/chat/completions 就是不通。

第三步：代理全局模式也不行

把代理切成「全局」，YouTube 能开，但 Gemini API 还是 502。说明问题不在路由规则，而在代理节点本身到不了 Google API 域名。常见三种情况：

02什么是 OpenRouter

OpenRouter 是一个统一的 AI 模型 API 网关。它把市面上几百个模型收进一个 OpenAI 兼容的端点，我用一套代码或客户端就能调所有模型。

它覆盖的厂商包括：OpenAI、Anthropic、Google、Meta、Mistral，以及大量开源模型（DeepSeek、Qwen、Llama 等）。核心特点：

• 单一端点：https://openrouter.ai/api/v1，完全兼容 OpenAI SDK。
• 一个 Key 通吃：在 OpenRouter 注册一次，拿到 sk-or-v1-... 的 key，所有模型都能用。
• 换模型只改名字：想从 Gemini 换成 Claude，改一个 model 字段即可，不用改代码、不用换 key。
• 按 token 计费：有免费模型和付费模型，先充值 credit，调用扣费。

03为什么它能解决国内访问问题

关键不在「它更快」，而在请求路径变了。

直连模式：我的客户端 → 直接请求 generativelanguage.googleapis.com（国内常不通）
OpenRouter 模式：我的客户端 → 请求 openrouter.ai → OpenRouter 的服务器（在美国）再去请求 Google / Anthropic

也就是说，我不再需要直连 Google 的 API 域名。只要我的网络能到 openrouter.ai（这个域名相对 Google Cloud API 更容易连通，很多代理节点对其也更友好），就能间接用上 Gemini、Claude 等所有模型。

04实战：在客户端里配置

以任意 OpenAI 兼容客户端（Cherry Studio、各类对话 App）为例，步骤很简单：

1. 注册并拿 Key

去 openrouter.ai 注册，在 API Keys 页面生成一个 key，格式是 sk-or-v1-xxxxxxxx。

2. 添加自定义提供方

3. 添加模型

模型名填 OpenRouter 的 slug，例如：

• google/gemini-2.5-pro
• anthropic/claude-3.7-sonnet
• openai/gpt-4o

保存后发一条测试消息即可。

4. 代码调用示例（Python）

如果是自己写程序，直接复用 OpenAI SDK，只改 base_url 和 api_key：

from openai import OpenAI

client = OpenAI(
    base_url="https://openrouter.ai/api/v1",
    api_key="sk-or-v1-xxx",   # 换成我的 key
)

resp = client.chat.completions.create(
    model="google/gemini-2.5-pro",
    messages=[{"role": "user", "content": "用一句话解释什么是 API 网关"}],
)
print(resp.choices[0].message.content)

就这么几行，原来调 OpenAI 的代码几乎不用改，模型却能从 GPT 换成 Gemini / Claude。

05常用模型名对照表

OpenRouter 的模型名是 厂商/模型 格式，跟官方 API 里的名字不一样，这是最容易踩的坑。常用对照：

完整列表在 OpenRouter 官网的 Models 页面，每个模型卡片下方都直接给出可复制的 slug。

06费用与配额

• 免费模型：很多开源模型（DeepSeek、Qwen、Llama、部分 Meta 模型）有免费档，模型名带 :free 后缀，适合试用和轻量调用。
• 付费模型：按 token 计费，价格通常跟官方一致或略高——OpenRouter 会收一点服务费作为中转成本。
• Credit 系统：先充值 credit，调用时按量扣费，比每个厂商分别开账单省心。
• 速率限制：免费模型有 RPM / TPM 上限；充值后可提高额度。

07其他常见坑

1. 模型名格式：必须 厂商/模型，不能填官方展示名（比如 Gemini 2.5 Pro 会 404）。
2. 401 vs 404：401 = key 错；404 = 模型名错（OpenRouter 对未知模型返回 404，不是 400）。
3. Key 安全：浏览器端直接调 OpenRouter 需要带 key，暴露在前端有泄露风险，正式项目务必走后端代理。
4. 思考模式：Gemini / Claude 的 thinking 在 OpenRouter 通过 reasoning 参数控制，不是所有客户端都暴露这个开关。
5. 流式响应：OpenAI SDK 默认 stream=True，客户端要支持 SSE 才能正常显示逐字输出。

08小结

回到开头那个 502：直连 Google API 失败，多半是网络 / 节点问题，不是我配置错了。与其跟 DNS 污染和流媒体节点较劲，不如把请求路径改成「我 → OpenRouter → Google」。一层统一网关，把 300+ 模型收进一个端点、一个 key，换模型只改名字——开发体验提升明显，国内连通性也稳得多。

代价也很清楚：多一层中转、按 token 略贵、免费模型有额度限制。但对于「想稳定用上 Gemini / Claude，又不想在代理配置上耗一下午」的场景，OpenRouter 是目前最省心的方案之一。

09实测补充：地区限制、充值与直连对比

文章发布后，我当场注册了 OpenRouter、拿了 key、从本地客户端实测了一遍连通性。结果比上面写的"国内更稳"要复杂——这里把带时间戳的真实排查过程记下来，给国内读者避坑。

实测时间线（北京时间 2026-07-11）

坑一：OpenRouter 也救不了 Gemini 的地区限制

很多人（包括我写上文时）以为"走 OpenRouter 中转就能绕过直连的 502"。实测发现：OpenRouter 是合规网关，不是翻墙代理。它到 Google 后端拿模型时，照样执行 Google 的地区规则。只要账号 / 请求 IP 在中国大陆，Gemini 就返回 403。

坑二：Gemini 在 OpenRouter 根本不是免费的

这是最大的认知偏差，也是 22:02 那一步才彻底想明白的。Google AI Studio 给的 Gemini 免费额度 ≠ OpenRouter 上的 Gemini 免费。OpenRouter 是 API 网关，每调一次都要付给 Google 上游费用，所以：

• Gemini / Claude / GPT 在 OpenRouter 全是付费模型，按 token 计费；
• OpenRouter 要求账户先购买 credit 才能调用任何付费模型（错误码 402 Insufficient credits. This account never purchased credits）；
• 只有模型名带 :free 后缀的（如部分 Llama / Mistral）才是真免费，但经常排队、限流，质量也不如 Gemini。

一句话：Gemini 在 Google 那能白嫖，在 OpenRouter 这不能白嫖。切新加坡节点只解决了地区限制，接下来要充钱才能用。

关键发现：如果新加坡能用，直连 Google 可能更香

切到新加坡节点后，OpenRouter 放行了 Gemini（403→402）。这证明新加坡 IP 通过了 OpenRouter 的地区判断。同一套逻辑也适用于直连 Google：

也就是说，如果我的目标只是用 Gemini，新加坡节点 + 直连 Google（用自己的 key）就够了，还免费用 AI Studio 额度，不用像 OpenRouter 那样充值。原先直连报 502，是因为旧节点到不了 generativelanguage.googleapis.com 这个域名；换成能正常路由 Google API 的新加坡节点后，直连 + 免费，比走 OpenRouter 更省。

给国内读者的建议

• 只要 Gemini：新加坡（或日 / 美）节点 + 直连 Google，走 AI Studio 免费额度，零成本。
• 想一个 key 调多家 + 自动容灾：用 OpenRouter，但先把模型换成不受地区限制的 DeepSeek / Qwen / Kimi / GLM，且先小额充值再测。
• 非要 OpenRouter 上的 Gemini / Claude：需同时满足「充钱」+「请求 IP 在允许地区」。新加坡节点可解地区，社区还验证过 Cloudflare AI Gateway 反代、欧洲 VPS 单独给 OpenRouter 走规则两种办法。

10 再实测：API 路径返回 JSON，但 Pro 系列不免费

22:09，把浏览器地址从根路径 generativelanguage.googleapis.com 换成完整 API 路径：

https://generativelanguage.googleapis.com/v1beta/models?key=我的GoogleKey

返回了完整的模型列表 JSON——包含 models/gemini-2.5-flash、models/gemini-2.5-pro、models/gemini-3.1-flash-lite 等几十条记录。这说明：

• 新加坡节点 + 直连 Google API，网络已通；
• API Key 有效；
• 地区限制已放行。

之前浏览器访问根路径报 404，是正常行为（API 域名没有网页首页），不是"打不开"。

22:13 查看 AI Studio 配额：Pro 系列 0/0/0

转到 aistudio.google.com/app/apikey 的 Rate limit 页面，发现免费额度不是"每个模型都有"，而是按模型分配的：

关键结论：Gemini 2.5 Pro / 3 Pro / 3.1 Pro 的 RPM/TPM/RPD 全为 0/0，说明免费层完全不提供 Pro 系列。前面第 06 节说"Pro 免费层额度少"不够准确，应理解为"Pro 没有免费额度"。

免费用户该用什么模型

从配额表看，可用且额度充足的模型是 Flash / Flash Lite 系列：

• gemini-2.5-flash：5 RPM / 250K TPM / 20 RPD，日常开发首选
• gemini-2.5-flash-lite：10 RPM / 250K TPM / 20 RPD，更便宜
• gemini-3.1-flash-lite：15 RPM / 250K TPM / 500 RPD，免费层额度最多

注意：OpenAI 兼容端点填写模型名时，要把列表里的 models/gemini-2.5-flash 去掉 models/ 前缀，写成 gemini-2.5-flash。

最终可用配置（直连 Google，免费）

• Base URL：https://generativelanguage.googleapis.com/v1beta/openai
• API Key：我用的 Google AI Studio Key
• 模型名：gemini-2.5-flash（或 gemini-3.1-flash-lite）

到此，OpenRouter 充值方案可以暂不执行。对于"只要 Gemini"这个需求，新加坡节点 + 直连 Google + Flash 系列免费模型已经够用。

11 新用户实测：2.5 系列已不可用，3.x 必填 preview

22:26，按第 10 节的最终配置，在客户端把模型名填成 gemini-2.5-flash 后，Google 返回 404，报错信息为：

This model models/gemini-2.5-flash is no longer available to new users. Please update your code to use a newer model for the latest features and improvements.

这说明 Google 对新注册 API 用户已经下线了 2.5 系列。虽然 AI Studio 的 Rate limit 页面仍显示 2.5 系列有额度，但新 key 实际无法调用——这是 2025 年中后期的策略变化。

新用户该用什么模型

从第 10 节的配额表看，3.x 系列才是新用户可用的免费模型：

注意：我之前直接填 gemini-3.1-flash-lite 失败，很可能是因为 OpenAI 兼容层只暴露 preview 版本。原生端点 /v1beta/models 列出的是 models/gemini-3.1-flash-lite，但兼容层 /v1beta/openai 实际支持的是 gemini-3.1-flash-lite-preview（或带日期后缀的完整版本）。

验证兼容层真实支持的模型名

访问这个地址，看 OpenAI 兼容层实际返回什么：

https://generativelanguage.googleapis.com/v1beta/openai/models?key=我的GoogleKey

把返回的 gemini-3.1 相关模型名原样填进客户端，基本就能用。

修正后的最终配置（新用户版）

• Base URL：https://generativelanguage.googleapis.com/v1beta/openai
• API Key：我用的 Google AI Studio Key
• 模型名：gemini-3.1-flash-lite-preview（或 gemini-3.5-flash）

12 修正：OpenAI 兼容层没有 /models 端点

22:28，按第 11 节的建议访问 https://generativelanguage.googleapis.com/v1beta/openai/models?key=...，Google 返回 404：

"error": { "code": 404, "message": "Requested entity was not found.", "status": "NOT_FOUND" }

这说明 Google 的 OpenAI 兼容层只实现了 /chat/completions，没有实现 /models。所以没法像原生 API 那样列模型清单来查名字，只能直接调用 chat/completions 试错。

修正后的验证方法

用 curl 或客户端直接发一条最小请求，逐个模型名测试：

curl -X POST https://generativelanguage.googleapis.com/v1beta/openai/chat/completions \
  -H "Authorization: Bearer 我的GoogleKey" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-lite-preview",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens": 10
  }'

如果返回正常回复，说明模型名可用；如果报错，再换下一个。注意：gemini-2.5-flash 返回的 404 不是"路径不存在"，而是"模型对新用户不可用"，这反而证明 /chat/completions 本身是通的。

建议按这个顺序试

1. gemini-3.1-flash-lite-preview（免费层额度最多：15 RPM / 500 RPD）
2. gemini-3.5-flash（稳定版，5 RPM / 20 RPD）
3. gemini-3-flash（备选，5 RPM / 20 RPD）

13 实测闭环：curl 直连成功，确认最终可用配置

22:32，按第 12 节的修正方法，在终端用 curl 直接调用 chat/completions 实测 gemini-3.1-flash-lite-preview，经新加坡节点（本地代理 127.0.0.1:1087）直连 Google，返回正常结果：

curl -x http://127.0.0.1:1087 -X POST https://generativelanguage.googleapis.com/v1beta/openai/chat/completions \
  -H "Authorization: Bearer 我的GoogleKey" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-3.1-flash-lite-preview","messages":[{"role":"user","content":"ping"}],"max_tokens":10}'

Google 正常回复 "content":"Pong! How can I help"，并带 usage 字段（prompt_tokens: 2, completion_tokens: 6, total_tokens: 8）。这证明整条链路完全打通：网络到 Google API 通、Key 有效、模型名正确，且免费额度可用（无 402 / 403）。

最终可用配置（新用户 · 经实测确认）

• Base URL：https://generativelanguage.googleapis.com/v1beta/openai
• API Key：我用的 Google AI Studio Key（以 AI... 或 AQ... 开头，不是 OpenRouter 的 sk-or-v1...）
• 模型名：gemini-3.1-flash-lite-preview（免费层 15 RPM / 250K TPM / 500 RPD）
• 网络：请求须经允许地区节点（实测新加坡可用），且终端/客户端须显式走代理

到此，本文开头的「国内直连 Gemini 报 502」问题被彻底解决——不需要 OpenRouter 充值，不需要任何中转，直连 Google + 免费 Flash 模型即可。OpenRouter 仍是「一个 key 调所有模型」的便利选项，但对「只要 Gemini」的需求，直连是更省的方案。