Gemini API key 怎麼申請？金鑰跟著專案走，不跟著你的帳號

Gemini API key（Gemini API 金鑰）很像一張只認門、不認人的門禁卡。卡片上沒有持有人的名字，只記著它能打開哪一間辦公室的門，而這間辦公室，就是 Google Cloud 專案。

額度怎麼算、帳單由誰付、誰能建立新的金鑰，全都跟著那個專案走。照著舊教學操作時畫面常常對不上，原因在於現行的金鑰已經分成兩種類型，Google 也從 2026 年 5 月起，對無限制的金鑰收緊了規則。

金鑰一旦外洩，別人可以耗掉你專案的額度，帳單上也會多出非預期的費用，所以申請只是第一步，限制用途和妥善保管，才決定這把金鑰用得安不安心。而要看懂後面每一步的畫面與限制，得先弄清楚這把金鑰掛在誰的名下。

Gemini API key 綁在 Google Cloud 專案，不屬於個人帳號

Gemini 是 Google 的生成式 AI 模型系列，程式要呼叫它就得帶上金鑰，而這把金鑰的歸屬單位是 Google Cloud 專案。

根據 Google 的說明，每把 Gemini API 金鑰都關聯一個 Google Cloud 專案，計費、協作者與權限都由專案管理，而 Google AI Studio 只是進出這些專案的輕量入口。換句話說，你在 AI Studio 看到的金鑰清單，本質上是「各個專案底下的金鑰」，不是「你這個 Google 帳號擁有的金鑰」。

金鑰本身也沒有獨立的計費設定，它會繼承所屬專案的層級與計費狀態。同一個專案底下的所有金鑰，用量會合併計算，並一起算進該專案的花費上限。後面談額度與外洩處理時，這個觀念會反覆用到。

現行的 Gemini API 金鑰有兩種類型，差別在於認不認得出呼叫者：

Google 說明，自 2026 年 5 月 28 日起，在 AI Studio 新建的金鑰預設都是 auth 金鑰。所以如果你手上的教學還在講「建立金鑰就是一串字」，而你在 AI Studio 的 API Keys 頁面卻看到 Key Type 欄位，那是因為教學寫的是標準金鑰時期的畫面，你不需要懷疑自己操作錯了。

在 Google AI Studio 建立第一把金鑰

建立金鑰的入口是 AI Studio 的 API Keys 頁面，用 Google 帳號登入並接受服務條款後就能使用。起點分成兩種，全新使用者由系統自動建立專案與金鑰，已經有 Google Cloud 帳號的人則要先把專案匯入，才建得了金鑰。

AI Studio 的介面更新頻繁，按鈕位置常和舊截圖不同，順著頁面上的名稱找會比較可靠。

第一次登入會自動建立預設專案與金鑰

全新的 Google 帳號第一次使用 AI Studio，接受服務條款後，系統會自動建立一個預設的 Google Cloud 專案和一把金鑰。進到 API Keys 頁面就看得到，通常兩三步就能拿到第一把金鑰。

預設專案的名稱可以在左側 Dashboard 的 Projects 檢視裡改掉，專案多了以後比較好辨認。之後想在別的專案建立金鑰，一樣回到 API Keys 頁面按 Create API key，並選定要掛在哪個專案底下。不論是哪一把金鑰，從拿到的那一刻起，就該把它當密碼對待。

已有 Google Cloud 帳號時，專案要先匯入

很多人是已經有 Google Cloud 帳號，才遇到「我的專案怎麼沒出現在 AI Studio」的狀況。AI Studio 不會自動列出你名下所有的 Cloud 專案，要自己匯入，步驟如下：

1. 進入 Google AI Studio，從左側打開 Dashboard，選 Projects。
2. 按 Import projects。
3. 搜尋並選取要使用的專案，按 Import。
4. 回到 API Keys 頁面，在剛匯入的專案底下建立金鑰。

