上周三我在给一个代码工具接 Gemini 2.5 Pro 的时候，折腾了大半天。流程本身不复杂，15 分钟能跑通，但有两个地方会让你第一次请求直接挂——model name 必须带 models/ 前缀（裸写模型名 404），以及 safety_settings 不显式设成 BLOCK_NONE 时，代码生成类请求会被默认安全策略拦截，返回空 candidates。这篇把最小可用配置模板直接给出来，省得你再踩一遍。

这篇适合谁

• 想接 Gemini 2.5 Pro API 做代码生成/文本补全，但第一次请求就报 404 或拿到空响应的
• 从 GPT-4.1 或 Claude Sonnet 3.7 切过来，对 Google 这套 model name 命名规则不熟悉的
• 用 REST API 直接调用（不走 SDK），需要知道完整 endpoint 格式的
• 团队里有人踩了 safety_settings 的坑，想一次性把配置模板定下来的

整体流程

1. 获取 API Key（Google AI Studio，2 分钟）
2. 确认模型名称格式（带 models/ 前缀）
3. 配置 safety_settings 为 BLOCK_NONE
4. 发出第一个请求，验证返回
5. 接入你的工具链（Cursor / Claude Code / 自定义脚本）

graph LR
 A[获取 API Key] --> B[确认 model name 格式]
 B --> C[配置 safety_settings]
 C --> D[发送测试请求]
 D --> E[接入工具链]

先说结论

坑点	现象	解法
model name 裸写	404 Not Found	必须用 models/gemini-2.5-pro 完整路径
safety_settings 缺省	返回空 candidates，无报错	显式传 4 个 category 全设 BLOCK_NONE
API Key 位置	Header 和 query param 混用，行为未定义	统一用 x-goog-api-key header，不建议混用

第一步：拿 API Key

去 aistudio.google.com/app/apikey 创建一个 Key。免费层 Gemini 2.5 Pro 每分钟 2 次请求，够测试用。

拿到 Key 之后先别急着写代码，用 curl 验一下网络通不通：

curl -s "https://aistudio.google.com/app/apikey" \
 -H "x-goog-api-key: YOUR_KEY" | head -20

如果能正常访问就说明网络没问题。如果超时——你需要配代理或者走聚合网关，后面会讲。

第二步：model name 必须带 models/ 前缀

这是最多人踩的坑。你大概率会这样写：

model = "gemini-2.5-pro"
url = f"https://generativelanguage.googleapis.com/v1beta/{model}:generateContent"

然后收到这个：

google.api_core.exceptions.NotFound: 404 models/gemini-2.5-pro is not found for API version v1beta

注意看报错信息——Google 内部其实会给你拼上 models/ 前缀再查找，但 REST endpoint 的路径格式要求你自己在 URL 里写完整：

model = "models/gemini-2.5-pro"
url = f"https://generativelanguage.googleapis.com/v1beta/{model}:generateContent"

记住一条：REST 调用时 model 字段永远是 models/xxx 格式。用 Python SDK 的话，SDK 内部会帮你处理前缀，但 REST 不会。

第三步：safety_settings 不传 = 代码请求被静默拦截

这个坑更隐蔽。你请求发出去了，HTTP 200，但 response["candidates"] 是空数组。没有报错，没有提示，就是空的。

我当时 debug 了快两小时，最后发现是 safety_settings 的默认值会把含代码片段的请求标记为 HARM_CATEGORY_DANGEROUS_CONTENT，然后直接吞掉。

最小可用配置，把四个 category 全设成 BLOCK_NONE：

safety_settings = [
 {"category": "HARM_CATEGORY_HARASSMENT", "threshold": "BLOCK_NONE"},
 {"category": "HARM_CATEGORY_HATE_SPEECH", "threshold": "BLOCK_NONE"},
 {"category": "HARM_CATEGORY_SEXUALLY_EXPLICIT", "threshold": "BLOCK_NONE"},
 {"category": "HARM_CATEGORY_DANGEROUS_CONTENT", "threshold": "BLOCK_NONE"},
]

把这个塞进请求体的 safetySettings 字段就行。

第四步：最小可用请求模板

完整的、能直接跑通的 REST 请求长这样：

import requests

API_KEY = "your-key-here"
url = (
 "https://generativelanguage.googleapis.com/v1beta/"
 "models/gemini-2.5-pro:generateContent"
)

请求体：

payload = {
 "contents": [{"parts": [{"text": "写一个 Python 快速排序函数"}]}],
 "safetySettings": safety_settings,  # 上面定义的那个列表
}

发送：

headers = {"x-goog-api-key": API_KEY, "Content-Type": "application/json"}
resp = requests.post(url, json=payload, headers=headers)
print(resp.json()["candidates"][0]["content"]["parts"][0]["text"])

跑通了。整个过程确实 15 分钟，但如果不知道那两个坑，能卡你一下午。

第五步：用 Python SDK 的写法

如果你不想手动拼 URL，用官方 SDK 也行。注意 Google 现在有两套 SDK，别装错：

