Gemini API 接入与错误速查
Gemini API 的基础接入、API key、generateContent、常见错误、限流维度、安全拦截、密钥泄露和排查建议。
| 项目 | 应该怎么填 | 排查重点 |
|---|---|---|
| Base URL | https://generativelanguage.googleapis.com | Gemini Developer API REST 请求使用 Google Generative Language API。 |
| 生成内容 | POST /v1beta/models/{model}:generateContent | 文本、图像和多轮内容生成的常用入口。 |
| 模型名 | gemini-3.5-flash 等 | 模型名变化较快；优先从官方模型页或 SDK 示例确认。 |
| 认证 | x-goog-api-key 或 SDK api_key | 403/permission 问题先检查 key、项目、权限和 API 限制。 |
| Google Cloud project | project-bound key | 每个 Gemini API key 关联一个 Google Cloud project，账单和权限也在项目里管理。 |
| 环境变量 | GEMINI_API_KEY | 本地和部署环境建议用环境变量，不要把 key 写进前端代码。 |
| 安全限制 | API restrictions | 只用于 Gemini API 的 key 建议限制到 Gemini API。 |
| 内容结果 | finishReason / safety | 无文本输出时检查 finishReason、安全拦截和 candidate 内容。 |
| HTTP | 状态 / 场景 | 含义 | 先检查什么 |
|---|---|---|---|
400 | INVALID_ARGUMENT | 请求参数、模型名或内容结构不合法。 | 检查 model、contents、parts、role、JSON 结构和 generation config。 |
401 | UNAUTHENTICATED | 认证缺失或凭证无效。 | 检查 x-goog-api-key、环境变量和服务是否启用。 |
403 | PERMISSION_DENIED | key 权限不足、项目错误或 tuned model 认证方式不对。 | 检查项目权限、API 限制、IAM 和 tuned model 访问方式。 |
404 | NOT_FOUND | 模型、资源或 endpoint 不存在。 | 检查模型名、API 版本、地区和资源 ID。 |
429 | RESOURCE_EXHAUSTED | RPM、TPM 或 RPD 任一维度超限。 | 降低并发、退避重试，查看当前 tier 限额。 |
500 | INTERNAL | 服务端错误。 | 记录请求上下文后退避重试。 |
503 | UNAVAILABLE | 服务临时不可用或模型过载。 | 退避重试，必要时切换模型或延后任务。 |
finishReason | SAFETY / MAX_TOKENS | 响应没有正常生成文本。 | 检查 safety ratings、max output tokens 和 prompt 内容。 |
| 维度 | 形式 | 备注 |
|---|---|---|
| RPM | requests / minute | 每分钟请求数，超过任一维度都会限流。 |
| TPM | input tokens / minute | 输入 token 维度，长上下文会更快触发。 |
| RPD | requests / day | 每日请求数，免费或低 tier 项目常见。 |
| Project | Google Cloud project | key、账单、权限和 API 限制都绑定项目。 |
| Blocked key | leaked key | 疑似泄露的 key 可能被阻断，需要重新生成并更新部署。 |
- 社区常见问题集中在 403、429、API key 绑定项目、前端泄露、blocked key、finishReason safety、无文本输出和模型名/API 版本。
- Gemini API key 与 Google Cloud project 绑定；权限、账单、协作者和 API 限制都要回到项目检查。
- 403 PERMISSION_DENIED 常见原因是 key 权限不足、项目选错、API 限制不匹配，或 tuned model 认证方式不对。
- 429 可能由 RPM、TPM、RPD 任一维度触发；降低并发和减少长上下文都可能有帮助。
- 如果响应没有 text，先看 finishReason、candidate、安全评分和 max output tokens。
- 不要把 Gemini API key 当作普通前端公开配置。移动端、浏览器和公开仓库泄露都可能造成账单和额度风险。
- 疑似泄露的 key 可能被 Google 阻断，需要重新生成 key 并更新部署。
来源：Google AI for Developers 官方 Gemini API 文档、API key 文档、troubleshooting、rate limits 文档，以及社区常见排查问题整理。本站只把社区问题作为选题线索；接口、模型、限额与计费事实以官方文档和控制台为准。
这是一张 Gemini API 接入和错误码速查表，适合排查 Gemini API key、403 PERMISSION_DENIED、429 RESOURCE_EXHAUSTED、blocked key、generateContent 请求失败、finishReason safety、无文本输出、前端泄露和限流问题。
相关搜索场景： Gemini API 接入 · Gemini API key · Gemini API 403 · Gemini API 429 · RESOURCE_EXHAUSTED · PERMISSION_DENIED · generateContent · finishReason · safety block · Gemini rate limit · Gemini API key leaked · Gemini blocked key · Gemini no text response · Google AI Studio key
FAQ
Gemini API REST 请求怎么认证？
常见方式是在请求头传 x-goog-api-key，或在官方 SDK 初始化时传 api_key；生产环境建议用环境变量，并确认 key 属于正确的 Google Cloud project。
403 PERMISSION_DENIED 怎么排查？
先确认 key 属于正确 Google Cloud project，再检查 IAM、API 限制、Generative Language API 是否启用、账单状态，以及是否在访问 tuned model。
429 RESOURCE_EXHAUSTED 是什么？
表示 RPM、TPM 或 RPD 等任一限流维度被触发。降低并发、减少上下文长度、退避重试，或查看当前 tier 限额。
为什么 Gemini 响应没有文本？
可能是 safety、MAX_TOKENS、RECITATION 或 candidate 结构导致。检查 finishReason、safety ratings、candidates 和 max output tokens，不要只判断 response.text 是否为空。
API key 被 blocked 怎么办？
如果 key 疑似泄露或被标记，需要在 Google AI Studio 或 Cloud Console 重新生成 key，更新部署后禁用旧 key，并检查近期 usage/billing。
Gemini API key 能不能直接放在前端？
不建议。即使 key 可以加 API restrictions，浏览器、移动端和公开仓库暴露仍可能带来账单、额度和滥用风险。生产应用建议走后端代理或服务端授权层。
为什么限制了 HTTP referrer 还是有风险？
referrer、包名或 IP 限制能降低误用，但不能替代服务端鉴权。社区近期常见事故集中在前端/移动端 key 被复用、额度被刷和账单异常。
为什么 model not found 或 404？
常见原因是模型名过期、API 版本不匹配、地区或项目权限不支持，或把 Vertex AI 和 Gemini Developer API 的模型路径混用了。
免费层和付费层限额为什么不一样？
Gemini 限流按项目、模型和 tier 变化。不要把示例代码里的模型和限额当成生产承诺；上线前要核对当前 rate limits 页面和控制台。
怎么区分 prompt 问题和安全拦截？
先看 finishReason 和 safety ratings。如果是安全或引用相关原因，改 max tokens 没有用；需要调整输入、系统提示、输出要求或业务兜底。