使用 Gemini API 金鑰

如要使用 Gemini API，您需要 API 金鑰。本頁面說明如何在 Google AI Studio 中建立及管理金鑰，以及如何設定環境，以便在程式碼中使用金鑰。

API 金鑰

API 金鑰是加密字串，可用於呼叫 Google Cloud API。您可以在 Google AI Studio 的「API 金鑰」頁面中，建立及管理所有 Gemini API 金鑰。

取得 API 金鑰後，您可以透過下列方式連線至 Gemini API：

進行初步測試時，您可以將 API 金鑰寫死在程式碼中，但這只是暫時做法，因為並不安全。如需以硬式編碼方式提供 API 金鑰的範例，請參閱「明確提供 API 金鑰」一節。

Google Cloud 專案

Google Cloud 專案是使用 Google Cloud 服務 (例如 Gemini API)、管理帳單，以及控管協作者和權限的基本要件。Google AI Studio 提供 Google Cloud 專案的輕量型介面。

如果您尚未建立任何專案，請建立新專案，或從 Google Cloud 匯入專案至 Google AI Studio。Google AI Studio 的「專案」頁面會顯示所有有權使用 Gemini API 的金鑰。如需操作說明，請參閱「匯入專案」一節。

匯入專案

每個 Gemini API 金鑰都與 Google Cloud 專案相關聯。根據預設，Google AI Studio 不會顯示所有 Cloud 專案。您必須在「匯入專案」對話方塊中搜尋名稱或專案 ID，匯入所需專案。如要查看您有權存取的完整專案清單，請前往 Cloud Console。

如果尚未匯入任何專案，請按照下列步驟匯入 Google Cloud 專案並建立金鑰：

  1. 前往 Google AI Studio。
  2. 開啟左側面板的「資訊主頁」。
  3. 選取「專案」。
  4. 在「專案」頁面中，選取「匯入專案」按鈕。
  5. 搜尋並選取要匯入的 Google Cloud 專案，然後選取「匯入」按鈕。

匯入專案後，請前往「資訊主頁」選單的「API 金鑰」頁面，在剛匯入的專案中建立 API 金鑰。

限制

在 Google AI Studio 中管理 API 金鑰和 Google Cloud 專案時，有以下限制。

  • 您最多可以一次從 Google AI Studio 的「專案」頁面建立 10 個專案。
  • 您可以命名及重新命名專案和金鑰。
  • 「API 金鑰」和「專案」頁面最多會顯示 100 個金鑰和 100 個專案。
  • 系統只會顯示未設限的 API 金鑰，或是僅限於 Generative Language API 的金鑰。

如要取得專案的其他管理存取權，請前往 Google Cloud 控制台。

將 API 金鑰設為環境變數

如果您設定環境變數 GEMINI_API_KEY 或 GOOGLE_API_KEY，使用 Gemini API 程式庫時，用戶端會自動擷取 API 金鑰。建議您只設定其中一個變數，但如果兩個都設定，GOOGLE_API_KEY 會優先採用。

如果您使用 REST API 或瀏覽器上的 JavaScript，則必須明確提供 API 金鑰。

以下說明如何在不同作業系統中，將 API 金鑰在本機設為環境變數 GEMINI_API_KEY。

Linux/macOS - Bash

Bash 是常見的 Linux 和 macOS 終端機設定。如要檢查是否有設定檔，請執行下列指令：

~/.bashrc

如果回應為「No such file or directory」，您需要建立這個檔案，並執行下列指令來開啟檔案，或使用 zsh：

touch ~/.bashrc
open ~/.bashrc

接著，您需要新增下列匯出指令，設定 API 金鑰：

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

儲存檔案後，請執行下列指令來套用變更：

source ~/.bashrc

macOS - Zsh

Zsh 是常見的 Linux 和 macOS 終端機設定。如要檢查是否有設定檔，請執行下列指令：

~/.zshrc

如果回應為「No such file or directory」，您需要建立這個檔案，並執行下列指令來開啟檔案，或使用 bash：

touch ~/.zshrc
open ~/.zshrc

