Gemini API 接不通？按这个顺序查

2026-07-27

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

Gemini API 跑不通的时候，绝大多数人第一反应是去改代码，这个顺序几乎总是错的。真正卡住人的问题按出现频率排下来是：网络与地区准入连不上、密钥没被进程读到或项目权限不够、SDK 装的是已经弃用的旧包、模型 ID 抄了过期教程、免费层配额撞墙。这五类里只有最后两类跟代码沾边，前面三类改多少行代码都没用。所以排查要从外往里剥，别一上来就怀疑自己的业务逻辑。

有个常见误解得先说破：很多人把”连不上 Gemini”默认理解成网络慢或者服务不稳定，于是加重试、加超时时间、换个时间段再试。但 Gemini API 和 AI Studio 官方并没有把中国大陆列入支持地区，这是准入层面的事实，不是链路抖动。把一个准入问题当成网络问题去调参数，能耗掉一整个下午还找不到方向。

第一层：先确认”这条路本来通不通”

排查的第零步不是看报错内容，是确认你所在的位置、你的账号形态，官方是否支持。

官方文档里有一份支持地区列表（https://ai.google.dev/gemini-api/docs/available-regions ），据其说明覆盖 230+ 个国家和地区，但明确不是全球可用。中国大陆不在官方支持地区列表中；香港、澳门的情况在不同信源之间说法不完全一致，建议直接以那份列表当前的页面为准，别信任何二手转述（包括这篇）。台湾、日本、新加坡、韩国、印度、印尼等在支持列表中。俄罗斯因为 Google 大幅收缩当地商业存在，从俄罗斯网络访问通常不可靠。受美国出口管制的国家则是完全受限。

这里还有个很多人没意识到的分岔：Gemini App（网页版聊天）和 Gemini API / AI Studio 的地区支持列表不是同一份。“我这边能打开 Gemini 网页版聊天”推不出”我这边能调 API”，反过来也一样。用前者去论证后者，是一种很典型的误判。

海外厂商的大陆准入这件事，按项目一贯的口径要说明白：这几家官方并未面向中国大陆开放，注册、控制台与 API 端点都在境外，具体以各自官网的地区政策页为准。市面上确实存在第三方中转、聚合类服务，但其合规性、计费透明度、数据处理方式都需要使用者自行核实并自负风险，这篇不提供也不背书任何具体渠道，也不写任何绕过地区限制的做法。

判断标准很简单：如果你收到的是连接超时、连接被拒绝、TLS 握手失败这类没有业务语义的错误，基本可以断定卡在这一层，不必再往下查密钥和参数。反过来，如果服务端已经明确返回了 401、403、404、429 这类带语义的响应，说明请求确实打到了 Google 的服务上，那这一层是通的，可以往下走。

第二层：密钥到底有没有被读到

这一层的报错通常是鉴权失败类。排查有个屡试不爽的笨办法：先别看代码逻辑，直接把环境变量打印出来。

官方 quickstart 的推荐做法是把密钥放在环境变量 GEMINI_API_KEY（也支持 GOOGLE_API_KEY），SDK 会自动读取。所以第一件事是确认这个变量在当前这个进程里真的存在——注意是当前进程，不是你在另一个终端窗口 export 过、不是你写进了某个 .env 但没加载、不是你在 IDE 的运行配置里漏了一项。Python 里 print(os.environ.get("GEMINI_API_KEY")) 打出来是 None，那后面所有分析都是白费。

如果变量确实读到了，接着看这三件事：

密钥是不是从对的地方生成的。正规路径是打开 AI Studio 的 API Keys 页面（https://aistudio.google.com/apikey ），用 Google 账号登录，首次接受服务条款时 AI Studio 会自动帮你创建一个默认的 Google Cloud 项目，然后点 “Create API key”，选择关联的项目，生成密钥字符串。
项目权限够不够。如果你用的不是 AI Studio 自动创建的个人项目，而是公司已有的正式 Google Cloud 项目，那创建 key 需要项目管理员具备一串权限：resourcemanager.projects.get、apikeys.keys.create、serviceusage.services.enable、iam.serviceAccounts.create、iam.serviceAccountApiKeyBindings.create。企业环境里”我按教程点了但按钮是灰的/报权限错误”，八成就卡在这里，得找 GCP 管理员，而不是自己反复重试。
密钥有没有被泄露或误提交。key 一旦进了公开仓库，谁都能拿去消耗你的额度。正确姿势是只放服务端环境变量或密钥管理服务，别硬编码、别提交进版本库。这块可以顺带看看API Key 的安全管理。

