Gemini API 怎么接入？免费额度、密钥获取与区域限制说明

2026-07-07

数据截至 2026-07，价格与限额以各官网为准。

Gemini API 的接入门槛比很多人想象得低：一个 Google 账号、打开 AI Studio、点两下就能拿到密钥，甚至不用先绑卡就能跑第一次调用；但免费层的额度到底有多少、什么时候会突然变成全额计费，这两件事官方文档写得不算清楚，得靠自己去控制台核实。

这篇按真实接入顺序走一遍，重点放在免费额度和区域限制这两块最容易被文章写死、结果读者一验证就发现不对的地方。

第一步：在 AI Studio 拿密钥

Gemini API 的密钥不在 Google Cloud Console 里单独申请，走的是更轻量的一条路：Google AI Studio。

打开 https://aistudio.google.com/apikey，用你的 Google 账号登录。如果是第一次进这个页面并接受服务条款，AI Studio 会自动帮你创建一个默认的 Google Cloud 项目——这一步是隐式发生的，很多人根本没意识到自己已经”有”了一个 GCP 项目。

进去之后点 Create API key，选关联的项目（用自动创建的默认项目就行，除非你已经有正式的 GCP 组织想挂上去），几秒钟生成一串密钥字符串。整个过程不需要填申请表、不需要等审核，跟 Claude 的自助式建 key 体验很接近。

有个数量限制值得记一下：每个账号在 AI Studio 里最多能建 10 个项目（这是第三方信源给的数字，是否为当前硬性上限未核实，实际以你账号里能不能继续新建为准）。如果已经有正式的 Google Cloud 账号或组织，要建 key 通常需要项目管理员具备几项权限，比如创建 API key、启用服务、创建服务账号相关的权限，个人开发者用默认项目基本不会碰到这些门槛。

拿到 key 之后，建议存进环境变量 GEMINI_API_KEY（或者 GOOGLE_API_KEY，两个官方 SDK 都认），不要直接写死在代码里，更不要提交进 Git 仓库。这条规矩跟接入任何 API 都一样，Gemini 也不例外。

第二步：SDK 最小调用

官方现在统一维护的 SDK 叫 google-genai（Python 包名）和 @google/genai（TypeScript/JavaScript，npm 包）。这里有个容易踩的坑：Google 之前还有一套包叫 google-generativeai（Python）和 @google/generative-ai（JS），已经被官方标记为弃用了。网上不少教程、甚至一些 AI 生成的代码示例还在用旧包名，装了跑不起来或者行为对不上文档，往新包切就好。

Python 侧，先 pip install google-genai：

import os
from google import genai

# 从环境变量 GEMINI_API_KEY 自动读取，也可显式传入 api_key='xxx'
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="用一句话解释什么是量子计算",
)
print(response.text)

TypeScript / Node.js 侧，先 npm install @google/genai：

import { GoogleGenAI } from "@google/genai";

// 默认从环境变量 GEMINI_API_KEY 读取；也可 new GoogleGenAI({ apiKey: "xxx" })
const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "用一句话解释什么是量子计算",
  });
  console.log(response.text);
}

main();

跟一些其它厂商的 SDK 比，这里省心的地方是：拿到 response.text 直接就是字符串，不用像有些接口那样先判断内容块类型再取文本。写法上也不需要手动拼 system/user 角色数组才能跑通最简单的一次调用——contents 直接传字符串就是最小可用形态，等你要做多轮对话或者传图片、文件的时候再换成结构化的 contents 数组。

模型 ID 这里说一句现状：本卡核实到的主力模型里，gemini-2.5-flash、gemini-2.5-pro 这套 2.5 系列还在正常提供服务，同时 gemini-3.5-flash、gemini-3.1-pro-preview 这些 3.x 系列的模型已经上线。示例代码里用 2.5 系列是因为它相对成熟稳定，真要追新模型能力，把 model 字段的值换掉即可，SDK 调用方式不变。

第三步：免费额度到底有多少（重点，如实说）

这是最多人关心、也是最容易被讲错的一块，因为官方把这部分数字放在了会变的控制台面板里，而不是一份固定不变的文档表格里。先把能确定的部分讲清楚，再说哪些数字暂时没法钉死。

能确定的部分：

官方定价页目前对 gemini-2.5-flash、gemini-2.5-flash-lite、gemini-3.5-flash、gemini-3.1-flash-lite 都标注着”Free of charge”（免费层可用），也就是说 Flash 系列这条线目前是有免费额度的。
免费层升级到付费（也就是所谓 Tier 1）的门槛很简单：开通并绑定一个有效的计费账户就行，不需要先攒够消费额度。
官方在 rate-limits 页面明确写了一个”10 分钟滚动窗口支出上限”的机制：Tier 1 是每 10 分钟 $10，Tier 2/3 是每 10 分钟 $200。这个数字是官方页面直接给的，比较能信。

