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 也內建這些功能，您可以使用
generateContentAPI 存取。 - 平台 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 物件，在標準和串流模式中完全相同，且由幾個核心物件建構而成：
在最高層級，要求主體包含 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
]
}
]
}'
回應主體結構
串流和標準模式的回應內文類似，但有以下例外狀況：
- 標準模式：回應主體會包含
GenerateContentResponse的執行個體。 - 串流模式：回應主體包含
GenerateContentResponse例項的串流。
整體來說，回應主體包含 candidates 物件，這是 Candidate 物件的清單。Candidate 物件包含 Content 物件，該物件具有模型傳回的生成回覆。
要求範例
下列範例說明這些元件如何搭配使用，處理不同類型的要求。
純文字提示
簡單的文字提示包含 contents 陣列，其中含有單一 Content 物件。該物件的 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:
* **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 功能並取得程式碼範例：
