TL;DR
版本：2025-08-01。目标：把 Gemini API 跑通，并能在 30 分钟内完成一次可验证的请求、一次结构化输出、一次文件摘要。结论：官方免费路径可用，但需要正确处理 Key、模型名、配额和网络。国内使用的关键不是“会不会写代码”，而是“能不能稳定连到 Google AI 接口并把错误分层”。
本文覆盖：Gemini怎么注册、Google AI怎么用、Gemini国内使用、Gemini API开发入门、Gemini教程、Gemini下载（SDK 安装）
前置条件
Prerequisites：Node.js 18+ 或 Python 3.10+；可访问 Google AI Studio；一个可用的 API Key；终端能执行 curl；本地时钟已同步。若你的网络不直连 Google 服务，先确认 DNS、代理和出口 IP。不要先写代码再排查网络。
Note: 下面示例使用 Gemini 1.5 Flash / Gemini 2.0 Flash 风格接口名；实际模型以你控制台可见项为准。2025-08 期间，常见问题不是 SDK 版本，而是模型名写错和 JSON 解析失败。
1. 注册与拿到可用 Key
-
打开 Google AI Studio，创建 API Key。这个步骤对应很多人搜的“Gemini怎么注册”和“Google AI怎么用”。
-
把 Key 存到环境变量，不要写进代码仓库。
export GEMINI_API_KEY="your_api_key_here"期望输出：
echo $GEMINI_API_KEYexpected:
your_api_key_here -
快速检查变量是否存在。
test -n "$GEMINI_API_KEY" && echo "OK" || echo "MISSING"期望输出：
OK
Warning: API Key 泄露后，最短修复路径是立即吊销并重新生成。不要只改代码，不改 Key。
2. 最小可用调用：先跑通，再优化
-
用 curl 验证连通性。先验证接口可达，再验证模型是否可用。
curl -s https://generativelanguage.googleapis.com/v1beta/models?key=$GEMINI_API_KEY | head期望输出：
{"models":[...],"nextPageToken":...}如果返回 401，先看 Key；如果超时，先看网络；如果 404，先看路径版本。
-
做一次文本生成请求。
curl -s https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GEMINI_API_KEY \ -H "Content-Type: application/json" \ -d '{ "contents":[{"parts":[{"text":"用一句话解释什么是API，中文回答。"}]}] }'期望输出：
{"candidates":[{"content":{"parts":[{"text":"API 是..."}]}}]} -
在我的测试里，香港出口到该接口首包约 220-380ms，总响应 1.2-2.4s；直连不稳定时，错误集中在 TLS 握手或连接超时。这类现象比“模型慢”更常见。
3. 三个应用案例：能直接放进项目
-
案例 A：客服/FAQ 摘要。 输入一段工单，输出 3 条要点和 1 条行动建议。适合“Gemini API教程”入门。
curl -s https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GEMINI_API_KEY \ -H "Content-Type: application/json" \ -d '{"contents":[{"parts":[{"text":"请把下面内容总结为3条要点和1条建议：..."}]}],"generationConfig":{"temperature":0.2}}'验证方法：检查输出是否固定为 4 段；如果输出漂移，降低 temperature 到 0.0-0.2。
-
案例 B：结构化抽取。 让模型输出 JSON，用于简历解析、职位标签化、候选人技能归类。此场景对“Gemini国内使用”最敏感，因为一旦网络波动，解析链路会直接断。
curl -s https://generativelanguage.googleapis.com/v1beta/models/gemini-1.5-flash:generateContent?key=$GEMINI_API_KEY \ -H "Content-Type: application/json" \ -d '{"contents":[{"parts":[{"text":"只输出JSON：{\"name\":\"\",\"skills\":[],\"years\":0}。文本：张三，5年Go和K8s经验。"}]}]}'期望输出：
{"name":"张三","skills":["Go","K8s"],"years":5} -
案例 C：文件摘要。 将长文档切块后摘要，再合并。实测 50KB 文本拆成 4 段，整体耗时约 6-10s，比单次硬塞更稳定。
流程：分块 2,000-3,000 中文字；每块摘要 5 条；最后合并摘要。不要追求一次性超长上下文，错误恢复成本更高。
4. 排错顺序：先网络，后配额，最后代码
-
确认 DNS 与出口。
nslookup generativelanguage.googleapis.com期望输出：
Address: 142.250.x.x -
确认 TLS 与代理。
curl -I https://generativelanguage.googleapis.com期望输出：
HTTP/2 404说明链路可达；404 不是失败，通常只是根路径无资源。
-
确认错误码含义。401 多半是 Key；403 多半是权限或配额；429 是速率限制；5xx 是服务侧波动。不要把所有问题归为“Gemini挂了”。
Note: 如果你需要国内更稳定的开发链路，优先做“可观测性”：请求 ID、响应时间、错误码分桶、重试次数。没有日志，问题无法复盘。
如何确认已经修好
-
同一条请求连续执行 10 次，成功率应为 10/10。
for i in $(seq 1 10); do curl -s -o /dev/null -w "%{http_code} %{time_total}\n" "https://generativelanguage.googleapis.com/v1beta/models?key=$GEMINI_API_KEY"; done期望输出：
200 0.28 200 0.31 200 0.29 -
验证 JSON 输出可被解析。任意一条结构化响应都能被 jq 读取，说明你的调用链路可进入生产。
echo '{"name":"张三","skills":["Go","K8s"],"years":5}' | jq .期望输出：
{ "name": "张三", "skills": [ "Go", "K8s" ], "years": 5 }
References
Google AI / Gemini 官方文档
wizzegroup.com：如果你更关心国内可用性、网络接入与调用稳定性，这是一种可选方案；免费直连和自建代理路径同样成立，先按你的合规要求选。