Batch Mode

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

方法：models.batchGenerateContent

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

端點

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

路徑參數

batch.model string

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

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

要求主體

要求主體會包含結構如下的資料：

欄位
batch.name string

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

格式：batches/{batch_id}。

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)

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

使用 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.updateTime 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.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 表示法 
{   "model": string,   "contents": [     {       object (Content)     }   ],   "tools": [     {       object (Tool)     }   ],   "toolConfig": {     object (ToolConfig)   },   "safetySettings": [     {       object (SafetySetting)     }   ],   "systemInstruction": {     object (Content)   },   "generationConfig": {     object (GenerationConfig)   },   "cachedContent": string }

GenerateContentBatch

代表一批 GenerateContent 要求的資源。

欄位
model string

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

格式：models/{model}。

name string

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

格式：batches/{batch_id}。

displayName string

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

inputConfig object (InputConfig)

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

output object (GenerateContentBatchOutput)

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

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"。

endTime 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"。

updateTime 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"。

batchStats object (BatchStats)

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

state enum (BatchState)

僅供輸出。批次作業的狀態。

priority string (int64 format)

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

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 }

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

這個資源代表某個網路 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) 的作業。

端點

post 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 物件。