另一個常見的疑惑是「金鑰怎麼找不到」。AI Studio 只會列出無限制的金鑰，或限制在 Gemini API 的金鑰，其他類型的金鑰要到 Google Cloud 主控台的憑證頁面才看得到。此外，API Keys 與 Projects 頁面各有顯示上限，金鑰最多顯示 100 把、專案最多顯示 50 個，清單很長時找不到某一把金鑰，不代表它不存在。

建立按鈕呈灰色，多半是權限不足

如果 Create API key 按鈕呈灰色，旁邊還出現「沒有權限在這個專案建立金鑰」的訊息，原因通常是你在該專案缺少某些 IAM 權限。Google 列出的權限，用白話講是五件事：

• 讀取專案資訊，讓 AI Studio 能確認這個專案。
• 建立 API 金鑰。
• 啟用 Generative Language API。
• 建立服務帳戶，因為現行的金鑰要綁定一個服務帳戶。
• 把服務帳戶與金鑰綁在一起。

這五項通常包含在 Project Editor 這類角色裡。專案如果屬於公司或學校的組織，是否開放建立金鑰是管理員的決定，建議先向專案或組織管理員說明用途，請他依組織的規範評估要不要授與角色，別自己繞過去。

如果只是個人使用，另一條路是用自己的 Google 帳號開一個不隸屬任何組織的新專案，在裡面建立金鑰。個人專案本來就由你自己管理，不需要誰來批准。

用環境變數放金鑰，並以 curl 確認可用

金鑰拿到之後，第一件事是放對地方。Google 建議把金鑰放在環境變數，Gemini API 的用戶端程式庫會自動讀取，程式碼裡就不用出現金鑰。只有在無法使用環境變數的情況下，才在程式裡明確傳入。

放好之後，再用一個最小的請求確認金鑰真的能用。這一節的指令與程式碼，金鑰一律用佔位字串 YOUR_API_KEY，請換成你自己的金鑰，而且別把換好的檔案提交到版本控制。

GOOGLE_API_KEY 的優先順序高於 GEMINI_API_KEY

用戶端程式庫會自動偵測 GEMINI_API_KEY 與 GOOGLE_API_KEY 兩個變數，任何一個有設定都能用。不過兩個都設定時，GOOGLE_API_KEY 的優先順序比較高。

這裡有個常見的小陷阱。你換了新金鑰，改的是 GEMINI_API_KEY，程式卻還在讀舊的 GOOGLE_API_KEY，結果新金鑰怎麼改都沒生效。遇到「改了變數卻沒變化」，先檢查這兩個名稱是不是同時存在。

Windows、macOS 和 Linux 設定環境變數的方式

Linux 與 macOS 使用 Bash 時，把下面這行寫進 ~/.bashrc，存檔後執行 source ~/.bashrc 讓它生效。如果檔案還不存在，先用 touch ~/.bashrc 建立。macOS 使用 Zsh 時，改寫進 ~/.zshrc，再執行 source ~/.zshrc。

export GEMINI_API_KEY="YOUR_API_KEY"Code language: Bash (bash)

Windows 的做法不同，從搜尋列打開「環境變數」視窗，在使用者變數（或系統變數）按「新增」，變數名稱填 GEMINI_API_KEY，變數值貼上你的金鑰，按確定。設定完要重新打開終端機，舊的視窗讀不到剛設好的變數。

用 curl 或 Python SDK 送出第一個請求

下面這段 curl 是 Google 快速入門的最小範例。金鑰放在 x-goog-api-key 標頭，而不是接在網址後面當參數，因為金鑰一旦出現在網址裡，就可能留在伺服器日誌、瀏覽紀錄這類地方。Google Cloud 的最佳做法也建議用標頭或用戶端程式庫傳金鑰。

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": "Explain how AI works in a few words"
  }'Code language: Bash (bash)

