Gemini API 現已推出 Gemini 2.5 Flash Image (又稱 Nano Banana)！瞭解詳情

本頁面由 Cloud Translation API 翻譯而成。

Batch Mode

Gemini API 支援批次模式，可透過單一呼叫處理多個要求。詳情請參閱批次模式指南。

方法：models.batchGenerateContent

端點
路徑參數
要求主體
- JSON 表示法
回應主體
授權範圍
GenerateContentRequest
- JSON 表示法

將一批 models.generateContent 要求排入佇列，以進行批次處理。

端點

貼文 https://generativelanguage.googleapis.com/v1beta/{batch.model=models/*}:batchGenerateContent

路徑參數

batch.model string

必要欄位。用於生成完成內容的 Model 名稱。

格式：models/{model}。格式為 models/{model}。

要求主體

要求主體的資料會採用以下結構：

欄位

batch.name string

僅供輸出。ID。批次的資源名稱。

格式：batches/{batchId}。

batch.displayName string

必要欄位。使用者定義的這批名稱。

batch.inputConfig object (InputConfig)

必要欄位。輸入執行批次處理作業的執行個體設定。

batch.output object (GenerateContentBatchOutput)

僅供輸出。批次要求的輸出內容。

batch.createTime string (Timestamp format)

僅供輸出。批次建立時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

batch.endTime string (Timestamp format)

僅供輸出。批次處理完成的時間。

batch.updateTime string (Timestamp format)

僅供輸出。批次上次更新的時間。

batch.batchStats object (BatchStats)

僅供輸出。批次的統計資料。

batch.state enum (BatchState)

僅供輸出。批次的狀態。

batch.priority string (int64 format)

(選用步驟) 批次的優先順序。優先順序值較高的批次，會優先於優先順序值較低的批次處理。允許使用負值。預設值為 0。

回應主體

如果成功，回應主體會包含 Operation 的執行例項。

GenerateContentRequest

要求模型生成完成內容。

欄位

model string

必要欄位。用於生成完成內容的 Model 名稱。

格式：models/{model}。

contents[] object (Content)

必要欄位。目前與模型對話的內容。

如果是單輪查詢，這就是單一執行個體。如果是多輪查詢 (例如即時通訊)，這個重複欄位會包含對話記錄和最新要求。

tools[] object (Tool)

(選用步驟) Tools 可能會用來生成下一個回應的 Model 清單。

Tool是一段程式碼，可讓系統與外部系統互動，以執行 Model 知識和範圍以外的動作或一連串動作。支援的 Tool 為 Function 和 codeExecution。詳情請參閱「函式呼叫」和「程式碼執行」指南。

toolConfig object (ToolConfig)

(選用步驟) 要求中指定任何 Tool 的工具設定。如需使用範例，請參閱函式呼叫指南。

safetySettings[] object (SafetySetting)

(選用步驟) 用於封鎖不安全內容的不重複 SafetySetting 執行個體清單。

這項規定將於 GenerateContentRequest.contents和 GenerateContentResponse.candidates生效。每個 SafetyCategory 類型不得有多個設定。如果內容和回覆未達到這些設定的門檻，API 就會封鎖。這份清單會覆寫 safetySettings 中指定的每個 SafetyCategory 預設設定。如果清單中提供的特定 SafetyCategory 沒有 SafetySetting，API 會使用該類別的預設安全設定。支援的危害類別包括 HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_DANGEROUS_CONTENT、HARM_CATEGORY_HARASSMENT、HARM_CATEGORY_CIVIC_INTEGRITY。如需可用安全設定的詳細資訊，請參閱指南。此外，請參閱安全指南，瞭解如何在 AI 應用程式中納入安全考量。

systemInstruction object (Content)

(選用步驟) 開發人員設定系統指令。目前僅支援文字。

generationConfig object (GenerationConfig)

(選用步驟) 模型生成和輸出內容的設定選項。

cachedContent string

(選用步驟) 快取內容的名稱，用來做為提供預測結果的背景資訊。格式：cachedContents/{cachedContent}

JSON 表示法

JSON 表示法
{ "model": string, "contents": [ { object (`Content`) } ], "tools": [ { object (`Tool`) } ], "toolConfig": { object (`ToolConfig`) }, "safetySettings": [ { object (`SafetySetting`) } ], "systemInstruction": { object (`Content`) }, "generationConfig": { object (`GenerationConfig`) }, "cachedContent": string }

{
  "model": string,
  "contents": [
    {
      object (Content)
    }
  ],
  "tools": [
    {
      object (Tool)
    }
  ],
  "toolConfig": {
    object (ToolConfig)
  },
  "safetySettings": [
    {
      object (SafetySetting)
    }
  ],
  "systemInstruction": {
    object (Content)
  },
  "generationConfig": {
    object (GenerationConfig)
  },
  "cachedContent": string
}

代表一批 GenerateContent 要求的資源。

欄位

model string

