Gemini API 教程能做什么

《Gemini API 中文教程》覆盖「把模型接进系统」的三件事：输入怎么进、输出怎么变结构化、出错怎么降级；免费层限额不保证、内容会用于改进产品（F20、F37），所以示例全部用 mock 数据。（核验 2026-11-05）

一、本教程的边界：问题不是资料不够，而是 Gemini API 能做什么、不能做什么

一句话：这是一套「把 Gemini 接进自己系统」的教程，不是官方文档的中文版，也不是十分钟速成文。它围绕一个具体项目——多模态工单助手——把从第一条请求到上线前自检的决策链走一遍。

具体说，它有三个特点。

• 只讲模型调用这一段。 输入怎么进（文字、图片、PDF）、输出怎么变成结构化字段、出错怎么降级、成本怎么算，这四件事讲透；部署、登录、权限不讲。
• 每个事实都带出处和日期。 价格、限额、模型名这类会变的东西，一律标 F 编号与核验日期，不写「记住就行」。
• 每节都有可离线跑的代码和判据卡。 代码不需要密钥，判据卡给的是「出现什么信号就换做法」，不是「视情况而定」。

它不是什么，同样要说清。

• 不是官方文档的翻译或索引。 官方导航按能力域分组，适合查手册；本教程按「先定哪一层、再选哪个模型、然后怎么把输出变成结构化对象、最后怎么守住账单和异常」来排。
• 不是速成文。 跑通一条请求，和做一个能上线的功能，中间差着结构化输出、错误分流、限流、降级这些活。
• 不是模型排行榜或提示词合集。 那些东西变得更快，也不解决工程决策。
• 不是能直接抄进生产的完整项目。 示例是 mock 数据，真实调用要你自备密钥和额度。

适合谁？三类人：要把 Gemini 接进自己系统的后端或全栈开发者；从别的模型接口迁过来的团队；要评估成本与合规边界、需要可核验依据的人。不适合谁？只想找个人聊天、想要现成提示词模板、或者想要一套开箱即用产品的，都会失望。

贯穿全教程的是一个多模态工单助手：用户丢进截图、语音或 PDF 工单，系统返回带引用位置的结构化 JSON，并在超配额、被安全拦截、模型下线时自动降级。每章推进这条链一步，章与章之间是依赖关系，不是并列的知识点清单。

二、把需求拆成决策：最小可运行示例

「边界」这个词听着抽象，落到具体需求上就很实在。老板给你一句话：做个工具，客服把报错截图传上来，自动填好工单的类型、严重级别和处理建议，两周上线。

这句话能拆成五件事：调哪一层、图片怎么传、输出怎么变成工单字段、密钥和日志怎么管、部署和权限怎么办。本教程管前三件，第四件给做法，第五件不碰。下面这段代码把这份判断变成一次本地计数。

## EXPECT: 覆盖 3/5 | 部分覆盖 1 | 需自备 1 | 先补：部署与权限
DECISIONS = [
    {"name": "调哪一层", "status": "覆盖"},
    {"name": "图片怎么传", "status": "覆盖"},
    {"name": "输出变结构化", "status": "覆盖"},
    {"name": "密钥与日志", "status": "部分覆盖"},
    {"name": "部署与权限", "status": "需自备"},
]
def split(items, status):
    return [x["name"] for x in items if x["status"] == status]
covered = split(DECISIONS, "覆盖")
partial = split(DECISIONS, "部分覆盖")
selfserve = split(DECISIONS, "需自备")
out = f"覆盖 {len(covered)}/{len(DECISIONS)} | 部分覆盖 {len(partial)} | 需自备 {len(selfserve)} | 先补：{selfserve[0]}"
assert (len(covered), len(partial), len(selfserve)) == (3, 1, 1)
print(out)

这份清单是本教程自己划的界，不是官方标准；换个需求，覆盖数会变。比如只做纯文本分类，「图片怎么传」就用不上，覆盖变成两件，部署与权限仍然要自备。清单真正的用处不是那个分数，是让你开工前就知道：哪一段没人替你写。

三、解释与边界：为什么只做这三件，不做那两件

前三件有个共同点：它们都会随官方变。模型会改名、价格会调、接口字段会加。官方定价页自己写着折扣与模型可用性可能变动（F38）；弃用表里还有一批模型，过了某一天就自动路由到新模型，按新模型的价收费（F29、F30）。这类知识靠「记住」没用，只能靠「知道去哪查、什么时候该重查」，所以它成了本教程的主线。

后两件的性质完全不同。部署和权限是公司的基础设施：用哪家云、走不走内网、账号体系怎么接，换一家公司答案就变，写进教程只会误导。密钥和日志只给原则——密钥放在服务端环境变量、日志要脱敏——但不会给某个云平台的具体配置，那是运维文档的活儿。

还有一条边界容易被误解：本教程不承诺免费额度。免费层的数据政策、分层门槛、限额都会变，示例统一用 mock 数据和本地断言，真实调用要你自备额度（F20、F21、F37）。这不是保守，是不想给你埋一颗半年后才会炸的雷。

四、预期输出与异常分支：三种「以为教程该管、其实不管」

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

覆盖 3/5 | 部分覆盖 1 | 需自备 1 | 先补：部署与权限

五种需求里覆盖三件、部分覆盖一件、需自备一件。先说部署与权限，不是因为它最急，而是它是唯一需要你从零搭的一项，其余四项都是接入或配置。三种常见的预期错位，说法不同，根子是同一个：

• 你要私有化部署、数据不出内网——本教程不覆盖，区域与部署方案得另查（见 1.2）。
• 你要接公司 SSO、按员工角色限制能查哪些工单——教程只讲到「检索结果不能直接当可信输入」（见 7.4），不替你实现权限系统。
• 你希望教程直接告诉你「现在最便宜的模型是哪个」——不会给。只会给判断方法：看价格页、看生效日期、看 F 编号（见 10.1）。

遇到这三种，合适的反应不是「教程不完整」，而是「这段本来就不该由教程写」。

五、判据卡：本教程适不适合你

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

• https://aistudio.google.com/docs/pricing.md（核验 2026-11-05，F38、F37）
• https://aistudio.google.com/docs/deprecations.md（核验 2026-11-05，F29、F30）
• https://aistudio.google.com/docs/rate-limits.md（核验 2026-11-05，F19）
• https://aistudio.google.com/docs/terms.md（核验 2026-11-05，F59，待核）

待核说明：网页版内容许可范围仍标为待核（F59）。本节只说明范围划分，不翻译官方文档，也不对许可条款下断言；引用与转载请到官方页复核。

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

1. 用三句话向同事说清「本教程讲什么、不讲什么、适合谁」。说不全，说明你还没决定要不要按它走。
2. 把你手上的需求按五件事拆一遍，标出哪几件属于「模型调用」。拆不出来，说明需求本身还没想清。
3. 找一篇你收藏的 Gemini 教程，看它有没有写核验日期。没写的话，它给的价格和模型名，你打算怎么核实？