pip install google-generativeai

SDK 调用方式：

import google.generativeai as genai

genai.configure(api_key="YOUR_KEY")
model = genai.GenerativeModel("gemini-2.5-pro")

生成时传入 safety_settings：

response = model.generate_content(
 "写一个 Python 快速排序函数",
 safety_settings=safety_settings,
)
print(response.text)

这里补充说明一下两步之间的区别：REST 调用（第二步）要求你在 URL 路径里自己写完整的 models/gemini-2.5-pro；SDK 调用（本步）则在内部自动处理 models/ 前缀，直接写 gemini-2.5-pro 即可。两种方式效果一样，记住"REST 要带前缀，SDK 不用带"这一条就行。

网络不通怎么办

如果你直连 generativelanguage.googleapis.com 超时：

ConnectionError: HTTPSConnectionPool(host='generativelanguage.googleapis.com', 
port=443): Max retries exceeded

两个方案。方案一，设环境变量走代理：

export HTTPS_PROXY=http://127.0.0.1:7890

方案二，用 OpenAI 兼容格式走聚合网关。OpenRouter、ofox.io 这类平台都支持 Gemini 2.5 Pro，ofox.io 是 Google 官方授权通道且 0% 加价对齐官方定价，改个 base_url 就能切：

from openai import OpenAI

client = OpenAI(
 api_key="your-ofox-key",
 base_url="https://api.ofox.io/v1/"
)

resp = client.chat.completions.create(
 model="gemini-2.5-pro",
 messages=[{"role": "user", "content": "写一个快速排序"}],
)
print(resp.choices[0].message.content)

走 OpenAI 兼容格式的好处是 safety_settings 的问题网关侧已经处理了，你不用自己传那一坨配置。

不同场景怎么选

个人开发者 / 快速原型：直接用 Google AI Studio 的免费额度 + 官方 SDK。每分钟 2 次够用，不用花钱。

后端服务 / 生产环境：走 REST API + 聚合网关。你需要统一的错误处理、重试逻辑、多模型 fallback。直连 Google 的话 429 太频繁了。

已有 OpenAI SDK 的项目迁移：用 OpenAI 兼容格式接入，改一行 base_url 和 model name 就完事，不用重写调用逻辑。

Cursor / Claude Code 用户：在设置里把 base_url 指向聚合网关，model 填 gemini-2.5-pro，保存即可。不需要碰任何代码。

场景	推荐方案	理由
个人测试	官方 SDK + 免费 Key	零成本，2 次/分钟够用
生产后端	REST + 聚合网关	稳定性、重试、审计
现有 OpenAI 项目	改 base_url	最小改动
IDE 插件	聚合网关 + 配置面板	不碰代码

踩坑记录 / 常见问题 FAQ

Q: Gemini 2.5 Pro 和 Gemini 2.5 Flash 怎么选？

A: 代码生成、复杂推理用 2.5 Pro，日常补全、快速问答用 2.5 Flash。2.5 Flash 便宜很多（输入 $0.075/M vs $1.25/M），延迟也低，但复杂任务质量差一截。我的做法是 Pro 做主力，Flash 做 fallback。（价格以 Google AI 官方定价页 为准，随时可能调整。）

Q: 为什么我传了 safety_settings 还是返回空 candidates？

A: 检查你的 threshold 值是不是写成了字符串 "BLOCK_NONE" 而不是枚举。REST 调用用字符串没问题，但如果你用的是旧版 SDK，可能需要用 genai.types.HarmBlockThreshold.BLOCK_NONE 枚举值——具体版本分界点建议查阅 google-generativeai 官方 changelog。升级到最新版后统一用字符串即可。

Q: 免费额度用完了怎么办？429 一直报错

A: 免费层 Pro 每分钟只有 2 次。付费层的速率上限因模型和账户等级不同差异较大，具体数字请参考 Google AI 官方限额文档。如果你跑批量任务，要么加指数退避重试，要么走聚合网关让网关侧帮你做队列管理。我之前写了个简单的 sleep(31) 循环，丑但管用。

Q: 两套 SDK（google-generativeai vs google-genai）到底用哪个？

A: 新项目推荐用 google-genai（新版 Client 模式），API 设计更现代。旧版 google-generativeai 还能用但不再有新功能。官方建议迁移到新版，不推荐两个同时安装，可能引发冲突。

Q: x-goog-api-key header 和 ?key=xxx query param 能混用吗？

A: 不建议混用，行为未定义。选一种就行，推荐 header 方式；query param 方式会让 Key 暴露在代理日志、访问日志和浏览器历史记录里，存在安全风险。

小结

Gemini 2.5 Pro 接入就两个坑：model name 的 models/ 前缀（REST 调用必须带，SDK 调用不用带），和 safety_settings 默认拦截代码生成请求（必须显式设 BLOCK_NONE）。把这篇里的最小配置模板存下来，下次新项目直接复制粘贴就完事。

就是免费层速率限制太抠了，生产用还是得开计费或者走网关。