Gemini API 金鑰無法運作——API_KEY_INVALID 及其五個原因

「API key not valid. Please pass a valid API key.」——Gemini 最沒幫助的一句話。金鑰通常本身是有效的；出錯的是周邊設定：來源限制、未啟用 Generative Language API，或將 AI Studio 金鑰傳送至 Vertex 端點。請依下列順序逐項檢查。

錯誤

response (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 referrer / IP）阻擋伺服器呼叫	在 Google Cloud Console → Credentials 中，受 referrer 限制的金鑰會拒絕伺服器端請求。請使用不受限制的金鑰，或改用依 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 金鑰在本機可用，但在生產環境失敗——為什麼？

通常是 referrer/IP 限制（未允許生產環境 IP）、生產環境使用不同的環境檔案，或生產環境專案未啟用 Generative Language API。比較不同環境中的金鑰 repr 與專案 ID。

Gemini API 免費嗎？

AI Studio 有免費方案，但每分鐘配額嚴格；生產流量需要啟用計費（或使用閘道）。如果你遇到的是配額錯誤而非金鑰錯誤，請參閱我們的 RESOURCE_EXHAUSTED 指南。