Google AI Studio API Key 是 Gemini Developer API 的调用凭据。它本身不是付费套餐，不附带一份独立额度，也不能替代地区、年龄、项目权限或账单条件。
对中国大陆读者来说，第一步不是找“隐藏入口”或购买别人生成的 Key，而是查看 Google 当前的 AI Studio 与 Gemini API 可用地区。截至 2026 年 8 月 29 日，本轮核验的官方列表没有中国大陆；页面同时写明 18 岁以上和年龄验证要求。如果 direct route 不符合当前条件，应在这里停止，不使用虚假地区、账单地址、他人身份或来路不明的 Google Key 绕过。
如果你在官方支持地区实际使用、账号也符合条款，下面这条路径能把“拿到一串字符”变成可管理、可验证的接入。
先确定 Key 归谁，而不是先复制
每枚 Gemini API Key 都关联一个 Google Cloud 项目。项目承载成员、权限、普通用量与账单关系；Key 只是请求携带的秘密凭据。
打开 Google AI Studio API Keys，使用真正应该管理该项目的账号登录。个人实验可以使用个人项目；团队或公司接入应先确定组织账号、项目管理员、账单负责人和轮换责任，避免把生产 Key 留在离职后无人控制的个人账号中。
Google 当前的 API Key 文档区分了两类常见状态：
- 新用户接受条款后，AI Studio 可能自动建立默认 Cloud 项目和 API Key；
- 已有 Google Cloud 项目的用户，需要在 Dashboard → Projects 导入目标项目，再到 API Keys 页面创建 Key。
创建前记下 project ID。它比展示名称更适合以后核对账单、限额、日志和部署环境。若 Create API key 不可用并提示没有权限，问题属于 project import 或 IAM，不是多点几次按钮就会恢复。应让项目管理员按官方页面核对项目读取、Key 创建、服务启用、service account 与 binding 所需的最小权限。
新建 Key 要看类型：旧 standard 教程正在失效
AI Studio 现在新建的是 authorization key（auth key），它绑定到 Google Cloud service account，并默认限制为 Gemini API。Google 当前文档还写明：Gemini API 计划在 2026 年 9 月拒绝 standard key。
这个日期和执行状态都属于易变事实。创建后查看 Key Type 列；迁移生产服务前重新打开官方 Key 文档，而不是沿用旧视频中 unrestricted standard key 的做法。旧 Key 显示 blocked、standard 或 unrestricted 时，也不要在客户端继续分发它。
把密钥放进环境，不放进仓库和浏览器
密钥应像密码一样处理。泄漏者可以消耗项目额度，启用付费后还可能造成意外账单。以下位置都不安全：
- Git 仓库、示例代码和提交历史；
- 前端 JavaScript、浏览器扩展或移动 App 包；
- issue、聊天截图、终端录屏和完整环境变量导出；
- 带
?key=的公开 URL、分析日志或错误上报。
本地开发时，Google SDK 能读取 GEMINI_API_KEY 或 GOOGLE_API_KEY。两者同时存在时，GOOGLE_API_KEY 优先；“明明换了 Key 但请求没变”经常由这个优先级造成。
bashexport GEMINI_API_KEY="YOUR_API_KEY"
示例里的值只是占位符。真实服务应在后端读取 secret manager 中的值，让浏览器调用自己的后端，而不是直接获得长期 Key。你可以只检查变量是否存在，不打印内容：
bashif [ -n "${GEMINI_API_KEY:-}" ]; then echo "GEMINI_API_KEY 已设置" else echo "GEMINI_API_KEY 未设置" fi
用当前 quickstart 做一次最小验证
Google 当前 Gemini API 快速开始使用 Interactions endpoint 和 gemini-3.7-flash。下面的 canary 把 Key 放在请求头中，不把它写进 URL：
bashcurl -sS -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \ -H "x-goog-api-key: $GEMINI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gemini-3.7-flash", "input": "请用一句短句确认连接成功。" }'
成功标志不是模型必须返回某句固定文案，而是请求到达预期 hostname，使用目标项目的凭据通过鉴权，并返回带完成状态和模型输出的结构化对象。模型 ID 与 API surface 会变化；若官方 quickstart 已经换了示例，就用新示例更新 canary，不从旧博客猜名称。
失败时只保留能诊断的证据
一次同时更换 Key、项目、endpoint 和模型，会让原始问题消失在变量里。先保存这些信息：HTTP 状态、脱敏 error body、project ID、hostname、model、UTC 时间、request ID；绝不保存完整 Key。
| 可观察结果 | 应查的责任边界 | 最小下一步 |
|---|---|---|
| 还没进入 Key 页面就被拦截 | 地区、年龄、账号验证、组织策略 | 复核官方地区与账号提示；direct route 不符合就停止 |
| 创建按钮不可用 | 项目导入与 IAM | 核对 project ID，让管理员补最小权限 |
403 PERMISSION_DENIED | 实际生效的 Key、项目、限制或调用动作 | 固定配置，按 Gemini API Key 403 排障检查 |
429 RESOURCE_EXHAUSTED | 该项目、模型、tier 的 live limit | 到 AI Studio 查看实际限额，再用限额指南诊断 |
| 模型或 route 不存在 | 当前 model ID 与 API 版本 | 从官方 quickstart 复制当前例子，只重试一次 |
| 暂时性服务端错误 | 服务状态和 retry 策略 | 有上限的指数退避，不创建新 Key |
这张表也说明：Key 能用不等于容量够，项目付费不等于正在使用正确 Key，AI Studio 能看到某模型也不等于同一 API route 免费可调用。
最后再判断免费层和付费层
创建 Key 通常不收“Key 费用”。Free 只覆盖部分模型和 serving mode，当前 RPM、TPM、RPD 等值以 AI Studio 对选中项目和模型显示的 active limits 为准。不要把一张 Key 当作一份新的免费池；同项目多建 Key 也不会自然增加容量。
首个请求成功后，再根据真实工作负载决定是否关联 billing account、是否进入 Prepay，以及选择哪种模型。价格和账单的完整判断交给 Gemini API Key 价格与接入路线，并在使用当天核对 Google 的实时价格页。
准备投入服务前，至少记录 project ID、凭据 owner、Key Type、secret 保存位置、轮换负责人、允许调用的后端、当前模型、AI Studio live limit 与 billing 状态。这样即使人员、模型或额度变化，也能知道应该撤销哪枚 Key、检查哪个项目，而不是重新到处“找 Key”。
