Gemini API 怎么学

读本教程不必从头到尾：先看你要解决哪类问题，再按路径跳读；每个数字都要能回答三个问题——谁说的、什么时候核的、现在还算不算。（核验 2026-11-05，F29、F38）

一、Gemini API 怎么学：问题不是顺序，而是先搞清你在解决哪类问题

同一套教程，三个人读，收益完全不同。

小王只想让程序跑通一次调用，验证这条路走不走得通。小李要把功能接进生产，担心限流、账单和异常。老张是从别的模型接口迁过来的，只想知道字段差在哪、哪些行为变了。

如果三个人都从第一节读到最后一节：小王会在模型介绍和成本章节里耗掉耐心，小李会在多模态细节里绕圈，老张会在导读里反复确认「这跟我有什么关系」。不是内容不好，是路径不对。

所以开始读之前，先回答一个问题：你现在要解决的是「跑通」「上线」还是「迁移」？ 答案决定你走哪条路，也决定哪些章节可以放心跳过。

三条路都省不掉一件事：看到数字，先看它带没带来源和日期。这是下一段要解决的问题。

每节的七段也不是装饰。二、最小可运行示例和四、预期输出负责让你跑通；三、解释与边界和五、判据卡负责让你上线不踩坑；六、来源与核验负责判断这条结论还能不能用；七、动手试是自测。只想跑通的人看二和四就够；要上线的人必须看三和五。

二、给每条结论打一个状态：最小可运行示例

为什么数字要带日期？因为这类事实会过期。有人三月照着一篇博客，把 gemini-2.5-pro 写进配置，跑得很顺；到了十二月一日，他没改一行代码，账单却按新费率走了——官方把这批模型自动路由到新模型，并按新模型的价收费（F29、F30）。博客没写错，是他抄的事实过期了。

官方变更日志在十天里就能列出多次更新（F60），定价页自己也写着折扣与模型可用性可能变动（F38）。所以判断一条结论还能不能用，只需要三个信息：谁说的、什么时候核的、现在算什么状态。下面这段代码把它们变成一次本地判断，不联网。

## EXPECT: 可用 1 | 需复核 1 | 过期 1
from datetime import date
TODAY = date(2026, 11, 6)
FACTS = [
    {"id": "F34", "checked": "2026-11-05", "status": "已确认"},
    {"id": "F59", "checked": "2026-11-05", "status": "待核"},
    {"id": "F29", "checked": "2026-07-01", "status": "已确认"},
]
def days_since(iso):
    y, m, d = map(int, iso.split("-"))
    return (TODAY - date(y, m, d)).days
def verdict(f):
    if f["status"] == "待核":
        return "需复核"
    return "可用" if days_since(f["checked"]) <= 30 else "过期"
results = [verdict(f) for f in FACTS]
out = f"可用 {results.count('可用')} | 需复核 {results.count('需复核')} | 过期 {results.count('过期')}"
assert verdict(FACTS[1]) == "需复核"
assert verdict(FACTS[2]) == "过期"
print(out)

verdict 先看状态：待核的一律返回「需复核」，不管日期多新——因为官方自己还没说清。已确认的再看日期，超过 30 天就标「过期」。这里的 30 天是示例阈值，不是官方规定：价格、模型这类一个月查一次，区域与合规半年查一次，分档见 1.3。TODAY 固定成 2026-11-06 是为了让输出可复现；真实项目里换成 date.today()。

三、解释与边界：三条路走完，各自该能做什么

路径表只是节号，能不能算走完，要看你能不能交付对应的东西。

走「跑通」那条：读完见 1.1 和见 2.2，你应该能自己写出发一条请求、取回 output_text 的代码，并且知道包名该装哪个（F1、F3）。做不到，说明卡在入口没分清。

走「上线」那条：读完见 5.1、见 11.1、见 12.3，你应该能给出结构化输出、把 429 与 402 分开处理、在上线前把该核的项核一遍。这条路的验收标准不是「跑通了」，是「出错时知道该看哪里」。

走「迁移」那条：读完见 1.1、见 2.3、见 12.1，你应该能列出新旧接口的字段差异，并说清哪些能力只在 beta 提供。迁移最容易犯的错是直接平移旧代码，字段对不上却不报错。

三条路共用一套事实基线：每条事实有 F 编号、说法、具体值、来源页、核验日期、状态。状态只有两种——已确认、待核。已确认的可以直接引用；待核的只允许写「请到官方页复核」。这不是免责声明：官方两个页面之间确实有互相矛盾的地方，比如音频每秒消耗多少 token，一处写 32、一处写 25（F50），这种情况本教程不替官方选一个数。

边界：本节教怎么判断一条结论能不能用、怎么按问题选路径，不教怎么重抓官方页、怎么给差异页重新编号，那些属于维护流程，见 1.3。

四、预期输出与异常分支：三种误判

跑上面那段代码，输出是：

可用 1 | 需复核 1 | 过期 1

三条事实：一条可用、一条需复核、一条过期。三种最常见的误判，正好一类对一条：

• 把待核当结论。F59（网页版许可范围）至今没有可复核的原文，写成「可以自由转载」就是替官方下结论。
• 把旧日期当今天。半年前核的价格，现在可能已经变了——F34 记的那次价格切换就在十二月一日生效。
• 把别人的模型名直接抄进配置。博客写作时的模型名，可能已经进了弃用表（F29）。

三种误判的共同点：都不是算错了，是没给结论标状态。

五、判据卡：这条路该怎么走

六、来源与核验：官方页与 F 编号

• https://aistudio.google.com/docs/pricing.md（核验 2026-11-05，F34、F38）
• https://aistudio.google.com/docs/changelog.md（核验 2026-11-05，F60）
• https://aistudio.google.com/docs/deprecations.md（核验 2026-11-05，F29、F30）
• https://aistudio.google.com/docs/terms.md（核验 2026-11-05，F59，待核）
• https://aistudio.google.com/docs/tokens.md、https://aistudio.google.com/docs/media-resolution.md（核验 2026-11-05，F50，待核）

待核说明：F50（音频 token 率两页口径冲突）、F59（网页版许可声明）均保持待核。本节只对它们写「请到官方页复核」，不下断言，也不替官方选一个数值。

七、动手试：三个可验收练习

1. 给自己归个类：跑通、上线、迁移。然后只读对应那三到五节，读完用一句话写下「我现在能做什么」。写不出来，说明路径走得不够深。
2. 给 FACTS 加一条 {"id": "F50", "checked": "2026-10-01", "status": "待核"}，重跑，看「需复核」变成几。再说明：为什么待核不看日期。
3. 翻你收藏的一篇 Gemini 教程，挑一个数字，用来源、日期、状态三问审一遍。三个都答不上来，就把它当线索，别当结论。