更新內容生成批次¶
PATCH https://generativelanguage.googleapis.com/v1beta/batches/{generateContentBatch}:updateGenerateContentBatch
更新一批用於批次處理的 GenerateContent 請求。
參數¶
generateContentBatch: required string
批次 ID。構成資源名稱 batches/{generateContentBatch}。
updateMask: string
選用。要更新的欄位清單。
請求主體¶
model: required string
用於生成補全內容的 Model 名稱。格式:models/{model}。
displayName: required string
使用者為此批次定義的名稱。
**inputConfig**: required `InputConfig` 對其執行批次處理的執行個體的輸入設定。
**source**: required `Union type` 輸入的來源。
聯集欄位 `source` 只能是下列其中之一: **fileName**: `string` 包含輸入請求的 `File` 名稱。**requests**: `InlinedRequests` 要在批次中處理的請求。
**requests**: required `InlinedRequest array` 要在批次中處理的請求。
**request**: required `GenerateContentRequest` 要在批次中處理的請求。
**model**: required `string` 用於生成補全內容的 `Model` 名稱。格式:`models/{model}`。**contents**: required `Content array` 與模型目前對話的內容。對於單輪查詢,這是單一執行個體。對於多輪查詢(例如 [chat](/docs/text-generation/#multi-turn-conversations)),這是重複欄位,包含對話記錄與最新請求。
**parts**: `Part array` 組成單一訊息的有序 `Parts`。各 Part 的 MIME 類型可能不同。
**data**: `Union type`
聯集欄位 `data` 只能是下列其中之一: **text**: `string` 內嵌文字。**inlineData**: `Blob` 內嵌媒體位元組。
**mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。支援的類型範例: - 圖片:image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif - 音訊:audio/*, video/audio/s16le, video/audio/wav - 影片:video/* - 文字:text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp - 應用程式:application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf 其他背景資訊請參閱 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **data**: `string` 媒體格式的原始位元組。 **displayName**: `string` 選用。指定用來向模型指稱此 blob 的名稱(例如 "my_blob.png")。當 `verbalization_mode` 設為 `REFERENCE_ONLY` 時,作為 blob 的參照識別碼。**functionCall**: `FunctionCall` 模型傳回的預測 `FunctionCall`,其中包含代表 `FunctionDeclaration.name` 的字串,以及其引數與值。
**name**: required `string` 要呼叫的函式名稱。必須為 a-z、A-Z、0-9,或包含底線與連字號,長度上限為 128。 **id**: `string` 選用。函式呼叫的唯一識別碼。若有填入,用戶端應執行 `function_call`,並傳回具有相符 `id` 的回應。 **args**: `object` 選用。以 JSON 物件格式表示的函式參數與值。**functionResponse**: `FunctionResponse` `FunctionCall` 的結果輸出,其中包含代表 `FunctionDeclaration.name` 的字串,以及包含函式任何輸出的結構化 JSON 物件,作為提供給模型的上下文。
**name**: required `string` 要呼叫的函式名稱。必須為 a-z、A-Z、0-9,或包含底線與連字號,長度上限為 128。 **response**: required `object` 以 JSON 物件格式表示的函式回應。呼叫端可以使用任何符合函式語法的自選鍵來傳回函式輸出,例如 "output"、"result" 等。特別是當函式呼叫執行失敗時,回應可以包含 "error" 鍵,將錯誤詳細資訊傳回給模型。多媒體內容可以透過子物件納入,該子物件包含單一 "$ref" 鍵,其值為 `inline_data.display_name` 或 `file_data.display_name`,屬於持有該多媒體內容的 `FunctionResponsePart`。請參閱 [Multimodal function responses](/docs/function-calling/#multimodal)。 **id**: `string` 選用。此回應所對應的函式呼叫識別碼。由用戶端填入,以對應相對應的函式呼叫 `id`。**parts**: `FunctionResponsePart array` 選用。組成函式回應的有序 `Parts`。各 Part 的 IANA MIME 類型可能不同。
**data**: `Union type` 函式回應部分的資料。
聯集欄位 `data` 只能是下列其中之一:**inlineData**: `FunctionResponseBlob` 內嵌媒體位元組。
**mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。範例: - image/png - image/jpeg 若提供不支援的 MIME 類型,將傳回錯誤。支援類型的完整清單請參閱 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **data**: `string` 媒體格式的原始位元組。 **displayName**: `string` 選用。blob 的顯示名稱。用來提供標籤或檔名以區分各個 blob,並可從 `FunctionResponse.response` 參照該 blob(例如透過 `{"$ref": "DISPLAY_NAME"}`)。**fileData**: `FunctionResponseFileData` 以 URI 為基礎的資料。
**fileUri**: required `string` URI。 **mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。若提供不支援的 MIME 類型,將傳回錯誤。支援類型的完整清單請參閱 [Multimodal function responses](/docs/function-calling/#multimodal) 與 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **displayName**: `string` 選用。檔案的顯示名稱。用來提供標籤或檔名以區分檔案資料,並可從 `FunctionResponse.response` 參照該檔案(例如透過 `{"$ref": "DISPLAY_NAME"}`)。**mediaProcessing**: `string enum` 選用。模型如何處理此部分的媒體以進行理解。僅對影片部分(`inline_data` 或具有影片 MIME 類型的 `file_data`)有意義。非影片部分會忽略此欄位。
可能的值: - `MEDIA_PROCESSING_UNSPECIFIED`: 預設為模型專屬的處理方式。 - `STATIC`: 固定速率的影格擷取。所有影格都放入上下文中。 - `AGENTIC`: 由模型驅動的動態導覽。建議用於大多數使用情境。**scheduling**: `string enum` 選用。指定回應在對話中的排程方式。僅適用於 NON_BLOCKING 函式呼叫,其他情況會被忽略。預設為 WHEN_IDLE。
可能的值: - `SCHEDULING_UNSPECIFIED`: 此值未使用。 - `SILENT`: 僅將結果加入對話上下文,不中斷也不觸發生成。 - `WHEN_IDLE`: 將結果加入對話上下文,並在不中斷進行中生成的情況下提示生成輸出。 - `INTERRUPT`: 將結果加入對話上下文,中斷進行中的生成,並提示生成輸出。**fileData**: `FileData` 以 URI 為基礎的資料。
**fileUri**: required `string` URI。 **mimeType**: `string` 選用。來源資料的 IANA 標準 MIME 類型。 **displayName**: `string` 選用。指定用來向模型指稱此檔案的名稱(例如 "my_file.pdf")。當 `verbalization_mode` 設為 `REFERENCE_ONLY` 時,作為檔案的參照識別碼。**executableCode**: `ExecutableCode` 由模型生成、預定要執行的程式碼。
**language**: required `string enum` `code` 的程式語言。
可能的值: - `LANGUAGE_UNSPECIFIED`: 未指定的語言。不應使用此值。 - `PYTHON`: Python >= 3.10,可使用 numpy 與 simpy。Python 為預設語言。**codeExecutionResult**: `CodeExecutionResult` 執行 `ExecutableCode` 的結果。
**outcome**: required `string enum` 程式碼執行的結果。
可能的值: - `OUTCOME_UNSPECIFIED`: 未指定的狀態。不應使用此值。 - `OUTCOME_OK`: 程式碼執行成功完成。`output` 包含標準輸出(若有)。 - `OUTCOME_FAILED`: 程式碼執行失敗。`output` 包含標準錯誤與標準輸出(若有)。 - `OUTCOME_DEADLINE_EXCEEDED`: 程式碼執行時間過長,已被取消。可能有、也可能沒有部分的 `output`。**toolCall**: `ToolCall` 伺服器端工具呼叫。當模型預測某個工具叫用應在伺服器上執行時,會填入此欄位。用戶端應將此訊息原樣回傳給 API。
**toolType**: required `V1mainToolType` 被呼叫的工具類型。
可能的值: - `TOOL_TYPE_UNSPECIFIED`: 未指定的工具類型。 - `GOOGLE_SEARCH_WEB`: Google 搜尋工具,對應至 Tool.google_search.search_types.web_search。 - `GOOGLE_SEARCH_IMAGE`: 圖片搜尋工具,對應至 Tool.google_search.search_types.image_search。 - `URL_CONTEXT`: URL 上下文工具,對應至 Tool.url_context。 - `GOOGLE_MAPS`: Google 地圖工具,對應至 Tool.google_maps。 - `FILE_SEARCH`: File Search 工具,對應至 Tool.file_search。 - `MEDIA_PROCESSING`: 媒體處理工具類型(例如影片、音訊等),對應至用於多模態理解的隱形工具,例如 GOOGLE_UNDERSTANDING_VIDEO。**toolResponse**: `ToolResponse` 伺服器端 `ToolCall` 執行的輸出。此欄位由用戶端填入,內容為執行對應 `ToolCall` 的結果。
**toolType**: required `V1mainToolType` 被呼叫的工具類型,其 `tool_type` 與對應的 `ToolCall` 相符。
可能的值: - `TOOL_TYPE_UNSPECIFIED`: 未指定的工具類型。 - `GOOGLE_SEARCH_WEB`: Google 搜尋工具,對應至 Tool.google_search.search_types.web_search。 - `GOOGLE_SEARCH_IMAGE`: 圖片搜尋工具,對應至 Tool.google_search.search_types.image_search。 - `URL_CONTEXT`: URL 上下文工具,對應至 Tool.url_context。 - `GOOGLE_MAPS`: Google 地圖工具,對應至 Tool.google_maps。 - `FILE_SEARCH`: File Search 工具,對應至 Tool.file_search。 - `MEDIA_PROCESSING`: 媒體處理工具類型(例如影片、音訊等),對應至用於多模態理解的隱形工具,例如 GOOGLE_UNDERSTANDING_VIDEO。**metadata**: `Union type` 控制資料的額外前置處理。當 `inline_data` 或 `file_data` 存在時設定此欄位,以設定每個部分的靜態媒體前置處理。
聯集欄位 `metadata` 只能是下列其中之一:**videoMetadata**: `VideoMetadata` 選用。影片中繼資料。僅當影片資料以 inline_data 或 file_data 呈現時,才應指定中繼資料。
**startOffset**: `string` 選用。影片的開始偏移。 **endOffset**: `string` 選用。影片的結束偏移。 **fps**: `number` 選用。傳送給模型的影片影格率。若未指定,預設值為 1.0。fps 範圍為 (0.0, 24.0]。**mediaResolution**: `V1mainMediaResolution` 選用。輸入媒體的媒體解析度。
**value**: `Union type` 媒體解析度等級。
聯集欄位 `value` 只能是下列其中之一:**level**: `string enum` 指定媒體所使用的權杖化品質。
可能的值: - `MEDIA_RESOLUTION_UNSPECIFIED`: 尚未設定媒體解析度。 - `MEDIA_RESOLUTION_LOW`: 媒體解析度設為低。 - `MEDIA_RESOLUTION_MEDIUM`: 媒體解析度設為中。 - `MEDIA_RESOLUTION_HIGH`: 媒體解析度設為高。 - `MEDIA_RESOLUTION_ULTRA_HIGH`: 媒體解析度設為超高。**mediaProcessing**: `string enum` 選用。模型如何處理此部分的媒體以進行理解。僅對影片部分(`inline_data` 或具有影片 MIME 類型的 `file_data`)有意義。非影片部分會忽略此欄位。
可能的值: - `MEDIA_PROCESSING_UNSPECIFIED`: 預設為模型專屬的處理方式。 - `STATIC`: 固定速率的影格擷取。所有影格都放入上下文中。 - `AGENTIC`: 由模型驅動的動態導覽。建議用於大多數使用情境。**audioTranscription**: `AudioTranscription` 選用。音訊(輸入或輸出)轉錄。僅當此 Part 包含音訊資料時才會設定。
**text**: required `string` 此音訊片段的轉錄文字。 **speakerLabel**: `string` 選用。標示此音訊片段說話者的標籤(例如 "spk_1"、"spk_2")。在設定 diarization 時出現。**words**: `WordInfo array` 選用。詳細的單字層級轉錄與時間資訊。在設定 word_timestamp 時出現。
**word**: required `string` 單字的轉錄。 **startOffset**: `string` 選用。單字相對於音訊開頭的開始時間偏移。 **endOffset**: `string` 選用。單字相對於音訊開頭的結束時間偏移。**speechMetadata**: `SpeechMetadata` 選用。套用至文字部分的中繼資料,用來客製化其朗讀或合成方式,例如指定說話者身分或說話風格。
**speaker**: `string` 選用。多說話者合成的選用說話者名稱。 **style**: `string` 選用。語音合成的選用風格指令。**systemInstruction**: `Content` 選用。開發人員設定的 [system instruction(s)](/docs/text-generation/#system-instructions)。目前僅支援文字。
**parts**: `Part array` 組成單一訊息的有序 `Parts`。各 Part 的 MIME 類型可能不同。
**data**: `Union type`
聯集欄位 `data` 只能是下列其中之一: **text**: `string` 內嵌文字。**inlineData**: `Blob` 內嵌媒體位元組。
**mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。支援的類型範例: - 圖片:image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif - 音訊:audio/*, video/audio/s16le, video/audio/wav - 影片:video/* - 文字:text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp - 應用程式:application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf 其他背景資訊請參閱 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **data**: `string` 媒體格式的原始位元組。 **displayName**: `string` 選用。指定用來向模型指稱此 blob 的名稱(例如 "my_blob.png")。當 `verbalization_mode` 設為 `REFERENCE_ONLY` 時,作為 blob 的參照識別碼。**functionCall**: `FunctionCall` 模型傳回的預測 `FunctionCall`,其中包含代表 `FunctionDeclaration.name` 的字串,以及其引數與值。
**name**: required `string` 要呼叫的函式名稱。必須為 a-z、A-Z、0-9,或包含底線與連字號,長度上限為 128。 **id**: `string` 選用。函式呼叫的唯一識別碼。若有填入,用戶端應執行 `function_call`,並傳回具有相符 `id` 的回應。 **args**: `object` 選用。以 JSON 物件格式表示的函式參數與值。**functionResponse**: `FunctionResponse` `FunctionCall` 的結果輸出,其中包含代表 `FunctionDeclaration.name` 的字串,以及包含函式任何輸出的結構化 JSON 物件,作為提供給模型的上下文。
**name**: required `string` 要呼叫的函式名稱。必須為 a-z、A-Z、0-9,或包含底線與連字號,長度上限為 128。 **response**: required `object` 以 JSON 物件格式表示的函式回應。呼叫端可以使用任何符合函式語法的自選鍵來傳回函式輸出,例如 "output"、"result" 等。特別是當函式呼叫執行失敗時,回應可以包含 "error" 鍵,將錯誤詳細資訊傳回給模型。多媒體內容可以透過子物件納入,該子物件包含單一 "$ref" 鍵,其值為 `inline_data.display_name` 或 `file_data.display_name`,屬於持有該多媒體內容的 `FunctionResponsePart`。請參閱 [Multimodal function responses](/docs/function-calling/#multimodal)。 **id**: `string` 選用。此回應所對應的函式呼叫識別碼。由用戶端填入,以對應相對應的函式呼叫 `id`。**parts**: `FunctionResponsePart array` 選用。組成函式回應的有序 `Parts`。各 Part 的 IANA MIME 類型可能不同。
**data**: `Union type` 函式回應部分的資料。
聯集欄位 `data` 只能是下列其中之一:**inlineData**: `FunctionResponseBlob` 內嵌媒體位元組。
**mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。範例: - image/png - image/jpeg 若提供不支援的 MIME 類型,將傳回錯誤。支援類型的完整清單請參閱 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **data**: `string` 媒體格式的原始位元組。 **displayName**: `string` 選用。blob 的顯示名稱。用來提供標籤或檔名以區分各個 blob,並可從 `FunctionResponse.response` 參照該 blob(例如透過 `{"$ref": "DISPLAY_NAME"}`)。**fileData**: `FunctionResponseFileData` 以 URI 為基礎的資料。
**fileUri**: required `string` URI。 **mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。若提供不支援的 MIME 類型,將傳回錯誤。支援類型的完整清單請參閱 [Multimodal function responses](/docs/function-calling/#multimodal) 與 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **displayName**: `string` 選用。檔案的顯示名稱。用來提供標籤或檔名以區分檔案資料,並可從 `FunctionResponse.response` 參照該檔案(例如透過 `{"$ref": "DISPLAY_NAME"}`)。**mediaProcessing**: `string enum` 選用。模型如何處理此部分的媒體以進行理解。僅對影片部分(`inline_data` 或具有影片 MIME 類型的 `file_data`)有意義。非影片部分會忽略此欄位。
可能的值: - `MEDIA_PROCESSING_UNSPECIFIED`: 預設為模型專屬的處理方式。 - `STATIC`: 固定速率的影格擷取。所有影格都放入上下文中。 - `AGENTIC`: 由模型驅動的動態導覽。建議用於大多數使用情境。**scheduling**: `string enum` 選用。指定回應在對話中的排程方式。僅適用於 NON_BLOCKING 函式呼叫,其他情況會被忽略。預設為 WHEN_IDLE。
可能的值: - `SCHEDULING_UNSPECIFIED`: 此值未使用。 - `SILENT`: 僅將結果加入對話上下文,不中斷也不觸發生成。 - `WHEN_IDLE`: 將結果加入對話上下文,並在不中斷進行中生成的情況下提示生成輸出。 - `INTERRUPT`: 將結果加入對話上下文,中斷進行中的生成,並提示生成輸出。**fileData**: `FileData` 以 URI 為基礎的資料。
**fileUri**: required `string` URI。 **mimeType**: `string` 選用。來源資料的 IANA 標準 MIME 類型。 **displayName**: `string` 選用。指定用來向模型指稱此檔案的名稱(例如 "my_file.pdf")。當 `verbalization_mode` 設為 `REFERENCE_ONLY` 時,作為檔案的參照識別碼。**executableCode**: `ExecutableCode` 由模型生成、預定要執行的程式碼。
**language**: required `string enum` `code` 的程式語言。
可能的值: - `LANGUAGE_UNSPECIFIED`: 未指定的語言。不應使用此值。 - `PYTHON`: Python >= 3.10,可使用 numpy 與 simpy。Python 為預設語言。**codeExecutionResult**: `CodeExecutionResult` 執行 `ExecutableCode` 的結果。
**outcome**: required `string enum` 程式碼執行的結果。
可能的值: - `OUTCOME_UNSPECIFIED`: 未指定的狀態。不應使用此值。 - `OUTCOME_OK`: 程式碼執行成功完成。`output` 包含標準輸出(若有)。 - `OUTCOME_FAILED`: 程式碼執行失敗。`output` 包含標準錯誤與標準輸出(若有)。 - `OUTCOME_DEADLINE_EXCEEDED`: 程式碼執行時間過長,已被取消。可能有、也可能沒有部分的 `output`。**toolCall**: `ToolCall` 伺服器端工具呼叫。當模型預測某個工具叫用應在伺服器上執行時,會填入此欄位。用戶端應將此訊息原樣回傳給 API。
**toolType**: required `V1mainToolType` 被呼叫的工具類型。
可能的值: - `TOOL_TYPE_UNSPECIFIED`: 未指定的工具類型。 - `GOOGLE_SEARCH_WEB`: Google 搜尋工具,對應至 Tool.google_search.search_types.web_search。 - `GOOGLE_SEARCH_IMAGE`: 圖片搜尋工具,對應至 Tool.google_search.search_types.image_search。 - `URL_CONTEXT`: URL 上下文工具,對應至 Tool.url_context。 - `GOOGLE_MAPS`: Google 地圖工具,對應至 Tool.google_maps。 - `FILE_SEARCH`: File Search 工具,對應至 Tool.file_search。 - `MEDIA_PROCESSING`: 媒體處理工具類型(例如影片、音訊等),對應至用於多模態理解的隱形工具,例如 GOOGLE_UNDERSTANDING_VIDEO。**toolResponse**: `ToolResponse` 伺服器端 `ToolCall` 執行的輸出。此欄位由用戶端填入,內容為執行對應 `ToolCall` 的結果。
**toolType**: required `V1mainToolType` 被呼叫的工具類型,其 `tool_type` 與對應的 `ToolCall` 相符。
可能的值: - `TOOL_TYPE_UNSPECIFIED`: 未指定的工具類型。 - `GOOGLE_SEARCH_WEB`: Google 搜尋工具,對應至 Tool.google_search.search_types.web_search。 - `GOOGLE_SEARCH_IMAGE`: 圖片搜尋工具,對應至 Tool.google_search.search_types.image_search。 - `URL_CONTEXT`: URL 上下文工具,對應至 Tool.url_context。 - `GOOGLE_MAPS`: Google 地圖工具,對應至 Tool.google_maps。 - `FILE_SEARCH`: File Search 工具,對應至 Tool.file_search。 - `MEDIA_PROCESSING`: 媒體處理工具類型(例如影片、音訊等),對應至用於多模態理解的隱形工具,例如 GOOGLE_UNDERSTANDING_VIDEO。**metadata**: `Union type` 控制資料的額外前置處理。當 `inline_data` 或 `file_data` 存在時設定此欄位,以設定每個部分的靜態媒體前置處理。
聯集欄位 `metadata` 只能是下列其中之一:**videoMetadata**: `VideoMetadata` 選用。影片中繼資料。僅當影片資料以 inline_data 或 file_data 呈現時,才應指定中繼資料。
**startOffset**: `string` 選用。影片的開始偏移。 **endOffset**: `string` 選用。影片的結束偏移。 **fps**: `number` 選用。傳送給模型的影片影格率。若未指定,預設值為 1.0。fps 範圍為 (0.0, 24.0]。**mediaResolution**: `V1mainMediaResolution` 選用。輸入媒體的媒體解析度。
**value**: `Union type` 媒體解析度等級。
聯集欄位 `value` 只能是下列其中之一:**level**: `string enum` 指定媒體所使用的權杖化品質。
可能的值: - `MEDIA_RESOLUTION_UNSPECIFIED`: 尚未設定媒體解析度。 - `MEDIA_RESOLUTION_LOW`: 媒體解析度設為低。 - `MEDIA_RESOLUTION_MEDIUM`: 媒體解析度設為中。 - `MEDIA_RESOLUTION_HIGH`: 媒體解析度設為高。 - `MEDIA_RESOLUTION_ULTRA_HIGH`: 媒體解析度設為超高。**mediaProcessing**: `string enum` 選用。模型如何處理此部分的媒體以進行理解。僅對影片部分(`inline_data` 或具有影片 MIME 類型的 `file_data`)有意義。非影片部分會忽略此欄位。
可能的值: - `MEDIA_PROCESSING_UNSPECIFIED`: 預設為模型專屬的處理方式。 - `STATIC`: 固定速率的影格擷取。所有影格都放入上下文中。 - `AGENTIC`: 由模型驅動的動態導覽。建議用於大多數使用情境。**audioTranscription**: `AudioTranscription` 選用。音訊(輸入或輸出)轉錄。僅當此 Part 包含音訊資料時才會設定。
**text**: required `string` 此音訊片段的轉錄文字。 **speakerLabel**: `string` 選用。標示此音訊片段說話者的標籤(例如 "spk_1"、"spk_2")。在設定 diarization 時出現。**words**: `WordInfo array` 選用。詳細的單字層級轉錄與時間資訊。在設定 word_timestamp 時出現。
**word**: required `string` 單字的轉錄。 **startOffset**: `string` 選用。單字相對於音訊開頭的開始時間偏移。 **endOffset**: `string` 選用。單字相對於音訊開頭的結束時間偏移。**speechMetadata**: `SpeechMetadata` 選用。套用至文字部分的中繼資料,用來客製化其朗讀或合成方式,例如指定說話者身分或說話風格。
**speaker**: `string` 選用。多說話者合成的選用說話者名稱。 **style**: `string` 選用。語音合成的選用風格指令。**tools**: `Tool array` 選用。`Tools` 清單,`Model` 可用來生成下一個回應。`Tool` 是一段程式碼,讓系統能與外部系統互動,以執行 `Model` 知識與範圍之外的動作或一組動作。支援的 `Tool` 有 `Function` 與 `code_execution`。詳情請參閱 [Function calling](/docs/function-calling/) 與 [Code execution](/docs/code-execution/) 指南。
**functionDeclarations**: `FunctionDeclaration array` 選用。可供模型用於函式呼叫的 `FunctionDeclarations` 清單。模型或系統不會執行函式。相反地,定義的函式可能會以 FunctionCall 的形式連同引數傳回至用戶端執行。模型可能會決定呼叫這些函式的子集,方式是在回應中填入 FunctionCall。下一個對話回合可能包含 FunctionResponse,作為下一個模型回合的 Content.role "function" 生成上下文。
**name**: required `string` 函式的名稱。必須為 a-z、A-Z、0-9,或包含底線、冒號、句點與連字號,長度上限為 128。 **description**: required `string` 函式的簡短說明。**parameters**: `Schema` 選用。描述此函式的參數。反映 Open API 3.03 Parameter Object。字串 Key:參數的名稱。參數名稱區分大小寫。Schema Value:定義參數所用類型的 Schema。
**type**: required `Type` 資料類型。
可能的值: - `TYPE_UNSPECIFIED`: 未指定,不應使用。 - `STRING`: 字串類型。 - `NUMBER`: 數字類型。 - `INTEGER`: 整數類型。 - `BOOLEAN`: 布林類型。 - `ARRAY`: 陣列類型。 - `OBJECT`: 物件類型。 - `NULL`: Null 類型。**response**: `Schema` 選用。以 JSON Schema 格式描述此函式的輸出。反映 Open API 3.03 Response Object。Schema 定義函式回應值所使用的類型。
**type**: required `Type` 資料類型。
可能的值: - `TYPE_UNSPECIFIED`: 未指定,不應使用。 - `STRING`: 字串類型。 - `NUMBER`: 數字類型。 - `INTEGER`: 整數類型。 - `BOOLEAN`: 布林類型。 - `ARRAY`: 陣列類型。 - `OBJECT`: 物件類型。 - `NULL`: Null 類型。**behavior**: `string enum` 選用。指定函式的 Behavior。目前僅 BidiGenerateContent 方法支援。
可能的值: - `UNSPECIFIED`: 此值未使用。 - `BLOCKING`: 若有設定,系統會等待收到函式回應後才繼續對話。 - `NON_BLOCKING`: 若有設定,系統不會等待收到函式回應。相反地,它會在維持使用者與模型之間對話的同時,嘗試在函式回應可用時加以處理。**googleSearchRetrieval**: `GoogleSearchRetrieval` 選用。由 Google 搜尋驅動的檢索工具。
**dynamicRetrievalConfig**: `DynamicRetrievalConfig` 指定指定來源的動態檢索設定。
**mode**: `string enum` 動態檢索中要使用的預測器模式。
可能的值: - `MODE_UNSPECIFIED`: 一律觸發檢索。 - `MODE_DYNAMIC`: 僅在系統判斷有必要時才執行檢索。**codeExecution**: `CodeExecution` 選用。讓模型能在生成過程中執行程式碼。
**googleSearch**: `GoogleSearch` 選用。GoogleSearch 工具類型。支援模型中的 Google 搜尋。由 Google 提供。
**timeRangeFilter**: `Interval` 選用。將搜尋結果篩選至特定時間範圍。若客戶設定了開始時間,就必須設定結束時間(反之亦然)。
**startTime**: `string` 選用。區間的起始(含)。若有指定,符合此區間的 Timestamp 必須等於或晚於開始。 **endTime**: `string` 選用。區間的結束(不含)。若有指定,符合此區間的 Timestamp 必須早於結束。**searchTypes**: `SearchTypes` 選用。要啟用的搜尋類型集合。若未設定,預設啟用網路搜尋。
**webSearch**: `WebSearch` 選用。啟用網路搜尋。僅傳回文字結果。
**imageSearch**: `ImageSearch` 選用。啟用圖片搜尋。傳回圖片位元組。
**computerUse**: `ComputerUse` 選用。支援模型直接與電腦互動的工具。若啟用,會自動填入電腦使用專屬的 Function Declarations。
**environment**: required `string enum` 正在操作的環境。
可能的值: - `ENVIRONMENT_UNSPECIFIED`: 預設為瀏覽器。 - `ENVIRONMENT_BROWSER`: 在網路瀏覽器中操作。 - `ENVIRONMENT_MOBILE`: 在行動環境中操作。 - `ENVIRONMENT_DESKTOP`: 在桌面環境中操作。**disabledSafetyPolicies**: `string enum array` 選用。電腦使用已停用的安全政策。
可能的值: - `SAFETY_POLICY_UNSPECIFIED`: 未指定的安全政策。 - `FINANCIAL_TRANSACTIONS`: 金融交易的安全政策。 - `SENSITIVE_DATA_MODIFICATION`: 敏感資料修改的安全政策。 - `COMMUNICATION_TOOL`: 通訊工具的安全政策(例如 Gmail、Chat、Meet)。 - `ACCOUNT_CREATION`: 帳號建立的安全政策。 - `DATA_MODIFICATION`: 資料修改的安全政策。 - `USER_CONSENT_MANAGEMENT`: 使用者同意管理的安全政策。 - `LEGAL_TERMS_AND_AGREEMENTS`: 法律條款與協議的安全政策。**urlContext**: `UrlContext` 選用。支援 URL 上下文檢索的工具。
**fileSearch**: `FileSearch` 選用。FileSearch 工具類型。用來從 Semantic Retrieval 語料庫檢索知識的工具。
**fileSearchStoreNames**: required `string array` 要從中檢索的 file_search_stores 名稱。範例:`fileSearchStores/my-file-search-store-123` **topK**: `integer` 選用。要檢索的語意檢索區塊數量。 **metadataFilter**: `string` 選用。要套用至語意檢索文件與區塊的中繼資料篩選條件。**mcpServers**: `McpServer array` 選用。要連線的 MCP 伺服器。
**transport**: `Union type` 用來連線至 MCPServer 的傳輸方式。
聯集欄位 `transport` 只能是下列其中之一:**streamableHttpTransport**: `StreamableHttpTransport` 可以串流 HTTP 請求與回應的傳輸方式。
**url**: `string` MCPServer 端點的完整 URL。範例:"https://api.example.com/mcp" **headers**: `object` 選用:如有需要,提供驗證標頭、逾時等欄位。 **timeout**: `string` 一般操作的 HTTP 逾時。 **sseReadTimeout**: `string` SSE 讀取操作的逾時。 **terminateOnClose**: `boolean` 當傳輸關閉時,是否關閉用戶端工作階段。**googleMaps**: `GoogleMaps` 選用。讓模型的回應能以與使用者查詢相關的地理空間上下文接地的工具。
**enableWidget**: `boolean` 選用。是否在回應的 GroundingMetadata 中傳回 widget 上下文權杖。開發人員可以使用 widget 上下文權杖,呈現與模型在回應中提及的地點相關的地理空間上下文 Google Maps widget。**toolConfig**: `ToolConfig` 選用。請求中指定的任何 `Tool` 的工具設定。使用範例請參閱 [Function calling guide](/docs/function-calling/#function_calling_modes)。
**functionCallingConfig**: `FunctionCallingConfig` 選用。函式呼叫設定。
**mode**: `string enum` 選用。指定函式呼叫應執行的模式。若未指定,預設值將設為 AUTO。
可能的值: - `MODE_UNSPECIFIED`: 未指定的函式呼叫模式。不應使用此值。 - `AUTO`: 預設的模型行為,由模型決定要預測函式呼叫或自然語言回應。 - `ANY`: 模型被限制為一律只預測函式呼叫。若有設定 "allowed_function_names",預測的函式呼叫將限於 "allowed_function_names" 中的任何一個,否則預測的函式呼叫將是所提供的 "function_declarations" 中的任何一個。 - `NONE`: 模型不會預測任何函式呼叫。模型行為與未傳入任何函式宣告時相同。 - `VALIDATED`: 模型決定要預測函式呼叫或自然語言回應,但會以受限解碼驗證函式呼叫。若有設定 "allowed_function_names",預測的函式呼叫將限於 "allowed_function_names" 中的任何一個,否則預測的函式呼叫將是所提供的 "function_declarations" 中的任何一個。**retrievalConfig**: `RetrievalConfig` 選用。檢索設定。
**latLng**: `LatLng` 選用。使用者的位置。
**latitude**: `number` 以度為單位的緯度。必須在 [-90.0, +90.0] 範圍內。 **longitude**: `number` 以度為單位的經度。必須在 [-180.0, +180.0] 範圍內。**safetySettings**: `SafetySetting array` 選用。用來封鎖不安全內容的唯一 `SafetySetting` 執行個體清單。這將強制套用於 `GenerateContentRequest.contents` 與 `GenerateContentResponse.candidates`。每個 `SafetyCategory` 類型不應有多於一個設定。API 會封鎖任何未達到這些設定所定閾值的內容與回應。此清單會覆寫 safety_settings 中指定的每個 `SafetyCategory` 的預設設定。若清單中未提供某個 `SafetySetting`(針對給定的 `SafetyCategory`),API 將使用該類別的預設安全設定。支援的危害類別為 HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_DANGEROUS_CONTENT、HARM_CATEGORY_HARASSMENT、HARM_CATEGORY_CIVIC_INTEGRITY、HARM_CATEGORY_JAILBREAK。可用安全設定的詳細資訊請參閱 [guide](/docs/safety-settings/)。另請參閱 [Safety guidance](/docs/safety-guidance/),了解如何將安全考量納入您的 AI 應用程式。
**category**: required `HarmCategory` 此設定的類別。
可能的值: - `HARM_CATEGORY_UNSPECIFIED`: 類別未指定。 - `HARM_CATEGORY_HARASSMENT`: **Gemini** - 騷擾內容。 - `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - 仇恨言論與內容。 - `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - 性露骨內容。 - `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - 危險內容。 - `HARM_CATEGORY_JAILBREAK`: **Gemini** - 試圖繞過或顛覆模型安全指南的提示詞(越獄嘗試)。**threshold**: required `string enum` 控制危害被封鎖的機率閾值。
可能的值: - `HARM_BLOCK_THRESHOLD_UNSPECIFIED`: 閾值未指定。 - `BLOCK_LOW_AND_ABOVE`: 將允許 NEGLIGIBLE 的內容。 - `BLOCK_MEDIUM_AND_ABOVE`: 將允許 NEGLIGIBLE 與 LOW 的內容。 - `BLOCK_ONLY_HIGH`: 將允許 NEGLIGIBLE、LOW 與 MEDIUM 的內容。 - `BLOCK_NONE`: 將允許所有內容。 - `OFF`: 關閉安全篩選器。**generationConfig**: `GenerationConfig` 選用。模型生成與輸出的設定選項。
**candidateCount**: `integer` 選用。要傳回的生成回應數量。若未設定,預設為 1。請注意,這不適用於舊一代模型(Gemini 1.0 系列) **stopSequences**: `string array` 選用。將停止輸出生成的字元序列集合(最多 5 個)。若有指定,API 會在 `stop_sequence` 首次出現時停止。停止序列不會包含在回應中。 **maxOutputTokens**: `integer` 選用。要包含在回應候選中的權杖數量上限。注意:預設值因模型而異,請參閱 `Model.output_token_limit`,這是 `Model` 的屬性,由 `getModel` 函式傳回。 **temperature**: `number` 選用。控制輸出的隨機性。注意:預設值因模型而異,請參閱 `Model.temperature`,這是 `Model` 的屬性,由 `getModel` 函式傳回。值可以介於 [0.0, 2.0]。此欄位在 Gemini 3.6 Flash 與更新的模型上已不再支援,會被靜默忽略。 **topP**: `number` 選用。取樣時要考慮的權杖累積機率上限。模型結合使用 Top-k 與 Top-p(nucleus)取樣。權杖會依其指派的機率排序,因此只考慮最有可能的權杖。Top-k 取樣直接限制要考慮的權杖數量上限,而 Nucleus 取樣則依累積機率限制權杖數量。注意:預設值因 `Model` 而異,由 `Model.top_p` 屬性指定,該屬性由 `getModel` 函式傳回。空的 `top_k` 屬性表示模型不套用 top-k 取樣,也不允許在請求上設定 `top_k`。此欄位在 Gemini 3.6 Flash 與更新的模型上已不再支援,會被靜默忽略。 **topK**: `integer` 選用。取樣時要考慮的權杖數量上限。Gemini 模型使用 Top-p(nucleus)取樣,或 Top-k 與 nucleus 取樣的組合。Top-k 取樣考慮 `top_k` 個最有可能的權杖集合。使用 nucleus 取樣的模型不允許設定 top_k。注意:預設值因 `Model` 而異,由 `Model.top_p` 屬性指定,該屬性由 `getModel` 函式傳回。空的 `top_k` 屬性表示模型不套用 top-k 取樣,也不允許在請求上設定 `top_k`。此欄位在 Gemini 3.6 Flash 與更新的模型上已不再支援,會被靜默忽略。 **seed**: `integer` 選用。解碼時使用的種子。若未設定,請求會使用隨機生成的種子。 **responseMimeType**: `string` 選用。生成的候選文字的 MIME 類型。支援的 MIME 類型為:`text/plain`:(預設)文字輸出。`application/json`:回應候選中的 JSON 回應。`text/x.enum`:回應候選中以字串形式表示的 ENUM 回應。所有支援的文字 MIME 類型清單請參閱 [docs](/docs/file-input-methods/#text-file-types)。 **responseJsonSchema**: `object` 選用。內部詳細資訊。請使用 `responseJsonSchema`,不要使用此欄位。 **presencePenalty**: `number` 選用。若權杖已出現在回應中,套用至下一個權杖 logprobs 的存在懲罰。此懲罰為二元的開/關,不取決於權杖被使用的次數(第一次之後)。若要懲罰隨每次使用而增加,請使用 frequency_penalty。正的懲罰會抑制使用已在回應中使用過的權杖,增加詞彙多樣性。負的懲罰會鼓勵使用已在回應中使用過的權杖,降低詞彙多樣性。 **frequencyPenalty**: `number` 選用。套用至下一個權杖 logprobs 的頻率懲罰,乘以每個權杖到目前為止在回應中出現的次數。正的懲罰會依權杖被使用的次數成比例地抑制已使用過的權杖:權杖使用得越多,模型就越難再次使用該權杖,從而增加回應的詞彙多樣性。注意:*負*的懲罰會依權杖被使用的次數成比例地鼓勵模型重複使用權杖。小的負值會降低回應的詞彙多樣性。較大的負值會使模型開始重複一個常見權杖,直到達到 max_output_tokens 上限。 **responseLogprobs**: `boolean` 選用。若為 true,在回應中匯出 logprobs 結果。 **logprobs**: `integer` 選用。僅在 response_logprobs=True 時有效。這會設定在每個解碼步驟要傳回的頂尖 logprobs 數量(包含所選候選),位於 Candidate.logprobs_result 中。數字必須在 [0, 20] 範圍內。 **enableEnhancedCivicAnswers**: `boolean` 選用。啟用強化公民答案。可能並非所有模型都可用。**responseModalities**: `string enum array` 選用。請求的回應模態。表示模型可以傳回、且應在回應中預期出現的模態集合。這與回應的模態完全相符。模型可能有多種支援模態的組合。若請求的模態與任何支援的組合都不相符,將傳回錯誤。空清單等同於僅請求文字。
可能的值: - `MODALITY_UNSPECIFIED`: 預設值。 - `TEXT`: 表示模型應傳回文字。 - `IMAGE`: 表示模型應傳回圖片。 - `AUDIO`: 表示模型應傳回音訊。**speechConfig**: `SpeechConfig` 選用。語音生成設定。
**voiceConfig**: `VoiceConfig` 單一語音輸出的設定。
**voiceConfig**: `Union type` 要使用的說話者設定。
聯集欄位 `voiceConfig` 只能是下列其中之一:**prebuiltVoiceConfig**: `PrebuiltVoiceConfig` 要使用的預建語音設定。
**voiceName**: `string` 選用。要使用的預設語音名稱。**multiSpeakerVoiceConfig**: `MultiSpeakerVoiceConfig` 選用。多說話者設定的設定。它與 voice_config 欄位互斥。
**speakerVoiceConfigs**: required `SpeakerVoiceConfig array` 所有已啟用的說話者語音。
**speaker**: required `string` 要使用的說話者名稱。應與提示詞中的名稱相同。**voiceConfig**: required `VoiceConfig` 要使用的語音設定。
**voiceConfig**: `Union type` 要使用的說話者設定。
聯集欄位 `voiceConfig` 只能是下列其中之一:**prebuiltVoiceConfig**: `PrebuiltVoiceConfig` 要使用的預建語音設定。
**voiceName**: `string` 選用。要使用的預設語音名稱。**thinkingConfig**: `ThinkingConfig` 選用。思考功能的設定。若為不支援思考的模型設定此欄位,將傳回錯誤。
**includeThoughts**: `boolean` 表示是否在回應中包含思考內容。若為 true,僅在思考內容可用時才傳回。 **thinkingBudget**: `integer` 模型應生成的思考權杖數量。**thinkingLevel**: `string enum` 選用。控制模型在產生回應之前,內部推理過程的最大深度。預設值取決於模型。詳情請參閱 [Thinking levels guide](/docs/thinking/#thinking-levels)。建議用於 Gemini 3 或更新的模型。在較早的模型上使用會導致錯誤。
可能的值: - `THINKING_LEVEL_UNSPECIFIED`: 預設值。 - `MINIMAL`: 幾乎不思考。 - `LOW`: 低思考等級。 - `MEDIUM`: 中思考等級。 - `HIGH`: 高思考等級。 - `XHIGH`: 超高思考等級。**imageConfig**: `ImageConfig` 選用。圖片生成的設定。若為不支援這些設定選項的模型設定此欄位,將傳回錯誤。
**aspectRatio**: `string` 選用。要生成的圖片長寬比。支援的長寬比:`1:1`、`1:4`、`4:1`、`1:8`、`8:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9` 或 `21:9`。若未指定,模型會根據提供的任何參照圖片選擇預設長寬比。 **imageSize**: `string` 選用。指定生成的圖片大小。支援的值為 `512`、`1K`、`2K`、`4K`。若未指定,模型會使用預設值 `1K`。**mediaResolution**: `string enum` 選用。若有指定,將使用指定的媒體解析度。
可能的值: - `MEDIA_RESOLUTION_UNSPECIFIED`: 尚未設定媒體解析度。 - `MEDIA_RESOLUTION_LOW`: 媒體解析度設為低(64 個權杖)。 - `MEDIA_RESOLUTION_MEDIUM`: 媒體解析度設為中(256 個權杖)。 - `MEDIA_RESOLUTION_HIGH`: 媒體解析度設為高(以 256 個權杖縮放重新取景)。**responseFormat**: `ResponseFormatConfig` 選用。回應輸出格式的設定。允許以扁平結構為每個模態(文字、音訊、圖片)指定輸出設定。
**text**: `TextResponseFormat` 選用。文字輸出格式設定。
**mimeType**: `string enum` 選用。文字輸出的 MIME 類型。
可能的值: - `MIME_TYPE_UNSPECIFIED`: 預設值。此值未使用。 - `APPLICATION_JSON`: JSON 輸出格式。 - `TEXT_PLAIN`: 純文字輸出格式。**audio**: `AudioResponseFormat` 選用。音訊輸出格式設定。
**mimeType**: `string enum` 選用。音訊輸出的 MIME 類型。
可能的值: - `MIME_TYPE_UNSPECIFIED`: 預設值。此值未使用。 - `AUDIO_MP3`: MP3 音訊格式。 - `AUDIO_OGG_OPUS`: OGG Opus 音訊格式。 - `AUDIO_L16`: 原始 PCM(L16)音訊格式。 - `AUDIO_WAV`: WAV 音訊格式。 - `AUDIO_ALAW`: A-law 音訊格式。 - `AUDIO_MULAW`: Mu-law 音訊格式。**delivery**: `string enum` 選用。音訊輸出的傳遞模式。
可能的值: - `DELIVERY_UNSPECIFIED`: 預設值。此值未使用。 - `INLINE`: 音訊資料在回應中內嵌傳回。 - `URI`: 音訊資料以 URI 形式傳回。**image**: `ImageResponseFormat` 選用。圖片輸出格式設定。
**mimeType**: `string enum` 選用。圖片輸出的 MIME 類型。
可能的值: - `MIME_TYPE_UNSPECIFIED`: 預設值。此值未使用。 - `IMAGE_JPEG`: JPEG 圖片格式。**delivery**: `string enum` 選用。圖片輸出的傳遞模式。
可能的值: - `DELIVERY_UNSPECIFIED`: 預設值。此值未使用。 - `INLINE`: 圖片資料在回應中內嵌傳回。 - `URI`: 圖片資料以 URI 形式傳回。**aspectRatio**: `string enum` 選用。圖片輸出的長寬比。
可能的值: - `ASPECT_RATIO_UNSPECIFIED`: 預設值。此值未使用。 - `ASPECT_RATIO_ONE_BY_ONE`: 1:1 長寬比。 - `ASPECT_RATIO_TWO_BY_THREE`: 2:3 長寬比。 - `ASPECT_RATIO_THREE_BY_TWO`: 3:2 長寬比。 - `ASPECT_RATIO_THREE_BY_FOUR`: 3:4 長寬比。 - `ASPECT_RATIO_FOUR_BY_THREE`: 4:3 長寬比。 - `ASPECT_RATIO_FOUR_BY_FIVE`: 4:5 長寬比。 - `ASPECT_RATIO_FIVE_BY_FOUR`: 5:4 長寬比。 - `ASPECT_RATIO_NINE_BY_SIXTEEN`: 9:16 長寬比。 - `ASPECT_RATIO_SIXTEEN_BY_NINE`: 16:9 長寬比。 - `ASPECT_RATIO_TWENTY_ONE_BY_NINE`: 21:9 長寬比。 - `ASPECT_RATIO_ONE_BY_EIGHT`: 1:8 長寬比。 - `ASPECT_RATIO_EIGHT_BY_ONE`: 8:1 長寬比。 - `ASPECT_RATIO_ONE_BY_FOUR`: 1:4 長寬比。 - `ASPECT_RATIO_FOUR_BY_ONE`: 4:1 長寬比。**imageSize**: `string enum` 選用。圖片輸出的大小。
可能的值: - `IMAGE_SIZE_UNSPECIFIED`: 預設值。此值未使用。 - `IMAGE_SIZE_FIVE_TWELVE`: 512px 圖片大小。 - `IMAGE_SIZE_ONE_K`: 1K 圖片大小。 - `IMAGE_SIZE_TWO_K`: 2K 圖片大小。 - `IMAGE_SIZE_FOUR_K`: 4K 圖片大小。**translationConfig**: `TranslationConfig` 選用。翻譯設定。
**targetLanguageCode**: required `string` 翻譯的目標語言。支援的值為 BCP-47 語言代碼(例如 "en"、"es"、"fr")。 **echoTargetLanguage**: `boolean` 選用。若為 true,當目標語言被說出時,模型會生成音訊,實質上會鸚鵡學舌般重複輸入。若為 false,我們不會為目標語言產生音訊。**audioTranscriptionConfig**: `AudioTranscriptionConfig` 選用。音訊轉錄設定(語音辨識)。
**languageCodes**: `string array` 選用。BCP-47 語言代碼,提供音訊中出現語言的提示。若省略或為空,預設為自動語言偵測。 **customVocabulary**: `string array` 選用。自訂詞彙短語清單,用來使語音辨識模型偏向辨識特定詞彙(產品名稱、專有名詞、術語)。 **wordTimestamp**: `boolean` 選用。設定單字層級時間戳記的生成。 **diarization**: `boolean` 選用。設定說話者分離(diarization)。 **sourceText**: `string` 選用。要透過語音指令編輯或改寫的來源文字。在 `SMART` 模式下提供時,模型會對照此文字評估音訊輸入,並在候選回應中發出完整的替代文字,而不是附加在其後。**mode**: `string enum` 選用。設定轉錄模式。支援的值:`VERBATIM`、`SMART`。若未指定,預設為 `VERBATIM` 轉錄。在 `SMART` 模式下,模型會執行去除不流暢(消除填充詞、重複與假開頭)、輕度文法清理、自動格式化(段落、項目符號、編號清單),以及輕微的使用者編輯(行內自我修正)。時間戳記與 diarization 與 `SMART` 模式不相容。
可能的值: - `MODE_UNSPECIFIED`: 未指定的轉錄模式。 - `VERBATIM`: 逐字轉錄模式。 - `SMART`: 智慧轉錄模式。**serviceTier**: [`ServiceTier`](/api-reference/batch-api/update-generate-content-batch/#Resource:ServiceTier) 選用。請求的服務層級。
可能的值: - `unspecified`: 預設服務層級,即標準。 - `standard`: 標準服務層級。 - `flex`: Flex 服務層級。 - `priority`: Priority 服務層級。priority: string
選用。批次的優先順序。優先順序值較高的批次會在優先順序值較低的批次之前處理。允許負值。預設為 0。
範例請求
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/batches/$BATCH_ID:updateGenerateContentBatch" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "string",
"displayName": "string",
"inputConfig": {
"fileName": "string"
}
}'
回應¶
model: required string
用於生成補全內容的 Model 名稱。格式:models/{model}。
displayName: required string
使用者為此批次定義的名稱。
**inputConfig**: required `InputConfig` 對其執行批次處理的執行個體的輸入設定。
**source**: required `Union type` 輸入的來源。
聯集欄位 `source` 只能是下列其中之一: **fileName**: `string` 包含輸入請求的 `File` 名稱。**requests**: `InlinedRequests` 要在批次中處理的請求。
**requests**: required `InlinedRequest array` 要在批次中處理的請求。
**request**: required `GenerateContentRequest` 要在批次中處理的請求。
**model**: required `string` 用於生成補全內容的 `Model` 名稱。格式:`models/{model}`。**contents**: required `Content array` 與模型目前對話的內容。對於單輪查詢,這是單一執行個體。對於多輪查詢(例如 [chat](/docs/text-generation/#multi-turn-conversations)),這是重複欄位,包含對話記錄與最新請求。
**parts**: `Part array` 組成單一訊息的有序 `Parts`。各 Part 的 MIME 類型可能不同。
**data**: `Union type`
聯集欄位 `data` 只能是下列其中之一: **text**: `string` 內嵌文字。**inlineData**: `Blob` 內嵌媒體位元組。
**mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。支援的類型範例: - 圖片:image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif - 音訊:audio/*, video/audio/s16le, video/audio/wav - 影片:video/* - 文字:text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp - 應用程式:application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf 其他背景資訊請參閱 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **data**: `string` 媒體格式的原始位元組。 **displayName**: `string` 選用。指定用來向模型指稱此 blob 的名稱(例如 "my_blob.png")。當 `verbalization_mode` 設為 `REFERENCE_ONLY` 時,作為 blob 的參照識別碼。**functionCall**: `FunctionCall` 模型傳回的預測 `FunctionCall`,其中包含代表 `FunctionDeclaration.name` 的字串,以及其引數與值。
**name**: required `string` 要呼叫的函式名稱。必須為 a-z、A-Z、0-9,或包含底線與連字號,長度上限為 128。 **id**: `string` 選用。函式呼叫的唯一識別碼。若有填入,用戶端應執行 `function_call`,並傳回具有相符 `id` 的回應。 **args**: `object` 選用。以 JSON 物件格式表示的函式參數與值。**functionResponse**: `FunctionResponse` `FunctionCall` 的結果輸出,其中包含代表 `FunctionDeclaration.name` 的字串,以及包含函式任何輸出的結構化 JSON 物件,作為提供給模型的上下文。
**name**: required `string` 要呼叫的函式名稱。必須為 a-z、A-Z、0-9,或包含底線與連字號,長度上限為 128。 **response**: required `object` 以 JSON 物件格式表示的函式回應。呼叫端可以使用任何符合函式語法的自選鍵來傳回函式輸出,例如 "output"、"result" 等。特別是當函式呼叫執行失敗時,回應可以包含 "error" 鍵,將錯誤詳細資訊傳回給模型。多媒體內容可以透過子物件納入,該子物件包含單一 "$ref" 鍵,其值為 `inline_data.display_name` 或 `file_data.display_name`,屬於持有該多媒體內容的 `FunctionResponsePart`。請參閱 [Multimodal function responses](/docs/function-calling/#multimodal)。 **id**: `string` 選用。此回應所對應的函式呼叫識別碼。由用戶端填入,以對應相對應的函式呼叫 `id`。**parts**: `FunctionResponsePart array` 選用。組成函式回應的有序 `Parts`。各 Part 的 IANA MIME 類型可能不同。
**data**: `Union type` 函式回應部分的資料。
聯集欄位 `data` 只能是下列其中之一:**inlineData**: `FunctionResponseBlob` 內嵌媒體位元組。
**mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。範例: - image/png - image/jpeg 若提供不支援的 MIME 類型,將傳回錯誤。支援類型的完整清單請參閱 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **data**: `string` 媒體格式的原始位元組。 **displayName**: `string` 選用。blob 的顯示名稱。用來提供標籤或檔名以區分各個 blob,並可從 `FunctionResponse.response` 參照該 blob(例如透過 `{"$ref": "DISPLAY_NAME"}`)。**fileData**: `FunctionResponseFileData` 以 URI 為基礎的資料。
**fileUri**: required `string` URI。 **mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。若提供不支援的 MIME 類型,將傳回錯誤。支援類型的完整清單請參閱 [Multimodal function responses](/docs/function-calling/#multimodal) 與 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **displayName**: `string` 選用。檔案的顯示名稱。用來提供標籤或檔名以區分檔案資料,並可從 `FunctionResponse.response` 參照該檔案(例如透過 `{"$ref": "DISPLAY_NAME"}`)。**mediaProcessing**: `string enum` 選用。模型如何處理此部分的媒體以進行理解。僅對影片部分(`inline_data` 或具有影片 MIME 類型的 `file_data`)有意義。非影片部分會忽略此欄位。
可能的值: - `MEDIA_PROCESSING_UNSPECIFIED`: 預設為模型專屬的處理方式。 - `STATIC`: 固定速率的影格擷取。所有影格都放入上下文中。 - `AGENTIC`: 由模型驅動的動態導覽。建議用於大多數使用情境。**scheduling**: `string enum` 選用。指定回應在對話中的排程方式。僅適用於 NON_BLOCKING 函式呼叫,其他情況會被忽略。預設為 WHEN_IDLE。
可能的值: - `SCHEDULING_UNSPECIFIED`: 此值未使用。 - `SILENT`: 僅將結果加入對話上下文,不中斷也不觸發生成。 - `WHEN_IDLE`: 將結果加入對話上下文,並在不中斷進行中生成的情況下提示生成輸出。 - `INTERRUPT`: 將結果加入對話上下文,中斷進行中的生成,並提示生成輸出。**fileData**: `FileData` 以 URI 為基礎的資料。
**fileUri**: required `string` URI。 **mimeType**: `string` 選用。來源資料的 IANA 標準 MIME 類型。 **displayName**: `string` 選用。指定用來向模型指稱此檔案的名稱(例如 "my_file.pdf")。當 `verbalization_mode` 設為 `REFERENCE_ONLY` 時,作為檔案的參照識別碼。**executableCode**: `ExecutableCode` 由模型生成、預定要執行的程式碼。
**language**: required `string enum` `code` 的程式語言。
可能的值: - `LANGUAGE_UNSPECIFIED`: 未指定的語言。不應使用此值。 - `PYTHON`: Python >= 3.10,可使用 numpy 與 simpy。Python 為預設語言。**codeExecutionResult**: `CodeExecutionResult` 執行 `ExecutableCode` 的結果。
**outcome**: required `string enum` 程式碼執行的結果。
可能的值: - `OUTCOME_UNSPECIFIED`: 未指定的狀態。不應使用此值。 - `OUTCOME_OK`: 程式碼執行成功完成。`output` 包含標準輸出(若有)。 - `OUTCOME_FAILED`: 程式碼執行失敗。`output` 包含標準錯誤與標準輸出(若有)。 - `OUTCOME_DEADLINE_EXCEEDED`: 程式碼執行時間過長,已被取消。可能有、也可能沒有部分的 `output`。**toolCall**: `ToolCall` 伺服器端工具呼叫。當模型預測某個工具叫用應在伺服器上執行時,會填入此欄位。用戶端應將此訊息原樣回傳給 API。
**toolType**: required `V1mainToolType` 被呼叫的工具類型。
可能的值: - `TOOL_TYPE_UNSPECIFIED`: 未指定的工具類型。 - `GOOGLE_SEARCH_WEB`: Google 搜尋工具,對應至 Tool.google_search.search_types.web_search。 - `GOOGLE_SEARCH_IMAGE`: 圖片搜尋工具,對應至 Tool.google_search.search_types.image_search。 - `URL_CONTEXT`: URL 上下文工具,對應至 Tool.url_context。 - `GOOGLE_MAPS`: Google 地圖工具,對應至 Tool.google_maps。 - `FILE_SEARCH`: File Search 工具,對應至 Tool.file_search。 - `MEDIA_PROCESSING`: 媒體處理工具類型(例如影片、音訊等),對應至用於多模態理解的隱形工具,例如 GOOGLE_UNDERSTANDING_VIDEO。**toolResponse**: `ToolResponse` 伺服器端 `ToolCall` 執行的輸出。此欄位由用戶端填入,內容為執行對應 `ToolCall` 的結果。
**toolType**: required `V1mainToolType` 被呼叫的工具類型,其 `tool_type` 與對應的 `ToolCall` 相符。
可能的值: - `TOOL_TYPE_UNSPECIFIED`: 未指定的工具類型。 - `GOOGLE_SEARCH_WEB`: Google 搜尋工具,對應至 Tool.google_search.search_types.web_search。 - `GOOGLE_SEARCH_IMAGE`: 圖片搜尋工具,對應至 Tool.google_search.search_types.image_search。 - `URL_CONTEXT`: URL 上下文工具,對應至 Tool.url_context。 - `GOOGLE_MAPS`: Google 地圖工具,對應至 Tool.google_maps。 - `FILE_SEARCH`: File Search 工具,對應至 Tool.file_search。 - `MEDIA_PROCESSING`: 媒體處理工具類型(例如影片、音訊等),對應至用於多模態理解的隱形工具,例如 GOOGLE_UNDERSTANDING_VIDEO。**metadata**: `Union type` 控制資料的額外前置處理。當 `inline_data` 或 `file_data` 存在時設定此欄位,以設定每個部分的靜態媒體前置處理。
聯集欄位 `metadata` 只能是下列其中之一:**videoMetadata**: `VideoMetadata` 選用。影片中繼資料。僅當影片資料以 inline_data 或 file_data 呈現時,才應指定中繼資料。
**startOffset**: `string` 選用。影片的開始偏移。 **endOffset**: `string` 選用。影片的結束偏移。 **fps**: `number` 選用。傳送給模型的影片影格率。若未指定,預設值為 1.0。fps 範圍為 (0.0, 24.0]。**mediaResolution**: `V1mainMediaResolution` 選用。輸入媒體的媒體解析度。
**value**: `Union type` 媒體解析度等級。
聯集欄位 `value` 只能是下列其中之一:**level**: `string enum` 指定媒體所使用的權杖化品質。
可能的值: - `MEDIA_RESOLUTION_UNSPECIFIED`: 尚未設定媒體解析度。 - `MEDIA_RESOLUTION_LOW`: 媒體解析度設為低。 - `MEDIA_RESOLUTION_MEDIUM`: 媒體解析度設為中。 - `MEDIA_RESOLUTION_HIGH`: 媒體解析度設為高。 - `MEDIA_RESOLUTION_ULTRA_HIGH`: 媒體解析度設為超高。**mediaProcessing**: `string enum` 選用。模型如何處理此部分的媒體以進行理解。僅對影片部分(`inline_data` 或具有影片 MIME 類型的 `file_data`)有意義。非影片部分會忽略此欄位。
可能的值: - `MEDIA_PROCESSING_UNSPECIFIED`: 預設為模型專屬的處理方式。 - `STATIC`: 固定速率的影格擷取。所有影格都放入上下文中。 - `AGENTIC`: 由模型驅動的動態導覽。建議用於大多數使用情境。**audioTranscription**: `AudioTranscription` 選用。音訊(輸入或輸出)轉錄。僅當此 Part 包含音訊資料時才會設定。
**text**: required `string` 此音訊片段的轉錄文字。 **speakerLabel**: `string` 選用。標示此音訊片段說話者的標籤(例如 "spk_1"、"spk_2")。在設定 diarization 時出現。**words**: `WordInfo array` 選用。詳細的單字層級轉錄與時間資訊。在設定 word_timestamp 時出現。
**word**: required `string` 單字的轉錄。 **startOffset**: `string` 選用。單字相對於音訊開頭的開始時間偏移。 **endOffset**: `string` 選用。單字相對於音訊開頭的結束時間偏移。**speechMetadata**: `SpeechMetadata` 選用。套用至文字部分的中繼資料,用來客製化其朗讀或合成方式,例如指定說話者身分或說話風格。
**speaker**: `string` 選用。多說話者合成的選用說話者名稱。 **style**: `string` 選用。語音合成的選用風格指令。**systemInstruction**: `Content` 選用。開發人員設定的 [system instruction(s)](/docs/text-generation/#system-instructions)。目前僅支援文字。
**parts**: `Part array` 組成單一訊息的有序 `Parts`。各 Part 的 MIME 類型可能不同。
**data**: `Union type`
聯集欄位 `data` 只能是下列其中之一: **text**: `string` 內嵌文字。**inlineData**: `Blob` 內嵌媒體位元組。
**mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。支援的類型範例: - 圖片:image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif - 音訊:audio/*, video/audio/s16le, video/audio/wav - 影片:video/* - 文字:text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp - 應用程式:application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf 其他背景資訊請參閱 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **data**: `string` 媒體格式的原始位元組。 **displayName**: `string` 選用。指定用來向模型指稱此 blob 的名稱(例如 "my_blob.png")。當 `verbalization_mode` 設為 `REFERENCE_ONLY` 時,作為 blob 的參照識別碼。**functionCall**: `FunctionCall` 模型傳回的預測 `FunctionCall`,其中包含代表 `FunctionDeclaration.name` 的字串,以及其引數與值。
**name**: required `string` 要呼叫的函式名稱。必須為 a-z、A-Z、0-9,或包含底線與連字號,長度上限為 128。 **id**: `string` 選用。函式呼叫的唯一識別碼。若有填入,用戶端應執行 `function_call`,並傳回具有相符 `id` 的回應。 **args**: `object` 選用。以 JSON 物件格式表示的函式參數與值。**functionResponse**: `FunctionResponse` `FunctionCall` 的結果輸出,其中包含代表 `FunctionDeclaration.name` 的字串,以及包含函式任何輸出的結構化 JSON 物件,作為提供給模型的上下文。
**name**: required `string` 要呼叫的函式名稱。必須為 a-z、A-Z、0-9,或包含底線與連字號,長度上限為 128。 **response**: required `object` 以 JSON 物件格式表示的函式回應。呼叫端可以使用任何符合函式語法的自選鍵來傳回函式輸出,例如 "output"、"result" 等。特別是當函式呼叫執行失敗時,回應可以包含 "error" 鍵,將錯誤詳細資訊傳回給模型。多媒體內容可以透過子物件納入,該子物件包含單一 "$ref" 鍵,其值為 `inline_data.display_name` 或 `file_data.display_name`,屬於持有該多媒體內容的 `FunctionResponsePart`。請參閱 [Multimodal function responses](/docs/function-calling/#multimodal)。 **id**: `string` 選用。此回應所對應的函式呼叫識別碼。由用戶端填入,以對應相對應的函式呼叫 `id`。**parts**: `FunctionResponsePart array` 選用。組成函式回應的有序 `Parts`。各 Part 的 IANA MIME 類型可能不同。
**data**: `Union type` 函式回應部分的資料。
聯集欄位 `data` 只能是下列其中之一:**inlineData**: `FunctionResponseBlob` 內嵌媒體位元組。
**mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。範例: - image/png - image/jpeg 若提供不支援的 MIME 類型,將傳回錯誤。支援類型的完整清單請參閱 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **data**: `string` 媒體格式的原始位元組。 **displayName**: `string` 選用。blob 的顯示名稱。用來提供標籤或檔名以區分各個 blob,並可從 `FunctionResponse.response` 參照該 blob(例如透過 `{"$ref": "DISPLAY_NAME"}`)。**fileData**: `FunctionResponseFileData` 以 URI 為基礎的資料。
**fileUri**: required `string` URI。 **mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。若提供不支援的 MIME 類型,將傳回錯誤。支援類型的完整清單請參閱 [Multimodal function responses](/docs/function-calling/#multimodal) 與 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **displayName**: `string` 選用。檔案的顯示名稱。用來提供標籤或檔名以區分檔案資料,並可從 `FunctionResponse.response` 參照該檔案(例如透過 `{"$ref": "DISPLAY_NAME"}`)。**mediaProcessing**: `string enum` 選用。模型如何處理此部分的媒體以進行理解。僅對影片部分(`inline_data` 或具有影片 MIME 類型的 `file_data`)有意義。非影片部分會忽略此欄位。
可能的值: - `MEDIA_PROCESSING_UNSPECIFIED`: 預設為模型專屬的處理方式。 - `STATIC`: 固定速率的影格擷取。所有影格都放入上下文中。 - `AGENTIC`: 由模型驅動的動態導覽。建議用於大多數使用情境。**scheduling**: `string enum` 選用。指定回應在對話中的排程方式。僅適用於 NON_BLOCKING 函式呼叫,其他情況會被忽略。預設為 WHEN_IDLE。
可能的值: - `SCHEDULING_UNSPECIFIED`: 此值未使用。 - `SILENT`: 僅將結果加入對話上下文,不中斷也不觸發生成。 - `WHEN_IDLE`: 將結果加入對話上下文,並在不中斷進行中生成的情況下提示生成輸出。 - `INTERRUPT`: 將結果加入對話上下文,中斷進行中的生成,並提示生成輸出。**fileData**: `FileData` 以 URI 為基礎的資料。
**fileUri**: required `string` URI。 **mimeType**: `string` 選用。來源資料的 IANA 標準 MIME 類型。 **displayName**: `string` 選用。指定用來向模型指稱此檔案的名稱(例如 "my_file.pdf")。當 `verbalization_mode` 設為 `REFERENCE_ONLY` 時,作為檔案的參照識別碼。**executableCode**: `ExecutableCode` 由模型生成、預定要執行的程式碼。
**language**: required `string enum` `code` 的程式語言。
可能的值: - `LANGUAGE_UNSPECIFIED`: 未指定的語言。不應使用此值。 - `PYTHON`: Python >= 3.10,可使用 numpy 與 simpy。Python 為預設語言。**codeExecutionResult**: `CodeExecutionResult` 執行 `ExecutableCode` 的結果。
**outcome**: required `string enum` 程式碼執行的結果。
可能的值: - `OUTCOME_UNSPECIFIED`: 未指定的狀態。不應使用此值。 - `OUTCOME_OK`: 程式碼執行成功完成。`output` 包含標準輸出(若有)。 - `OUTCOME_FAILED`: 程式碼執行失敗。`output` 包含標準錯誤與標準輸出(若有)。 - `OUTCOME_DEADLINE_EXCEEDED`: 程式碼執行時間過長,已被取消。可能有、也可能沒有部分的 `output`。**toolCall**: `ToolCall` 伺服器端工具呼叫。當模型預測某個工具叫用應在伺服器上執行時,會填入此欄位。用戶端應將此訊息原樣回傳給 API。
**toolType**: required `V1mainToolType` 被呼叫的工具類型。
可能的值: - `TOOL_TYPE_UNSPECIFIED`: 未指定的工具類型。 - `GOOGLE_SEARCH_WEB`: Google 搜尋工具,對應至 Tool.google_search.search_types.web_search。 - `GOOGLE_SEARCH_IMAGE`: 圖片搜尋工具,對應至 Tool.google_search.search_types.image_search。 - `URL_CONTEXT`: URL 上下文工具,對應至 Tool.url_context。 - `GOOGLE_MAPS`: Google 地圖工具,對應至 Tool.google_maps。 - `FILE_SEARCH`: File Search 工具,對應至 Tool.file_search。 - `MEDIA_PROCESSING`: 媒體處理工具類型(例如影片、音訊等),對應至用於多模態理解的隱形工具,例如 GOOGLE_UNDERSTANDING_VIDEO。**toolResponse**: `ToolResponse` 伺服器端 `ToolCall` 執行的輸出。此欄位由用戶端填入,內容為執行對應 `ToolCall` 的結果。
**toolType**: required `V1mainToolType` 被呼叫的工具類型,其 `tool_type` 與對應的 `ToolCall` 相符。
可能的值: - `TOOL_TYPE_UNSPECIFIED`: 未指定的工具類型。 - `GOOGLE_SEARCH_WEB`: Google 搜尋工具,對應至 Tool.google_search.search_types.web_search。 - `GOOGLE_SEARCH_IMAGE`: 圖片搜尋工具,對應至 Tool.google_search.search_types.image_search。 - `URL_CONTEXT`: URL 上下文工具,對應至 Tool.url_context。 - `GOOGLE_MAPS`: Google 地圖工具,對應至 Tool.google_maps。 - `FILE_SEARCH`: File Search 工具,對應至 Tool.file_search。 - `MEDIA_PROCESSING`: 媒體處理工具類型(例如影片、音訊等),對應至用於多模態理解的隱形工具,例如 GOOGLE_UNDERSTANDING_VIDEO。**metadata**: `Union type` 控制資料的額外前置處理。當 `inline_data` 或 `file_data` 存在時設定此欄位,以設定每個部分的靜態媒體前置處理。
聯集欄位 `metadata` 只能是下列其中之一:**videoMetadata**: `VideoMetadata` 選用。影片中繼資料。僅當影片資料以 inline_data 或 file_data 呈現時,才應指定中繼資料。
**startOffset**: `string` 選用。影片的開始偏移。 **endOffset**: `string` 選用。影片的結束偏移。 **fps**: `number` 選用。傳送給模型的影片影格率。若未指定,預設值為 1.0。fps 範圍為 (0.0, 24.0]。**mediaResolution**: `V1mainMediaResolution` 選用。輸入媒體的媒體解析度。
**value**: `Union type` 媒體解析度等級。
聯集欄位 `value` 只能是下列其中之一:**level**: `string enum` 指定媒體所使用的權杖化品質。
可能的值: - `MEDIA_RESOLUTION_UNSPECIFIED`: 尚未設定媒體解析度。 - `MEDIA_RESOLUTION_LOW`: 媒體解析度設為低。 - `MEDIA_RESOLUTION_MEDIUM`: 媒體解析度設為中。 - `MEDIA_RESOLUTION_HIGH`: 媒體解析度設為高。 - `MEDIA_RESOLUTION_ULTRA_HIGH`: 媒體解析度設為超高。**mediaProcessing**: `string enum` 選用。模型如何處理此部分的媒體以進行理解。僅對影片部分(`inline_data` 或具有影片 MIME 類型的 `file_data`)有意義。非影片部分會忽略此欄位。
可能的值: - `MEDIA_PROCESSING_UNSPECIFIED`: 預設為模型專屬的處理方式。 - `STATIC`: 固定速率的影格擷取。所有影格都放入上下文中。 - `AGENTIC`: 由模型驅動的動態導覽。建議用於大多數使用情境。**audioTranscription**: `AudioTranscription` 選用。音訊(輸入或輸出)轉錄。僅當此 Part 包含音訊資料時才會設定。
**text**: required `string` 此音訊片段的轉錄文字。 **speakerLabel**: `string` 選用。標示此音訊片段說話者的標籤(例如 "spk_1"、"spk_2")。在設定 diarization 時出現。**words**: `WordInfo array` 選用。詳細的單字層級轉錄與時間資訊。在設定 word_timestamp 時出現。
**word**: required `string` 單字的轉錄。 **startOffset**: `string` 選用。單字相對於音訊開頭的開始時間偏移。 **endOffset**: `string` 選用。單字相對於音訊開頭的結束時間偏移。**speechMetadata**: `SpeechMetadata` 選用。套用至文字部分的中繼資料,用來客製化其朗讀或合成方式,例如指定說話者身分或說話風格。
**speaker**: `string` 選用。多說話者合成的選用說話者名稱。 **style**: `string` 選用。語音合成的選用風格指令。**tools**: `Tool array` 選用。`Tools` 清單,`Model` 可用來生成下一個回應。`Tool` 是一段程式碼,讓系統能與外部系統互動,以執行 `Model` 知識與範圍之外的動作或一組動作。支援的 `Tool` 有 `Function` 與 `code_execution`。詳情請參閱 [Function calling](/docs/function-calling/) 與 [Code execution](/docs/code-execution/) 指南。
**functionDeclarations**: `FunctionDeclaration array` 選用。可供模型用於函式呼叫的 `FunctionDeclarations` 清單。模型或系統不會執行函式。相反地,定義的函式可能會以 FunctionCall 的形式連同引數傳回至用戶端執行。模型可能會決定呼叫這些函式的子集,方式是在回應中填入 FunctionCall。下一個對話回合可能包含 FunctionResponse,作為下一個模型回合的 Content.role "function" 生成上下文。
**name**: required `string` 函式的名稱。必須為 a-z、A-Z、0-9,或包含底線、冒號、句點與連字號,長度上限為 128。 **description**: required `string` 函式的簡短說明。**parameters**: `Schema` 選用。描述此函式的參數。反映 Open API 3.03 Parameter Object。字串 Key:參數的名稱。參數名稱區分大小寫。Schema Value:定義參數所用類型的 Schema。
**type**: required `Type` 資料類型。
可能的值: - `TYPE_UNSPECIFIED`: 未指定,不應使用。 - `STRING`: 字串類型。 - `NUMBER`: 數字類型。 - `INTEGER`: 整數類型。 - `BOOLEAN`: 布林類型。 - `ARRAY`: 陣列類型。 - `OBJECT`: 物件類型。 - `NULL`: Null 類型。**response**: `Schema` 選用。以 JSON Schema 格式描述此函式的輸出。反映 Open API 3.03 Response Object。Schema 定義函式回應值所使用的類型。
**type**: required `Type` 資料類型。
可能的值: - `TYPE_UNSPECIFIED`: 未指定,不應使用。 - `STRING`: 字串類型。 - `NUMBER`: 數字類型。 - `INTEGER`: 整數類型。 - `BOOLEAN`: 布林類型。 - `ARRAY`: 陣列類型。 - `OBJECT`: 物件類型。 - `NULL`: Null 類型。**behavior**: `string enum` 選用。指定函式的 Behavior。目前僅 BidiGenerateContent 方法支援。
可能的值: - `UNSPECIFIED`: 此值未使用。 - `BLOCKING`: 若有設定,系統會等待收到函式回應後才繼續對話。 - `NON_BLOCKING`: 若有設定,系統不會等待收到函式回應。相反地,它會在維持使用者與模型之間對話的同時,嘗試在函式回應可用時加以處理。**googleSearchRetrieval**: `GoogleSearchRetrieval` 選用。由 Google 搜尋驅動的檢索工具。
**dynamicRetrievalConfig**: `DynamicRetrievalConfig` 指定指定來源的動態檢索設定。
**mode**: `string enum` 動態檢索中要使用的預測器模式。
可能的值: - `MODE_UNSPECIFIED`: 一律觸發檢索。 - `MODE_DYNAMIC`: 僅在系統判斷有必要時才執行檢索。**codeExecution**: `CodeExecution` 選用。讓模型能在生成過程中執行程式碼。
**googleSearch**: `GoogleSearch` 選用。GoogleSearch 工具類型。支援模型中的 Google 搜尋。由 Google 提供。
**timeRangeFilter**: `Interval` 選用。將搜尋結果篩選至特定時間範圍。若客戶設定了開始時間,就必須設定結束時間(反之亦然)。
**startTime**: `string` 選用。區間的起始(含)。若有指定,符合此區間的 Timestamp 必須等於或晚於開始。 **endTime**: `string` 選用。區間的結束(不含)。若有指定,符合此區間的 Timestamp 必須早於結束。**searchTypes**: `SearchTypes` 選用。要啟用的搜尋類型集合。若未設定,預設啟用網路搜尋。
**webSearch**: `WebSearch` 選用。啟用網路搜尋。僅傳回文字結果。
**imageSearch**: `ImageSearch` 選用。啟用圖片搜尋。傳回圖片位元組。
**computerUse**: `ComputerUse` 選用。支援模型直接與電腦互動的工具。若啟用,會自動填入電腦使用專屬的 Function Declarations。
**environment**: required `string enum` 正在操作的環境。
可能的值: - `ENVIRONMENT_UNSPECIFIED`: 預設為瀏覽器。 - `ENVIRONMENT_BROWSER`: 在網路瀏覽器中操作。 - `ENVIRONMENT_MOBILE`: 在行動環境中操作。 - `ENVIRONMENT_DESKTOP`: 在桌面環境中操作。**disabledSafetyPolicies**: `string enum array` 選用。電腦使用已停用的安全政策。
可能的值: - `SAFETY_POLICY_UNSPECIFIED`: 未指定的安全政策。 - `FINANCIAL_TRANSACTIONS`: 金融交易的安全政策。 - `SENSITIVE_DATA_MODIFICATION`: 敏感資料修改的安全政策。 - `COMMUNICATION_TOOL`: 通訊工具的安全政策(例如 Gmail、Chat、Meet)。 - `ACCOUNT_CREATION`: 帳號建立的安全政策。 - `DATA_MODIFICATION`: 資料修改的安全政策。 - `USER_CONSENT_MANAGEMENT`: 使用者同意管理的安全政策。 - `LEGAL_TERMS_AND_AGREEMENTS`: 法律條款與協議的安全政策。**urlContext**: `UrlContext` 選用。支援 URL 上下文檢索的工具。
**fileSearch**: `FileSearch` 選用。FileSearch 工具類型。用來從 Semantic Retrieval 語料庫檢索知識的工具。
**fileSearchStoreNames**: required `string array` 要從中檢索的 file_search_stores 名稱。範例:`fileSearchStores/my-file-search-store-123` **topK**: `integer` 選用。要檢索的語意檢索區塊數量。 **metadataFilter**: `string` 選用。要套用至語意檢索文件與區塊的中繼資料篩選條件。**mcpServers**: `McpServer array` 選用。要連線的 MCP 伺服器。
**transport**: `Union type` 用來連線至 MCPServer 的傳輸方式。
聯集欄位 `transport` 只能是下列其中之一:**streamableHttpTransport**: `StreamableHttpTransport` 可以串流 HTTP 請求與回應的傳輸方式。
**url**: `string` MCPServer 端點的完整 URL。範例:"https://api.example.com/mcp" **headers**: `object` 選用:如有需要,提供驗證標頭、逾時等欄位。 **timeout**: `string` 一般操作的 HTTP 逾時。 **sseReadTimeout**: `string` SSE 讀取操作的逾時。 **terminateOnClose**: `boolean` 當傳輸關閉時,是否關閉用戶端工作階段。**googleMaps**: `GoogleMaps` 選用。讓模型的回應能以與使用者查詢相關的地理空間上下文接地的工具。
**enableWidget**: `boolean` 選用。是否在回應的 GroundingMetadata 中傳回 widget 上下文權杖。開發人員可以使用 widget 上下文權杖,呈現與模型在回應中提及的地點相關的地理空間上下文 Google Maps widget。**toolConfig**: `ToolConfig` 選用。請求中指定的任何 `Tool` 的工具設定。使用範例請參閱 [Function calling guide](/docs/function-calling/#function_calling_modes)。
**functionCallingConfig**: `FunctionCallingConfig` 選用。函式呼叫設定。
**mode**: `string enum` 選用。指定函式呼叫應執行的模式。若未指定,預設值將設為 AUTO。
可能的值: - `MODE_UNSPECIFIED`: 未指定的函式呼叫模式。不應使用此值。 - `AUTO`: 預設的模型行為,由模型決定要預測函式呼叫或自然語言回應。 - `ANY`: 模型被限制為一律只預測函式呼叫。若有設定 "allowed_function_names",預測的函式呼叫將限於 "allowed_function_names" 中的任何一個,否則預測的函式呼叫將是所提供的 "function_declarations" 中的任何一個。 - `NONE`: 模型不會預測任何函式呼叫。模型行為與未傳入任何函式宣告時相同。 - `VALIDATED`: 模型決定要預測函式呼叫或自然語言回應,但會以受限解碼驗證函式呼叫。若有設定 "allowed_function_names",預測的函式呼叫將限於 "allowed_function_names" 中的任何一個,否則預測的函式呼叫將是所提供的 "function_declarations" 中的任何一個。**retrievalConfig**: `RetrievalConfig` 選用。檢索設定。
**latLng**: `LatLng` 選用。使用者的位置。
**latitude**: `number` 以度為單位的緯度。必須在 [-90.0, +90.0] 範圍內。 **longitude**: `number` 以度為單位的經度。必須在 [-180.0, +180.0] 範圍內。**safetySettings**: `SafetySetting array` 選用。用來封鎖不安全內容的唯一 `SafetySetting` 執行個體清單。這將強制套用於 `GenerateContentRequest.contents` 與 `GenerateContentResponse.candidates`。每個 `SafetyCategory` 類型不應有多於一個設定。API 會封鎖任何未達到這些設定所定閾值的內容與回應。此清單會覆寫 safety_settings 中指定的每個 `SafetyCategory` 的預設設定。若清單中未提供某個 `SafetySetting`(針對給定的 `SafetyCategory`),API 將使用該類別的預設安全設定。支援的危害類別為 HARM_CATEGORY_HATE_SPEECH、HARM_CATEGORY_SEXUALLY_EXPLICIT、HARM_CATEGORY_DANGEROUS_CONTENT、HARM_CATEGORY_HARASSMENT、HARM_CATEGORY_CIVIC_INTEGRITY、HARM_CATEGORY_JAILBREAK。可用安全設定的詳細資訊請參閱 [guide](/docs/safety-settings/)。另請參閱 [Safety guidance](/docs/safety-guidance/),了解如何將安全考量納入您的 AI 應用程式。
**category**: required `HarmCategory` 此設定的類別。
可能的值: - `HARM_CATEGORY_UNSPECIFIED`: 類別未指定。 - `HARM_CATEGORY_HARASSMENT`: **Gemini** - 騷擾內容。 - `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - 仇恨言論與內容。 - `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - 性露骨內容。 - `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - 危險內容。 - `HARM_CATEGORY_JAILBREAK`: **Gemini** - 試圖繞過或顛覆模型安全指南的提示詞(越獄嘗試)。**threshold**: required `string enum` 控制危害被封鎖的機率閾值。
可能的值: - `HARM_BLOCK_THRESHOLD_UNSPECIFIED`: 閾值未指定。 - `BLOCK_LOW_AND_ABOVE`: 將允許 NEGLIGIBLE 的內容。 - `BLOCK_MEDIUM_AND_ABOVE`: 將允許 NEGLIGIBLE 與 LOW 的內容。 - `BLOCK_ONLY_HIGH`: 將允許 NEGLIGIBLE、LOW 與 MEDIUM 的內容。 - `BLOCK_NONE`: 將允許所有內容。 - `OFF`: 關閉安全篩選器。**generationConfig**: `GenerationConfig` 選用。模型生成與輸出的設定選項。
**candidateCount**: `integer` 選用。要傳回的生成回應數量。若未設定,預設為 1。請注意,這不適用於舊一代模型(Gemini 1.0 系列) **stopSequences**: `string array` 選用。將停止輸出生成的字元序列集合(最多 5 個)。若有指定,API 會在 `stop_sequence` 首次出現時停止。停止序列不會包含在回應中。 **maxOutputTokens**: `integer` 選用。要包含在回應候選中的權杖數量上限。注意:預設值因模型而異,請參閱 `Model.output_token_limit`,這是 `Model` 的屬性,由 `getModel` 函式傳回。 **temperature**: `number` 選用。控制輸出的隨機性。注意:預設值因模型而異,請參閱 `Model.temperature`,這是 `Model` 的屬性,由 `getModel` 函式傳回。值可以介於 [0.0, 2.0]。此欄位在 Gemini 3.6 Flash 與更新的模型上已不再支援,會被靜默忽略。 **topP**: `number` 選用。取樣時要考慮的權杖累積機率上限。模型結合使用 Top-k 與 Top-p(nucleus)取樣。權杖會依其指派的機率排序,因此只考慮最有可能的權杖。Top-k 取樣直接限制要考慮的權杖數量上限,而 Nucleus 取樣則依累積機率限制權杖數量。注意:預設值因 `Model` 而異,由 `Model.top_p` 屬性指定,該屬性由 `getModel` 函式傳回。空的 `top_k` 屬性表示模型不套用 top-k 取樣,也不允許在請求上設定 `top_k`。此欄位在 Gemini 3.6 Flash 與更新的模型上已不再支援,會被靜默忽略。 **topK**: `integer` 選用。取樣時要考慮的權杖數量上限。Gemini 模型使用 Top-p(nucleus)取樣,或 Top-k 與 nucleus 取樣的組合。Top-k 取樣考慮 `top_k` 個最有可能的權杖集合。使用 nucleus 取樣的模型不允許設定 top_k。注意:預設值因 `Model` 而異,由 `Model.top_p` 屬性指定,該屬性由 `getModel` 函式傳回。空的 `top_k` 屬性表示模型不套用 top-k 取樣,也不允許在請求上設定 `top_k`。此欄位在 Gemini 3.6 Flash 與更新的模型上已不再支援,會被靜默忽略。 **seed**: `integer` 選用。解碼時使用的種子。若未設定,請求會使用隨機生成的種子。 **responseMimeType**: `string` 選用。生成的候選文字的 MIME 類型。支援的 MIME 類型為:`text/plain`:(預設)文字輸出。`application/json`:回應候選中的 JSON 回應。`text/x.enum`:回應候選中以字串形式表示的 ENUM 回應。所有支援的文字 MIME 類型清單請參閱 [docs](/docs/file-input-methods/#text-file-types)。 **responseJsonSchema**: `object` 選用。內部詳細資訊。請使用 `responseJsonSchema`,不要使用此欄位。 **presencePenalty**: `number` 選用。若權杖已出現在回應中,套用至下一個權杖 logprobs 的存在懲罰。此懲罰為二元的開/關,不取決於權杖被使用的次數(第一次之後)。若要懲罰隨每次使用而增加,請使用 frequency_penalty。正的懲罰會抑制使用已在回應中使用過的權杖,增加詞彙多樣性。負的懲罰會鼓勵使用已在回應中使用過的權杖,降低詞彙多樣性。 **frequencyPenalty**: `number` 選用。套用至下一個權杖 logprobs 的頻率懲罰,乘以每個權杖到目前為止在回應中出現的次數。正的懲罰會依權杖被使用的次數成比例地抑制已使用過的權杖:權杖使用得越多,模型就越難再次使用該權杖,從而增加回應的詞彙多樣性。注意:*負*的懲罰會依權杖被使用的次數成比例地鼓勵模型重複使用權杖。小的負值會降低回應的詞彙多樣性。較大的負值會使模型開始重複一個常見權杖,直到達到 max_output_tokens 上限。 **responseLogprobs**: `boolean` 選用。若為 true,在回應中匯出 logprobs 結果。 **logprobs**: `integer` 選用。僅在 response_logprobs=True 時有效。這會設定在每個解碼步驟要傳回的頂尖 logprobs 數量(包含所選候選),位於 Candidate.logprobs_result 中。數字必須在 [0, 20] 範圍內。 **enableEnhancedCivicAnswers**: `boolean` 選用。啟用強化公民答案。可能並非所有模型都可用。**responseModalities**: `string enum array` 選用。請求的回應模態。表示模型可以傳回、且應在回應中預期出現的模態集合。這與回應的模態完全相符。模型可能有多種支援模態的組合。若請求的模態與任何支援的組合都不相符,將傳回錯誤。空清單等同於僅請求文字。
可能的值: - `MODALITY_UNSPECIFIED`: 預設值。 - `TEXT`: 表示模型應傳回文字。 - `IMAGE`: 表示模型應傳回圖片。 - `AUDIO`: 表示模型應傳回音訊。**speechConfig**: `SpeechConfig` 選用。語音生成設定。
**voiceConfig**: `VoiceConfig` 單一語音輸出的設定。
**voiceConfig**: `Union type` 要使用的說話者設定。
聯集欄位 `voiceConfig` 只能是下列其中之一:**prebuiltVoiceConfig**: `PrebuiltVoiceConfig` 要使用的預建語音設定。
**voiceName**: `string` 選用。要使用的預設語音名稱。**multiSpeakerVoiceConfig**: `MultiSpeakerVoiceConfig` 選用。多說話者設定的設定。它與 voice_config 欄位互斥。
**speakerVoiceConfigs**: required `SpeakerVoiceConfig array` 所有已啟用的說話者語音。
**speaker**: required `string` 要使用的說話者名稱。應與提示詞中的名稱相同。**voiceConfig**: required `VoiceConfig` 要使用的語音設定。
**voiceConfig**: `Union type` 要使用的說話者設定。
聯集欄位 `voiceConfig` 只能是下列其中之一:**prebuiltVoiceConfig**: `PrebuiltVoiceConfig` 要使用的預建語音設定。
**voiceName**: `string` 選用。要使用的預設語音名稱。**thinkingConfig**: `ThinkingConfig` 選用。思考功能的設定。若為不支援思考的模型設定此欄位,將傳回錯誤。
**includeThoughts**: `boolean` 表示是否在回應中包含思考內容。若為 true,僅在思考內容可用時才傳回。 **thinkingBudget**: `integer` 模型應生成的思考權杖數量。**thinkingLevel**: `string enum` 選用。控制模型在產生回應之前,內部推理過程的最大深度。預設值取決於模型。詳情請參閱 [Thinking levels guide](/docs/thinking/#thinking-levels)。建議用於 Gemini 3 或更新的模型。在較早的模型上使用會導致錯誤。
可能的值: - `THINKING_LEVEL_UNSPECIFIED`: 預設值。 - `MINIMAL`: 幾乎不思考。 - `LOW`: 低思考等級。 - `MEDIUM`: 中思考等級。 - `HIGH`: 高思考等級。 - `XHIGH`: 超高思考等級。**imageConfig**: `ImageConfig` 選用。圖片生成的設定。若為不支援這些設定選項的模型設定此欄位,將傳回錯誤。
**aspectRatio**: `string` 選用。要生成的圖片長寬比。支援的長寬比:`1:1`、`1:4`、`4:1`、`1:8`、`8:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9` 或 `21:9`。若未指定,模型會根據提供的任何參照圖片選擇預設長寬比。 **imageSize**: `string` 選用。指定生成的圖片大小。支援的值為 `512`、`1K`、`2K`、`4K`。若未指定,模型會使用預設值 `1K`。**mediaResolution**: `string enum` 選用。若有指定,將使用指定的媒體解析度。
可能的值: - `MEDIA_RESOLUTION_UNSPECIFIED`: 尚未設定媒體解析度。 - `MEDIA_RESOLUTION_LOW`: 媒體解析度設為低(64 個權杖)。 - `MEDIA_RESOLUTION_MEDIUM`: 媒體解析度設為中(256 個權杖)。 - `MEDIA_RESOLUTION_HIGH`: 媒體解析度設為高(以 256 個權杖縮放重新取景)。**responseFormat**: `ResponseFormatConfig` 選用。回應輸出格式的設定。允許以扁平結構為每個模態(文字、音訊、圖片)指定輸出設定。
**text**: `TextResponseFormat` 選用。文字輸出格式設定。
**mimeType**: `string enum` 選用。文字輸出的 MIME 類型。
可能的值: - `MIME_TYPE_UNSPECIFIED`: 預設值。此值未使用。 - `APPLICATION_JSON`: JSON 輸出格式。 - `TEXT_PLAIN`: 純文字輸出格式。**audio**: `AudioResponseFormat` 選用。音訊輸出格式設定。
**mimeType**: `string enum` 選用。音訊輸出的 MIME 類型。
可能的值: - `MIME_TYPE_UNSPECIFIED`: 預設值。此值未使用。 - `AUDIO_MP3`: MP3 音訊格式。 - `AUDIO_OGG_OPUS`: OGG Opus 音訊格式。 - `AUDIO_L16`: 原始 PCM(L16)音訊格式。 - `AUDIO_WAV`: WAV 音訊格式。 - `AUDIO_ALAW`: A-law 音訊格式。 - `AUDIO_MULAW`: Mu-law 音訊格式。**delivery**: `string enum` 選用。音訊輸出的傳遞模式。
可能的值: - `DELIVERY_UNSPECIFIED`: 預設值。此值未使用。 - `INLINE`: 音訊資料在回應中內嵌傳回。 - `URI`: 音訊資料以 URI 形式傳回。**image**: `ImageResponseFormat` 選用。圖片輸出格式設定。
**mimeType**: `string enum` 選用。圖片輸出的 MIME 類型。
可能的值: - `MIME_TYPE_UNSPECIFIED`: 預設值。此值未使用。 - `IMAGE_JPEG`: JPEG 圖片格式。**delivery**: `string enum` 選用。圖片輸出的傳遞模式。
可能的值: - `DELIVERY_UNSPECIFIED`: 預設值。此值未使用。 - `INLINE`: 圖片資料在回應中內嵌傳回。 - `URI`: 圖片資料以 URI 形式傳回。**aspectRatio**: `string enum` 選用。圖片輸出的長寬比。
可能的值: - `ASPECT_RATIO_UNSPECIFIED`: 預設值。此值未使用。 - `ASPECT_RATIO_ONE_BY_ONE`: 1:1 長寬比。 - `ASPECT_RATIO_TWO_BY_THREE`: 2:3 長寬比。 - `ASPECT_RATIO_THREE_BY_TWO`: 3:2 長寬比。 - `ASPECT_RATIO_THREE_BY_FOUR`: 3:4 長寬比。 - `ASPECT_RATIO_FOUR_BY_THREE`: 4:3 長寬比。 - `ASPECT_RATIO_FOUR_BY_FIVE`: 4:5 長寬比。 - `ASPECT_RATIO_FIVE_BY_FOUR`: 5:4 長寬比。 - `ASPECT_RATIO_NINE_BY_SIXTEEN`: 9:16 長寬比。 - `ASPECT_RATIO_SIXTEEN_BY_NINE`: 16:9 長寬比。 - `ASPECT_RATIO_TWENTY_ONE_BY_NINE`: 21:9 長寬比。 - `ASPECT_RATIO_ONE_BY_EIGHT`: 1:8 長寬比。 - `ASPECT_RATIO_EIGHT_BY_ONE`: 8:1 長寬比。 - `ASPECT_RATIO_ONE_BY_FOUR`: 1:4 長寬比。 - `ASPECT_RATIO_FOUR_BY_ONE`: 4:1 長寬比。**imageSize**: `string enum` 選用。圖片輸出的大小。
可能的值: - `IMAGE_SIZE_UNSPECIFIED`: 預設值。此值未使用。 - `IMAGE_SIZE_FIVE_TWELVE`: 512px 圖片大小。 - `IMAGE_SIZE_ONE_K`: 1K 圖片大小。 - `IMAGE_SIZE_TWO_K`: 2K 圖片大小。 - `IMAGE_SIZE_FOUR_K`: 4K 圖片大小。**translationConfig**: `TranslationConfig` 選用。翻譯設定。
**targetLanguageCode**: required `string` 翻譯的目標語言。支援的值為 BCP-47 語言代碼(例如 "en"、"es"、"fr")。 **echoTargetLanguage**: `boolean` 選用。若為 true,當目標語言被說出時,模型會生成音訊,實質上會鸚鵡學舌般重複輸入。若為 false,我們不會為目標語言產生音訊。**audioTranscriptionConfig**: `AudioTranscriptionConfig` 選用。音訊轉錄設定(語音辨識)。
**languageCodes**: `string array` 選用。BCP-47 語言代碼,提供音訊中出現語言的提示。若省略或為空,預設為自動語言偵測。 **customVocabulary**: `string array` 選用。自訂詞彙短語清單,用來使語音辨識模型偏向辨識特定詞彙(產品名稱、專有名詞、術語)。 **wordTimestamp**: `boolean` 選用。設定單字層級時間戳記的生成。 **diarization**: `boolean` 選用。設定說話者分離(diarization)。 **sourceText**: `string` 選用。要透過語音指令編輯或改寫的來源文字。在 `SMART` 模式下提供時,模型會對照此文字評估音訊輸入,並在候選回應中發出完整的替代文字,而不是附加在其後。**mode**: `string enum` 選用。設定轉錄模式。支援的值:`VERBATIM`、`SMART`。若未指定,預設為 `VERBATIM` 轉錄。在 `SMART` 模式下,模型會執行去除不流暢(消除填充詞、重複與假開頭)、輕度文法清理、自動格式化(段落、項目符號、編號清單),以及輕微的使用者編輯(行內自我修正)。時間戳記與 diarization 與 `SMART` 模式不相容。
可能的值: - `MODE_UNSPECIFIED`: 未指定的轉錄模式。 - `VERBATIM`: 逐字轉錄模式。 - `SMART`: 智慧轉錄模式。**serviceTier**: [`ServiceTier`](/api-reference/batch-api/update-generate-content-batch/#Resource:ServiceTier) 選用。請求的服務層級。
可能的值: - `unspecified`: 預設服務層級,即標準。 - `standard`: 標準服務層級。 - `flex`: Flex 服務層級。 - `priority`: Priority 服務層級。name: string
僅供輸出。識別碼。批次的資源名稱。格式:batches/{batch_id}。
**output**: `GenerateContentBatchOutput` 僅供輸出。批次請求的輸出。
**output**: `Union type` 批次請求的輸出。
聯集欄位 `output` 只能是下列其中之一: **responsesFile**: `string` 僅供輸出。包含回應的檔案的檔案 ID。該檔案將是 JSONL 檔案,每行一個回應。回應將是格式化為 JSON 的 `GenerateContentResponse` 訊息。回應將以與輸入請求相同的順序寫入。**inlinedResponses**: `InlinedResponses` 僅供輸出。批次中各請求的回應。當批次是使用內嵌請求建立時傳回。回應將以與輸入請求相同的順序排列。
**inlinedResponses**: `InlinedResponse array` 僅供輸出。批次中各請求的回應。
**output**: `Union type` 請求的輸出。
聯集欄位 `output` 只能是下列其中之一:**error**: `Status` 僅供輸出。處理請求時遇到的錯誤。
**code**: `integer` 狀態碼,應為 google.rpc.Code 的列舉值。 **message**: `string` 面向開發人員的錯誤訊息,應以英文撰寫。任何面向使用者的錯誤訊息都應本地化,並在 google.rpc.Status.details 欄位中傳送,或由用戶端本地化。 **details**: `object array` 承載錯誤詳細資訊的訊息清單。API 可以使用一組常見的訊息類型。**response**: `GenerateContentResponse` 僅供輸出。對請求的回應。
**candidates**: `Candidate array` 來自模型的候選回應。
**index**: `integer` 僅供輸出。候選在回應候選清單中的索引。**content**: `Content` 僅供輸出。模型傳回的生成內容。
**parts**: `Part array` 組成單一訊息的有序 `Parts`。各 Part 的 MIME 類型可能不同。
**data**: `Union type`
聯集欄位 `data` 只能是下列其中之一: **text**: `string` 內嵌文字。**inlineData**: `Blob` 內嵌媒體位元組。
**mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。支援的類型範例: - 圖片:image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif - 音訊:audio/*, video/audio/s16le, video/audio/wav - 影片:video/* - 文字:text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp - 應用程式:application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf 其他背景資訊請參閱 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **data**: `string` 媒體格式的原始位元組。 **displayName**: `string` 選用。指定用來向模型指稱此 blob 的名稱(例如 "my_blob.png")。當 `verbalization_mode` 設為 `REFERENCE_ONLY` 時,作為 blob 的參照識別碼。**functionCall**: `FunctionCall` 模型傳回的預測 `FunctionCall`,其中包含代表 `FunctionDeclaration.name` 的字串,以及其引數與值。
**name**: required `string` 要呼叫的函式名稱。必須為 a-z、A-Z、0-9,或包含底線與連字號,長度上限為 128。 **id**: `string` 選用。函式呼叫的唯一識別碼。若有填入,用戶端應執行 `function_call`,並傳回具有相符 `id` 的回應。 **args**: `object` 選用。以 JSON 物件格式表示的函式參數與值。**functionResponse**: `FunctionResponse` `FunctionCall` 的結果輸出,其中包含代表 `FunctionDeclaration.name` 的字串,以及包含函式任何輸出的結構化 JSON 物件,作為提供給模型的上下文。
**name**: required `string` 要呼叫的函式名稱。必須為 a-z、A-Z、0-9,或包含底線與連字號,長度上限為 128。 **response**: required `object` 以 JSON 物件格式表示的函式回應。呼叫端可以使用任何符合函式語法的自選鍵來傳回函式輸出,例如 "output"、"result" 等。特別是當函式呼叫執行失敗時,回應可以包含 "error" 鍵,將錯誤詳細資訊傳回給模型。多媒體內容可以透過子物件納入,該子物件包含單一 "$ref" 鍵,其值為 `inline_data.display_name` 或 `file_data.display_name`,屬於持有該多媒體內容的 `FunctionResponsePart`。請參閱 [Multimodal function responses](/docs/function-calling/#multimodal)。 **id**: `string` 選用。此回應所對應的函式呼叫識別碼。由用戶端填入,以對應相對應的函式呼叫 `id`。**parts**: `FunctionResponsePart array` 選用。組成函式回應的有序 `Parts`。各 Part 的 IANA MIME 類型可能不同。
**data**: `Union type` 函式回應部分的資料。
聯集欄位 `data` 只能是下列其中之一:**inlineData**: `FunctionResponseBlob` 內嵌媒體位元組。
**mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。範例: - image/png - image/jpeg 若提供不支援的 MIME 類型,將傳回錯誤。支援類型的完整清單請參閱 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **data**: `string` 媒體格式的原始位元組。 **displayName**: `string` 選用。blob 的顯示名稱。用來提供標籤或檔名以區分各個 blob,並可從 `FunctionResponse.response` 參照該 blob(例如透過 `{"$ref": "DISPLAY_NAME"}`)。**fileData**: `FunctionResponseFileData` 以 URI 為基礎的資料。
**fileUri**: required `string` URI。 **mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。若提供不支援的 MIME 類型,將傳回錯誤。支援類型的完整清單請參閱 [Multimodal function responses](/docs/function-calling/#multimodal) 與 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **displayName**: `string` 選用。檔案的顯示名稱。用來提供標籤或檔名以區分檔案資料,並可從 `FunctionResponse.response` 參照該檔案(例如透過 `{"$ref": "DISPLAY_NAME"}`)。**mediaProcessing**: `string enum` 選用。模型如何處理此部分的媒體以進行理解。僅對影片部分(`inline_data` 或具有影片 MIME 類型的 `file_data`)有意義。非影片部分會忽略此欄位。
可能的值: - `MEDIA_PROCESSING_UNSPECIFIED`: 預設為模型專屬的處理方式。 - `STATIC`: 固定速率的影格擷取。所有影格都放入上下文中。 - `AGENTIC`: 由模型驅動的動態導覽。建議用於大多數使用情境。**scheduling**: `string enum` 選用。指定回應在對話中的排程方式。僅適用於 NON_BLOCKING 函式呼叫,其他情況會被忽略。預設為 WHEN_IDLE。
可能的值: - `SCHEDULING_UNSPECIFIED`: 此值未使用。 - `SILENT`: 僅將結果加入對話上下文,不中斷也不觸發生成。 - `WHEN_IDLE`: 將結果加入對話上下文,並在不中斷進行中生成的情況下提示生成輸出。 - `INTERRUPT`: 將結果加入對話上下文,中斷進行中的生成,並提示生成輸出。**fileData**: `FileData` 以 URI 為基礎的資料。
**fileUri**: required `string` URI。 **mimeType**: `string` 選用。來源資料的 IANA 標準 MIME 類型。 **displayName**: `string` 選用。指定用來向模型指稱此檔案的名稱(例如 "my_file.pdf")。當 `verbalization_mode` 設為 `REFERENCE_ONLY` 時,作為檔案的參照識別碼。**executableCode**: `ExecutableCode` 由模型生成、預定要執行的程式碼。
**language**: required `string enum` `code` 的程式語言。
可能的值: - `LANGUAGE_UNSPECIFIED`: 未指定的語言。不應使用此值。 - `PYTHON`: Python >= 3.10,可使用 numpy 與 simpy。Python 為預設語言。**codeExecutionResult**: `CodeExecutionResult` 執行 `ExecutableCode` 的結果。
**outcome**: required `string enum` 程式碼執行的結果。
可能的值: - `OUTCOME_UNSPECIFIED`: 未指定的狀態。不應使用此值。 - `OUTCOME_OK`: 程式碼執行成功完成。`output` 包含標準輸出(若有)。 - `OUTCOME_FAILED`: 程式碼執行失敗。`output` 包含標準錯誤與標準輸出(若有)。 - `OUTCOME_DEADLINE_EXCEEDED`: 程式碼執行時間過長,已被取消。可能有、也可能沒有部分的 `output`。**toolCall**: `ToolCall` 伺服器端工具呼叫。當模型預測某個工具叫用應在伺服器上執行時,會填入此欄位。用戶端應將此訊息原樣回傳給 API。
**toolType**: required `V1mainToolType` 被呼叫的工具類型。
可能的值: - `TOOL_TYPE_UNSPECIFIED`: 未指定的工具類型。 - `GOOGLE_SEARCH_WEB`: Google 搜尋工具,對應至 Tool.google_search.search_types.web_search。 - `GOOGLE_SEARCH_IMAGE`: 圖片搜尋工具,對應至 Tool.google_search.search_types.image_search。 - `URL_CONTEXT`: URL 上下文工具,對應至 Tool.url_context。 - `GOOGLE_MAPS`: Google 地圖工具,對應至 Tool.google_maps。 - `FILE_SEARCH`: File Search 工具,對應至 Tool.file_search。 - `MEDIA_PROCESSING`: 媒體處理工具類型(例如影片、音訊等),對應至用於多模態理解的隱形工具,例如 GOOGLE_UNDERSTANDING_VIDEO。**toolResponse**: `ToolResponse` 伺服器端 `ToolCall` 執行的輸出。此欄位由用戶端填入,內容為執行對應 `ToolCall` 的結果。
**toolType**: required `V1mainToolType` 被呼叫的工具類型,其 `tool_type` 與對應的 `ToolCall` 相符。
可能的值: - `TOOL_TYPE_UNSPECIFIED`: 未指定的工具類型。 - `GOOGLE_SEARCH_WEB`: Google 搜尋工具,對應至 Tool.google_search.search_types.web_search。 - `GOOGLE_SEARCH_IMAGE`: 圖片搜尋工具,對應至 Tool.google_search.search_types.image_search。 - `URL_CONTEXT`: URL 上下文工具,對應至 Tool.url_context。 - `GOOGLE_MAPS`: Google 地圖工具,對應至 Tool.google_maps。 - `FILE_SEARCH`: File Search 工具,對應至 Tool.file_search。 - `MEDIA_PROCESSING`: 媒體處理工具類型(例如影片、音訊等),對應至用於多模態理解的隱形工具,例如 GOOGLE_UNDERSTANDING_VIDEO。**metadata**: `Union type` 控制資料的額外前置處理。當 `inline_data` 或 `file_data` 存在時設定此欄位,以設定每個部分的靜態媒體前置處理。
聯集欄位 `metadata` 只能是下列其中之一:**videoMetadata**: `VideoMetadata` 選用。影片中繼資料。僅當影片資料以 inline_data 或 file_data 呈現時,才應指定中繼資料。
**startOffset**: `string` 選用。影片的開始偏移。 **endOffset**: `string` 選用。影片的結束偏移。 **fps**: `number` 選用。傳送給模型的影片影格率。若未指定,預設值為 1.0。fps 範圍為 (0.0, 24.0]。**mediaResolution**: `V1mainMediaResolution` 選用。輸入媒體的媒體解析度。
**value**: `Union type` 媒體解析度等級。
聯集欄位 `value` 只能是下列其中之一:**level**: `string enum` 指定媒體所使用的權杖化品質。
可能的值: - `MEDIA_RESOLUTION_UNSPECIFIED`: 尚未設定媒體解析度。 - `MEDIA_RESOLUTION_LOW`: 媒體解析度設為低。 - `MEDIA_RESOLUTION_MEDIUM`: 媒體解析度設為中。 - `MEDIA_RESOLUTION_HIGH`: 媒體解析度設為高。 - `MEDIA_RESOLUTION_ULTRA_HIGH`: 媒體解析度設為超高。**mediaProcessing**: `string enum` 選用。模型如何處理此部分的媒體以進行理解。僅對影片部分(`inline_data` 或具有影片 MIME 類型的 `file_data`)有意義。非影片部分會忽略此欄位。
可能的值: - `MEDIA_PROCESSING_UNSPECIFIED`: 預設為模型專屬的處理方式。 - `STATIC`: 固定速率的影格擷取。所有影格都放入上下文中。 - `AGENTIC`: 由模型驅動的動態導覽。建議用於大多數使用情境。**audioTranscription**: `AudioTranscription` 選用。音訊(輸入或輸出)轉錄。僅當此 Part 包含音訊資料時才會設定。
**text**: required `string` 此音訊片段的轉錄文字。 **speakerLabel**: `string` 選用。標示此音訊片段說話者的標籤(例如 "spk_1"、"spk_2")。在設定 diarization 時出現。**words**: `WordInfo array` 選用。詳細的單字層級轉錄與時間資訊。在設定 word_timestamp 時出現。
**word**: required `string` 單字的轉錄。 **startOffset**: `string` 選用。單字相對於音訊開頭的開始時間偏移。 **endOffset**: `string` 選用。單字相對於音訊開頭的結束時間偏移。**speechMetadata**: `SpeechMetadata` 選用。套用至文字部分的中繼資料,用來客製化其朗讀或合成方式,例如指定說話者身分或說話風格。
**speaker**: `string` 選用。多說話者合成的選用說話者名稱。 **style**: `string` 選用。語音合成的選用風格指令。**finishReason**: `string enum` 選用。僅供輸出。模型停止生成權杖的原因。若為空,模型尚未停止生成權杖。
可能的值: - `FINISH_REASON_UNSPECIFIED`: 預設值。此值未使用。 - `STOP`: 模型的自然停止點或提供的停止序列。 - `MAX_TOKENS`: 已達到請求中指定的權杖數量上限。 - `SAFETY`: 回應候選內容因安全原因被標記。 - `RECITATION`: 回應候選內容因重述(recitation)原因被標記。 - `LANGUAGE`: 回應候選內容因使用不支援的語言被標記。 - `OTHER`: 未知原因。 - `BLOCKLIST`: 權杖生成因內容包含禁用詞彙而停止。 - `PROHIBITED_CONTENT`: 權杖生成因可能包含禁止內容而停止。 - `SPII`: 權杖生成因內容可能包含敏感個人識別資訊(SPII)而停止。 - `MALFORMED_FUNCTION_CALL`: 模型生成的函式呼叫無效。 - `IMAGE_SAFETY`: 權杖生成因生成的圖片包含安全違規而停止。 - `IMAGE_PROHIBITED_CONTENT`: 圖片生成因生成的圖片含有其他禁止內容而停止。 - `IMAGE_OTHER`: 圖片生成因其他雜項問題而停止。 - `NO_IMAGE`: 模型預期要生成圖片,但沒有生成任何圖片。 - `IMAGE_RECITATION`: 圖片生成因重述(recitation)而停止。 - `UNEXPECTED_TOOL_CALL`: 模型生成了工具呼叫,但請求中未啟用任何工具。 - `TOO_MANY_TOOL_CALLS`: 模型連續呼叫了太多工具,因此系統退出執行。 - `MISSING_THOUGHT_SIGNATURE`: 請求至少缺少一個思考簽章。 - `MALFORMED_RESPONSE`: 因回應格式錯誤而結束。 - `ESCALATION`: 請求被升級規則(escalation rule)篩除。 - `PUP_LIMITED_DISABLED`: 表示權杖生成因使用者帳號違反禁止使用政策(PUP)而受限或停用,因而停止。 - `CONTINUATION`: 權杖生成因回應已達到每個請求的權杖上限而停止,但生成尚未完成。模型的回應可以透過後續請求、使用傳回的 `continuation_token` 繼續。請注意,`max_output_tokens` 在各接續跳躍之間是累積的,且必須單調增加或省略。**safetyRatings**: `SafetyRating array` 回應候選的安全性評級清單。每個類別最多有一個評級。
**category**: required `HarmCategory` 此評級的類別。
可能的值: - `HARM_CATEGORY_UNSPECIFIED`: 類別未指定。 - `HARM_CATEGORY_HARASSMENT`: **Gemini** - 騷擾內容。 - `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - 仇恨言論與內容。 - `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - 性露骨內容。 - `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - 危險內容。 - `HARM_CATEGORY_JAILBREAK`: **Gemini** - 試圖繞過或顛覆模型安全指南的提示詞(越獄嘗試)。**probability**: required `string enum` 此內容的危害機率。
可能的值: - `HARM_PROBABILITY_UNSPECIFIED`: 機率未指定。 - `NEGLIGIBLE`: 內容不安全的可能性微乎其微。 - `LOW`: 內容不安全的可能性低。 - `MEDIUM`: 內容不安全的可能性中。 - `HIGH`: 內容不安全的可能性高。**citationMetadata**: `CitationMetadata` 僅供輸出。模型生成候選的引用資訊。此欄位可能會填入 `content` 中包含的任何文字的重述資訊。這些是從基礎 LLM 訓練資料中的受版權保護材料「重述」的段落。
**citationSources**: `CitationSource array` 特定回應的來源引用。
**startIndex**: `integer` 選用。歸因於此來源的回應片段的開頭。索引表示片段的開頭,以位元組為單位測量。 **endIndex**: `integer` 選用。歸因片段的結尾(不含)。 **uri**: `string` 選用。歸因於文字某部分來源的 URI。 **license**: `string` 選用。歸因於片段來源的 GitHub 專案授權。程式碼引用需要授權資訊。**groundingAttributions**: `GroundingAttribution array` 僅供輸出。為接地答案提供貢獻的來源歸因資訊。此欄位會為 `GenerateAnswer` 呼叫填入。
**sourceId**: `AttributionSourceId` 僅供輸出。為此歸因提供貢獻的來源識別碼。
**source**: `Union type`
聯集欄位 `source` 只能是下列其中之一:**groundingPassage**: `GroundingPassageId` 內嵌段落的識別碼。
**passageId**: `string` 僅供輸出。與 `GenerateAnswerRequest` 的 `GroundingPassage.id` 相符的段落 ID。 **partIndex**: `integer` 僅供輸出。`GenerateAnswerRequest` 的 `GroundingPassage.content` 內的部分索引。**semanticRetrieverChunk**: `SemanticRetrieverChunk` 透過 Semantic Retriever 取得的 `Chunk` 識別碼。
**source**: `string` 僅供輸出。與請求的 `SemanticRetrieverConfig.source` 相符的來源名稱。範例:`corpora/123` 或 `corpora/123/documents/abc` **chunk**: `string` 僅供輸出。包含歸因文字的 `Chunk` 名稱。範例:`corpora/123/documents/abc/chunks/xyz`**content**: `Content` 組成此歸因的接地來源內容。
**parts**: `Part array` 組成單一訊息的有序 `Parts`。各 Part 的 MIME 類型可能不同。
**data**: `Union type`
聯集欄位 `data` 只能是下列其中之一: **text**: `string` 內嵌文字。**inlineData**: `Blob` 內嵌媒體位元組。
**mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。支援的類型範例: - 圖片:image/png, image/jpeg, image/jpg, image/webp, image/heic, image/heif, image/gif, image/avif - 音訊:audio/*, video/audio/s16le, video/audio/wav - 影片:video/* - 文字:text/plain, text/html, text/css, text/javascript, text/x-typescript, text/csv, text/markdown, text/x-python, text/xml, text/rtf, video/text/timestamp - 應用程式:application/x-javascript, application/x-typescript, application/x-python-code, application/json, application/x-ipynb+json, application/rtf, application/pdf 其他背景資訊請參閱 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **data**: `string` 媒體格式的原始位元組。 **displayName**: `string` 選用。指定用來向模型指稱此 blob 的名稱(例如 "my_blob.png")。當 `verbalization_mode` 設為 `REFERENCE_ONLY` 時,作為 blob 的參照識別碼。**functionCall**: `FunctionCall` 模型傳回的預測 `FunctionCall`,其中包含代表 `FunctionDeclaration.name` 的字串,以及其引數與值。
**name**: required `string` 要呼叫的函式名稱。必須為 a-z、A-Z、0-9,或包含底線與連字號,長度上限為 128。 **id**: `string` 選用。函式呼叫的唯一識別碼。若有填入,用戶端應執行 `function_call`,並傳回具有相符 `id` 的回應。 **args**: `object` 選用。以 JSON 物件格式表示的函式參數與值。**functionResponse**: `FunctionResponse` `FunctionCall` 的結果輸出,其中包含代表 `FunctionDeclaration.name` 的字串,以及包含函式任何輸出的結構化 JSON 物件,作為提供給模型的上下文。
**name**: required `string` 要呼叫的函式名稱。必須為 a-z、A-Z、0-9,或包含底線與連字號,長度上限為 128。 **response**: required `object` 以 JSON 物件格式表示的函式回應。呼叫端可以使用任何符合函式語法的自選鍵來傳回函式輸出,例如 "output"、"result" 等。特別是當函式呼叫執行失敗時,回應可以包含 "error" 鍵,將錯誤詳細資訊傳回給模型。多媒體內容可以透過子物件納入,該子物件包含單一 "$ref" 鍵,其值為 `inline_data.display_name` 或 `file_data.display_name`,屬於持有該多媒體內容的 `FunctionResponsePart`。請參閱 [Multimodal function responses](/docs/function-calling/#multimodal)。 **id**: `string` 選用。此回應所對應的函式呼叫識別碼。由用戶端填入,以對應相對應的函式呼叫 `id`。**parts**: `FunctionResponsePart array` 選用。組成函式回應的有序 `Parts`。各 Part 的 IANA MIME 類型可能不同。
**data**: `Union type` 函式回應部分的資料。
聯集欄位 `data` 只能是下列其中之一:**inlineData**: `FunctionResponseBlob` 內嵌媒體位元組。
**mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。範例: - image/png - image/jpeg 若提供不支援的 MIME 類型,將傳回錯誤。支援類型的完整清單請參閱 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **data**: `string` 媒體格式的原始位元組。 **displayName**: `string` 選用。blob 的顯示名稱。用來提供標籤或檔名以區分各個 blob,並可從 `FunctionResponse.response` 參照該 blob(例如透過 `{"$ref": "DISPLAY_NAME"}`)。**fileData**: `FunctionResponseFileData` 以 URI 為基礎的資料。
**fileUri**: required `string` URI。 **mimeType**: `string` 來源資料的 IANA 標準 MIME 類型。若提供不支援的 MIME 類型,將傳回錯誤。支援類型的完整清單請參閱 [Multimodal function responses](/docs/function-calling/#multimodal) 與 [Supported file formats](/docs/file-input-methods/#supported-content-types)。 **displayName**: `string` 選用。檔案的顯示名稱。用來提供標籤或檔名以區分檔案資料,並可從 `FunctionResponse.response` 參照該檔案(例如透過 `{"$ref": "DISPLAY_NAME"}`)。**mediaProcessing**: `string enum` 選用。模型如何處理此部分的媒體以進行理解。僅對影片部分(`inline_data` 或具有影片 MIME 類型的 `file_data`)有意義。非影片部分會忽略此欄位。
可能的值: - `MEDIA_PROCESSING_UNSPECIFIED`: 預設為模型專屬的處理方式。 - `STATIC`: 固定速率的影格擷取。所有影格都放入上下文中。 - `AGENTIC`: 由模型驅動的動態導覽。建議用於大多數使用情境。**scheduling**: `string enum` 選用。指定回應在對話中的排程方式。僅適用於 NON_BLOCKING 函式呼叫,其他情況會被忽略。預設為 WHEN_IDLE。
可能的值: - `SCHEDULING_UNSPECIFIED`: 此值未使用。 - `SILENT`: 僅將結果加入對話上下文,不中斷也不觸發生成。 - `WHEN_IDLE`: 將結果加入對話上下文,並在不中斷進行中生成的情況下提示生成輸出。 - `INTERRUPT`: 將結果加入對話上下文,中斷進行中的生成,並提示生成輸出。**fileData**: `FileData` 以 URI 為基礎的資料。
**fileUri**: required `string` URI。 **mimeType**: `string` 選用。來源資料的 IANA 標準 MIME 類型。 **displayName**: `string` 選用。指定用來向模型指稱此檔案的名稱(例如 "my_file.pdf")。當 `verbalization_mode` 設為 `REFERENCE_ONLY` 時,作為檔案的參照識別碼。**executableCode**: `ExecutableCode` 由模型生成、預定要執行的程式碼。
**language**: required `string enum` `code` 的程式語言。
可能的值: - `LANGUAGE_UNSPECIFIED`: 未指定的語言。不應使用此值。 - `PYTHON`: Python >= 3.10,可使用 numpy 與 simpy。Python 為預設語言。**codeExecutionResult**: `CodeExecutionResult` 執行 `ExecutableCode` 的結果。
**outcome**: required `string enum` 程式碼執行的結果。
可能的值: - `OUTCOME_UNSPECIFIED`: 未指定的狀態。不應使用此值。 - `OUTCOME_OK`: 程式碼執行成功完成。`output` 包含標準輸出(若有)。 - `OUTCOME_FAILED`: 程式碼執行失敗。`output` 包含標準錯誤與標準輸出(若有)。 - `OUTCOME_DEADLINE_EXCEEDED`: 程式碼執行時間過長,已被取消。可能有、也可能沒有部分的 `output`。**toolCall**: `ToolCall` 伺服器端工具呼叫。當模型預測某個工具叫用應在伺服器上執行時,會填入此欄位。用戶端應將此訊息原樣回傳給 API。
**toolType**: required `V1mainToolType` 被呼叫的工具類型。
可能的值: - `TOOL_TYPE_UNSPECIFIED`: 未指定的工具類型。 - `GOOGLE_SEARCH_WEB`: Google 搜尋工具,對應至 Tool.google_search.search_types.web_search。 - `GOOGLE_SEARCH_IMAGE`: 圖片搜尋工具,對應至 Tool.google_search.search_types.image_search。 - `URL_CONTEXT`: URL 上下文工具,對應至 Tool.url_context。 - `GOOGLE_MAPS`: Google 地圖工具,對應至 Tool.google_maps。 - `FILE_SEARCH`: File Search 工具,對應至 Tool.file_search。 - `MEDIA_PROCESSING`: 媒體處理工具類型(例如影片、音訊等),對應至用於多模態理解的隱形工具,例如 GOOGLE_UNDERSTANDING_VIDEO。**toolResponse**: `ToolResponse` 伺服器端 `ToolCall` 執行的輸出。此欄位由用戶端填入,內容為執行對應 `ToolCall` 的結果。
**toolType**: required `V1mainToolType` 被呼叫的工具類型,其 `tool_type` 與對應的 `ToolCall` 相符。
可能的值: - `TOOL_TYPE_UNSPECIFIED`: 未指定的工具類型。 - `GOOGLE_SEARCH_WEB`: Google 搜尋工具,對應至 Tool.google_search.search_types.web_search。 - `GOOGLE_SEARCH_IMAGE`: 圖片搜尋工具,對應至 Tool.google_search.search_types.image_search。 - `URL_CONTEXT`: URL 上下文工具,對應至 Tool.url_context。 - `GOOGLE_MAPS`: Google 地圖工具,對應至 Tool.google_maps。 - `FILE_SEARCH`: File Search 工具,對應至 Tool.file_search。 - `MEDIA_PROCESSING`: 媒體處理工具類型(例如影片、音訊等),對應至用於多模態理解的隱形工具,例如 GOOGLE_UNDERSTANDING_VIDEO。**metadata**: `Union type` 控制資料的額外前置處理。當 `inline_data` 或 `file_data` 存在時設定此欄位,以設定每個部分的靜態媒體前置處理。
聯集欄位 `metadata` 只能是下列其中之一:**videoMetadata**: `VideoMetadata` 選用。影片中繼資料。僅當影片資料以 inline_data 或 file_data 呈現時,才應指定中繼資料。
**startOffset**: `string` 選用。影片的開始偏移。 **endOffset**: `string` 選用。影片的結束偏移。 **fps**: `number` 選用。傳送給模型的影片影格率。若未指定,預設值為 1.0。fps 範圍為 (0.0, 24.0]。**mediaResolution**: `V1mainMediaResolution` 選用。輸入媒體的媒體解析度。
**value**: `Union type` 媒體解析度等級。
聯集欄位 `value` 只能是下列其中之一:**level**: `string enum` 指定媒體所使用的權杖化品質。
可能的值: - `MEDIA_RESOLUTION_UNSPECIFIED`: 尚未設定媒體解析度。 - `MEDIA_RESOLUTION_LOW`: 媒體解析度設為低。 - `MEDIA_RESOLUTION_MEDIUM`: 媒體解析度設為中。 - `MEDIA_RESOLUTION_HIGH`: 媒體解析度設為高。 - `MEDIA_RESOLUTION_ULTRA_HIGH`: 媒體解析度設為超高。**mediaProcessing**: `string enum` 選用。模型如何處理此部分的媒體以進行理解。僅對影片部分(`inline_data` 或具有影片 MIME 類型的 `file_data`)有意義。非影片部分會忽略此欄位。
可能的值: - `MEDIA_PROCESSING_UNSPECIFIED`: 預設為模型專屬的處理方式。 - `STATIC`: 固定速率的影格擷取。所有影格都放入上下文中。 - `AGENTIC`: 由模型驅動的動態導覽。建議用於大多數使用情境。**audioTranscription**: `AudioTranscription` 選用。音訊(輸入或輸出)轉錄。僅當此 Part 包含音訊資料時才會設定。
**text**: required `string` 此音訊片段的轉錄文字。 **speakerLabel**: `string` 選用。標示此音訊片段說話者的標籤(例如 "spk_1"、"spk_2")。在設定 diarization 時出現。**words**: `WordInfo array` 選用。詳細的單字層級轉錄與時間資訊。在設定 word_timestamp 時出現。
**word**: required `string` 單字的轉錄。 **startOffset**: `string` 選用。單字相對於音訊開頭的開始時間偏移。 **endOffset**: `string` 選用。單字相對於音訊開頭的結束時間偏移。**speechMetadata**: `SpeechMetadata` 選用。套用至文字部分的中繼資料,用來客製化其朗讀或合成方式,例如指定說話者身分或說話風格。
**speaker**: `string` 選用。多說話者合成的選用說話者名稱。 **style**: `string` 選用。語音合成的選用風格指令。**groundingMetadata**: `GroundingMetadata` 僅供輸出。候選的接地中繼資料。此欄位會為 `GenerateContent` 呼叫填入。
**searchEntryPoint**: `SearchEntryPoint` 選用。後續網路搜尋的 Google 搜尋入口。
**renderedContent**: `string` 選用。可以內嵌在網頁或應用程式 webview 中的網路內容片段。 **sdkBlob**: `string` 選用。代表 tuple 陣列的 Base64 編碼 JSON。**groundingChunks**: `GroundingChunk array` 從指定接地來源檢索到的支援參照清單。串流時,這只包含尚未包含在先前回應接地中繼資料中的接地區塊。
**chunkType**: `Union type` 區塊類型。
聯集欄位 `chunkType` 只能是下列其中之一:**web**: `Web` 來自網路的接地區塊。
**uri**: `string` 僅供輸出。區塊的 URI 參照。 **title**: `string` 僅供輸出。區塊的標題。**image**: `Image` 選用。來自圖片搜尋的接地區塊。
**sourceUri**: `string` 用於歸因的網頁 URI。 **imageUri**: `string` 圖片素材 URL。 **title**: `string` 圖片來源網頁的標題。 **domain**: `string` 圖片來源網頁的根網域,例如 "example.com"。**retrievedContext**: `RetrievedContext` 選用。來自檔案搜尋工具檢索到的上下文的接地區塊。
**uri**: `string` 選用。語意檢索文件的 URI 參照。 **title**: `string` 選用。文件的標題。 **text**: `string` 選用。區塊的文字。 **fileSearchStore**: `string` 選用。包含文件的 `FileSearchStore` 名稱。範例:`fileSearchStores/123`**customMetadata**: `GroundingChunkCustomMetadata array` 選用。使用者提供的、關於檢索到的上下文的中繼資料。
**value**: `Union type` 中繼資料的值。可以是字串、字串清單或數字。
聯集欄位 `value` 只能是下列其中之一: **stringValue**: `string` 選用。中繼資料的字串值。**stringListValue**: `GroundingChunkStringList` 選用。中繼資料的字串值清單。
**values**: `string array` 清單的字串值。**maps**: `Maps` 選用。來自 Google 地圖的接地區塊。
**uri**: `string` 地點的 URI 參照。 **title**: `string` 地點的標題。 **text**: `string` 地點答案的文字說明。 **placeId**: `string` 地點的 ID,格式為 `places/{place_id}`。使用者可以使用此 ID 查詢該地點。**placeAnswerSources**: `PlaceAnswerSources` 提供關於 Google 地圖中指定地點特徵答案的來源。
**reviewSnippets**: `ReviewSnippet array` 用來生成關於 Google 地圖中指定地點特徵答案的評論片段。
**reviewId**: `string` 評論片段的 ID。 **googleMapsUri**: `string` 對應至 Google 地圖上使用者評論的連結。 **title**: `string` 評論的標題。**groundingSupports**: `GoogleAiGenerativelanguageV1betaGroundingSupport array` 接地支援清單。
**segment**: `GoogleAiGenerativelanguageV1betaSegment` 此支援所屬內容的片段。
**partIndex**: `integer` Part 物件在其父 Content 物件內的索引。 **startIndex**: `integer` 指定 Part 中的開始索引,以位元組為單位測量。從 Part 的開頭起算(含),從零開始。 **endIndex**: `integer` 指定 Part 中的結束索引,以位元組為單位測量。從 Part 的開頭起算(不含),從零開始。 **text**: `string` 與回應片段相對應的文字。**retrievalMetadata**: `RetrievalMetadata` 與接地流程中檢索相關的中繼資料。
**googleSearchDynamicRetrievalScore**: `number` 選用。表示 Google 搜尋資訊能協助回答提示詞的可能性分數。分數範圍為 [0, 1],其中 0 表示可能性最低,1 表示可能性最高。此分數僅在啟用 Google 搜尋接地與動態檢索時才會填入。它將與閾值比較,以決定是否觸發 Google 搜尋。**logprobsResult**: `LogprobsResult` 僅供輸出。回應權杖與頂尖權杖的對數概似分數
**logProbabilitySum**: `number` 所有權杖的對數機率總和。**topCandidates**: `TopCandidates array` 長度 = 解碼步驟的總數。
**candidates**: `LogprobsResultCandidate array` 依對數機率降冪排序。
**token**: `string` 候選的權杖字串值。 **tokenId**: `integer` 候選的權杖 id 值。 **logProbability**: `number` 候選的對數機率。**chosenCandidates**: `LogprobsResultCandidate array` 長度 = 解碼步驟的總數。所選候選可能會、也可能不會出現在 top_candidates 中。
**token**: `string` 候選的權杖字串值。 **tokenId**: `integer` 候選的權杖 id 值。 **logProbability**: `number` 候選的對數機率。**urlContextMetadata**: `UrlContextMetadata` 僅供輸出。與 url 上下文檢索工具相關的中繼資料。
**urlMetadata**: `UrlMetadata array` url 上下文清單。
**retrievedUrl**: `string` 工具檢索到的 url。**urlRetrievalStatus**: `string enum` url 檢索的狀態。
可能的值: - `URL_RETRIEVAL_STATUS_UNSPECIFIED`: 預設值。此值未使用。 - `URL_RETRIEVAL_STATUS_SUCCESS`: Url 檢索成功。 - `URL_RETRIEVAL_STATUS_ERROR`: Url 檢索因錯誤而失敗。 - `URL_RETRIEVAL_STATUS_PAYWALL`: Url 檢索因內容位於付費牆後而失敗。 - `URL_RETRIEVAL_STATUS_UNSAFE`: Url 檢索因內容不安全而失敗。**promptFeedback**: `PromptFeedback` 傳回提示詞與內容篩選器相關的回饋。
**blockReason**: `string enum` 選用。若有設定,提示詞已被封鎖,且不會傳回任何候選。請重新措辭提示詞。
可能的值: - `BLOCK_REASON_UNSPECIFIED`: 預設值。此值未使用。 - `SAFETY`: 提示詞因安全原因被封鎖。請檢查 `safety_ratings` 以了解哪個安全類別封鎖了它。 - `OTHER`: 提示詞因未知原因被封鎖。 - `BLOCKLIST`: 提示詞因包含術語封鎖清單中的詞彙而被封鎖。 - `PROHIBITED_CONTENT`: 提示詞因禁止內容而被封鎖。 - `IMAGE_SAFETY`: 候選因不安全的圖片生成內容而被封鎖。**safetyRatings**: `SafetyRating array` 提示詞的安全性評級。每個類別最多有一個評級。
**category**: required `HarmCategory` 此評級的類別。
可能的值: - `HARM_CATEGORY_UNSPECIFIED`: 類別未指定。 - `HARM_CATEGORY_HARASSMENT`: **Gemini** - 騷擾內容。 - `HARM_CATEGORY_HATE_SPEECH`: **Gemini** - 仇恨言論與內容。 - `HARM_CATEGORY_SEXUALLY_EXPLICIT`: **Gemini** - 性露骨內容。 - `HARM_CATEGORY_DANGEROUS_CONTENT`: **Gemini** - 危險內容。 - `HARM_CATEGORY_JAILBREAK`: **Gemini** - 試圖繞過或顛覆模型安全指南的提示詞(越獄嘗試)。**probability**: required `string enum` 此內容的危害機率。
可能的值: - `HARM_PROBABILITY_UNSPECIFIED`: 機率未指定。 - `NEGLIGIBLE`: 內容不安全的可能性微乎其微。 - `LOW`: 內容不安全的可能性低。 - `MEDIUM`: 內容不安全的可能性中。 - `HIGH`: 內容不安全的可能性高。**usageMetadata**: `UsageMetadata` 僅供輸出。生成請求的權杖使用量中繼資料。
**promptTokenCount**: `integer` 提示詞中的權杖數量。當設定 `cached_content` 時,這仍是有效的提示詞總大小,表示這包含快取內容中的權杖數量。 **cachedContentTokenCount**: `integer` 提示詞快取部分的權杖數量(快取內容) **candidatesTokenCount**: `integer` 所有生成的回應候選的權杖總數。 **toolUsePromptTokenCount**: `integer` 僅供輸出。工具使用提示詞中存在的權杖數量。 **thoughtsTokenCount**: `integer` 僅供輸出。思考模型的思考權杖數量。 **totalTokenCount**: `integer` 生成請求的權杖總數(提示詞 + 工具使用提示詞 + 思考 + 回應候選)。**promptTokensDetails**: `ModalityTokenCount array` 僅供輸出。在請求輸入中處理的模態清單。
**modality**: `GenerativeLanguageModality` 與此權杖數量相關聯的模態。
可能的值: - `MODALITY_UNSPECIFIED`: 未指定的模態。 - `TEXT`: 純文字。 - `IMAGE`: 圖片。 - `VIDEO`: 影片。 - `AUDIO`: 音訊。 - `DOCUMENT`: 文件,例如 PDF。**cacheTokensDetails**: `ModalityTokenCount array` 僅供輸出。請求輸入中快取內容的模態清單。
**modality**: `GenerativeLanguageModality` 與此權杖數量相關聯的模態。
可能的值: - `MODALITY_UNSPECIFIED`: 未指定的模態。 - `TEXT`: 純文字。 - `IMAGE`: 圖片。 - `VIDEO`: 影片。 - `AUDIO`: 音訊。 - `DOCUMENT`: 文件,例如 PDF。**candidatesTokensDetails**: `ModalityTokenCount array` 僅供輸出。回應中傳回的模態清單。
**modality**: `GenerativeLanguageModality` 與此權杖數量相關聯的模態。
可能的值: - `MODALITY_UNSPECIFIED`: 未指定的模態。 - `TEXT`: 純文字。 - `IMAGE`: 圖片。 - `VIDEO`: 影片。 - `AUDIO`: 音訊。 - `DOCUMENT`: 文件,例如 PDF。**toolUsePromptTokensDetails**: `ModalityTokenCount array` 僅供輸出。為工具使用請求輸入處理的模態清單。
**modality**: `GenerativeLanguageModality` 與此權杖數量相關聯的模態。
可能的值: - `MODALITY_UNSPECIFIED`: 未指定的模態。 - `TEXT`: 純文字。 - `IMAGE`: 圖片。 - `VIDEO`: 影片。 - `AUDIO`: 音訊。 - `DOCUMENT`: 文件,例如 PDF。**serviceTier**: [`ServiceTier`](/api-reference/batch-api/update-generate-content-batch/#Resource:ServiceTier) 僅供輸出。請求的服務層級。
可能的值: - `unspecified`: 預設服務層級,即標準。 - `standard`: 標準服務層級。 - `flex`: Flex 服務層級。 - `priority`: Priority 服務層級。**modelStatus**: `ModelStatus` 僅供輸出。此模型目前的模型狀態。
**modelStage**: `ModelStage` 底層模型的階段。
可能的值: - `MODEL_STAGE_UNSPECIFIED`: 未指定的模型階段。 - `EXPERIMENTAL`: 此階段的模型僅供實驗用途。 - `PREVIEW`: 此階段的模型比實驗模型更成熟。 - `STABLE`: 此階段的模型被視為穩定,可用於生產環境。 - `LEGACY`: 若模型處於此階段,表示該模型在不久的將來將走上淘汰之路。只有現有客戶可以使用此模型。 - `RETIRED`: 此階段的模型已退役。這些模型無法使用。createTime: string
僅供輸出。批次建立的時間。
endTime: string
僅供輸出。批次處理完成的時間。
updateTime: string
僅供輸出。批次上次更新的時間。
**batchStats**: `BatchStats` 僅供輸出。關於批次的統計資料。
**requestCount**: `string` 僅供輸出。批次中的請求數量。 **successfulRequestCount**: `string` 僅供輸出。成功處理的請求數量。 **failedRequestCount**: `string` 僅供輸出。處理失敗的請求數量。 **pendingRequestCount**: `string` 僅供輸出。仍在等待處理的請求數量。**state**: [`BatchState`](/api-reference/batch-api/update-generate-content-batch/#Resource:BatchState) 僅供輸出。批次的狀態。
可能的值: - `BATCH_STATE_UNSPECIFIED`: 批次狀態未指定。 - `BATCH_STATE_PENDING`: 服務正在準備執行批次。 - `BATCH_STATE_RUNNING`: 批次正在進行中。 - `BATCH_STATE_SUCCEEDED`: 批次已成功完成。 - `BATCH_STATE_FAILED`: 批次失敗。 - `BATCH_STATE_CANCELLED`: 批次已被取消。 - `BATCH_STATE_EXPIRED`: 批次已過期。priority: string
選用。批次的優先順序。優先順序值較高的批次會在優先順序值較低的批次之前處理。允許負值。預設為 0。
範例回應
{
"model": "string",
"displayName": "string",
"inputConfig": {
"fileName": "string",
"requests": {
"requests": [
{
"request": {
"model": "...",
"contents": "...",
"systemInstruction": "...",
"tools": "...",
"toolConfig": "...",
"safetySettings": "...",
"generationConfig": "...",
"cachedContent": "...",
"serviceTier": "...",
"store": "...",
"continuationToken": "...",
"labels": "..."
},
"metadata": {}
}
]
}
},
"name": "string",
"output": {
"responsesFile": "string",
"inlinedResponses": {
"inlinedResponses": [
{
"error": {
"code": "...",
"message": "...",
"details": "..."
},
"response": {
"candidates": "...",
"promptFeedback": "...",
"usageMetadata": "...",
"modelVersion": "...",
"responseId": "...",
"modelStatus": "..."
},
"metadata": {}
}
]
}
},
"createTime": "string",
"endTime": "string",
"updateTime": "string",
"batchStats": {
"requestCount": "string",
"successfulRequestCount": "string",
"failedRequestCount": "string",
"pendingRequestCount": "string"
},
"state": "BATCH_STATE_UNSPECIFIED",
"priority": "string"
}
資料模型¶
BatchState¶
可能的值:
BATCH_STATE_UNSPECIFIED: 批次狀態未指定。BATCH_STATE_PENDING: 服務正在準備執行批次。BATCH_STATE_RUNNING: 批次正在進行中。BATCH_STATE_SUCCEEDED: 批次已成功完成。BATCH_STATE_FAILED: 批次失敗。BATCH_STATE_CANCELLED: 批次已被取消。BATCH_STATE_EXPIRED: 批次已過期。
ServiceTier¶
可能的值:
unspecified: 預設服務層級,即標準。standard: 標準服務層級。flex: Flex 服務層級。priority: Priority 服務層級。