Gemini API 入门实战：从密钥到首次调用

Google 的 Gemini API 为开发者提供了调用其语言模型的直接通道。原文用不到 500 词完成了一份步骤清单，但真正落到代码时，认证、SDK 初始化和成本控制这几个环节往往才是新手卡住的地方。下面结合这份教程，把每个环节拆开讲清楚，并补充一些原文没展开的实践细节。

获取 API Key 与配置环境

原文的第一步是访问 Google AI Platform 控制台，创建项目、启用 Generative Language API，然后生成密钥。这三步顺序不能颠倒，尤其是启用 API 这一环——很多人在控制台里找不到密钥生成入口，原因就是没先激活对应服务。

拿到密钥后，安装官方 Python 包：

pip install google-generativeai

密钥通过环境变量注入，而不是硬编码在脚本里：

import os
os.environ["GOOGLE_API_KEY"] = "YOUR_API_KEY"

原文把密钥直接赋值给环境变量，这种方式仅适合本地快速验证。生产环境应使用 .env 文件配合 python-dotenv，或接入密钥管理服务，避免密钥随代码提交到仓库。

初始化客户端与发起请求

导入 SDK 并指定模型：

import google.generativeai as genai

model = genai.GenModel("gemini-1.5-pro")

随后构造 prompt 并生成内容：

prompt = "Explain quantum computing in simple terms."
response = model.generate(prompt)
print(response.text)

这段代码是整份教程的核心。GenModel 负责绑定具体模型版本，generate 是同步调用，会阻塞直到返回结果。原文选择 gemini-1.5-pro 作为示例模型，兼顾了能力与成本；如果只是做简单分类或摘要，用更小的模型往往更快也更省钱。

值得注意的是，GenModel 是旧版 SDK（google-generativeai）的构造方式。Google 后来推出了全新的 google-genai SDK，统一了 Gemini 与 Vertex AI 的调用风格，推荐写法改为 from google import genai 后创建 client = genai.Client(api_key=...)，再通过 client.models.generate_content(model="gemini-2.0-flash", contents=prompt) 发起请求。两套 SDK 在方法命名、响应字段和异常类型上都有差异，混用示例代码时容易踩坑。新项目建议直接采用 google-genai，旧代码迁移时重点核对模型名、调用入口和响应解包方式。

理解响应对象的结构

原文指出响应对象包含两个关键字段：

• text：模型生成的实际输出文本。
• usage：token 消耗与成本明细。

usage 常被忽略，但它决定了你能否算清一次调用花了多少钱。把每次请求的 token 数记录下来，是后续做成本优化的前提。原文没有提到的是，部分响应还会携带安全过滤相关的元信息，当 prompt 触及敏感话题时，text 可能为空，此时需要检查过滤原因而不是直接判定调用失败。

token 是模型处理文本的最小计量单位，英文里大约 1 个 token 对应 4 个字符，中文通常 1 个汉字约占 1 至 2 个 token。一次调用消耗的 token 分为输入（prompt）和输出（completion）两部分，而输出单价通常高于输入，因此长回复比长提问更贵。计费口径上，输入和输出的百万 token 单价分别计算，再按实际用量加总。理解这一点后，优化手段就很直接：精简 prompt、限制 max_output_tokens、复用上下文缓存。缓存是指把重复出现的系统提示或长文档预先存储，后续请求以更低单价复用，适合多轮问答或固定知识库场景。

成本管理与错误处理

Gemini API 按百万 token 计费，原文建议监控用量、控制预算，并提到免费额度通常能覆盖小型项目。这条建议对个人开发者和原型验证阶段很实用——先把功能跑通，再考虑扩容。

网络请求天然会失败，原文给出的 try/except 模板：

try:
    response = model.generate(prompt)
except Exception as e:
    print(f"Error: {e}")

捕获宽泛的 Exception 适合起步阶段，但上线前应细化异常类型，区分限流、超时和认证失败，分别做重试或告警，否则线上问题会被统一吞掉，排查成本很高。

网络调用中常见的失败类型各有对应的处理策略。限流（HTTP 429）通常由请求频率或并发过高触发，适合用指数退避重试，即每次失败后等待时间翻倍；超时（网络层异常）应设置合理的超时阈值并有限次重试，避免请求堆积；认证失败（401/403）多为密钥失效或权限不足，重试无意义，应立即告警。生产环境建议区分这些异常类分别捕获，并对重试次数设上限，否则一次下游故障可能引发连锁重试，进一步加剧限流。

后续可以往哪些方向走

原文最后列出三条延伸路径：

• 尝试 gemini-1.5-ultra 等更强模型以获取更高质量输出。
• 将 API 用于对话、嵌入或批量请求。
• 集成进 Web 应用、机器人或数据管道。

这三条其实对应三个不同的工程复杂度层级：换模型只是改一个字符串，对话和嵌入需要管理上下文与向量存储，而集成到数据管道则涉及并发、重试和结果落库。建议按这个顺序逐步推进，每完成一层再进入下一层，避免一开始就把系统设计得过重。

流式输出（streaming）是与本文同步调用并列的另一条主线。同步调用必须等模型生成完整回复才返回，首字延迟等于全部生成时间；流式则在生成过程中逐块推送文本，用户能立刻看到开头，体验更接近实时对话。SDK 一般通过 generate_content_stream 之类的方法返回一个迭代器，循环读取即可打印增量内容。涉及前端展示时，可用 SSE（Server-Sent Events）把分块结果透传给浏览器。对于聊天机器人或长文生成，流式几乎是必备能力，代价是错误处理更复杂——流中断时需要在已输出内容基础上决定重试还是终止。

这份教程适合谁

原文定位清晰——面向完全没接触过 Gemini API 的开发者，用最短路径完成"拿到密钥到打印出第一段文本"。它没有覆盖异步调用、流式输出和多轮对话状态管理，这些在实际项目中迟早会遇到。把它当作一张入场券而非完整手册，会更符合它的价值。