很多人第一次接 Gemini API，代码跑通了就以为没事，结果月底账单比预期高，或者同样的提示词换个入口结果不一样。问题通常不在模型本身，而在几个默认值你根本没看：免费层和付费层的边界、思考预算算不算输出、长上下文怎么计价、安全过滤默认拦什么。这篇按「先确认哪几件事」的顺序讲，给判断标准和排查动作，不给绝对结论。
很多人第一次接 Gemini API，代码跑通、能返回一段字，就觉得接完了。真正出问题往往是后面：月底账单比预估高一截，或者同一句提示词，昨天好使今天返回空。这些通常不是模型突然变笨，而是几个默认值你压根没打开看过。免费层还是付费层、思考算不算钱、长上下文怎么计、安全过滤默认拦什么、超时重试怎么配，这几件事决定了你的账单和结果长什么样。
这篇按「上手前先确认哪几件事」的顺序讲，每节都给判断标准和能直接做的动作。价格、限速、模型清单这类当期数字一律不写死，只告诉你到站内哪个页面核对当时的数字——这种东西变得比文章快，记在脑子里不如记在收藏夹里。
先分清你调的是免费层还是付费层
这是最容易被跳过的第一步。同一个 API key，挂在不同的项目下、结算状态不同，走的其实是两条通道：配额不一样、限速不一样，连数据使用条款都可能不一样。先到控制台确认项目绑没绑结算账号，再看调用的到底是哪一档。别凭「我没充过值」来判断，有些项目是别人给你开好的。
报 429 的时候更别急着改代码。先分清是每分钟请求数超了、每分钟 token 数超了、还是每日总量到顶了，这三种处理方式完全不同：前两种退避等待可能有用，最后一种等到明天也不会好。日志里把错误码和限流类型打出来，比盯着「请求失败」四个字强。
- 到控制台看项目是否绑定了结算账号，确认当前处在免费层还是付费层
- 抓一次 429 的完整响应，看清是请求数、token 数还是日上限触发
- 涉及敏感数据时先读当前档位的数据使用条款，这条比价格优先
- 当期配额和限速数字到 /official-api/providers/google 核对，不要凭印象
计费单位：输入、输出、思考三笔账分开看
Gemini 的账不是一笔。输入 token 和输出 token 单价不同，输出一般更贵，所以「回答写得长」这件事成本容易被估低。再加上带思考能力的模型会额外产生思考 token，这部分有的算进输出、有的单列出来，账单对不上时第一件事就是查这里。
图片、音频、视频输入也不是按张数、按分钟直接报价的，而是折算成 token 再计。你传一张图，实际消耗多少跟分辨率、处理方式都有关。所以看单价表估算，误差会比较大。更靠谱的做法是拿一次真实请求代进计算器，把输入、输出、思考三段拆开记。
| 账目 | 什么时候产生 | 常见误判 |
|---|---|---|
| 输入 token | 每次请求带上的提示词、历史消息、附件 | 以为历史消息不重复计费 |
| 输出 token | 模型生成的可见回答 | 按字数估算，低估长回答 |
| 思考 token | 带思考能力的模型在内部推理时产生 | 完全没算进预算，账单出来才发现 |
| 多模态输入 | 图片、音频、视频折算成 token | 按张数、按分钟估，偏差大 |
动手验证的方式很简单：先用 /tools/token-price-calculator 把你线上最典型的一条请求代进去，再用 /tools/model-cost-calculator 按你预估的日调用量乘一遍。当期单价到 /official-api 核对，别照着旧文章里的数字算。
长上下文不是免费的：塞多少，花多少
把整个代码库、几十页 PDF 一次性塞进 prompt，确实省了写检索的功夫，但输入 token 是线性涨的，而且多轮对话里每一轮都要把历史重发一遍。成本拐点往往不是出现在单次调用，而是出现在你连着追问第五、第六轮的时候——那时候每次请求都在为前面所有内容重新付费。
怎么判断值不值？做个对照：同一个任务，先用检索截出相关片段跑一遍，再用全量上下文跑一遍，比较结果差异有多大。如果差异不明显，就没必要长期背这个成本。反过来，一次性分析一份长文档、不做多轮追问的场景，长上下文反而省事，不必为了省 token 强行拆成好几段。
- 记录基线用当前最长的那个 prompt 跑一次，记下输入 token 数，作为对照基线
- 做截取实验同一任务改用检索出的片段，跑一遍，比较结果质量差多少
- 看多轮成本模拟连续追问三轮以上，观察每轮请求的输入 token 是不是在滚雪球
- 再决定策略差异小就长期用截取，差异大且是单次分析场景，就保留全量
安全过滤和拒答：结果不一样未必是模型变了
默认安全阈值会拦掉一部分内容，表现出来可能是空候选，也可能是回答被截断。代码里如果只判断「有没有文本返回」，就会把拒答当成故障去排查模型、排查网络，绕一大圈。正确的做法是显式读 finish reason 和安全评级，把这两种情况区分开。
还有一种情况：同一句提示词，在网页端试好好的，走 API 就返回空。两边默认阈值和版本不一定一致，这不是玄学。遇到莫名其妙的空返回，先把请求体、finish reason、安全评级三样打进日志，再谈是不是模型问题。涉政、医疗、法律这类内容拦截会更严，业务上要预留兜底话术，别把拒答当异常报警。
- finish reason
- 判断这次是正常结束、被截断还是被拦，必须显式读
- 安全评级
- 看是哪一类内容触发了阈值，决定是改提示词还是走兜底
- 空候选
- 不等于请求失败，先看上面两项再定性
- 兜底话术
- 敏感场景提前准备，把拒答转成用户能看懂的话
重试和超时：最容易悄悄烧钱的地方
超时后盲目重试，等于同一次请求可能付两遍钱，尤其是已经生成了大半输出的请求——前面那部分 token 大概率照计。流式返回中途断开也是同理，日志里要记录已经接收了多少内容，不然账对不上你都不知道从哪查。
重试要有条件。网络错误和 5xx 可以重试；4xx 尤其是 429，要先退避，不要立刻打回去，否则只会把限流窗口越撞越长。排查顺序也固定下来：先看错误码，再看是不是流式，最后数重试次数，别一上来就怀疑模型参数。
排查顺序：错误码 → 是否流式 → 重试次数 → 请求体内容 → 模型参数；只有网络错误和 5xx 才自动重试，429 先退避再试，4xx 其他类别不重试。模型名别写死在代码里
这条跟「写死」相反：别名类模型名（带 latest 那种）会随官方更新指向新版本，行为和价格都可能跟着变。线上服务建议固定到具体版本，避免某天早上自动升级，结果和账单一起变。当期有哪些版本、各是什么价位，到 /models 和 /price-watch 看，别凭记忆写。
换版本前做一次小样本对照：同一批提示词同时跑新旧两版，比结果稳定性和 token 消耗。切换后缓存命中率可能下降，成本会跟着变，这点最容易被忽略——你以为只是换了个名字，实际是计费结构动了一下。
- 线上服务固定到具体版本，别名留给试验环境
- 换版本前用同一批提示词跑新旧对照，记录差异
- 切换后观察一段时间 token 消耗，确认没因缓存失效而上涨
- 当期版本和价位到 /models、/price-watch 核对
上线前照着走一遍的自查清单
上面几节拆开讲，是为了让你知道每一项为什么重要。真正上线前不用背，照下面这个顺序走一遍就行，每一条都对应一个能验证的动作，不是空口号。
- 确认结算档位看项目绑没绑结算账号，明确当前跑在免费层还是付费层
- 跑一次真实成本测算用线上典型请求代进 /tools/token-price-calculator，输入、输出、思考分开记
- 打开拒答日志把 finish reason 和安全评级写进日志，确认空返回能被识别
- 配好超时与重试设超时、退避和重试上限，只对网络错误和 5xx 自动重试
- 固定模型版本线上写具体版本，换版前做小样本对照
- 看一眼当期状态上线前到 /ai-status 确认服务状态，别在故障窗口里压测
这套清单不保证你一定不出问题，但能保证出问题时你知道去哪查。尤其是账单跑偏这种事，等你看到月底数字再去翻代码，成本已经发生了。
下一步把当期官方价格、限速和模型清单放到一个页面里对照看，比翻文档快。到 /official-api/providers/google 核对当时的数字，再回 /price-watch 看价格变动记录。→常见问题
Gemini API 有免费额度吗，能一直用吗？
有免费层，但它的限速、每日上限和数据使用条款都跟付费层不同，官方也可能调整。适合做原型验证，不适合当生产依赖。当期规则到 /official-api/providers/google 核对，别把某次看到的数字当成长期承诺。
为什么我同样的提示词，网页端和 API 结果不一样？
常见原因有三个：默认安全阈值不同、模型版本或别名指向不同、采样参数默认值不同。先把 finish reason、模型版本、温度这几项打进日志比对，再考虑是不是提示词本身的问题。
账单比预估高很多，先查哪里？
按顺序查：输出 token 占比是否偏高、思考 token 有没有被算进去、是不是多轮对话反复计费、重试有没有造成重复请求、长上下文是不是被整段重发。这几项排完，多数偏差能定位到。
报 429 就是额度用完了吗？
不一定。429 可能来自每分钟请求数、每分钟 token 数或每日总量，三者处理方式不同。先看响应里的具体限制类型，再决定是退避等待、降并发还是换层。
模型名写 latest 有什么风险？
别名会随官方更新指向新版本，输出风格、拒答行为和计费口径都可能变，线上服务会出现难以复现的差异。建议固定到具体版本，换版前做小样本对照。