這裡的模型名稱與端點，會隨 Google 更新而調整，請以 Google 文件當下列出的為準。上面是 bash 的寫法；在 Windows 的 PowerShell 或命令提示字元執行時，變數的引用語法不同，需要自己調整。

如果你習慣用 Python，先執行 pip install -U google-genai 安裝或更新 SDK（Interactions API 的範例要求 2.3.0 以上的版本）。genai.Client() 不傳金鑰時，會自動去讀剛才設定的環境變數：

from google import genai

# 不傳金鑰，SDK 會自動讀取 GEMINI_API_KEY 或 GOOGLE_API_KEY
client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",  # 模型名稱以 Google 文件當下列出的為準
    input="Explain how AI works in a few words",
)
print(interaction.output_text)Code language: Python (python)

能收到一段文字回覆，就表示金鑰有效。如果收到的是錯誤訊息，429 與 402 屬於額度與計費的問題，後面談額度的段落會說明處理方向。

限制金鑰用途，外洩時損失才有上限

限制金鑰用途的目的很單純，萬一金鑰外洩，拿到的人也只能做有限的事，而這正是舊教學最常缺的一塊。

一把金鑰只負責一件事，其他服務另開金鑰，是下面每個做法共同的原則。

無限制的標準金鑰已被 Gemini API 拒絕

不少人是因為舊程式突然回報金鑰被拒，才開始找原因。根據 Google 的說明，Gemini API 現在會拒絕來自無限制標準金鑰的請求，已經套用明確限制的標準金鑰則仍可使用。

還有另一個日期要留意。自 2026 年 5 月 7 日起，長期休眠的無限制金鑰會被封鎖，在 AI Studio 上會顯示 Blocked 標籤。遇到這種情況，解法是建立一把新金鑰，或改用已加上限制的金鑰。

把金鑰限縮成只能呼叫 Gemini API

最短的做法在 AI Studio 裡就能完成：

1. 在 API Keys 頁面找到標示 Unrestricted 的金鑰。
2. 滑鼠移到標籤上，按 Add restrictions。
3. 選 Restrict to Gemini API only。
4. 按 Restrict key 確認。

這個動作需要 apikeys.keys.update 權限，API Keys Admin 或 Editor 這類角色都包含它。

如果這把金鑰同時給其他 Google API 共用（Google 本身並不建議這種用法），限制方式就不同，要到 Cloud 主控台的憑證頁面，在 API restrictions 裡勾選這把金鑰要存取的其他 API，而且不勾 Generative Language API。限制套用之後，用這把金鑰呼叫 Gemini API 的請求就會失敗，所以 Google 的指示是另外在 AI Studio 建一把限定 Gemini API 的金鑰來用。換句話說，讓 Gemini 用自己的一把金鑰，其他服務另外開，各管各的。

在 Cloud 主控台加上 IP 位址限制

如果呼叫 Gemini API 的是你自己的伺服器，可以把允許的來源 IP 鎖死，這樣金鑰就算外洩，在別的地方也用不了。設定步驟如下：

1. 打開 Google Cloud 主控台的憑證頁面。
2. 選擇專案，再選擇要設定的金鑰。
3. 在 Application restrictions 選 IP addresses。
4. 填入允許的 IP 或 IP 範圍，按 Save。

這個做法適合固定 IP 的伺服器。本機開發的 IP 常常會變動，每次變動都要回來改設定，適不適合要自己評估。至於前端網頁與手機 App，則根本不該把金鑰放進去，原因在下一節。

舊的標準金鑰換成 auth 金鑰的流程

如果你還在使用舊的標準金鑰，換成 auth 金鑰時，順序比步驟本身更重要，一定是先換、後刪：

1. 在 AI Studio 的 API Keys 頁面，看 Key Type 欄位，找出標示 Standard 的金鑰。
2. 按 Create API key 建立新金鑰，新建的一律是 auth 金鑰，然後複製它。
3. 更新程式碼、環境變數與部署設定，讓它們改用新金鑰。
4. 測試應用程式，確認能正常運作。
5. 測試通過後，再刪除或撤銷舊金鑰。

