Gemini API reference

這份 API 參考資料說明如何使用標準、串流和即時 API 與 Gemini 模型互動。您可以在支援 HTTP 要求的任何環境中使用 REST API。如要瞭解如何發出第一個 API 呼叫，請參閱快速入門指南。如需語言專屬程式庫和 SDK 的參考資料，請前往「SDK 參考資料」下左側導覽中的該語言連結。

主要端點

Gemini API 主要有下列端點：

  • 標準內容生成 (generateContent)： 標準 REST 端點，可處理您的要求，並在單一封包中傳回模型的完整回覆。這最適合非互動式工作，您可以等待整個結果。
  • 串流生成內容 (streamGenerateContent)： 使用伺服器推送事件 (SSE)，在生成回覆的同時將回覆片段推送給您。為聊天機器人等應用程式提供更快速、更具互動性的體驗。
  • Live API (BidiGenerateContent)：以 WebSocket 為基礎的具狀態 API，適用於雙向串流，專為即時對話用途設計。
  • 批次模式 (batchGenerateContent)：提交批次 generateContent 要求的標準 REST 端點。
  • 嵌入 (embedContent)：標準 REST 端點，可從輸入的 Content 生成文字嵌入向量。
  • 生成媒體 API：端點，可使用我們的專用模型生成媒體，例如 Imagen 可生成圖像，Veo 可生成影片。Gemini 也內建這些功能，您可以使用 generateContent API 存取。
  • 平台 API：支援核心功能的實用端點，例如上傳檔案和計算權杖。

驗證

所有 Gemini API 要求都必須包含 x-goog-api-key 標頭和 API 金鑰。在 Google AI Studio 中按幾下滑鼠即可建立。

以下範例要求在標頭中加入 API 金鑰：

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

如要瞭解如何使用 Gemini SDK 將金鑰傳遞至 API，請參閱「使用 Gemini API 金鑰」指南。

內容生成

這是將提示傳送至模型的主要端點。生成內容的端點有兩個，主要差異在於接收回應的方式：

  • generateContent (REST)： 接收要求，並在模型完成整個生成程序後，提供單一回覆。
  • streamGenerateContent (SSE)：接收完全相同的要求，但模型會在生成回覆時，將回覆內容分塊串流傳回。這項功能可立即顯示部分結果，因此能為互動式應用程式提供更優質的使用者體驗。

要求主體結構

要求主體是 JSON 物件，在標準和串流模式中完全相同，且由幾個核心物件建構而成：

  • Content 物件：代表對話中的單一回合。
  • Part 物件：Content 輪流中的一筆資料 (例如文字或圖片)。
  • inline_data (Blob)：原始媒體位元組及其 MIME 類型的容器。

在最高層級，要求主體包含 contents 物件，這是 Content 物件的清單，每個物件代表對話中的一輪。在大多數情況下，如要生成基本文字，您會使用單一 Content 物件，但如要保留對話記錄，則可使用多個 Content 物件。

以下是典型的 generateContent 要求主體：

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
          "role": "user",
          "parts": [
              // A list of Part objects goes here
          ]
      },
      {
          "role": "model",
          "parts": [
              // A list of Part objects goes here
          ]
      }
    ]
  }'

回應主體結構

串流和標準模式的回應內文類似，但有以下例外狀況：

整體來說，回應主體包含 candidates 物件，也就是 Candidate 物件的清單。Candidate 物件包含 Content 物件，該物件具有模型傳回的生成回覆。

要求範例

下列範例說明這些元件如何搭配運作，處理不同類型的要求。

純文字提示

簡單的文字提示包含單一 Content 物件的 contents 陣列。該物件的 parts 陣列則包含具有 text 欄位的單一 Part 物件。

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

多模態提示 (文字和圖片)

如要在提示中同時提供文字和圖片，parts 陣列應包含兩個 Part 物件：一個用於文字，另一個用於圖片 inline_data。

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-X POST \
-d '{
    "contents": [{
    "parts":[
        {
            "inline_data": {
            "mime_type":"image/jpeg",
            "data": "/9j/4AAQSkZJRgABAQ... (base64-encoded image)"
            }
        },
        {"text": "What is in this picture?"},
      ]
    }]
  }'

多輪對話 (即時通訊)

如要建構包含多個輪流對話的對話，請使用多個 Content 物件定義 contents 陣列。API 會將整個記錄做為下一個回應的脈絡資訊。每個 Content 物件的 role 應在 user 和 model 之間交替。

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          { "text": "Hello." }
        ]
      },
      {
        "role": "model",
        "parts": [
          { "text": "Hello! How can I help you today?" }
        ]
      },
      {
        "role": "user",
        "parts": [
          { "text": "Please write a four-line poem about the ocean." }
        ]
      }
    ]
  }'

重點複習

  • Content 是信封：這是訊息回合的頂層容器，無論訊息來自使用者或模型都適用。
  • Part 啟用多模態：在單一 Content 物件中使用多個 Part 物件，結合不同類型的資料 (文字、圖片、影片 URI 等)。
  • 選擇資料方法：
    • 如果是直接嵌入的小型媒體 (例如大多數圖片)，請使用 Part 和 inline_data。
    • 如要上傳較大的檔案，或是在多個要求中重複使用檔案，請使用 File API 上傳檔案，並以 file_data 部分參照該檔案。
  • 管理對話記錄：如果是使用 REST API 的即時通訊應用程式，請為每個回合附加 Content 物件，交替使用 "user" 和 "model" 角色，藉此建構 contents 陣列。如果您使用 SDK，請參閱 SDK 說明文件，瞭解管理對話記錄的建議方式。

回覆範例

下列範例說明這些元件如何搭配運作，處理不同類型的要求。

純文字回覆

簡單的文字回覆包含 candidates 陣列，其中有一或多個包含模型回覆的 content 物件。

以下是標準回應的範例：

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "At its core, Artificial Intelligence works by learning from vast amounts of data ..."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 1
    }
  ],
}

以下是一連串的串流回應。每個回應都包含一個 responseId，可將完整的回應連結在一起：

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "The image displays"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  },
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

...

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " the following materials:\n\n*   **Wood:** The accordion and the violin are primarily"
          }
        ],
        "role": "model"
      },
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": ...
  }
  "modelVersion": "gemini-2.5-flash-lite",
  "responseId": "mAitaLmkHPPlz7IPvtfUqQ4"
}

Live API (BidiGenerateContent) WebSockets API

Live API 提供以 WebSocket 為基礎的具狀態 API，可進行雙向串流，實現即時串流用途。如需更多詳細資料，請參閱 Live API 指南和 Live API 參考資料。

專用模型

除了 Gemini 系列模型，Gemini API 也提供 Imagen、Lyria 和嵌入模型等專用模型的端點。請參閱「模型」部分中的指南。

平台 API

其餘端點則可啟用其他功能，搭配目前所述的主要端點使用。如要瞭解詳情，請參閱「指南」部分的「批次模式」和「檔案 API」主題。

後續步驟

如果你剛開始使用，請參閱下列指南，瞭解 Gemini API 程式設計模型：

您也可以查看功能指南，瞭解不同的 Gemini API 功能並取得程式碼範例：