Gemini API 的官方密钥入口是 aistudio.google.com/apikey,用 Google 账号登录、点 Create API key 即可生成以 AIza 开头的密钥,免费层无需绑卡。目前 API 主力为 Gemini 3.x Flash 系列(3.8 / 3.7 / 3.6 Flash 均为 $0.75 输入、$3.75 输出每百万 token),旗舰 Gemini 3.1 Pro 处于预览阶段。 Gemini API 官方入口与 AI Studio、Vertex AI 的区别
Gemini 的入口比多数人以为的多,走错门最典型的后果是:在 Gemini 网页版里聊得很开心,回头发现根本拿不到 API Key。下面把常用入口一次列全:
- API 密钥页:aistudio.google.com/apikey(亦可通过页面内 Get API key 进入),创建、复制、吊销密钥的直达入口。
- 官方模型清单:ai.google.dev/gemini-api/docs/models,查模型 ID、上下文长度与生命周期状态(Stable / Preview / 已下线)。
- 官方定价页:ai.google.dev/gemini-api/docs/pricing,按模型列出每百万 token 单价、缓存与批处理折扣。
- 可用地区列表:ai.google.dev/gemini-api/docs/available-regions,注册前务必先查这一页。
- 限额面板:aistudio.google.com/rate-limit 与 aistudio.google.com/usage,查看当前层级的 RPM / TPM / RPD 与用量。
- Vertex AI(Gemini Enterprise Agent Platform):Google Cloud 上的企业通道,提供 SLA、数据驻留、VPC 与 IAM,适合生产与合规场景。
注意区分:AI Studio 走的是「开发者 API」,注册即用、有免费层、密钥几秒钟生成;Vertex AI 走的是「企业云」,没有免费层,需要完整的 Cloud 项目与 IAM 配置,换来的是合规与容量保障。同一套 google-genai SDK 两边都能用,切换通常只改环境变量。
Gemini API Key 获取步骤与前置条件
免费层不需要信用卡,整个流程基本能在五分钟内走完:
- 用 Google 账号登录 aistudio.google.com(没有就先注册一个 Gmail);
- 首次进入时阅读并接受 Gemini API 服务条款与附加条款;
- 打开 aistudio.google.com/apikey,点击 Create API key;
- 选择「Create API key in new Google Cloud project」,让系统自动建一个项目(新手推荐,便于后续单独管额度);
- 密钥生成后立即复制保存,格式为 AIza 开头的一长串,建议直接写进环境变量 GEMINI_API_KEY 或密码管理器;
- 用一条 curl 或官方 SDK 的最小示例验证密钥可用,能拿到返回即表示打通;
- 若要用 Pro 级模型或提高配额,在 AI Studio 里为项目启用结算(Enable billing)。
前置条件:所在地区需在官方可用地区列表内、Google 账号满足年龄要求(18 岁以上),以及一个可正常访问 Google 服务的网络环境。缺任何一项,页面要么直接提示地区不支持,要么密钥生成被拦。
调用方式有两种。原生端点为 https://generativelanguage.googleapis.com/,配合 google-genai SDK 使用;如果已有基于 OpenAI SDK 的代码,可以走官方提供的 OpenAI 兼容层(https://generativelanguage.googleapis.com/v1beta/openai),多数情况下只改 base_url 和模型名即可复用,具体支持范围以官方文档为准。
Gemini API 的注意事项
- 密钥等同于账单:泄露的密钥会被爬虫在几分钟内扫到并盗刷,Google 官方也会主动封锁已泄露的密钥。不要写进前端、不要提交到 Git、不要出现在截图与群里。
- 地区准入是硬门槛:Gemini API 与 Gemini 网页版的支持地区列表不是同一份。能打开网页聊天,推不出能调 API,反过来也一样。
- 免费层不是全部模型都能用:Pro 级模型通常要求项目已启用结算。在不支持免费层的地区调用会直接返回 400 FAILED_PRECONDITION。
- 模型 ID 会过期:Gemini 迭代极快,3 Pro Preview 已于 2026 年 3 月 9 日下线,2.0 系列也在同年 6 月关停。生产代码请把模型名做成配置项,不要硬编码。
- 合规提醒:请在你所在司法辖区法律允许的范围内使用境外 API 服务,并遵守相关数据出境与内容合规要求。
Gemini 模型清单与最新 API 价格
截至本文核查时间(2026 年 9 月 9 日),Google 官方模型索引与定价信息整理如下。Gemini 3.x 已是稳定主力,2.5 系列作为上一代仍在服役:
| | | |
|---|
| | 最新 Flash,长程软件工程与 agent 工作流 | |
| | | |
| | | |
| | | |
| | | |
| | | |
| | 旗舰,复杂问题求解与 agentic 编码,上下文最高 2M | |
| | | |
Gemini 2.5 Pro / Flash / Flash-Lite | | | |
付费层标准单价(美元 / 每百万 token):
| | | | |
|---|
| | | | 促销价,2027-01-01 起恢复 $1.50 / $7.50 |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
| | | | |
省钱三板斧:一是批处理(Batch API)约 5 折,代价是放弃实时性,通常 24 小时内完成;二是上下文缓存,重复使用的长提示词走缓存读取价,折扣幅度接近九成,但缓存存储按小时计费,高频复用才划算;三是控制上下文长度,Pro 级模型一旦单次请求超过 200K token,费率直接跳档。
Gemini API 免费额度与计费规则
Gemini API 的免费层是它相对同价位产品最大的差异化:在支持的地区,用 Google 账号在 AI Studio 生成的密钥即可直接调用,不需要绑定信用卡,Flash 系列有免费额度可用于原型开发与轻量级生产。Pro 级模型与更高配额则需要为项目启用结算。
付费采用按量后付模式,按 token 计费,可在 Google Cloud 项目上设置预算与告警。Google 将用户划分为四个使用层级:Free、Tier 1、Tier 2、Tier 3。Tier 1 的门槛最低——只要为项目绑定并关联有效的结算账号即可升级;Tier 2 与 Tier 3 则要求累计消费达到一定金额并满足账龄天数,达到条件后系统自动提升,无需人工申请。
需要特别提醒:Google 官方速率限制文档已不再公布固定的每模型 RPM / TPM / RPD 表格,而是说明限额取决于你的使用层级,并引导用户前往 aistudio.google.com/rate-limit 查看当前账户的实际限额,且明确提示「所列限额不作保证,实际容量可能波动」。第三方流传的「免费层 15 RPM、1,500 RPD」一类数字仅供参考,不要拿它做容量规划,以你自己面板上显示的数值为准。
Gemini API 常见报错与排查
按 HTTP 状态码对照排查,比无脑重试高效得多。官方建议对 429 与 5xx 使用指数退避重试:首次约 1 秒,之后逐步加倍,并加入随机抖动;Python SDK 默认已内置该逻辑,最多重试 4 次、最大延迟 60 秒。
| | |
|---|
| | 对照 API 参考核对请求格式与 API 版本,新旧端点混用最容易踩 |
| | 在 Google AI Studio 为项目启用结算,或改用该地区支持的方式 |
| API 密钥没有所需权限,或试图使用未通过鉴权的微调模型 | 确认密钥正确、属于对应项目,并完成模型所需的鉴权流程 |
| | 检查请求参数是否适用于当前 API 版本,确认模型 ID 未下线 |
| 超出速率限制(RPM / TPM / RPD)或支出上限 | 降低请求速率或缩减请求大小,等待后重试,必要时申请提高配额 |
| Google 侧意外错误,输入上下文过长也可能触发 | |
| | |
| | 在客户端设置更大的 timeout,或改用流式输出 |
| | |
还有一类非报错的「假故障」值得单独说:模型因为安全过滤拒绝生成,或输出因 RECITATION 被截断。这类问题改代码没用,需要调整提示词表述、提高其独特性,或在合规前提下调整安全过滤阈值。
Gemini API 常见问题
Q:Gemini API 完全免费吗?
A:有免费层但不是全部免费。Flash 系列在支持的地区有免费额度且无需绑卡,Pro 级模型与高配额需要为项目启用结算。
Q:申请密钥需要信用卡吗?
A:免费层不需要。只有当你想用 Pro 模型、提升配额或进入付费层级时,才需要在 Google AI Studio 里给项目启用账单。
Q:密钥以什么开头,在哪里能再看到?
A:以 AIza 开头。在 aistudio.google.com/apikey 可以查看和管理已有密钥,但完整明文通常只在创建时展示一次,建议创建后立即存进环境变量或密码管理器。
Q:免费层的速率限制到底是多少?
A:官方已不再公布固定表格,改为按账户层级动态显示。请登录 aistudio.google.com/rate-limit 查看你自己账号当前的 RPM / TPM / RPD。
Q:怎么从免费层升到更高层级?
A:最省事的一步是给 Google Cloud 项目绑定有效结算账号,通常会从 Free 直接升到 Tier 1;再往上靠累计消费与账龄自动提升。
Q:Gemini API 和 Vertex AI 该选哪个?
A:原型、学习、小项目用 AI Studio 的开发者 API,几秒钟拿密钥、有免费层;需要 SLA、数据驻留、VPC、IAM 与审计的正式生产环境用 Vertex AI。
Q:已有的 OpenAI SDK 代码能直接复用吗?
A:可以走官方提供的 OpenAI 兼容层,把 base_url 指向 Google 的兼容端点、替换模型名即可,多数调用代码无需改动,具体覆盖范围以官方文档为准。
Q:中国大陆能用 Gemini API 吗?
A:官方层面不支持。Google 在 ai.google.dev/gemini-api/docs/available-regions 公布了支持地区列表,中国大陆不在其中;俄罗斯及受美国出口管制的国家同样受限。中国香港、中国澳门的情况在不同二手信源间说法不一,请以官方列表当前页面为准。
Q:国内开发者有合规的替代方案吗?
A:常见思路有三条——使用支持地区的合规身份与结算方式接入官方 API;通过 Google Cloud 的 Vertex AI 在海外区域部署(企业级路径,成本与合规条款需自行向 Google Cloud 渠道核实);或改用国产大模型 API,多数提供兼容 OpenAI 风格的接口。
Q:模型名经常变,生产环境怎么防踩坑?
A:把模型 ID 写进配置而非代码,订阅官方的版本说明与弃用公告。Gemini 3 Pro Preview 已于 2026 年 3 月 9 日关停,2.0 Flash 系列也已在同年 6 月下线,硬编码旧 ID 的服务会毫无征兆地挂掉。
Q:怎么把账单压下来?
A:能上 Flash 就别上 Pro;非实时任务走 Batch 拿 5 折;重复的长提示词用上下文缓存;把请求上下文控制在 200K 以内避免跳档;再给 Cloud 项目设好预算告警。
Q:返回被截断或突然停住是什么原因?
A:可能是触发了安全过滤,也可能是 RECITATION 机制判断输出与既有内容过于相似。前者需调整提示词与安全设置,后者要让提示词更具独特性或提高 temperature。
Q:调用总超时怎么办?
A:504 DEADLINE_EXCEEDED 说明请求体太大或处理时间过长。减小单次输入、改用流式输出、在客户端调大 timeout,三招按序试。
以上内容仅供参考,Gemini 的模型版本、价格、免费额度与地区支持范围可能随时调整,请以 Google 官方文档(ai.google.dev)与 AI Studio 控制台页面的最新公布为准。