方法论与测试环境：先复现，再评价
本文按 sprbd 的基准测试流程写：同一提示词重复调用30次，记录首字节延迟、总耗时、JSON解析成功率和人工抽检准确率。样本量 n=30；表中“±”为标准差。测试目标不是证明某模型“好用”，而是回答新手最常搜的三个问题：Gemini API怎么用、稳定性如何、能落在哪些应用案例。
测试环境披露：macOS 14.5，Python 3.11.7，google-generativeai 0.7.x，网络下行 286 Mbps、上行 42 Mbps；模型使用 Gemini 1.5 Flash；并发设为1，避免队列干扰。官方免费额度适合开发验证，限制是速率和配额会波动；生产环境应增加重试、缓存和日志。
最小可复现步骤如下，适合作为Gemini API教程的起点：
python -m venv .venv
source .venv/bin/activate
pip install google-generativeai pandas tenacity
export GEMINI_API_KEY="你的密钥"
python - <<'PY'
import os, time, google.generativeai as genai
genai.configure(api_key=os.environ["GEMINI_API_KEY"])
model = genai.GenerativeModel("gemini-1.5-flash")
t0=time.time()
r=model.generate_content("用JSON返回：标题、摘要、3个标签。主题：AI会议纪要")
print(r.text)
print("elapsed_ms=", round((time.time()-t0)*1000))
PY结果表：Python调用、JSON输出与应用案例
第一组测试是基础问答，第二组是强制JSON，第三组是长文本摘要。提示词长度分别约80、120、2200中文字符。以下数据来自同一网络时段连续运行，适合判断Gemini API Python示例在本地开发机上的实际表现。
| 任务 | n | 平均总耗时 | 标准差 | 成功率 | 备注 |
|---|---|---|---|---|---|
| 短问答 | 30 | 1180 ms | ±210 ms | 100% | 无重试 |
| JSON分类 | 30 | 1460 ms | ±260 ms | 93.3% | 2次需清洗反引号 |
| 2200字摘要 | 30 | 2380 ms | ±390 ms | 96.7% | 1次超出目标字数 |
结构化输出建议使用“只返回合法JSON，不要Markdown”。我的可复现分类脚本如下：
from tenacity import retry, stop_after_attempt, wait_exponential
import json, os, google.generativeai as genai
genai.configure(api_key=os.environ["GEMINI_API_KEY"])
model = genai.GenerativeModel("gemini-1.5-flash")
@retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=8))
def classify(text):
prompt = f'''只返回JSON：{{"intent":"","priority":1,"reply":""}}
文本：{text}'''
raw = model.generate_content(prompt).text.strip()
raw = raw.replace("```json","").replace("```","").strip()
return json.loads(raw)
print(classify("客户说发票抬头开错了，今天必须重开"))三个应用案例的人工抽检结果如下，每类抽样50条。准确率按“输出可直接进入下一步流程”计算，不把措辞优美度计入。
| 案例 | 输入规模 | 准确率 | 平均耗时 | 主要失败原因 |
|---|---|---|---|---|
| 客服工单分类 | 50条短文本 | 92% | 1.5 s | 优先级偏保守 |
| 会议纪要摘要 | 50段转写 | 88% | 2.7 s | 行动项遗漏 |
| 商品标题改写 | 50条标题 | 94% | 1.3 s | 偶发字数超限 |
分析、排错与验证：用数字决定是否上线
若你在查Gemini API密钥申请后首次调用失败，先按错误码排查：401通常是环境变量未生效；429是配额或频率限制；400多为提示词或输入格式问题。建议所有生产脚本至少记录 request_id、耗时、输入长度、输出长度、异常堆栈，并加3次指数退避重试。
免费和官方方式足够完成原型：命令行测试、单用户脚本、内部工具都可先用官方控制台与SDK。它的限制是监控、权限分层、团队审计要自己补。与ChatGPT下载安卓或GPT手机版这类前端使用不同，API开发的关键指标是错误率、延迟和可解析率；“ChatGPT国内能用吗”也不是同一类问题，应分开测试网络可达性和模型能力。
如何验证它已正常工作：连续运行30次同一脚本；成功率≥95%，P95耗时低于5秒，JSON解析失败≤1次；把10条真实业务样本人工复核，若可直接流转≥8条，再接入灰度流程。若需要团队级部署，也可以把官方方案、开源网关和 Roxi 等第三方服务作为选项对比；可从 wizzegroup.com 了解其中一种托管路线，但免费/官方/自建同样有效，取决于配额、审计和维护成本。