提早刪掉舊金鑰，等於在新金鑰還沒上線前先拆掉現有服務。把「新金鑰能用」確認好，再動舊的，服務才不會中斷。

金鑰保管守則與外洩後的處理順序

Google 把 API 金鑰等同密碼看待。外洩後，別人可以耗用你專案的額度、產生非預期的費用，甚至存取私有資源。平時做好幾個習慣，事發當下知道先做什麼，就能把傷害壓到最低。

金鑰不進 Git，也不寫進網頁或 App

第一件事是永遠不要把金鑰提交到 Git 之類的版本控制系統。環境變數檔與設定檔，記得加進 .gitignore，這樣即使專案後來公開，金鑰也不會一起被帶出去。

第二件事是正式環境的網頁與行動 App，不要把金鑰寫死在程式裡。編譯進去的金鑰，使用者還是能想辦法擷取出來，正確做法是讓使用者的裝置把請求傳給你的後端伺服器，由伺服器加上金鑰再去呼叫 Gemini API。這樣金鑰始終只留在你控制的環境，不會經過使用者的手機或瀏覽器。

Google Cloud 也建議，團隊裡每位成員、每個應用程式，各自使用一把金鑰。這樣哪一把出問題，都能清楚追到是誰、在哪個應用程式，撤銷時也不會牽連其他人。

正式環境把金鑰移進 Secret Manager 並設定用量警示

個人開發階段，環境變數就夠用了。服務上線之後，Google 建議改把金鑰放進 Google Cloud 的 Secret Manager，由專門的機密管理服務保管，比散落在各台機器的設定檔安全。

另外要在 Cloud 主控台設定 billing alerts，用量或費用突然爬升時，系統會通知你。不過要分清楚，警示的作用是讓你早一點發現異常，它不會替你擋住花費；真正能設上限的機制是花費上限，在後面談用量與帳單的段落會說明。

發現外洩時，先換新金鑰再停用舊的

確定或懷疑金鑰外洩時，處理順序是：

1. 建立一把新金鑰，可以在 AI Studio 或 Cloud 主控台建立。
2. 部署使用新金鑰的程式。
3. 確認新金鑰運作正常後，到 Cloud 主控台停用外洩的舊金鑰。
4. 檢查 Google Cloud 主控台的計費紀錄與 API 用量，找出有沒有未授權的使用。

重點在第 3 步的前置條件，也就是「確認新的能用，再動舊的」。Google 特別提醒，新金鑰還沒完全生效前，不要刪除舊金鑰，否則自己的服務會先中斷。

auth 金鑰雖然具備快速攔阻外洩金鑰的機制，但這只是額外的保險，上面四步仍然要自己走完。

免費額度、速率限制與用量的查看位置

具體額度、每分鐘請求數與金額，會依模型、層級與帳戶狀態而異，也經常調整，所以比起數字本身，更實用的是知道每一項去哪裡看。你真正需要的是三個答案：自己現在是免費還是付費、限制是多少、用量與花費在哪裡看。

每個專案的層級從 Free 到 Tier 1 以上不等，由專案連結的計費帳戶決定，連到同一個計費帳戶的專案沿用同一個層級。不同模型的限制不同，預覽模型的限制通常更嚴。需要精確的數字，一律以 AI Studio 上的頁面為準。

新專案預設是免費層，綁定帳單才升級

新帳戶從免費層開始，只能使用部分模型，並受免費層的速率限制。想要更高的限制與進階模型，需要連結 Cloud Billing 帳戶，並走預付或後付的計費方式。升級入口在 AI Studio 的 API Keys 或 Projects 頁面；專案還是免費層時，Projects 頁面的 Billing Tier 欄位會出現 Set up billing 按鈕。

有幾件事特別容易誤會：

