Google AI Studio API Key 获取与设置：创建后先查这 6 个可用性问题

先从 Google AI Studio 的 API Keys 页面创建 Gemini API key。创建成功只说明你拿到了入口，不代表第一次 API 调用一定能跑通；真正决定可用性的，是这个 key 绑定的 Google Cloud 项目、所在地区、计费或 free tier 状态、目标模型、active limits，以及 key 是否已经泄露或被限制。

写代码前先按这 6 项检查，比反复新建 key 更快：

Google AI Studio API Key 该从哪里创建？

官方路线是打开 Google AI Studio API Keys，登录 Google 账号，选择或创建一个 Google Cloud 项目，然后创建 Gemini API key。Google 的 Gemini API key 文档把这个关系说得很清楚：Gemini API 调用需要 API key，而 key 会关联到一个 Google Cloud 项目。

这个项目归属非常重要。API key 不是一串孤立密码，它背后有项目、权限、计费、使用量和限制。你在 AI Studio 里看到的 key，可能来自默认项目，也可能来自你手动选择的项目；团队协作时，一个同事发来的 key 也可能属于他的项目，而不是你的预算和权限边界。

创建后只复制一次 key，并立刻放到安全位置。Google 文档允许你在初始测试中临时 hardcode key，但这不是安全做法。真正进入开发环境后，应使用 GEMINI_API_KEY 或 GOOGLE_API_KEY 这类环境变量，或者使用服务端密钥管理工具。不要把 key 写进前端代码、移动端包、公开 Git 仓库、截图或聊天记录。

如果 AI Studio 页面没有直接显示某个受限 key，不代表 key 不存在。Google 说明 AI Studio 只显示 unrestricted keys 或限制到 Generative Language API 的 keys；更细的 key restrictions 需要回到 Google Cloud Console 管理。普通个人开发者最容易出错的不是按钮找不到，而是看错项目、拿错 key、把前端公开环境当成服务器环境。

创建后先检查哪 6 个可用性问题？

key 创建完以后，先不要把所有失败都归因于代码。第一次 Gemini API 请求能不能成功，通常由六个状态共同决定。

这 6 项的顺序也有意义。先确认项目，因为项目决定你看到的计费和限额是否是同一个对象。再确认地区，因为地区不支持时，后面的代码优化没有意义。然后看 billing/free tier 和模型，因为免费层与模型可用性不是一回事。最后看 active limits 与 key 安全，这两类问题经常在“昨天还可以，今天突然失败”的场景里出现。

如果你已经有一个相邻问题，比如只想知道 Gemini API 免费层还剩什么，可以看 Gemini API 免费层限制：现在还免费什么、实时额度去哪查、什么时候该开通付费项目。当前页面只负责把 API key 从创建到首次请求的可用性链路梳清，不复制一张会很快过期的限额表。

怎么把 key 放进本地环境并做第一次请求？

本地测试的目标不是跑一个华丽 demo，而是用最小请求证明三件事：key 能被读取、项目可以调用目标模型、当前限制没有立即阻断请求。

最小环境变量可以这样放：

hljs bash复制
export GEMINI_API_KEY="你的真实 key 放在本机或服务器环境变量里"
export MODEL_ID="从当前官方 model docs 选择的模型 ID"

测试请求可以保留成最短的健康检查。下面的形状强调的是边界：key 从环境变量读取，模型 ID 不写死旧教程值，请求内容保持小而可重复。

hljs bash复制
curl "https://generativelanguage.googleapis.com/v1beta/models/${MODEL_ID}:generateContent?key=${GEMINI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          { "text": "Reply with one short sentence." }
        ]
      }
    ]
  }'

如果你使用官方 SDK，也保留同样原则：从环境变量读取 key，用当前 model docs 里的模型 ID，先发一个短请求，再逐步增加上下文、工具、文件或并发。不要一上来就把真实用户流量、长文档、批处理任务、前端页面和重试队列都压到同一个新 key 上。

