本文根據 Google AI for Developers 官方文檔（Using Gemini API keys、Quickstart、Troubleshooting、Troubleshoot Google AI Studio）整理，資料核對於 2026-10-10。密鑰規則在 2026 年有較大調整，以官方 API key 頁面為準。
適用於誰
- 第一次想調用 Gemini API，不知道 API Key 去哪裏申請的人；
- 手裏有舊密鑰，突然報錯或在 AI Studio 裏看到 Unrestricted、Blocked 標籤的人；
- 想知道密鑰該放在哪、怎樣才算安全的開發者。
結論先說
- 在 Google AI Studio 的 API Keys 頁面創建，地址是 aistudio.google.com/apikey，創建本身免費。
- 每個密鑰都屬於一個 Google Cloud 項目。新用戶接受服務條款後，AI Studio 會自動建好一個預設項目和一個密鑰。
- 限額和計費跟着項目走，不跟着密鑰走：同一個項目下多建幾個密鑰，額度不會變多。
- 2026 年起密鑰規則變了：新建的密鑰都是「授權密鑰（auth key）」；沒有加限制的舊式標準密鑰會被 Gemini API 拒絕。
- 密鑰當密碼對待：用環境變量
GEMINI_API_KEY儲存，不寫進代碼倉庫，不放進網頁或手機應用的前端代碼。
一、創建密鑰
- 用 Google 帳號登入 Google AI Studio，打開 API Keys 頁面（左側 Dashboard 裏也能進）。
- 新用戶：接受服務條款後，官方說明 AI Studio 會自動創建一個預設的 Google Cloud 項目和 API 密鑰，可以直接用。預設項目的名字可以在 Dashboard 的 Projects 頁面裏改。
- 需要新密鑰時，點「創建 API 密鑰（Create API key）」，按彈窗選擇或新建項目。
- 複製密鑰，馬上存到安全的地方。
已經有 Google Cloud 帳號的人：官方說明這種情況下 AI Studio 不會自動建預設項目，也不會預設顯示你所有的項目，需要先導入：Dashboard → Projects → 「導入項目（Import projects）」→ 搜尋並選中項目 → Import，然後回到 API Keys 頁面在這個項目裏建密鑰。
前提條件（官方條款和可用地區頁）：年滿 18 歲；所在地區在官方可用地區列表內。該列表目前沒有列出中國大陸，請遵守所在地法律和服務條款。
二、密鑰、項目和計費的關係
- 項目（Google Cloud project）管理計費、協作者和權限，AI Studio 只是提供了一個輕量的管理介面。
- 速率限制按項目計算，不按密鑰。帳單頁也寫明：密鑰沒有獨立的計費設定，它繼承所在項目的檔位和計費狀態；同一項目下所有密鑰的用量加在一起算。
- 項目沒有綁定結算帳號時處於免費層，綁定並充值後進入付費層。區別見本站《Gemini API 免費額度是多少：免費層級、RPM / TPM / RPD 速率限制與限額查詢》和《Gemini API 怎麼收費：按 token 計費、預付費充值（Prepay）與支出上限設定》。
AI Studio 的管理上限（官方列出）：Projects 頁面一次最多可創建 10 個項目；API keys 和 Projects 頁面最多顯示 100 個密鑰、50 個項目；只顯示無限制的密鑰或僅限 Gemini API 的密鑰，其他限制方式的密鑰要去 Google Cloud 控制台管理。
三、2026 年的新規則：標準密鑰與授權密鑰
官方 API key 頁面說明，Gemini API 正在從標準密鑰過渡到授權密鑰：
| 標準密鑰（Standard） | 授權密鑰（Authorization / auth key） | |
|---|---|---|
| 作用 | 把請求關聯到項目，用於計費和配額 | 直接綁定到一個 Google Cloud 服務帳號，請求以該服務帳號身份處理 |
| 權限控制 | 不能識別調用者，權限粒度有限 | 支持更細的訪問控制 |
| 預設限制 | 無 | 預設只能用於 Gemini API（Generative Language API） |
| 泄露處理 | — | 檢測到泄露後能更快停用 |
三個時間點：
- 2026 年 5 月 28 日起，在 AI Studio 新建的密鑰自動是授權密鑰；
- 沒有任何限制的標準密鑰，Gemini API 會拒絕它的請求；加了明確限制的標準密鑰還能繼續用；
- 2026 年 5 月 7 日起，長期休眠的無限制密鑰會被封禁，在 AI Studio 裏顯示 Blocked 標籤，只能新建密鑰或改用已有的受限密鑰。
舊密鑰怎麼處理，官方給了兩條路：
- 只用於 Gemini API 的密鑰：在 API Keys 頁面找到帶 Unrestricted 標籤的密鑰，滑鼠懸停後點「添加限制（Add restrictions）」→ 選「僅限 Gemini API（Restrict to Gemini API only）」→ 「限制密鑰（Restrict key）」。需要有項目的
apikeys.keys.update權限。 - 遷移到授權密鑰：看「密鑰類型（Key Type）」一列找出 Standard 的密鑰 → 新建一個密鑰（自動是授權密鑰）→ 把程序、環境變量和部署配置都換成新密鑰 → 測試通過後刪除舊密鑰。
四、設定環境變量
官方推薦把密鑰放在環境變量 GEMINI_API_KEY 或 GOOGLE_API_KEY 裏，官方 SDK 會自動讀取；兩個都設了的話，GOOGLE_API_KEY 優先。
macOS（Zsh）或 Linux（Bash）：在 ~/.zshrc 或 ~/.bashrc 末尾加一行，然後執行 source 讓它生效。
bash
export GEMINI_API_KEY="你的API密鑰"Windows：在搜尋欄搜「環境變量」→ 在系統屬性裏點「環境變量」→ 在用戶變量或系統變量下點「新建」→ 變量名填 GEMINI_API_KEY，值填密鑰 → 確定，然後重新打開一個終端窗口。
不方便用環境變量時，也可以在代碼裏顯式傳入（官方說只在沒法用環境變量時這樣做）：
python
from google import genai
client = genai.Client(api_key="你的API密鑰")五、測試密鑰能不能用
用官方文檔裏的 REST 請求最直接：
bash
curl "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-X POST \
-d '{
"model": "gemini-3.8-flash",
"input": "用一句話介紹你自己"
}'返回的 JSON 裏 status 為 completed 就說明密鑰有效。用 Python 調用見本站《Gemini API Python 調用教學：安裝 google-genai SDK、流式輸出、多輪對話與傳圖片》。
六、密鑰安全
官方把它概括為「像對待密碼一樣對待 API 密鑰」。泄露的後果是別人消耗你的配額、產生意外費用，甚至訪問到私有資源。
- 不要提交到 Git 等版本控制系統；
- 生產環境不要把密鑰放在客戶端：寫進網頁或手機應用裏的密鑰可以被用戶提取出來，正確做法是自己搭一個後端服務代為調用；
- 生產環境建議用 Google Cloud Secret Manager 這類密鑰管理服務；
- 在 Google Cloud 控制台設定結算提醒，用量或費用異常時能收到通知；
- 可以在 Google Cloud 控制台的憑據頁面給密鑰加「應用限制」，例如只允許指定 IP 地址使用。
懷疑泄露時，官方的處理順序是：先生成新密鑰 → 把應用更新為新密鑰並部署 → 確認新密鑰工作正常後，再停用或刪除舊密鑰（避免服務中斷）→ 到 Google Cloud 控制台檢查帳單和用量裏有沒有異常調用。
常見問題
Q：「創建 API 密鑰」按鈕是灰的，提示沒有權限？
官方說明這是缺少 IAM 權限。請項目或組織管理員授予包含這些權限的角色（如項目編輯者）：resourcemanager.projects.get、apikeys.keys.create、serviceusage.services.enable、iam.serviceAccounts.create、iam.serviceAccountApiKeyBindings.create。拿不到權限時，可以新建一個不隸屬於任何組織的項目來創建密鑰。
Q：報「API key not valid. Please pass a valid API key.」？
這是密鑰無效的提示：檢查是否複製完整、環境變量在當前終端是否生效、有沒有同時設定了另一個 GOOGLE_API_KEY（它優先生效）、密鑰是否已被刪除。
Q：報「Your API key was reported as leaked. Please use another API key.」？
官方排錯頁說明，已知泄露的密鑰會被主動封禁，不能再調用 Gemini API。到 AI Studio 新建密鑰，並檢查自己的密鑰保管方式。因此產生的異常費用，官方的指引是提交結算支持工單。
Q：項目裏的其他成員能看到密鑰嗎？
按官方權限表，項目的編輯者（Editor）和所有者（Owner）可以查看面板並管理密鑰；查看者（Viewer）能看面板和密鑰，但不能創建、修改或刪除。
Q：多建幾個密鑰能多拿免費額度嗎？
不能。官方寫明速率限制按項目計算，而不是按密鑰。
參考資料
- Using Gemini API keys（官方）：https://ai.google.dev/gemini-api/docs/api-key
- Gemini API quickstart（官方）：https://ai.google.dev/gemini-api/docs/quickstart
- Troubleshooting guide（官方）：https://ai.google.dev/gemini-api/docs/troubleshooting
- Troubleshoot Google AI Studio（官方）：https://ai.google.dev/gemini-api/docs/troubleshoot-ai-studio
- API errors（官方）：https://ai.google.dev/gemini-api/docs/api-errors
- API errors（generateContent 版，官方）：https://ai.google.dev/gemini-api/docs/generate-content/api-errors
- Billing（官方）：https://ai.google.dev/gemini-api/docs/billing
- Available regions for Google AI Studio and Gemini API（官方）：https://ai.google.dev/gemini-api/docs/available-regions
- Gemini API Additional Terms of Service（官方）：https://ai.google.dev/gemini-api/terms
0 條評論
還沒有評論，來搶沙發～