• 判斷專案是不是付費：看 Billing Tier 與 Plan 欄位。Plan 欄位標示 Paid，就是付費專案。
• AI Studio 本身免費：但如果你連結了付費金鑰，用這把金鑰在 AI Studio 產生的用量，也會計費。
• 資料用途：付費服務條款下，提示與回應不會用來改進 Google 產品。只要至少有一個 API 專案啟用了計費，你在 AI Studio 裡的提示也會適用同一套付費服務條款。
• 免費試用額度不能抵：自 2026 年 3 月起，Gemini API 的費用排除在 Google Cloud 免費試用方案之外，2026 年 3 月 2 日之後開立帳戶拿到的試用抵扣額度，不能拿來付 Gemini API 與 AI Studio 的用量。
• 回到免費層：要停用專案的計費才會回到免費層，預付餘額歸零也不會自動降級。

預付的最低金額與各個 Tier 的門檻金額，Google 會調整，請以 AI Studio 的 Billing 頁面為準。

速率限制以專案計算，與金鑰數量無關

多開幾把金鑰，並不能多拿到額度。根據 Google 的說明，速率限制以專案計算，不是以金鑰計算，同一個專案裡的金鑰共用同一份額度。

限制通常從三個維度衡量：

• RPM：每分鐘的請求數。
• TPM：每分鐘的輸入 token 數。
• RPD：每天的請求數。

三個維度只要有任何一個超標，就會被限制，即使另外兩個還沒用完。RPD 在太平洋時間的午夜重置。部分模型另外還有每分鐘圖片數或每天 token 數的限制，預覽與實驗模型的限制則通常更嚴。

Google 也註明，文件列出的限制不保證，實際容量可能變動。你的專案現在適用哪些限制，可以直接看 AI Studio 的 rate limit 頁面，它會隨層級與帳戶狀態自動更新。Google 的 API 服務條款也規定不得試圖規避文件所列的限制，靠多個專案輪流使用來繞過限制，並不是正當的做法，需要更高的額度時，正規的路徑是提升層級或申請提高限制。

查看用量、帳單和花費上限的 6 個頁面

想看的東西不同，要去的頁面也不同，整理成下表：

看這些數字時要記得，帳單資料有時間差。根據 Google 的說明，帳單資料的處理大約有 10 分鐘的延遲，這段期間繼續累積的費用，可能讓預付餘額或專案花費上限略為超出；批次模式、代理這類長時間執行的任務，也可能在系統停下之前多用掉一些。

花費上限和前面提到的 billing alerts 是兩回事，一個是提醒，一個是擋住，不能互相取代。不過 Google 也註明，專案層級的花費上限目前仍是實驗性功能，適用範圍有限。另外要留意，預付餘額歸零時，同一個計費帳戶下所有專案的金鑰會同時停止運作，請求會收到 HTTP 402。

429 與 402 錯誤的成因和處理方式

金鑰「突然不能用」時，最常見的就是這兩個錯誤碼。

429 RESOURCE_EXHAUSTED 代表撞到速率限制。處理方向有三個：稍候再重試；降低高成本請求的頻率，例如縮小上下文、縮短輸出；如果在正常使用下也常常撞到限制，再依 Google 提供的表單申請提高限制，不過申請不保證通過。

402 則是預付餘額用完，補足儲值金額後，服務就會恢復。這兩種情況，都沒有「換一把金鑰」或「換一個專案」這種解法，因為限制和餘額都是跟著專案與計費帳戶走的。

AI Studio 金鑰與 Vertex AI 金鑰屬於兩條路線

許多人在 Google 文件之間迷路，是因為 Google 其實有兩個 Gemini API 入口，一個是本篇主線的 Gemini Developer API（用 AI Studio 的金鑰），另一個是 Google Cloud 提供的企業級路線。後者就是大家熟悉的 Vertex AI。

