“API key not valid. Please pass a valid API key.”——Gemini 所说的五种情况

这是 Google 的统称错误：你发送的密钥无法用于此次调用。这并不等同于密钥错误，而且五种原因中有四种情况下密钥本身完全有效——因此重新复制密钥通常是在浪费时间。

错误

响应（HTTP 400）

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

原因和解决方法一览

原因	解决方法
密钥所属项目未启用 Generative Language API	为该项目启用它，然后等待一分钟——刚启用的 API 会在短时间内拒绝请求。
发送到 AI Studio 端点的 Vertex AI 凭据	Vertex 使用 OAuth 访问区域主机；generativelanguage.googleapis.com 需要 AI Studio API 密钥。二者不可互换。
密钥带有 HTTP-referrer 或 IP 限制	服务器端调用不会发送 referrer。请按 IP 限制，或为后端使用签发不受限制的密钥。
密钥发送到了错误的位置	Gemini 读取 `x-goog-api-key` 或 `?key=`。它会忽略 `Authorization: Bearer` 请求头，因此请求到达时没有密钥。
密钥已删除，或来自与你认知不同的 Google 账户	这是唯一重新签发密钥有帮助的原因。请检查 AI Studio 当前登录的是哪个账户。

先单独验证密钥

在处理应用之前，先将密钥用于一个最简单的请求。如果请求成功而应用失败，说明密钥没问题，错误在应用传输密钥的方式上——这样可以同时排除最常见的三种原因。

check-key.sh

curl -s -H "x-goog-api-key: $GEMINI_API_KEY" \
  "https://generativelanguage.googleapis.com/v1beta/models" \
  | head -20

# 200 + a model list  -> the key is valid; look at your client
# 400 API_KEY_INVALID -> the key really cannot call this API

读取客户端实际发送的请求头

大多数 OpenAI 形状的 SDK 会将凭据放入 `Authorization: Bearer`。Gemini 原生 API 不读取该请求头，因此直接将 OpenAI 客户端指向 generativelanguage.googleapis.com，会在密钥完全有效的情况下产生此确切错误。请使用 Google 的 SDK，或调用需要 bearer 形式的 OpenAI 兼容端点。

openai_shape.py

from openai import OpenAI

# Bearer auth, OpenAI request shape, Gemini model names.
client = OpenAI(
    api_key=KUNAVO_API_KEY,
    base_url="https://api.kunavo.com/v1",
)

print(client.chat.completions.create(
    model="gemini-2-5-flash",
    messages=[{"role": "user", "content": "ping"}],
).choices[0].message.content)

区分 400 和 403

如果密钥正确传输后，原因变为 PERMISSION_DENIED，说明密钥已被读取，但因权限范围被拒绝——这是另一个问题，也需要不同的修复方式（项目权限，而非密钥格式）。从 400 变为 403 是进展，不是回退。

如果你通过 Kunavo 调用

在 Kunavo 上，Gemini 通过与其他所有服务相同的 OpenAI 形状端点和相同的 `sk-kn-` 密钥提供服务，并作为普通 bearer token 发送——因此上述请求头不匹配和 Vertex 与 AI Studio 不兼容的原因在这里根本不存在。没有需要启用的 Google 项目，也没有会造成问题的每密钥 referrer 策略。你需要负责的是确保密钥有效且钱包有余额；被拒绝的请求不会计费。按 Token 计费的 Gemini 价格见我们的 Gemini 价格指南.

常见问题

我刚创建了密钥，但仍然显示无效。

刚启用的 API 和全新密钥可能会在一到两分钟内被拒绝。如果超过这段时间仍未解决，项目几乎肯定缺少 Generative Language API，而不是密钥本身有问题。

这是否意味着我用完了配额？

不是。配额耗尽会返回 429 RESOURCE_EXHAUSTED，计费问题会表现为 403。400 API_KEY_INVALID 从不意味着你的余额用完了。

为什么同一个密钥在 AI Studio 中有效，在我的代码中却无效？

AI Studio 的调用来自 Google 自己的来源。受到 referrer 限制的密钥允许该来源，但会拒绝你的服务器，因为服务器根本不会发送 referrer。