深色模式
Gemini API Key 怎么获取？AI Studio 申请、免费额度、价格与 400/429 报错排查（2026）
核查日期：2026 年 10 月 6 日。 Google 会按模型、项目、地区、账号状态和计费层级调整价格、免费层和速率限制。本文只说明核验路径，不把旧截图或固定数字当成当前承诺。
如果你搜索“Gemini API Key 怎么获取”，通常想解决的是四件事：在哪里创建 Key、免费额度是否还在、Python 或 REST 怎么调用，以及为什么请求返回 400、403 或 429。先记住一个边界：Gemini 网页版会员、Google AI Studio 和 Gemini API 不是同一个计费账户。 API Key 绑定的是项目，实际额度和权限要在 AI Studio 或 Google Cloud 的当前页面确认。
想先比较兼容 API 入口？
如果你暂时没有合适的官方网络、支付或项目配置条件，可以自行查看 ZeoAPI 注册入口。ZeoAPI 是独立第三方服务，不是 Google、Gemini 或 Google Cloud 官方平台；链接含推荐参数，是否注册和购买完全自愿。使用前请在登录后的页面核对实际模型 ID、Base URL、价格、额度、日志、退款和数据处理规则，不要把第三方 Key 当作 Google 官方 Key。
先看官方入口和实时页面
| 目的 | 官方页面 | 应该核对什么 |
|---|---|---|
| 创建或查看 Key | Google AI Studio | 项目、API Keys、可见模型和当前权限 |
| API Key 说明 | Using Gemini API keys | Key 与项目关系、环境变量和安全措施 |
| 第一次调用 | Gemini API Quickstart | 当前 SDK、接口路径和示例模型 |
| 模型名称 | Models | 精确 model ID、稳定/Preview 状态和弃用提示 |
| 价格 | Gemini API pricing | 输入、输出、缓存、批处理和工具计费 |
| 速率限制 | Rate limits | RPM、TPM、RPD、项目层级和使用层级 |
| 错误排查 | Troubleshooting · API errors | HTTP 状态、错误码和重试条件 |
| 地区 | Available regions | AI Studio 与 Gemini API 当前支持地区 |
官方文档域名可能从 ai.google.dev 跳转到新的文档页面；发布前应打开链接，确认页面内容和你的账号页面一致。
Gemini API Key 的申请步骤
1. 登录 Google AI Studio
打开 aistudio.google.com，登录 Google 账号并接受页面要求的条款。服务是否对你的账号开放，取决于地区、年龄、账号类型和组织策略。若页面提示地区不可用或需要验证，先处理账号条件，不要把第三方页面宣传的“无需 Google 账号”当作官方规则。
2. 创建或导入项目
每个 Gemini API Key 都关联一个 Google Cloud project。Google AI Studio 对新用户可能自动创建默认项目和 Key；已有 Google Cloud 项目通常需要在 AI Studio 的 Dashboard → Projects 中导入后才能选择。
建议为不同应用分开使用项目，至少不要把个人测试、生产服务和客户项目共用同一个 Key。项目分开后，配额、账单、权限和撤销操作更容易追踪。
3. 在 API Keys 页面创建 Key
进入 AI Studio 的 Get API key / API keys 页面，选择项目并点击 Create API key，按页面提示完成 Key 与项目的绑定。若按钮不可用，常见原因是当前账号没有项目权限、Generative Language API 没启用，或者组织策略禁止创建 Key；这时查看页面给出的 IAM 权限提示，或改用自己有管理权限的新项目。
创建后立即把 Key 保存到密码管理器或密钥管理系统。不要把真实 Key 粘贴到文章、截图、浏览器前端、公开仓库或聊天记录中。
4. 配置环境变量
官方客户端可以从 GEMINI_API_KEY 或 GOOGLE_API_KEY 读取密钥；如果两个变量同时存在，客户端可能优先使用 GOOGLE_API_KEY。为避免调错项目，建议只保留一个变量，并在部署平台的 Secret 设置中保存。
Windows PowerShell：
powershell
$env:GEMINI_API_KEY = "你的_API_Key"macOS 或 Linux：
bash
export GEMINI_API_KEY="你的_API_Key"生产环境应使用部署平台的 Secret、Google Cloud Secret Manager 或同类密钥服务。若怀疑泄露，先创建替代 Key 并更新应用，确认新 Key 生效后再禁用旧 Key，同时检查 Usage 和账单日志。
Python 最小调用示例
Google 当前 Quickstart 使用 google-genai SDK 和 Interactions API。先安装 SDK：
bash
pip install -U google-genai然后从环境变量读取 Key：
python
from google import genai
client = genai.Client() # 自动读取 GEMINI_API_KEY
# 用 AI Studio 的 Models 页面确认可用的精确 model ID。
model_id = "在官方模型目录中确认的模型 ID"
interaction = client.interactions.create(
model=model_id,
input="用三句话解释什么是 API，并标出需要核验的事实。",
)
print(interaction.output_text)如果你要复现 Google 文档中的示例，可以把 model_id 暂时替换为 Quickstart 当前显示的示例型号；生产代码不要盲目复制旧文章中的 gemini-* 名称。模型可能被标记为 stable、preview、latest 或 experimental，生命周期和限额不同。
REST 最小调用示例
当前官方 Quickstart 的 Interactions API 示例使用 v1beta/interactions 和 x-goog-api-key 请求头：
bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "在官方模型目录中确认的模型 ID",
"input": "用一句话说明 API Key 应该放在哪里。"
}'返回对象可能包含 interaction ID、状态、模型和 usage 信息。不要只判断 HTTP 200；生产程序还应检查返回状态、输出是否为空、usage 是否能和账单对上。
网上仍有大量 generateContent 的旧示例。那类示例的路径、请求体和响应结构与 Interactions API 不完全相同。使用旧接口时，应打开对应的 官方 API Reference，不要把一个接口的 JSON 直接套到另一个接口上。
免费额度、价格和速率限制怎么查
免费层不是一个固定的“每月多少次”
Google 的免费层按模型和项目的实时规则计算，可能涉及 RPM、TPM、RPD、图片或搜索调用等不同维度。不同模型的免费层不一定相同，Preview 或实验模型也可能有更严格的限制。请在 AI Studio 的项目页面、Usage 页面和 Rate limits 页面查看当前值。
价格不要从旧文章复制
打开 官方 Pricing 页面，逐项核对：
- 输入 Token 与输出 Token 是否分别计费；
- 长上下文、缓存、批处理、图片、视频或搜索工具是否另计；
- 当前模型是 Free Tier、Paid Tier、Preview 还是其他计费层；
- 价格表的货币、有效期和模型 ID 是否与你的项目一致。
如果需要提高限额，AI Studio 可能要求为项目关联 Cloud Billing 并按页面流程预付或启用付费层。具体金额、资格和自动升级条件会变化，以 Billing 页面 和你的项目页面为准。
速率限制按项目核算
官方文档将常见限制分为：
| 指标 | 含义 | 排查方向 |
|---|---|---|
| RPM | 每分钟请求数 | 降低并发、合并请求或申请提高限制 |
| TPM | 每分钟输入 Token | 缩短上下文、限制输出、分批处理 |
| RPD | 每日请求数 | 等待重置或调整项目预算与任务队列 |
| IPM/其他模型维度 | 图片或特定能力的调用限制 | 查看对应模型的实时说明 |
这些限制通常按 project 而不是单个 API Key 计算；同一项目创建多个 Key 不会自动获得多份配额。RPD 的重置时间、模型层级和使用层级也应以官方页面为准。
400、403、429 报错排查表
| 状态 | 常见错误码或原因 | 处理顺序 |
|---|---|---|
| 400 | invalid_request、failed_precondition、参数或 JSON 不合法 | 检查请求体、字段拼写、API 版本、模型 ID、参数范围和计费前置条件；不要盲目重试 |
| 401 | Key 缺失、无效或过期 | 检查环境变量是否在当前进程生效、是否复制了多余空格、Key 是否已被禁用 |
| 402 | 预付余额或付费额度不足 | 查看 Billing 和余额；补足条件前重试没有意义 |
| 403 | permission_denied、项目或 Key 无权限 | 确认 Key 所属项目、API 服务、组织 IAM、地区和模型权限 |
| 404 | 路径或模型不存在 | 重新打开 Models 页面，复制精确模型 ID，并确认使用了对应 API 版本 |
| 429 | rate_limit_exceeded、quota_exceeded、too_many_requests | 查看 RPM/TPM/RPD 和项目使用层级；降低并发，使用指数退避，必要时申请提高限制 |
| 5xx | 服务暂时不可用或超时 | 只对瞬时错误做有限次数指数退避，并记录 request ID；不要无限重试 |
官方故障排查建议：对 429、408 和部分 5xx 使用指数退避与随机抖动；400、402、403 通常属于客户端、计费或权限问题，不应靠重复请求解决。Python 官方 SDK 可能已经提供部分重试逻辑，自己再包一层时要设置最大次数，避免请求放大。
400：先检查模型和请求格式
最常见的 400 原因是把网页模型名称当成 API model、把旧 generateContent 请求体发到 Interactions API，或使用了该模型不支持的参数。先用官方 Quickstart 的最小请求验证，再一次只改一个参数。
403：Key 有效不等于项目有权限
Key 能被识别，只代表身份验证通过；项目仍可能没有启用所需服务、没有相应模型权限、受组织策略限制，或当前地区不在 Available regions 列表。检查 Key 的项目归属和 AI Studio 的当前项目选择，不要把 Key 复制到另一个项目继续试。
429：先区分速率、每日配额和计费层
查看错误正文和 AI Studio Usage 页面，确认是 RPM、TPM、RPD 还是 spend-based limit。对短暂拥塞可以退避；如果是每日配额或项目计费层级，等待或调整项目设置才有用。把并发降到很低仍持续 429 时，通常应回到模型、项目和账单页面核验，而不是继续增加重试次数。
Gemini 网页会员和 API 有什么区别？
| 项目 | Gemini 网页/App | Gemini API |
|---|---|---|
| 使用方式 | 在 Gemini 产品中对话 | 用 Key 从程序发请求 |
| 账号权益 | Google 账号、Google AI 计划和产品权限 | Google Cloud project、API Key、模型和计费层 |
| 额度查看 | 产品内显示的消息、文件或功能限制 | AI Studio/Cloud 中的 RPM、TPM、RPD、Token 与账单 |
| 代码调用 | 通常不能直接当作服务端 API | 面向脚本、网站、Agent 和自动化 |
| 费用关系 | 网页订阅不等于 API 余额 | API 计费与项目设置单独核对 |
因此，购买 Gemini 网页会员不会自动生成可用于 API 的余额；拥有 API Key 也不代表网页端会开放同样的模型和功能。需要开发时，直接按 API 项目流程创建 Key 并查看官方价格页。
安全清单
- 不把 Key 写进浏览器 JavaScript、移动端安装包、Git 仓库或公开日志；
- 服务端只从环境变量或 Secret Manager 读取 Key；
- 测试、生产和不同客户项目使用分开的 Key 或项目；
- 在 Cloud Console 设置预算、账单告警和必要的来源/IP 限制；
- 发现泄露时先换 Key、更新部署、禁用旧 Key，再检查用量和账单；
- 上传 PDF、代码和客户资料前先脱敏，确认账号和平台的数据保留规则。
常见问题 FAQ
Gemini API Key 免费吗？
Key 本身的创建方式、可用模型和免费层由 Google 当前账号、项目和地区规则决定。不要把“能创建 Key”理解成所有模型永久免费；请查看 AI Studio 项目页、Pricing 和 Rate limits。
一个项目可以创建多个 Gemini API Key 吗？
通常可以，但多个 Key 仍关联同一项目，不能把项目配额拆成多份。更适合按应用隔离密钥，并为每个 Key 设置可撤销的使用范围。
为什么 AI Studio 能聊天，代码却返回 403？
AI Studio 界面权限与 API 项目权限不是一回事。先确认 Key、项目、模型 ID、API 版本、地区和计费状态，再查看错误正文；必要时用官方最小示例复现。
429 要不要马上申请更高额度？
先确认触发的是 RPM、TPM、RPD 还是 spend-based limit。降低并发和上下文能解决前两类瞬时问题；每日配额或付费层限制则需要等待重置或按官方流程调整项目。
国内可以直接申请 Gemini API Key 吗？
不能用一篇教程保证所有账号和网络都能申请。Google 会按地区、账号年龄、组织策略和服务状态判断可用性，请查看 官方地区列表 与登录后的页面。第三方平台的可用性、模型路由和数据规则需要单独核验。
Gemini API 和 OpenAI 兼容接口一样吗？
请求格式、模型 ID、鉴权头、计费和错误码都可能不同。若使用兼容层，应先阅读服务商文档并用无敏感数据测试，不能因为接口看起来相似就假设参数和能力完全相同。
相关阅读
- Gemini 3 Pro 国内使用指南：官网、AI Studio 与模型核验
- 2026 年 AI 聚合平台怎么选？模型、API 与 Key 安全
- ChatGPT API Key 与 Responses API 报错排查
- Grok API Python 教程：Responses API、密钥与错误处理
- Grok、ChatGPT、Claude 与 Gemini 模型对比导读
官方来源核查日期：2026 年 10 月 6 日。 模型 ID、价格、免费层、速率限制、地区和 API 行为可能继续变化；发布或部署前请重新打开上表中的官方页面核对。