這條路線的名稱最近有變動。Google Cloud 的發行說明在 2026 年 4 月 22 日公告，Vertex AI 改納入 Gemini Enterprise Agent Platform（簡稱 Agent Platform），原本的各項功能也換上新名稱。不過許多既有教學仍沿用 Vertex AI 這個名字，SDK 的參數裡也還看得到 vertexai，所以你搜尋時兩個名稱都會遇到，指的是同一條路線。

兩條路線並沒有優劣之分，各自對應不同的需求。Google 的立場是，大多數開發者使用 Gemini Developer API 即可，除非需要特定的企業控管。兩者現在也都能透過同一套 Google GenAI SDK 存取，差別在建立 client 時的設定。

Gemini Developer API 適合個人和一般應用程式

Gemini Developer API 是取得最快的路線，用 AI Studio 的金鑰驗證，適合個人與一般的應用程式。前面各節談的金鑰申請、限制與保管，全部都屬於這條路線。

對剛開始使用 Gemini API 的人來說，從這裡開始就夠了。等到真的需要企業級的功能與控管時，再評估要不要換到另一條路線。

Vertex AI 快捷模式的金鑰適合快速試用

Google Cloud 也提供 API 金鑰，叫快捷模式（express mode），給想快速試用的人。使用資格是擁有 @gmail.com 的 Google 帳號。Google Cloud 的新使用者可以註冊最長 90 天的免費方案，註冊時不必提供帳單資訊，已經是 Google Cloud 使用者或啟用計費之後，就沒有這段免費期。金鑰在 Google Cloud 主控台的 APIs & Services 底下的 Credentials 頁面查看，中文介面是「API 和服務」下的「憑證」。

快捷模式使用的是不含專案 ID 與位置的全域端點，金鑰同樣放在 x-goog-api-key 標頭。它和完整的 Agent Platform 有幾個差異：

模型與頻率限制另有一張表，數字請以 Google Cloud 的文件頁為準。這個免費方案，也和一般的 Google Cloud 免費試用方案是兩回事。

Google 對這類金鑰的建議也很明確，測試時可以用 API 金鑰，正式環境則建議改用應用程式預設憑證。一旦你升級離開快捷模式，REST 呼叫就要改成指定專案 ID 與位置，不再只帶金鑰。

從 AI Studio 遷移到 Vertex AI 時，程式碼和驗證都要調整

之後如果想從 AI Studio 金鑰遷移到企業級路線，程式端與驗證端各有地方要改。以 Python 為例，建立 client 的寫法會從不帶參數，變成指定專案與位置：

from google import genai

# AI Studio 金鑰路線：不傳金鑰，SDK 自動讀環境變數
client = genai.Client()

# 企業級路線：指定專案與位置，並改用服務帳戶驗證
client = genai.Client(
    enterprise=True, project="your-project-id", location="global"
)Code language: Python (python)

上面是 Interactions API 的寫法；Google 文件裡用 generateContent 的範例，寫的則是 vertexai=True，位置參數也不同，參數寫法以 Google 文件當下的版本為準。

驗證方式也不同，企業級路線需要使用 Google Cloud 的服務帳戶驗證，而不是單純帶一把金鑰。你可以沿用原本產生金鑰的那個 Google Cloud 專案，也可以另建新專案，兩邊支援的區域可能不一樣，遷移前要先確認。

遷移完成後，不再需要的 AI Studio 金鑰，依安全最佳做法應該刪除。做法是到 Google Cloud 的憑證頁面找到那把金鑰，在 Actions 選單選 Delete API key 並確認。刪除需要幾分鐘才會生效，生效後，用那把金鑰的流量就會被拒絕。

Gemini API key 申請起來只要幾分鐘，真正需要花心思的是後面的事：限制它的用途、放在對的地方、發現外洩時知道先做哪一步。把這三件事做在出事之前，這把金鑰才會是一個省事的工具，而不是下個月帳單上的意外。