前端项目尤其要停一下。Gemini API key 是可计费凭证，不适合直接暴露给浏览器。即使你只做测试，也不要把 key 写进 NEXT_PUBLIC_、客户端 bundle、移动端反编译后能看到的位置，或者任何会被用户下载的文件。更安全的结构是：浏览器请求你的后端，后端从私有环境变量读取 key，再调用 Gemini API。

免费 API key 是否等于免费额度？

不等于。API key 可以免费创建，但 key 本身不是额度池。Google 的 rate limits 文档把限制放在项目和模型维度上，active limits 需要回到 AI Studio 查看；同一个项目里的多个 key 通常共享同一项目限制。

Google 的 billing 文档还把 free tier 和 paid tier 分开。新账号可能从 Free Tier 开始，并且只能访问某些模型；Paid Tier 需要关联有效 billing account 并预付。当前官方 billing 页面还提示，新设置可能需要最低 10 美元预付，这类金额和门槛都属于易变事实，应该以你打开页面时看到的官方说明为准。

开发、学习、小型原型可以从 free tier 开始。只要要处理真实用户、敏感数据、稳定吞吐、客户演示或长期服务，就应该提前把付费项目、预算告警、数据边界和失败恢复流程规划好。免费层适合验证，不适合替代容量规划。

地区不支持或 403 时怎么判断？

地区问题必须按 API 路线判断。Gemini 网页、Gemini App、Google AI Studio、Gemini API、Vertex AI 不是同一张地区合同。对于 API key 设置，应该看 Google AI Studio / Gemini API available regions。

截至 2026 年 4 月 27 日，官方 Gemini API 可用地区页包含 Taiwan；Mainland China、Hong Kong、Macao 没有出现在 AI Studio/Gemini API 支持列表中。这个判断只适用于 Google AI Studio / Gemini API 路线，不能反推 Gemini 网页、移动 App、Workspace 或 Vertex AI 的可用性。

遇到 403 PERMISSION_DENIED，先把它当成 owner 状态问题，而不是马上改代码。Google 的 troubleshooting 文档列出的常见方向包括 wrong key、权限不足、free-tier region 不支持、认证方式不匹配等。正确排查顺序是：确认 key 属于正确项目，确认地区和 free tier 条件，确认 billing 状态，确认模型是否对该项目可用，再看代码请求。

如果你正在处理更宽的 Gemini 地区不可用问题，可以转到 Gemini 目前不支持你所在的地区？先分清网页、App 和 API 的解决路线。那类页面负责入口分流；这里保留在 AI Studio API key 和 Gemini API 调用链路内。

429、模型不可用、key 泄露分别怎么恢复？

429 RESOURCE_EXHAUSTED 通常意味着某个速率限制维度耗尽。不要只看请求次数，也要看 token、并发、模型、项目层级和当日限制。Google 的 rate limits 页面说明限制可能包含 RPM、TPM、RPD，RPD 会在 Pacific Time 午夜重置，并且实际容量可能随项目和模型状态变化。

恢复顺序可以直接按成本从低到高排：

1. 在 AI Studio 确认当前 key 背后的项目。
2. 看 active limits 里是 RPM、TPM、RPD 还是其他维度触顶。
3. 降低并发，加入指数退避，停止无意义重试。
4. 缩短 prompt，缓存重复请求，拆分批处理。
5. 检查目标模型是否需要 paid tier 或更高额度。
6. 正常流量仍然触顶时，申请 quota increase 或迁到启用计费的项目。

模型不可用时，不要从旧教程里换另一个看起来相似的 ID。Google 的 models 页面会标注当前模型状态。一个典型例子是 Gemini 3 Pro Preview 已在 2026 年 3 月 9 日 shut down，官方要求迁移到 Gemini 3.1 Pro Preview。所以更稳的做法不是记住某个历史 ID，而是让代码配置明确指向当前文档中仍可用、符合项目计费和地区状态的模型。

key 泄露的恢复更直接：不要继续复用旧 key。Google troubleshooting 文档说明，Google 可能主动阻断被报告泄露的 API key，并要求生成新 key。泄露后应创建新 key、更新环境变量或 secret manager、删除公开位置里的旧 key、检查使用量和账单异常，再把旧 key 禁用或删除。