暂时没法钉死、需要你自己去查的部分：

Pro 档模型（比如 gemini-3.1-pro-preview）的免费层状态目前存在冲突信息：官方定价页对 gemini-2.5-pro 仍标注”Free of charge”，但另有信源说 2026-04-01 起 Pro 系列已经从免费层下架，gemini-3.1-pro-preview 的模型页也确实写着 Free Tier “Not available”。这两个说法对不上，本文不替你下结论——你要用 Pro 档模型做免费开发，务必先去当前官网页面确认清楚，别按本文任何一个数字去规划生产用量。
免费层的具体 RPM（每分钟请求数）、TPM（每分钟 token 数）、RPD（每天请求数）没有一份官方静态文档表格，这些精确数字被放在你登录后才能看到的实时面板里。这是本文最想强调的一点：与其记一个可能随时调整的数字，不如养成习惯直接去看。
Tier 1 升级到 Tier 2 需要累计消费达到某个阈值，第三方说法里出现过 $100 和 $250 两种版本，加上首次付款后要等一定天数（3 天还是 30 天，说法也不一致），这块本文同样不下定论。

一定要记住的操作路径：登录 https://aistudio.google.com/rate-limit，那里显示的是你当前账号的实时配额面板，比任何一篇文章、包括这篇，都更准。

还有一个真正容易踩的坑，值得单拎出来加粗：一旦某个项目开通了计费（enable billing），从那一刻起该项目下的所有调用都按付费价格从第一个 token 起算，不会先把免费额度用完再切换。这跟 Google 其它云服务（比如 BigQuery 那种”免费额度用完再收费”的逻辑）不是一回事，很多人是在账单上看到意外扣费才发现这个区别的。如果你想长期白嫖免费额度做学习和小流量试验，最好专门开一个没有绑定计费账户的项目，别跟正式付费项目混用。

另外，欧盟（EEA）、瑞士、英国这三个地方因为监管要求，免费层被完全禁用，当地开发者哪怕实际用量很小，也必须开通付费账户形态才能调用，不是免费额度缩水而是压根没有免费选项。

第四步：区域限制（重点，诚实说明）

官方说 Gemini API 覆盖 230 多个国家/地区，但不等于全球任何地方都能直接用，写这篇文章前特意核实过，实际情况分几档：

中国大陆：不在官方支持地区列表内。 这个跟 Google 2010 年之后在中国大陆的整体业务状态是一致的，AI Studio 和 Gemini API 都不可用。本文不提供、也不推荐任何绕过地区限制的方法，如果你人在大陆想学习和实验，客观现实是需要先解决网络环境的合规接入问题，这不在本文展开。
香港、澳门：官方公开的地区列表里没有把它们明确列为常规支持地区，但也存在信源说法不完全一致的情况，这条建议直接去官方地区列表页当场确认，别信任何一篇文章的旧结论。
台湾、日本、新加坡、韩国、印度、印尼等，都在官方支持列表内。
俄罗斯：因为地缘政治因素，Google 在俄罗斯的商业存在已经大幅收缩，从俄罗斯 IP 通常无法可靠访问 AI Studio 和 Gemini API。
伊朗、朝鲜、古巴、叙利亚等受美国出口管制/制裁的国家和地区，完全受限，这个不意外。

还有一个容易被搞混的点：Gemini App（也就是普通用户用的聊天应用）和 Gemini in Workspace 的地区支持列表，跟 API / AI Studio 的支持列表不是同一份。看到”某个国家能用 Gemini App”不能反推”该国能用 Gemini API”，这是两条独立维护的规则。

官方对不在支持列表内地区的开发者给出的建议路径是通过 Google Cloud 的 Vertex AI 或者 Gemini Enterprise Agent Platform 去访问，具体资格和条件以 Google Cloud 当时的政策为准，这不构成任何合规建议。地区列表本身变动比较频繁，官方也建议按月复查，别把某一天查到的结果当成永久事实。

常见坑 / 注意

忘了从旧包切新包：google-generativeai / @google/generative-ai 已弃用，认准 google-genai / @google/genai。
首次进 AI Studio 会隐式建项目：容易搞不清自己在哪个项目下操作，建 key 前留意页面上显示的项目名。
开通计费=立即全额计费：不是先用完免费额度再计费，是从第一个 token 起就按付费价算，专用项目分开管理更安全。
Pro 档免费层状态有冲突：官网标注和第三方信息对不上，别按本文任何数字规划生产用量，用前自行确认。
免费层精确 RPM/TPM/RPD 没有静态表格：只登录 aistudio.google.com/rate-limit 看自己账号的实时数字才准。
App 支持地区≠API 支持地区：两份清单是分开的，别互相推断。
中国大陆无官方直连：AI Studio 和 Gemini API 都不在支持地区内，本文不提供绕行方法。