Gemini API
Gemini 的坑集中在两个地方：错误码和结算。它的 429 底下挂着两个语义完全不同的错误码，退避重试只能救其中一个；流式请求的错误根本不走 HTTP 状态码；预付款余额归零会让名下所有密钥同时停摆。这些都写在官方文档里，只是很少有人翻到。 本专题共 23 篇。 内容依据 Gemini API 官方文档 整理，核对日 2026-08-25。 本专题只讲计费与接入机制，不列具体价格数字——价格变动频繁，写进正文只会过期误导，请以各平台官方定价页为准。
Gemini API 怎么接入？免费额度、密钥获取与区域限制说明
讲清 Gemini API 怎么接入：AI Studio 拿密钥的具体步骤、Python 与 TypeScript SDK（google-genai）最小调用、免费层的真实额度与那个容易踩坑的"账单陷阱"，以及区域限制的诚实现状。
错误码与排查
官方把错误分成三族：标准请求级、生成被阻止、生成结构错误。两种 429 的区别、recitation 与 spii 是什么、工具调用报 malformed 怎么办、流式错误怎么才能收到。
Gemini 的 recitation 和 spii 是什么错：内容被拦了怎么办
Gemini API 的生成被阻止码是一族独立的错误，safety、recitation、spii、blocklist、content_blocked 都归在这里。这篇讲清它和请求级错误、输出结构错误的边界，官方给的统一处置是什么，以及为什么把它塞进指数退避重试里是错的。
Gemini 的两种 429 完全不是一回事：退避重试救不了哪一种
Gemini API 的 429 至少对应两个语义不同的错误码，rate_limit_exceeded 靠指数退避能恢复，quota_exceeded 退避再多次也没用。本文讲清怎么从 error 对象里分辨、各自该怎么处置，以及流式请求为什么只看状态码会漏掉它们。
Gemini 工具调用报 malformed_function_call 怎么办
Gemini 官方 Interactions API 错误参考里，malformed_function_call 不属于请求级错误码，而是「生成结构错误码」这一族，说明模型输出结构有问题。本文讲清这一族官方分别写了什么、怎么和 400 请求错误区分开、流式下为什么会被漏掉。
Gemini 流式请求的错误不走 HTTP 状态码：只判状态码会漏掉它
Gemini 官方错误参考（Interactions API）里，标准与流式请求的错误走两条通道：非流式设置 HTTP 状态码并在 JSON 体返回 error 对象，流式则通过 SSE 发送 event_type 为 error 的事件。本文讲清分叉与只判状态码会漏掉什么。
Gemini API 错误码三大族怎么分、怎么对号入座
Gemini API 的错误码不是一张平表，而是请求级、生成被阻止、生成结构三族，各自的判定位置和处置方式都不一样。本文按官方错误参考页把三族拆开，讲清 code 字段怎么读、哪些码重试有用、流式请求为什么会漏掉错误。
Gemini API 接不通？按这个顺序查
把 Gemini API 的报错按"从外往里剥"的顺序排一遍：先看地区准入这一层能不能连通，再看密钥是不是真的被读到、项目权限够不够，然后才是 SDK 包名弃用、模型 ID 写错、免费层被限速，最后讲那个最容易让人莫名其妙开始扣费的计费开关。
限流与层级
限流按项目不按密钥——多申请几个 key 分摊流量这条路走不通。层级怎么升、跟着什么走。
Gemini 的层级体系怎么升：限流跟着结算账号走
Gemini API 的免费层与三个付费层级到底挂在哪一层对象上、每一级的门槛是什么条件、升级之后限流怎么变、付了钱层级却没动该往哪查，以及哪几种操作会让层级掉回去。全文只讲官方文档写明的机制与判定口径，不写任何金额与限流数值。
Gemini 限流是按项目算的，不是按 API 密钥算的
很多人撞到 Gemini API 的 429 后第一反应是再签几把密钥，但官方文档写明速率限制按项目应用、密钥没有独立结算设置。这篇把 Gemini 限流的计数维度、项目与结算账号的层次关系、配额重置时点和两种 429 的区别讲清楚，顺带说明哪些流量不走这套计数。
缓存机制
隐式缓存默认开启但有门槛、缓存存储时长要单独计费、Interactions API 用不了显式缓存。
Gemini 的缓存存储时长要单独计费：估成本时容易漏掉的一项
Gemini API 官方把计费依据列成四项，其中一项是缓存 token 的存储时长——它按时间走而不是按调用次数走。这篇讲清这项支出从哪儿来、官方文档对两种缓存交代到哪一层、用哪个字段查缓存命中量，以及估月成本时该怎么把这一项补上。
Gemini 隐式缓存怎么才能命中：官方给的两个办法
Gemini 的隐式缓存对 2.5 及更新型号默认启用，不用你写一行代码，但也不保证命中。本文按官方文档讲清提高命中率的两个办法、那道因模型而异的最低输入门槛、用 usage.total_cached_tokens 确认命中量的方法，以及什么时候该改用显式缓存。
Interactions API 用不了 Gemini 显式缓存：只能走隐式那条路
Gemini 有隐式与显式两套缓存，但官方文档写明 Interactions API 仅支持隐式缓存，要用显式缓存必须改用 generateContent API。这篇讲清这条限制卡在接口这一层、留在 Interactions API 上怎么抬高隐式命中率、靠哪个字段确认命中。
批量与接入
Batch 的两种提交形态、批量响应怎么对回请求、用 OpenAI 库怎么调、思考参数怎么映射、哪些模型的推理关不掉。
哪些 Gemini 模型的推理是关不掉的：思考参数怎么设
用 OpenAI 库调 Gemini，reasoning_effort 映射到 thinking_level 或 thinking_budget。官方明文：2.5 系列可设 none 关闭思考，2.5 Pro 与 Gemini 3 系列关不掉。本篇讲互斥规则、默认行为与账单口径。
用 OpenAI 库调 Gemini：官方说只改三行
Gemini 官方给 OpenAI 库用户的迁移说法是只改 api_key、base_url、model 三处。这篇讲清这三行分别改成什么、鉴权头与原生接口的差别、思考参数怎么映射、流式错误为什么可能不在状态码里，以及官方自己为什么反过来劝新项目别走兼容层。
Gemini 的 reasoning_effort 和 thinking_level 怎么对应
用 OpenAI 库调 Gemini 时，reasoning_effort 会被映射成 thinking_level 或 thinking_budget。本文讲清这层映射的四个档位、为什么两者不能同时传、哪些模型关不掉推理，以及思考 token 落在账单的哪一栏。
Gemini 批量任务怎么把响应对回请求：key 字段的用法
Gemini Batch API 提交上千条请求后，结果回来怎么知道哪条对哪条？官方给出的对账机制是用户自定义的 key 字段，响应会用同名 key 标注。本文讲清 key 在内嵌与 JSONL 两种提交形态下的位置、输出结构的差异，以及批量对账最容易翻车的几个点。
Gemini Batch API 的两种提交形态怎么选
Gemini Batch API 只有内嵌请求和 JSONL 输入文件两种提交形态。这篇按官方文档讲清两者的分工边界、上传链路、对账用的 key 字段、独立于常规调用的那套限流约束，以及跑批时要特别留意的那个计费环节，帮你在开工之前就把形态选对。
结算、区域与迁移
预付款与后付费怎么选（切过去回不来）、余额归零的连锁反应、结算延迟带来的超额风险、区域可用性怎么看、迁到企业平台要改什么。
Gemini 预付款和后付费怎么选：切过去就回不来了
Gemini API 的结算方案分预付款与后付费两种，本文按官方结算文档讲清两者的扣款方式、支出上限的两级结构、第 3 层级那道不可逆的切换门，以及预付款余额归零会连累整个结算账号的运维风险，帮你在开工前把方案定对。
Gemini 预付款余额归零，名下所有密钥会同时停摆
Gemini 预付款余额一旦归零，官方明确该结算账号下所有项目的所有 API 密钥同时停止工作。这篇按排查顺序讲清爆炸半径、余额被吃光的几条隐蔽路径、充值后服务什么时候才恢复，以及官方文档在哪几处根本没说。
Gemini 账单有结算延迟：长任务怎么就超出预算了
Gemini API 的结算流水线、层级升级、费用明细图表各有各的延迟，支出上限因此不是即时断路器。这篇按排查顺序讲清楚批量与 Agent 类长任务为什么会在预算之外继续消耗，以及账单高于预期时先核哪几项。
Gemini API 的区域可用性怎么看：官方给的替代路径是什么
Gemini API 的可用区域以官方 available-regions 页为准，该列表不包含中国大陆，官方给出的替代路径是 Gemini Enterprise Agent Platform。本文讲清区域判定依据、两条非区域准入条件、Colab 判定口径与国内合规方向。
Gemini API 迁移到企业平台：Vertex 后端只改客户端这几行
Google 的 Gemini 有两条产品线，Developer API 与 Gemini Enterprise Agent Platform 共用同一套 Gen AI SDK。这篇讲清迁移时改哪几行客户端初始化、调用层为什么不用动，以及代码之外必须重新核对的账号侧机制。
Gemini API 收费吗？免费层额度、付费单价与省钱用法
讲清 Gemini API 收费规则：免费层与付费层的分界线在哪、各主力模型付费单价表、一个月成本怎么估算，以及 context caching、Batch API、选对 Flash 档这几招真正能压低账单的方法。
想把模型平台的差异挡在业务代码之外？
站内有成体系的 AI 编程与 Agent 工程教程，从接入到成本治理都覆盖。