安全处理不是最后一步，而是 setup 的一部分。只要 key 被放到公开仓库、前端 bundle、截图、issue、日志或第三方在线工具里，就要按泄露处理。真正可靠的 key 设置应该能回答三个问题：谁能读取 key、哪里记录了调用、泄露后谁负责轮换。

AI Studio、Vertex AI、Android Studio 和第三方 gateway 有什么区别？

很多教程把这些路线混在一起，所以读者才会在创建 key 后继续困惑。它们不是同一个合同。

对于当前任务，首选仍是官方 AI Studio API key 路线。只有当你明确需要 Google Cloud IAM、区域 endpoint、企业治理或现有 GCP 项目时，才优先评估 Vertex AI。只有当你需要第三方平台承担接入、计费或多模型兼容时，才把 gateway 当作另一份合同单独评估；不要把 gateway 当成“官方地区限制已经不存在”的证明。

最小可用检查清单

真正设置完成，不是页面上出现了一串 key，而是你能稳定回答这些问题：

如果这张表有任何一项答不上来，API key 还只是“创建了”，不是“可用于真实调用”。把这 8 个问题确认完，再把 key 接入应用，后面的错误会少很多，也更容易定位。

常见问题

Google AI Studio API key 是免费的吗？

创建 key 本身通常不收费，但 key 不是免费额度承诺。能不能免费调用取决于目标模型、项目、地区、free tier、billing 和 active limits。准确状态要看 Google 当前 pricing、billing 和 AI Studio 项目视图。

我应该用 GEMINI_API_KEY 还是 GOOGLE_API_KEY？

Google 的 API key 文档说明，Gemini API libraries 可以使用 GEMINI_API_KEY 或 GOOGLE_API_KEY。团队项目里建议统一一个变量名，并在部署文档里写清楚来源、作用域和轮换流程。

多创建几个 API key 能增加 Gemini API 额度吗？

不能把它当成扩容办法。限制按项目、模型和层级判断，不是按同项目 key 叠加。多个 key 适合环境隔离、轮换和权限管理，不适合绕过 active limits。

为什么刚创建的 key 就 403？

常见原因包括 key 属于错误项目、权限不足、使用地区不支持、free tier 条件不满足、billing 状态不对，或者认证方式与 API 路线不匹配。先按项目、地区、billing、模型顺序查，不要先重写业务代码。

为什么昨天能用，今天变成 429？

可能是 RPM、TPM、RPD 任一维度触顶，也可能是流量、重试、模型或项目层级变化。打开 AI Studio 的 active limits 看当前项目，而不是只看代码日志。

Mainland China、Hong Kong、Macao 能直接用 Google AI Studio / Gemini API 吗？

截至 2026 年 4 月 27 日，这三个地区没有出现在官方 Google AI Studio / Gemini API available regions 列表中；Taiwan 出现在列表中。地区支持会变化，发布或部署前应重新核对官方页面。

Gemini 网页能用，是否代表 Gemini API key 也能用？

不代表。Gemini 网页、App、AI Studio、Gemini API、Vertex AI 是不同入口，地区、账号、计费和合规边界不同。API key 设置应按 Google AI Studio / Gemini API 文档判断。

key 泄露后还能继续使用吗？

不应该。Google 可能阻断被报告泄露的 key。正确恢复方式是创建新 key，更新服务端环境变量或 secret manager，移除公开位置中的旧 key，检查异常使用量，然后禁用或删除旧 key。

Vertex AI 和 AI Studio API key 该选哪个？

个人开发、原型和快速后端接入通常先用 AI Studio / Gemini API key。已经在 GCP 上有企业治理、IAM、区域 endpoint、预算和合规要求的团队，更适合评估 Vertex AI。

代码示例里应该固定哪个模型 ID？

不要从旧教程里固定一个 preview ID。先查当前 Google model docs，确认模型仍可用、适合你的项目、地区和计费状态，再把模型 ID 放进可配置变量。模型状态变化时，配置应能独立更新。