顺带说一句项目数量：有第三方信源提到每个账号在 AI Studio 中最多创建 10 个项目，但这个数字未经官方核实，是否仍是当前硬性上限以官方页面为准。

第三层：SDK 装错了包，或者模型 ID 抄了旧教程

这一层是纯代码问题，但它的坑很有欺骗性——报错信息往往指向别处。

先看包名。 当前官方统一 SDK 是 Python 的 google-genai（导入写法是 from google import genai）和 TypeScript/JavaScript 的 @google/genai。而旧包 google-generativeai（Python）与 @google/generative-ai（JS）已经被官方标记为弃用。网上大量教程还停留在旧包上，照抄之后你会遇到导入路径对不上、方法名找不到、参数结构不一致这类问题，而报错文本经常看着像是你参数写错了。

一个能跑通的最小调用长这样：

# pip install google-genai
import os
from google import genai

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 侧同理：

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

const ai = new GoogleGenAI({}); // 默认读环境变量 GEMINI_API_KEY

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

排查时把业务代码放一边，先用这段十行不到的最小样例跑一次。它跑通了，说明密钥、网络、SDK 三层都没问题，问题一定在你的业务参数里；它跑不通，那就还在前面几层，别再改业务代码了。这个”最小复现”的习惯，比读任何报错解释都省时间。

再看模型 ID。 官方模型清单在演进，写死一个几个月前的模型名，很容易撞上”模型不存在”。截至 2026-07，官方页面上既有 2.5 系列（gemini-2.5-pro、gemini-2.5-flash、gemini-2.5-flash-lite），也已经列出了 3.x 系列（如 gemini-3.5-flash、gemini-3.1-flash-lite、gemini-3.1-pro-preview）。示例代码里用 2.5 系列作为经典稳定写法是稳的，但如果你要上新模型，具体哪些 ID 当前可用，请以官方模型清单页（https://ai.google.dev/gemini-api/docs/models ）为准，别从版本号规律去”推”一个名字出来。

还有一类容易被误诊成”模型不存在”的情况：你选的模型在你当前的账号档位上根本不可用。 比如 gemini-3.1-pro-preview 的定价页明确写着免费层 Not available。这时报错看着像模型名错，实际是权限/档位问题，换个 Flash 档模型试一下就能区分开。

第四层：429 和配额，别照抄网上的数字

如果请求打通了、密钥也对，但间歇性失败，重点看限速。

免费层的具体配额有个让人不太舒服的现实：官方的 rate-limits 文档主要讲机制，逐模型的 RPM/TPM/RPD 具体数字放在 AI Studio 控制台里，不是静态文档。 网上流传的”15 RPM、1500 RPD”之类的数字来自第三方汇总，未经官方页面确认，而且额度调整很频繁。所以碰到限速问题，唯一靠谱的做法是登录 https://aistudio.google.com/rate-limit 看你自己账号的实时面板，而不是拿一篇文章（包括这篇）里的数字去反推自己为什么被限。

关于档位，官方讲清楚的机制是这些：

Free Tier 升到 Tier 1，条件是开通并绑定有效的计费账户。
Tier 1 升 Tier 2 需要累计消费达到某个阈值，并在首次成功付款后经过一定天数——第三方信源对这个阈值和天数的说法不一致，这里不给具体数字，以官方 rate-limits 页面或 AI Studio 面板当前显示为准。
官方页面明确写出的是”10 分钟滚动窗口支出上限”：Tier 1 为 10 美元/10 分钟，Tier 2 和 Tier 3 为 200 美元/10 分钟。如果你在做批量任务、突然被打断，而 RPM 看着又没超，可以怀疑是不是撞上了这个支出窗口。