接著，您需要新增下列匯出指令，設定 API 金鑰：

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

儲存檔案後，請執行下列指令來套用變更：

source ~/.zshrc

Windows

  1. 在搜尋列中搜尋「環境變數」。
  2. 選擇修改「系統設定」。系統可能會要求你確認是否要執行這項操作。
  3. 在系統設定對話方塊中，按一下標示為「環境變數」的按鈕。
  4. 在「使用者變數」 (適用於目前使用者) 或「系統變數」 (適用於使用該機器的所有使用者) 下方，按一下「新增...」
  5. 將變數名稱指定為 GEMINI_API_KEY。將 Gemini API 金鑰指定為變數值。
  6. 按一下「確定」套用變更。
  7. 開啟新的終端機工作階段 (cmd 或 Powershell)，取得新變數。

明確提供 API 金鑰

在某些情況下，您可能需要明確提供 API 金鑰。例如：

  • 您要進行簡單的 API 呼叫，且偏好對 API 金鑰進行硬式編碼。
  • 您希望明確控管，而不必依賴 Gemini API 程式庫自動探索環境變數
  • 您使用的環境不支援環境變數 (例如網頁)，或是您正在發出 REST 呼叫。

以下範例說明如何明確提供 API 金鑰：

Python

from google import genai

client = genai.Client(api_key="YOUR_API_KEY")

response = client.models.generate_content(
    model="gemini-2.5-flash", contents="Explain how AI works in a few words"
)
print(response.text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" });

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: "Explain how AI works in a few words",
  });
  console.log(response.text);
}

main();

Go

package main

import (
    "context"
    "fmt"
    "log"
    "google.golang.org/genai"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        APIKey:  "YOUR_API_KEY",
        Backend: genai.BackendGeminiAPI,
    })
    if err != nil {
        log.Fatal(err)
    }

    result, err := client.Models.GenerateContent(
        ctx,
        "gemini-2.5-flash",
        genai.Text("Explain how AI works in a few words"),
        nil,
    )
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(result.Text())
}

Java

package com.example;

import com.google.genai.Client;
import com.google.genai.types.GenerateContentResponse;

public class GenerateTextFromTextInput {
  public static void main(String[] args) {
    Client client = Client.builder().apiKey("YOUR_API_KEY").build();

    GenerateContentResponse response =
        client.models.generateContent(
            "gemini-2.5-flash",
            "Explain how AI works in a few words",
            null);

    System.out.println(response.text());
  }
}

REST

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H 'Content-Type: application/json' \
  -H "x-goog-api-key: YOUR_API_KEY" \
  -X POST \
  -d '{
    "contents": [
      {
        "parts": [
          {
            "text": "Explain how AI works in a few words"
          }
        ]
      }
    ]
  }'

妥善保管 API 金鑰

請將 Gemini API 金鑰視為密碼，如果遭到入侵，他人就能使用專案配額、產生費用 (如果已啟用帳單)，以及存取私人資料 (例如檔案)。

重大安全性規則

  • 切勿將 API 金鑰提交至原始碼控管系統。請勿在 Git 等版本管控系統中登錄 API 金鑰。

  • 請勿在用戶端公開 API 金鑰。請勿直接在正式版網頁或行動應用程式中使用 API 金鑰。用戶端程式碼中的金鑰 (包括我們的 JavaScript/TypeScript 程式庫和 REST 呼叫) 可以擷取。

最佳做法

  • 使用 API 金鑰進行伺服器端呼叫：使用 API 金鑰最安全的方式，是從伺服器端應用程式呼叫 Gemini API，這樣金鑰就能保密。

  • 使用臨時權杖進行用戶端存取 (僅限 Live API)：如要直接從用戶端存取 Live API，可以使用臨時權杖。這些版本安全性風險較低，適合用於實際工作環境。詳情請參閱臨時權杖指南。

  • 考慮為金鑰新增限制：您可以新增 API 金鑰限制，藉此限制金鑰的權限。這麼做可將金鑰外洩時造成的潛在損害降到最低。

如需一般最佳做法，請參閱這篇支援文章。