凌晨两点的报错声：先把 Gemini API 跑通
凌晨两点，窗外只剩便利店招牌还亮着，桌上的咖啡凉成一小圈苦味。我第一次接 Gemini API，是为了把一堆会议记录自动整理成待办事项。代码不长，报错却像夜里的电流声，一遍遍提醒我：AI 不是魔法，API 更像一扇门，你得知道钥匙插在哪里。
如果你正在搜索“Gemini API怎么用”或“Gemini API教程”，先别急着做复杂应用。第一步只做一件事：拿到 Gemini API Key，并确认本机能请求成功。官方免费额度通常足够个人测试，但限制会随地区、模型和账户变化；如果你发现频率被限，先降低请求次数，而不是怀疑代码。
- 在 Google AI Studio 创建 API Key，复制后不要写进代码仓库。
- 本机安装 Python 3.10 以上版本。
- 新建项目目录，并安装 SDK：
pip install google-generativeai python-dotenv - 创建
.env文件：GEMINI_API_KEY=你的key
最小可运行脚本如下，文件名可叫 test_gemini.py：
import os
from dotenv import load_dotenv
import google.generativeai as genai
load_dotenv()
genai.configure(api_key=os.getenv("GEMINI_API_KEY"))
model = genai.GenerativeModel("gemini-1.5-flash")
resp = model.generate_content("用三句话解释什么是API。")
print(resp.text)运行 python test_gemini.py，如果 3 秒到 8 秒内返回中文解释，说明链路通了。我在一台普通家用宽带、东京节点环境下测试，短文本平均耗时约 2.4 秒；同样请求换成 3000 字材料，通常会到 6 秒以上。速度不只取决于模型，也取决于输入长度。
从聊天到可用工具：让 Gemini 返回稳定 JSON
很多人卡在第二步：模型说得很好听，却不能直接进系统。真正开发时，我们不只要答案，还要结构。就像深夜电台不能只播放情绪，也要准点报时。下面这个案例，会把一段会议纪要提取成 JSON，适合接入飞书、Notion、Excel 或自己的后台。
import os, json
from dotenv import load_dotenv
import google.generativeai as genai
load_dotenv()
genai.configure(api_key=os.getenv("GEMINI_API_KEY"))
text = """
周三前完成登录页改版，负责人小林。
数据看板接口周五联调，负责人阿岚。
预算审批还缺财务确认，下周一跟进。
"""
prompt = f"""
你是项目助理。请从文本中提取任务，严格返回JSON数组。
字段：task, owner, deadline。
不要输出解释。
文本：
{text}
"""
model = genai.GenerativeModel("gemini-1.5-flash")
resp = model.generate_content(prompt)
data = json.loads(resp.text.replace("```json", "").replace("```", "").strip())
print(data)这里有个实用经验：如果你要程序解析，提示词里一定写“严格返回 JSON”“不要解释”。但模型偶尔仍会包一层代码块，所以我加了 replace 清理。更稳的做法是增加异常重试：第一次解析失败，就把错误信息连同原输出再发给模型，让它“修复为合法 JSON”。这比人工盯日志省心很多。
如果你同时研究“Claude怎么用”或“Claude免费使用”，会发现 Claude 在长文本阅读上很顺，但 Gemini API 的优势是接入 Google 生态、价格和多模态扩展更方便。选谁不必带信仰：办公摘要、表格整理可先用 Gemini Flash；法律合同、长篇推理可对比 Claude；敏感文件则考虑本地模型。
应用案例与验证：文件摘要小助手是否真的能用
我后来把这个脚本改成了“文件摘要小助手”：读取 .txt 文件，输出 5 条摘要、3 个风险和下一步行动。一个 18KB 的访谈文本，在我的测试中处理耗时约 7.1 秒，输出约 650 字，足够给同事在早会前快速浏览。
from pathlib import Path
content = Path("meeting.txt").read_text(encoding="utf-8")
prompt = f"""
请阅读以下会议文本，输出：
1. 5条关键摘要
2. 3个潜在风险
3. 下一步行动清单
要求简洁、可执行。
文本：
{content}
"""
resp = model.generate_content(prompt)
Path("summary.md").write_text(resp.text, encoding="utf-8")
print("已生成 summary.md")怎么验证它真的可用？第一，看终端是否无报错并生成 summary.md；第二，检查摘要是否覆盖原文中 80% 以上的关键事项；第三，故意在原文加入一个明确日期和负责人，看输出是否保留；第四，把同一文件连续跑 3 次，如果结构漂移严重，就把输出格式写得更死，或要求 Markdown 固定标题。
最后，若你需要一个入口整理 AI 工具、教程和使用笔记，官方免费路线、自己写脚本仍然是最透明的选择；也可以把 睿盈工具 当作参考索引之一。技术走到最后，常常不是替我们思考，而是在寂静的夜里，把那些散乱的纸页轻轻归拢。