另外，免费层还有一条地区性的额外限制值得单独记：欧盟（EEA）、瑞士、英国的免费层完全不可用，当地开发者必须开通计费账户才能调 API。如果你或者你的服务器在这些地区，“免费额度怎么一次都没生效”就有解释了，这不是 bug。

第五层：账单突然开始跑，多半是这个开关

最后一类不是报错，是”没报错但开始扣费了”，也值得放进排查清单，因为很多人是先看到账单才回头查的。

关键机制是：一旦项目开通了计费（enable billing）升级到付费档，该项目下的所有调用就从第一个 token 起计费，不再保留免费额度的余量。 这和 BigQuery 等一些 Google Cloud 服务”先扣免费额度再计费”的逻辑不一样，属于典型的反直觉设计。很多人为了解决限速问题顺手点了开通计费，之后发现原本免费的调用全变成了计费调用，就是这个原因。

如果你的目标是省钱，可以往两个方向看：官方对所有付费模型提供 Batch 通道（约 50% 折扣，代价是最长 24 小时的异步交付），以及上下文缓存（缓存读取价格约为标准输入价的 10%，另按 token 和小时计存储费）。具体倍率和适用模型以官方计费页为准，成本这块可以看Gemini API 的计费拆解。

关于免费层还有一处必须诚实说明的分歧：Pro 档模型现在还免不免费，信息是冲突的。 官方定价页目前对多个模型标注 Free of charge 字样，但也有 2026 年的第三方信息称从 2026-04-01 起 Pro 档已从免费层下架、免费层只保留 Flash 与 Flash-Lite，而 gemini-3.1-pro-preview 的定价页确实写着免费层不可用。这两种说法我没法替你判定，只能建议在动手前自己去官方定价页确认当前状态，别把”Pro 免费”当成既定前提去做技术方案。

一份可以照着走的排查清单

按顺序走，每步只回答一个是非题：

报错有没有业务语义？没有（超时/连接被拒）→ 卡在准入与网络层，先解决这个，别往下。
GEMINI_API_KEY 在当前进程里打印出来是不是 None？是 → 环境变量问题。
key 是不是在 AI Studio 的 API Keys 页面生成的？企业项目里创建按钮报权限错？→ 找 GCP 管理员补权限。
用上面那段十行最小样例能不能跑通？能 → 问题在你的业务参数；不能 → 回到第 1、2 步。
装的是 google-genai / @google/genai，还是已弃用的旧包？
模型 ID 是从官方模型清单页抄的，还是从旧教程抄的？换个 Flash 档模型试试能否区分”名字错”和”档位不可用”。
间歇性失败 → 登录 AI Studio 的实时速率面板看自己账号的真实配额，别信文章里的数字。
出现意外账单 → 检查项目是否开通了计费。

这篇的局限

有几件事我给不了确定答案，直说：免费层逐模型的具体配额官方没有静态表格，只能你自己去面板看；Pro 档免费与否存在信源冲突；地区列表变动频繁，官方自己都建议按月复查；Tier 升级的消费阈值和等待天数，不同来源说法不一，这里不写具体数字。任何一篇文章里的这类数字都有保质期，把它当索引用（知道去哪儿查），别当结论用。

如果你是第一次接入、还没跑通过任何一次调用，建议先看Gemini API 的接入流程把最小链路走一遍，再回来对着这份清单排错，会快很多。

小结

排查 Gemini API 的报错，最重要的不是记住错误码含义，而是守住”从外往里剥”的顺序：准入和网络 → 密钥与项目权限 → SDK 包与模型 ID → 配额与限速 → 计费状态。没有业务语义的连接错误，说明请求根本没打到服务上，改代码没有意义。SDK 请认准 google-genai 和 @google/genai，旧包已弃用，网上大量教程还没更新。配额数字请到 AI Studio 的实时面板看自己账号的，别引用任何静态文章。最后记住那个反直觉的计费开关：项目一开通计费，免费余量就不再保留了。