必要欄位。用於生成完成內容的 Model 名稱。

格式：models/{model}。

name string

僅供輸出。ID。批次的資源名稱。

格式：batches/{batchId}。

displayName string

必要欄位。使用者定義的這批名稱。

inputConfig object (InputConfig)

必要欄位。輸入執行批次處理作業的執行個體設定。

output object (GenerateContentBatchOutput)

僅供輸出。批次要求的輸出內容。

createTime string (Timestamp format)

僅供輸出。批次建立時間。

endTime string (Timestamp format)

僅供輸出。批次處理完成的時間。

updateTime string (Timestamp format)

僅供輸出。批次上次更新的時間。

batchStats object (BatchStats)

僅供輸出。批次的統計資料。

state enum (BatchState)

僅供輸出。批次的狀態。

priority string (int64 format)

(選用步驟) 批次的優先順序。優先順序值較高的批次，會優先於優先順序值較低的批次處理。允許使用負值。預設值為 0。

JSON 表示法

JSON 表示法
{ "model": string, "name": string, "displayName": string, "inputConfig": { object (`InputConfig`) }, "output": { object (`GenerateContentBatchOutput`) }, "createTime": string, "endTime": string, "updateTime": string, "batchStats": { object (`BatchStats`) }, "state": enum (`BatchState`), "priority": string }

{
  "model": string,
  "name": string,
  "displayName": string,
  "inputConfig": {
    object (InputConfig)
  },
  "output": {
    object (GenerateContentBatchOutput)
  },
  "createTime": string,
  "endTime": string,
  "updateTime": string,
  "batchStats": {
    object (BatchStats)
  },
  "state": enum (BatchState),
  "priority": string
}

InputConfig

設定批次要求的輸入內容。

欄位

source Union type

必要欄位。輸入來源。source 只能是下列其中一項：

fileName string

包含輸入要求的 File 名稱。

requests object (InlinedRequests)

批次處理的要求。

