Gemini API 密钥无法使用——API_KEY_INVALID 及其五大原因

“API key not valid. Please pass a valid API key.”——这是 Gemini 最没有帮助的一句话。密钥通常确实有效；出错的是周边配置：引用来源限制、未启用 Generative Language API，或将 AI Studio 密钥发送到了 Vertex 端点。请按以下顺序逐项排查。

错误

响应（HTTP 400）

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [{ "reason": "API_KEY_INVALID" }]
  }
}

原因和解决方法一览

原因	解决方法
密钥限制（HTTP 引用来源 / IP）阻止服务器调用	在 Google Cloud Console → Credentials 中，受引用来源限制的密钥会拒绝服务器端请求。请使用不受限制的密钥，或改为按 API 限制。
项目未启用 Generative Language API	为 AI Studio 风格的密钥启用“Generative Language API”。
AI Studio 密钥与 Vertex AI 端点不匹配	AIza… 密钥调用 generativelanguage.googleapis.com；Vertex 使用另一个主机上的 OAuth/服务账号。不要混用。
不支持的区域	AI Studio 密钥并非在每个国家/地区都可用；请检查可用性，或通过网关进行路由。
环境变量配置（引号/空白/变量名错误）	在失败的进程中执行 print(repr(key))；然后重新干净地导出变量。

单独测试密钥

对 REST 端点执行一次 curl，即可判断密钥本身是否正常：

test-gemini-key.sh

curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=$GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"parts":[{"text":"ping"}]}]}' | head -c 400

检查限制和已启用的 API

Cloud Console → APIs & Services → Credentials：打开该密钥。如果 Application restrictions 显示为“HTTP referrers”，服务器调用将返回 400——切换为 None 或基于 IP 的限制。然后确认同一项目已启用 Generative Language API。

如果无论如何都需要一个密钥来访问多个模型

如果您同时管理 Gemini、Claude 和 GPT 密钥，兼容 OpenAI 的网关可以将它们合并为一个凭证——代码不变，只需一个 base_url，也不需要 Google Cloud 项目。

如果你通过 Kunavo 调用

Kunavo 在同一个兼容 OpenAI 的端点和 sk-kn 密钥后提供 Gemini 2.5 Flash、Pro，以及 Claude 和 GPT——无需 Google Cloud 项目，无需排查密钥限制，并且可在不提供 AI Studio 密钥的区域使用。费率明显低于 Google 列表价格，在任何 OpenAI SDK 中只需配置三个字段。

常见问题

我的 Gemini 密钥在本地有效，但在生产环境失败——为什么？

通常是引用来源/IP 限制（未允许生产环境 IP）、生产环境使用了不同的环境文件，或生产项目未启用 Generative Language API。比较不同环境中密钥的 repr 和项目 ID。

Gemini API 免费吗？

AI Studio 提供免费层，但每分钟配额严格；生产流量需要启用计费（或使用网关）。如果遇到的是配额错误而不是密钥错误，请参阅我们的 RESOURCE_EXHAUSTED 指南。