如果你的团队已经在使用 CC Switch 或 NewAPI 风格的控制平面，那么把 Gemini 打开最快的方式，并不是在每个地方再加一个提供商凭据。更好的做法是在上线前先定义一个上游路由、一套模型命名规则、一次使用校验和一个生产评审关卡。
Google 现在通过更改 API key、base URL 和模型名称来文档化如何通过 OpenAI 库访问 Gemini。对于直接访问 Gemini，兼容 OpenAI 的 base URL 是 https://generativelanguage.googleapis.com/v1beta/openai/。对于希望在 Gemini 和其他提供商之间使用统一操作层的团队，Flatkey 提供了一个兼容 OpenAI 的统一路由 https://router.flatkey.ai/v1，其当前首页文案强调一个 key、一个 base URL，以及继续使用你现有的 SDK。
本指南面向生产应用，而不是个人兴趣演示。目标是帮助你以一种在流量切换前能够被工程、运维和安全团队审查的方式接入 Gemini。
快速答案：生产环境中应该改什么？
对于生产级 Gemini API 上线，在保存上游配置之前先锁定以下五件事：
| 项目 | 直接 Gemini 配置 | 适用于 CC Switch 或 NewAPI 风格客户端的单网关配置 |
|---|---|---|
| 认证来源 | 来自 Google AI Studio 的 Gemini API key，或导入的 Google Cloud 项目 | 在一个地方管理的单个网关 key |
| Base URL | https://generativelanguage.googleapis.com/v1beta/openai/ | https://router.flatkey.ai/v1 |
| 协议模式 | 兼容 OpenAI | 兼容 OpenAI |
| 模型策略 | 已批准的 Gemini 模型列表 | 已批准的 Gemini 模型列表，加上跨提供商回退策略 |
| 验证 | Google 侧的使用量和计费检查 | 网关请求日志、配额、模型映射以及下游审查 |
如果你的应用已经支持兼容 OpenAI 的上游，那么 Gemini 通常只是路由和策略工作，而不是完整的 SDK 重写。
为什么这份清单在 2026 年 7 月 17 日星期五如此重要
以下三个当前事实让生产清单比快速上手更重要：
- Google 的 Gemini 文档现在明确支持通过 OpenAI 库访问，这使团队可以轻松切换端点，而不必收紧审查纪律。
- Google 还说明，新创建的 AI Studio keys 默认会作为 auth keys 创建，并且标准 keys 将在 2026 年 9 月被拒绝，因此 key 类型和项目所有权也是上线决策的一部分。
- Flatkey 的公开配置文案强调一个 key、一个 base URL，以及保留现有 SDK；只有在团队同时标准化字段映射、日志记录和回滚时，这种方式才有意义。
开始之前
不要先打开 CC Switch 或 NewAPI。先从你希望上游满足的契约开始。
请使用以下最小预检清单：
| 检查项 | 需要确认的内容 | 重要原因 |
|---|---|---|
| 负责人 | 团队知道由谁负责 Gemini 密钥创建、轮换和配额 | 防止共享账户漂移 |
| 路由类型 | 你使用的是 OpenAI 兼容的上游，而不是混合的自定义适配器 | 保持字段映射简单 |
| 模型列表 | 你已经为此应用批准了一份 Gemini 模型 ID 清单 | 防止静默别名漂移 |
| 日志记录 | 你知道请求日志、用量和计费审查将在哪里进行 | 切换上线需要这些证据 |
| 回滚 | 你可以快速切回上游或模型策略 | 分阶段发布所必需 |
如果你没有这些答案，就还没有准备好将该设置视为生产就绪。
CC Switch 或 NewAPI 风格上游的字段映射
不同客户端对字段的命名不同，但生产环境中的映射应保持一致。
| 上游字段 | 本次发布的值 | 审查说明 |
|---|---|---|
| 提供商类型 | OpenAI-compatible | 除非客户端具有你打算运行的、已验证的 Gemini 原生模式，否则使用通用的 OpenAI 兼容模式 |
| API 密钥 | Flatkey key 或已批准的上游密钥 | 将其保存在单一密钥来源中，而不是每个用户的本地副本中 |
| Base URL | https://router.flatkey.ai/v1 | 使用单一路由进行集中控制 |
| 模型来源 | 手动允许列表，或在保存路由后获取 | 在向应用暴露返回的模型 ID 之前先审查它们 |
| 默认模型 | 已批准的 Gemini 生产模型 | 不要误把生产环境指向预览模型 |
| 备用模型 | 可选且有意设置 | 仅在模型命名和日志检查通过后启用 |
| 请求头 | 标准 Bearer 认证，除非你的客户端文档说明了额外字段 | 避免会破坏可移植性的临时请求头技巧 |
| 用量审查 | 请求日志加上配额或计费仪表板 | 必须纳入批准签字流程 |
这就是直接 Gemini 设置与网关设置之间最关键的运营差异：网关路径减少了凭据扩散，但由于更多应用可能继承同一个上游，因此更需要一个清晰的审查关卡。
第 1 步：决定这个应用需要直接使用 Gemini，还是使用单一网关
如果应用是隔离的、负责人明确，而且你现在不需要跨提供商路由，就使用直接 Gemini。
如果以下任一情况成立，就使用单一网关：
- 同一个客户端已经接触多个提供商。
- 有不止一名工程师或团队将管理该集成。
- 你希望在一个地方验证用量、配额或请求日志。
- 你预计之后会进行模型替换、回退或提供商扩展。
对于 CC Switch 和 NewAPI 风格的团队来说，第二条路径通常更容易长期支持，因为客户端保持一种与 OpenAI 兼容的形态，而路由策略则保持在上游。
步骤 2：锁定你将允许的确切 Gemini 模型 ID
不要把“Gemini”当作一个模糊的需求。为此应用和环境批准精确的模型 ID。
该评审应回答：
- 哪个 Gemini 模型是生产环境默认模型？
- 哪些模型仅允许用于测试？
- 预览模型是否完全允许在生产环境中使用？
- 应用会暴露模型选择器，还是只使用一个固定模型？
- 如果启用了回退，允许哪些非 Gemini 模型，以及在什么条件下允许？
很多团队就是在这里引发了本可避免的事故。他们把上游保存正确了，却把模型命名留得过于宽松，导致测试和生产表现不同。
如果你需要在路由上线后帮助对齐模型名称，请在将集成暴露给用户之前，先查看现有的 OpenAI-Compatible API Migration 指南。
步骤 3：保存一个上游并在获取模型前运行冒烟测试
输入 API 密钥和基础 URL 后，在导入或暴露完整模型列表之前先做一次冒烟测试。
你的冒烟测试应确认：
| 测试 | 预期结果 |
|---|---|
| 认证 | 上游接受该密钥，不会出现本地凭据错误 |
| 路由 | 一条简单的聊天补全请求能从已配置的基础 URL 返回 |
| 模型 | 确切的 Gemini 模型 ID 能成功解析 |
| 日志记录 | 你能在所选的审查界面中找到该请求 |
| 计费或配额 | 请求会显示在团队预期看到使用证据的位置 |
对于标准化使用单一网关的团队来说，这一点比获取模型列表更重要。获取模型列表只能证明客户端能看到名称，并不能证明生产请求路径是可审查的。
步骤 4：审查密钥类型和项目所有权
这一步很容易跳过，因为请求可能已经能工作了。
Google 当前关于密钥的指导就是不能跳过它的原因。Google AI Studio 现在默认创建认证密钥，未受限制的标准密钥已经被更严格地限制，而 Google 表示 Gemini API 将在 2026 年 9 月拒绝标准密钥。这意味着生产团队应将密钥类型视为上线准备的一部分，而不是后续清理任务。
使用这个简短审查：
| 问题 | 可接受的答案 |
|---|---|
| 谁拥有 Gemini 项目？ | 明确的负责人或团队 |
| 正在使用哪种密钥类型？ | 新生产环境建议使用认证密钥 |
| 密钥存储在哪里？ | 集中式密钥管理器或受控的平台密钥 |
| 将如何轮换？ | 有文档记录的负责人和流程 |
| 如果使用量激增会怎样？ | 存在计费告警或配额审查路径 |
如果你通过一个网关进行集中管理，那么对网关密钥和下游提供商账户也做同样的审查。
步骤 5：决定应用是否应直接向用户暴露 Gemini
不要默认答案一定是“是”。
在许多生产应用中，更好的模式是：
- 先将 Gemini 路由到上游。
- 验证日志、延迟和使用情况审查。
- 将模型放在功能开关或内部允许名单之后。
- 仅在审查门通过后再向最终用户暴露它。
这在 CC Switch 和 NewAPI 风格的环境中尤其有用，因为一次配置变更可能会影响多个操作人员或应用路径。
步骤 6：添加生产审查门
这正是大多数设置指南会遗漏的部分。在流量迁移之前，要求有一个简短的审查门，某个人可以一次性批准。
请使用这份确切的检查清单：
| 审查门项目 | 通过条件 |
|---|---|
| 字段映射 | API 密钥来源、基础 URL、提供商模式和默认模型均已记录 |
| 冒烟测试证据 | 已记录一条成功请求及其最终路由 |
| 模型允许名单 | 应用中仅可使用已批准的 Gemini 模型 ID |
| 使用可见性 | 已确认请求日志或计费审查路径 |
| 密钥所有权 | 已指定密钥负责人和轮换路径 |
| 回滚 | 可以快速恢复之前的上游或模型策略 |
| 范围 | 团队知道此次变更会影响一个应用、一个工作区还是多个客户端 |
这是最简短、但仍能保护发布过程的设置文档。
步骤 7：在启用回退之前，先决定其工作方式
如果你使用的是单一网关，往往会想立即开启回退。除非你能回答以下两个问题，否则不要这样做：
- 什么故障条件应触发回退？
- 对于相同的用户可见任务，回退模型的行为是否可接受？
对于 Gemini 生产发布而言，回退通常在首次切换之后更安全，而不是在切换期间。先证明主路径可用，然后再添加带有独立测试证据的回退。
步骤 8：从应用本身验证路由，而不只是从本地脚本验证
本地 curl 测试是必要的，但不充分。
从真实应用路径执行一次验证，并确认：
- 应用使用的是预期的上游。
- 返回的模型是预期的 Gemini 模型。
- 可观测性中显示的是同一条请求。
- 任何应用层超时、重试或配额行为仍然正常工作。
当应用存在旧环境变量、缓存的模型名称，或与执行首次测试的工程师不同的密钥来源时，生产问题就会在这里暴露出来。
CC Switch 和 NewAPI 风格团队的推荐发布方式
使用分阶段发布，让控制平面保持简单：
- 添加一个兼容 OpenAI、支持 Gemini 的上游。
- 测试一个已批准的 Gemini 模型。
- 确认日志和使用情况审核。
- 仅向内部用户公开该模型。
- 仅在主路径稳定后再添加回退。
- 只有在第一个应用通过审核门禁后，才扩展到更多应用。
Flatkey 的实时路由提示在这里很有用，因为同一个基础 URL 可以保持不变，而你的模型策略会随着时间变得更加严格。如果你在发布前要比较成本或采购影响，实时的 定价页面 是下一步应该查看的内容。
可在内部批准的简短设置文档
如果你想要一份可审查的交接材料，请将以下结构复制到你的内部设置说明中：
| 字段 | 值 |
|---|---|
| 应用名称 | |
| 上游负责人 | |
| 提供商模式 | 兼容 OpenAI |
| 基础 URL | https://router.flatkey.ai/v1 |
| API 密钥来源 | |
| 已批准的 Gemini 模型 ID | |
| 已启用回退 | 是或否 |
| 使用情况审核界面 | |
| 计费或配额审核界面 | |
| 回滚操作 | |
| 审查人 | |
| 批准日期 |
这样的结构已经足以批准一次 Gemini 上线，而无需把设置写成一份冗长的架构备忘录。
如果你的团队还在同一个控制平面中使用 Claude Code，那么实时的 CC Switch Claude Code 与 Flatkey 和 NewAPI 的设置 文章是一个很有用的补充，因为它从客户端侧展示了相同的运维模式。
常见问题
在兼容 OpenAI 的客户端中进行生产环境 Gemini 上线，最安全的基础 URL 模式是什么？
最安全的模式是每个环境使用一个经过审核的基础 URL。对于直接访问 Gemini，Google 文档中提供的是 https://generativelanguage.googleapis.com/v1beta/openai/。对于集中式网关上线，请使用单一已批准的网关路径，并将该值纳入配置控制。
我是否应该为每个 CC Switch 或 NewAPI 客户端使用单独的 Gemini 凭证？
通常不需要。对于生产团队来说，一个受控的密钥来源比散落在各处的本地凭证更安全。其代价是你必须增加审核门禁，因为更多客户端可能会继承同一路径。
在兼容 OpenAI 的应用中使用 Gemini，我需要替换 SDK 吗？
通常不需要。Google 当前的 Gemini 文档明确支持通过修改密钥、基础 URL 和模型名称来使用 OpenAI 库。真正需要做的是验证路由策略、模型命名、日志记录和所有权。
2026 年 Gemini API 密钥有什么变化？
截至 2026 年 7 月 17 日星期五，Google AI Studio 默认将新密钥创建为身份验证密钥，警告未限制的标准密钥不适合长期使用，并表示 Gemini API 将在 2026 年 9 月拒绝标准密钥。团队应在切换到生产环境之前审查密钥类型。
我应该在什么时候为 Gemini 启用回退？
在主 Gemini 路由稳定之后。先通过最终应用路径验证一个已批准的 Gemini 模型。然后，仅当触发条件和备份模型行为对同一工作流可接受时，再添加回退。
在批准设置文档之前，我应该检查什么？
检查准确的基础 URL、密钥来源、已批准的 Gemini 模型 ID、一条成功的请求日志、使用情况审查界面以及回滚操作。如果其中任何一项缺失，则该设置尚未准备好用于生产批准。