JSON 表示法
{ // source "fileName": string, "requests": { object (`InlinedRequests`) } // Union type }

InlinedRequests

如果要求是批次建立要求的一部分，則為批次中要處理的要求。

欄位

requests[] object (InlinedRequest)

必要欄位。批次處理的要求。

JSON 表示法
{ "requests": [ { object (`InlinedRequest`) } ] }

InlinedRequest

要在批次中處理的要求。

欄位

request object (GenerateContentRequest)

必要欄位。要在批次中處理的要求。

metadata object (Struct format)

(選用步驟) 要與要求建立關聯的中繼資料。

JSON 表示法
{ "request": { object (`GenerateContentRequest`) }, "metadata": { object } }

GenerateContentBatchOutput

批次要求的輸出內容。這會傳回 BatchGenerateContentResponse 或 GenerateContentBatch.output 欄位。

欄位

output Union type

批次要求的輸出內容。output 只能是下列其中一項：

responsesFile string

僅供輸出。包含回覆內容的檔案 ID。這個檔案會是 JSONL 檔案，每行一個回覆。回應會是格式化為 JSON 的 GenerateContentResponse 訊息。回覆的順序與輸入要求相同。

inlinedResponses object (InlinedResponses)

僅供輸出。批次要求的回覆。使用內嵌要求建構批次時，系統會傳回這個錯誤代碼。回應的順序與輸入要求相同。

JSON 表示法
{ // output "responsesFile": string, "inlinedResponses": { object (`InlinedResponses`) } // Union type }

InlinedResponses

批次中的要求回覆。

欄位

inlinedResponses[] object (InlinedResponse)

僅供輸出。批次中的要求回覆。

JSON 表示法
{ "inlinedResponses": [ { object (`InlinedResponse`) } ] }

InlinedResponse

批次中單一要求的相關回應。

欄位

metadata object (Struct format)

僅供輸出。與要求相關聯的中繼資料。

output Union type

要求的輸出內容。output 只能是下列其中一項：

error object (Status)

僅供輸出。處理要求時發生錯誤。

response object (GenerateContentResponse)

僅供輸出。要求的相關回覆。

JSON 表示法
{ "metadata": { object }, // output "error": { object (`Status`) }, "response": { object (`GenerateContentResponse`) } // Union type }

BatchStats

批次的統計資料。

欄位

requestCount string (int64 format)

僅供輸出。批次中的要求數量。

successfulRequestCount string (int64 format)

僅供輸出。成功處理的要求數量。

failedRequestCount string (int64 format)

僅供輸出。無法處理的要求數。

pendingRequestCount string (int64 format)

僅供輸出。仍待處理的要求數量。

JSON 表示法
{ "requestCount": string, "successfulRequestCount": string, "failedRequestCount": string, "pendingRequestCount": string }

BatchState

批次的狀態。

列舉
`BATCH_STATE_UNSPECIFIED`	未指定批次狀態。
`BATCH_STATE_PENDING`	服務正在準備執行批次。
`BATCH_STATE_RUNNING`	批次作業正在進行中。
`BATCH_STATE_SUCCEEDED`	批次作業已順利完成。
`BATCH_STATE_FAILED`	批次作業失敗。
`BATCH_STATE_CANCELLED`	批次作業已取消。
`BATCH_STATE_EXPIRED`	批次已過期。

REST 資源：batches

資源：Operation
- JSON 表示法
方法

資源：Operation

這個資源表示屬於網路 API 呼叫結果的長時間執行作業。

欄位

name string

伺服器指派的名稱，而且只在當初傳回這個名稱的服務中是唯一的。如果您使用預設的 HTTP 對應，則 name 應該是以 operations/{unique_id} 結尾的資源名稱。

metadata object

服務專屬，且與該作業相關聯的中繼資料，通常包含進度資訊和常用中繼資料 (例如建立時間)。部分服務可能不會提供這類中繼資料。凡是會傳回長時間執行作業的方法，都應記錄中繼資料類型 (如果有的話)。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。範例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

done boolean

如果值為 false，代表作業仍在執行中。如果值為 true，代表作業已執行完畢，系統會顯示 error 或 response 的執行結果。

result Union type

這是作業的執行結果，可能為 error，或是有效的 response。如果 done == false，系統不會將結果設定為 error，也不會設定為 response。如果 done == true，系統會將結果設定為 error 或 response。部分服務可能不會提供結果。result 只能是下列其中一項：

error object (Status)

作業執行失敗或遭到取消時，所顯示的錯誤結果。

response object

作業執行成功時的一般回應。如果原始方法在執行成功時沒有傳回資料 (例如 Delete)，則回應為 google.protobuf.Empty。如果原始方法是標準的 Get/Create/Update，回應則應該為資源。如果是其他方法，回應必須包含類型 XxxResponse，其中 Xxx 是原始方法的名稱。舉例來說，如果原始方法的名稱為 TakeSnapshot()，您就能推測出回應類型應該是 TakeSnapshotResponse。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。範例：{ "id": 1234, "@type": "types.example.com/standard/id" }。

JSON 表示法
{ "name": string, "metadata": { "@type": string, field1: ..., ... }, "done": boolean, // result "error": { object (`Status`) }, "response": { "@type": string, field1: ..., ... } // Union type }

方法：batches.get

端點
路徑參數
要求主體
回應主體
授權範圍

取得長時間執行作業的最新狀態。用戶端可以使用這個方法按照 API 服務建議的間隔查詢作業結果。

端點

get https://generativelanguage.googleapis.com/v1beta/{name=batches/*}

路徑參數

name string

作業資源名稱。格式為 batches/{batches}。

要求主體

要求主體必須為空白。

回應主體

如果成功，回應主體會包含 Operation 的執行例項。

方法：batches.list

端點
路徑參數
查詢參數
要求主體
回應主體
授權範圍

列出符合要求中指定篩選器的作業。如果伺服器不支援此方法，則會傳回 UNIMPLEMENTED。

端點

get https://generativelanguage.googleapis.com/v1beta/{name=batches}

路徑參數

name string

作業的父項資源名稱。格式為 batches。

查詢參數

filter string

標準清單篩選器。

pageSize integer

標準清單頁面大小。

pageToken string

標準清單頁面符記。

要求主體

要求主體必須為空白。

回應主體

如果成功，回應主體會包含 ListOperationsResponse 的執行例項。

方法：batches.cancel

端點
路徑參數
要求主體
回應主體
授權範圍

開始非同步取消長時間執行的作業。伺服器會盡全力取消作業，但不保證一定會成功。如果伺服器不支援這個方法，就會傳回 google.rpc.Code.UNIMPLEMENTED。用戶端可以使用 Operations.GetOperation 或其他方法，查看作業是否已成功取消，或是作業即使在用戶端下令取消之後仍然執行完畢。作業在成功取消之後，並不會遭到刪除，而是會成為擁有 Operation.error 值，且 google.rpc.Status.code 為 1 (也就是 Code.CANCELLED) 的作業。

端點

貼文 https://generativelanguage.googleapis.com/v1beta/{name=batches/*}:cancel

路徑參數

name string

要取消的作業資源名稱。格式為 batches/{batches}。

要求主體

要求主體必須為空白。

回應主體

如果成功，回應主體會是空白的 JSON 物件。

方法：batches.delete

端點
路徑參數
要求主體
回應主體
授權範圍

刪除長時間執行的作業。此方法指示用戶端不再對作業結果感興趣。它不會取消作業。如果伺服器不支援這個方法，則會傳回 google.rpc.Code.UNIMPLEMENTED。

端點

delete https://generativelanguage.googleapis.com/v1beta/{name=batches/*}

路徑參數

name string

要刪除的作業資源名稱。格式為 batches/{batches}。

要求主體

要求主體必須為空白。

回應主體

如果成功，回應主體會是空白的 JSON 物件。