Gemini Interactions API 是實驗性 API,可讓開發人員使用 Gemini 模型建構生成式 AI 應用程式。Gemini 是 Google 最強大的模型,打從設計之初就具有多模態的特質。可歸納內容,完美解讀、操作及結合語言、圖片、音訊、影片和程式碼等不同類型的資訊。您可以使用 Gemini API 處理各種用途,例如:跨文字和圖片進行推論、生成內容、對話式代理程式、摘要和分類系統等。
建立互動
建立新的互動。
要求主體
要求主體會包含結構如下的資料:
model ModelOption (選用)
用於生成互動的 `Model` 名稱。
如未提供 `agent`,則為必要。
可能的值:
-
gemini-2.5-computer-use-preview-10-2025這類模型專為直接介面互動而設計,可讓 Gemini 感知及瀏覽數位環境。
-
gemini-2.5-flash這是我們第一個混合式推論模型,支援 100 萬個詞元的脈絡窗口,並具有思考預算。
-
gemini-2.5-flash-image我們原生的圖像生成模型,經過最佳化調整,可提供快速、彈性且具備情境理解能力。文字輸入和輸出內容的價格與 2.5 Flash 相同。
-
gemini-2.5-flash-lite這是我們最小巧且最具成本效益的模型,專為大規模使用而打造。
-
gemini-2.5-flash-lite-preview-09-2025這款最新模型以 Gemini 2.5 Flash Lite 為基礎,經過最佳化處理,成本效益高、高處理量且品質優異。
-
gemini-2.5-flash-native-audio-preview-12-2025我們的原生語音模型經過最佳化調整,可以輸出更優質的音訊,在節奏、語音自然程度、詳細程度和情緒方面都更為出色。
-
gemini-2.5-flash-preview-09-2025以 2.5 Flash 模型為基礎的最新模型。2.5 Flash 搶先版最適合用於大規模處理、低延遲、需要思考的大量工作,以及代理程式應用情境。
-
gemini-2.5-flash-preview-tts我們的 2.5 Flash 文字轉語音模型經過最佳化,可生成功能強大、延遲時間短且可控制的語音。
-
gemini-2.5-proGoogle 最先進的多功能模型,擅長程式設計和複雜的推論工作。
-
gemini-2.5-pro-preview-tts我們的 2.5 Pro 文字轉語音音訊模型經過最佳化調整,可生成強大且低延遲的語音,輸出更自然的內容,並輕鬆引導提示。
-
gemini-3-flash-preview這是 Google 最聰明的模型,專為快速處理任務而打造,結合了前沿智慧、卓越的搜尋和基礎功能。
-
gemini-3-pro-image-preview最先進的圖像生成及編輯模型。
-
gemini-3-pro-preview這是 Google 最聰明的模型,具備最先進的推論和多模態理解能力,以及強大的代理功能和直覺式程式開發功能。
-
gemini-3.1-pro-preview我們最新的 SOTA 推論模型,具備前所未有的深度和細微差異,以及強大的多模態理解和程式設計能力。
-
gemini-3.1-flash-image-preview具備專業級視覺智慧,效率極高,且能生成貼近現實的內容。
-
gemini-3.1-flash-lite-previewGoogle 最經濟實惠的模型,適用於需要處理大量要求的代理工作、翻譯和簡單的資料處理作業。
-
gemini-3.1-flash-tts-previewGemini 3.1 Flash TTS:功能強大,延遲時間短的語音生成模型。享受自然輸出、可導向的提示,以及用於精確旁白控制的新表情音訊標記。
-
lyria-3-clip-preview這款低延遲音樂生成模型經過最佳化調整,可生成高傳真音訊片段,並精準控制節奏。
-
lyria-3-pro-preview這款進階模型可生成完整歌曲,深入瞭解作曲結構,並經過最佳化調整,可精確控制結構,並在不同音樂風格之間進行複雜的轉場。
agent AgentOption (optional)
用於生成互動的 `Agent` 名稱。
如未提供 `model`,則為必要。
可能的值:
-
deep-research-pro-preview-12-2025Gemini Deep Research 代理程式
-
deep-research-preview-04-2026Gemini Deep Research 代理程式
-
deep-research-max-preview-04-2026Gemini Deep Research Max 代理程式
互動的系統指令。
模型在互動期間可能會呼叫的工具宣告清單。
強制生成的 JSON 物件回覆必須符合這個欄位中指定的 JSON 結構定義。
回應的 MIME 類型。如果已設定 response_format,就必須提供這個屬性。
僅限輸入。互動是否會串流。
僅限輸入。是否要儲存回覆和要求,以供日後擷取。
僅限輸入。是否要在背景執行模型互動。
generation_config GenerationConfig (optional)
模型設定
模型互動的設定參數。
`agent_config` 的替代方案。僅適用於設定 `model` 時。
欄位
控制輸出內容的隨機程度。
取樣時要考慮的符記累計機率上限。
用於解碼的種子,確保可重現結果。
會停止輸出互動的字元序列清單。
thinking_level ThinkingLevel (optional)
模型應生成的思考權杖數量。
可能的值:
-
minimal -
low -
medium -
high
thinking_summaries ThinkingSummaries (選用)
是否要在回覆中加入想法摘要。
可能的值:
-
auto -
none
回覆中可包含的詞元數量上限。
speech_config SpeechConfig (optional)
語音互動設定。
欄位
說話者的聲音。
語音的語言。
說話者姓名,應與提示中提供的說話者姓名相符。
image_config ImageConfig (optional)
圖片互動設定。
欄位
未提供說明。
可能的值:
-
1:1 -
2:3 -
3:2 -
3:4 -
4:3 -
4:5 -
5:4 -
9:16 -
16:9 -
21:9 -
1:8 -
8:1 -
1:4 -
4:1
未提供說明。
可能的值:
-
1K -
2K -
4K -
512
工具選擇設定。
agent_config object (optional)
代理程式設定
代理程式設定。
`generation_config` 的替代方案。僅適用於設定 `agent` 時。
可能類型
多型鑑別器:type
DynamicAgentConfig
動態代理程式的設定。
未提供說明。
一律設為 "dynamic"。
DeepResearchAgentConfig
Deep Research 代理的設定。
未提供說明。
一律設為 "deep-research"。
thinking_summaries ThinkingSummaries (選用)
是否要在回覆中加入想法摘要。
可能的值:
-
auto -
none
是否要在回覆中加入視覺化內容。
可能的值:
-
off -
auto
為 Deep Research 代理啟用人機迴圈規劃。如果設為 true,Deep Research 代理會在回覆中提供研究計畫。使用者在下一個回合確認方案後,代理程式才會繼續。
先前的互動 ID (如有)。
response_modalities ResponseModality (optional)
要求的回覆模態 (TEXT、IMAGE、AUDIO)。
可能的值:
-
text -
image -
audio -
video -
document
互動的服務層級。
可能的值:
-
flex -
standard -
priority
回應
傳回 Interaction 資源。
簡單要求
回應範例
{ "created": "2025-11-26T12:25:15Z", "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg", "model": "gemini-3-flash-preview", "object": "interaction", "outputs": [ { "text": "Hello! I'm functioning perfectly and ready to assist you.\n\nHow are you doing today?", "type": "text" } ], "role": "model", "status": "completed", "updated": "2025-11-26T12:25:15Z", "usage": { "input_tokens_by_modality": [ { "modality": "text", "tokens": 7 } ], "total_cached_tokens": 0, "total_input_tokens": 7, "total_output_tokens": 20, "total_thought_tokens": 22, "total_tokens": 49, "total_tool_use_tokens": 0 } }
多輪
回應範例
{ "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg", "model": "gemini-3-flash-preview", "status": "completed", "object": "interaction", "created": "2025-11-26T12:22:47Z", "updated": "2025-11-26T12:22:47Z", "role": "model", "outputs": [ { "type": "text", "text": "The capital of France is Paris." } ], "usage": { "input_tokens_by_modality": [ { "modality": "text", "tokens": 50 } ], "total_cached_tokens": 0, "total_input_tokens": 50, "total_output_tokens": 10, "total_thought_tokens": 0, "total_tokens": 60, "total_tool_use_tokens": 0 } }
輸入圖片
回應範例
{ "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg", "model": "gemini-3-flash-preview", "status": "completed", "object": "interaction", "created": "2025-11-26T12:22:47Z", "updated": "2025-11-26T12:22:47Z", "role": "model", "outputs": [ { "type": "text", "text": "A white humanoid robot with glowing blue eyes stands holding a red skateboard." } ], "usage": { "input_tokens_by_modality": [ { "modality": "text", "tokens": 10 }, { "modality": "image", "tokens": 258 } ], "total_cached_tokens": 0, "total_input_tokens": 268, "total_output_tokens": 20, "total_thought_tokens": 0, "total_tokens": 288, "total_tool_use_tokens": 0 } }
函式呼叫
回應範例
{ "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg", "model": "gemini-3-flash-preview", "status": "requires_action", "object": "interaction", "created": "2025-11-26T12:22:47Z", "updated": "2025-11-26T12:22:47Z", "role": "model", "outputs": [ { "type": "function_call", "id": "gth23981", "name": "get_weather", "arguments": { "location": "Boston, MA" } } ], "usage": { "input_tokens_by_modality": [ { "modality": "text", "tokens": 100 } ], "total_cached_tokens": 0, "total_input_tokens": 100, "total_output_tokens": 25, "total_thought_tokens": 0, "total_tokens": 125, "total_tool_use_tokens": 50 } }
Deep Research
回應範例
{ "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg", "agent": "deep-research-pro-preview-12-2025", "status": "completed", "object": "interaction", "created": "2025-11-26T12:22:47Z", "updated": "2025-11-26T12:22:47Z", "role": "agent", "outputs": [ { "type": "text", "text": "Here is a comprehensive research report on the current state of cancer research..." } ], "usage": { "input_tokens_by_modality": [ { "modality": "text", "tokens": 20 } ], "total_cached_tokens": 0, "total_input_tokens": 20, "total_output_tokens": 1000, "total_thought_tokens": 500, "total_tokens": 1520, "total_tool_use_tokens": 0 } }
擷取互動
根據 `Interaction.id` 擷取單一互動的完整詳細資料。
路徑 / 查詢參數
要擷取的互動專屬 ID。
如果設為 True,系統會以串流方式逐步提供生成的內容。
預設值:False
(選用步驟) 如果已設定,則從事件 ID 標示的事件後,繼續互動串流的下一個區塊。只有在 `stream` 為 true 時才能使用。
如果設為 true,回應會包含輸入內容。
預設值:False
要使用的 API 版本。
回應
傳回 Interaction 資源。
取得互動
回應範例
{ "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg", "model": "gemini-3-flash-preview", "status": "completed", "object": "interaction", "created": "2025-11-26T12:25:15Z", "updated": "2025-11-26T12:25:15Z", "role": "model", "outputs": [ { "type": "text", "text": "I'm doing great, thank you for asking! How can I help you today?" } ] }
刪除互動
依 ID 刪除互動。
路徑 / 查詢參數
要刪除的互動專屬 ID。
要使用的 API 版本。
回應
如果成功,回應會留白。
刪除互動
取消互動
依 ID 取消互動。這項設定只適用於仍在執行的背景互動。
路徑 / 查詢參數
要取消的互動專屬 ID。
要使用的 API 版本。
回應
傳回 Interaction 資源。
取消互動
回應範例
{ "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg", "agent": "deep-research-pro-preview-12-2025", "status": "cancelled", "object": "interaction", "created": "2025-11-26T12:25:15Z", "updated": "2025-11-26T12:25:15Z", "role": "agent" }
資源
互動
Interaction 資源。
欄位
model ModelOption (選用)
用於生成互動的 `Model` 名稱。
可能的值:
-
gemini-2.5-computer-use-preview-10-2025這類模型專為直接介面互動而設計,可讓 Gemini 感知及瀏覽數位環境。
-
gemini-2.5-flash這是我們第一個混合式推論模型,支援 100 萬個詞元的脈絡窗口,並具有思考預算。
-
gemini-2.5-flash-image我們原生的圖像生成模型,經過最佳化調整,可提供快速、彈性且具備情境理解能力。文字輸入和輸出內容的價格與 2.5 Flash 相同。
-
gemini-2.5-flash-lite這是我們最小巧且最具成本效益的模型,專為大規模使用而打造。
-
gemini-2.5-flash-lite-preview-09-2025這款最新模型以 Gemini 2.5 Flash Lite 為基礎,經過最佳化處理,成本效益高、高處理量且品質優異。
-
gemini-2.5-flash-native-audio-preview-12-2025我們的原生語音模型經過最佳化調整,可以輸出更優質的音訊,在節奏、語音自然程度、詳細程度和情緒方面都更為出色。
-
gemini-2.5-flash-preview-09-2025以 2.5 Flash 模型為基礎的最新模型。2.5 Flash 搶先版最適合用於大規模處理、低延遲、需要思考的大量工作,以及代理程式應用情境。
-
gemini-2.5-flash-preview-tts我們的 2.5 Flash 文字轉語音模型經過最佳化,可生成功能強大、延遲時間短且可控制的語音。
-
gemini-2.5-proGoogle 最先進的多功能模型,擅長程式設計和複雜的推論工作。
-
gemini-2.5-pro-preview-tts我們的 2.5 Pro 文字轉語音音訊模型經過最佳化調整,可生成強大且低延遲的語音,輸出更自然的內容,並輕鬆引導提示。
-
gemini-3-flash-preview這是 Google 最聰明的模型,專為快速處理任務而打造,結合了前沿智慧、卓越的搜尋和基礎功能。
-
gemini-3-pro-image-preview最先進的圖像生成及編輯模型。
-
gemini-3-pro-preview這是 Google 最聰明的模型,具備最先進的推論和多模態理解能力,以及強大的代理功能和直覺式程式開發功能。
-
gemini-3.1-pro-preview我們最新的 SOTA 推論模型,具備前所未有的深度和細微差異,以及強大的多模態理解和程式設計能力。
-
gemini-3.1-flash-image-preview具備專業級視覺智慧,效率極高,且能生成貼近現實的內容。
-
gemini-3.1-flash-lite-previewGoogle 最經濟實惠的模型,適用於需要處理大量要求的代理工作、翻譯和簡單的資料處理作業。
-
gemini-3.1-flash-tts-previewGemini 3.1 Flash TTS:功能強大,延遲時間短的語音生成模型。享受自然輸出、可導向的提示,以及用於精確旁白控制的新表情音訊標記。
-
lyria-3-clip-preview這款低延遲音樂生成模型經過最佳化調整,可生成高傳真音訊片段,並精準控制節奏。
-
lyria-3-pro-preview這款進階模型可生成完整歌曲,深入瞭解作曲結構,並經過最佳化調整,可精確控制結構,並在不同音樂風格之間進行複雜的轉場。
agent AgentOption (選填)
用於生成互動的 `Agent` 名稱。
可能的值:
-
deep-research-pro-preview-12-2025Gemini Deep Research 代理程式
-
deep-research-preview-04-2026Gemini Deep Research 代理程式
-
deep-research-max-preview-04-2026Gemini Deep Research Max 代理程式
必填。僅供輸出。互動完成的專屬 ID。
必填。僅供輸出。互動狀態。
可能的值:
-
in_progress -
requires_action -
completed -
failed -
cancelled -
incomplete
必填。僅供輸出。回應的建立時間 (採用 ISO 8601 格式:YYYY-MM-DDThh:mm:ssZ)。
必填。僅供輸出。回應上次更新的時間,採用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。
僅供輸出。互動的角色。
僅供輸出。模型的回覆。
互動的系統指令。
模型在互動期間可能會呼叫的工具宣告清單。
usage Usage (選填)
僅供輸出。互動要求的權杖用量統計資料。
欄位
提示 (脈絡) 中的權杖數量。
input_tokens_by_modality ModalityTokens (optional)
依模式細分的輸入權杖用量。
欄位
modality ResponseModality (optional)
與權杖數相關聯的模態。
可能的值:
-
text -
image -
audio -
video -
document
模態的權杖數量。
提示快取部分的權杖數量 (快取內容)。
cached_tokens_by_modality ModalityTokens (optional)
依模式細分快取權杖用量。
欄位
modality ResponseModality (optional)
與權杖數相關聯的模態。
可能的值:
-
text -
image -
audio -
video -
document
模態的權杖數量。
所有生成回覆的詞元總數。
output_tokens_by_modality ModalityTokens (選用)
依模式細分的輸出權杖用量。
欄位
modality ResponseModality (optional)
與權杖數相關聯的模態。
可能的值:
-
text -
image -
audio -
video -
document
模態的權杖數量。
工具使用提示中的權杖數量。
tool_use_tokens_by_modality ModalityTokens (選用)
依模式細分工具使用權杖用量。
欄位
modality ResponseModality (optional)
與權杖數相關聯的模態。
可能的值:
-
text -
image -
audio -
video -
document
模態的權杖數量。
思考型模型思考時使用的權杖數。
互動要求的權杖總數 (提示 + 回覆 + 其他內部權杖)。
response_modalities ResponseModality (optional)
要求的回覆模態 (TEXT、IMAGE、AUDIO)。
可能的值:
-
text -
image -
audio -
video -
document
強制生成的 JSON 物件回覆必須符合這個欄位中指定的 JSON 結構定義。
回應的 MIME 類型。如果已設定 response_format,就必須提供這個屬性。
先前的互動 ID (如有)。
互動的服務層級。
可能的值:
-
flex -
standard -
priority
agent_config object (optional)
代理程式互動的設定參數。
可能類型
多型鑑別器:type
DynamicAgentConfig
動態代理程式的設定。
未提供說明。
一律設為 "dynamic"。
DeepResearchAgentConfig
Deep Research 代理的設定。
未提供說明。
一律設為 "deep-research"。
thinking_summaries ThinkingSummaries (選用)
是否要在回覆中加入想法摘要。
可能的值:
-
auto -
none
是否要在回覆中加入視覺化內容。
可能的值:
-
off -
auto
為 Deep Research 代理啟用人機迴圈規劃。如果設為 true,Deep Research 代理會在回覆中提供研究計畫。使用者在下一個回合確認方案後,代理程式才會繼續。
範例
範例
{ "created": "2025-12-04T15:01:45Z", "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg", "model": "gemini-3-flash-preview", "object": "interaction", "outputs": [ { "text": "Hello! I'm doing well, functioning as expected. Thank you for asking! How are you doing today?", "type": "text" } ], "role": "model", "status": "completed", "updated": "2025-12-04T15:01:45Z", "usage": { "input_tokens_by_modality": [ { "modality": "text", "tokens": 7 } ], "total_cached_tokens": 0, "total_input_tokens": 7, "total_output_tokens": 23, "total_thought_tokens": 49, "total_tokens": 79, "total_tool_use_tokens": 0 } }
資料模型
內容
回覆內容。
可能類型
多型鑑別器:type
TextContent
文字內容區塊。
未提供說明。
一律設為 "text"。
必填。文字內容。
annotations Annotation (optional)
模型生成內容的引用資訊。
可能類型
多型鑑別器:type
UrlCitation
網址引用註解。
未提供說明。
一律設為 "url_citation"。
網址。
網址的標題。
歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭,以位元組為單位。
歸因區隔的結束時間 (不含)。
FileCitation
檔案引用註解。
未提供說明。
一律設為 "file_citation"。
檔案的 URI。
檔案名稱。
歸因於部分文字的來源。
歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭,以位元組為單位。
歸因區隔的結束時間 (不含)。
PlaceCitation
地點引用註解。
未提供說明。
一律設為 "place_citation"。
地點 ID,格式為 `places/{place_id}`。
地點名稱。
地點的 URI 參照。
review_snippets ReviewSnippet (optional)
評論片段,用於生成 Google 地圖中特定地點功能相關的答案。
欄位
評論標題。
與 Google 地圖上的使用者評論相應的連結。
評論摘錄的 ID。
歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭,以位元組為單位。
歸因區隔的結束時間 (不含)。
ImageContent
圖片內容區塊。
未提供說明。
一律設為 "image"。
圖片內容。
圖片的 URI。
圖片的 MIME 類型。
可能的值:
-
image/png -
image/jpeg -
image/webp -
image/heic -
image/heif -
image/gif -
image/bmp -
image/tiff
resolution MediaResolution (optional)
媒體的解析度。
可能的值:
-
low -
medium -
high -
ultra_high
AudioContent
音訊內容區塊。
未提供說明。
一律設為 "audio"。
音訊內容。
音訊的 URI。
音訊的 MIME 類型。
可能的值:
-
audio/wav -
audio/mp3 -
audio/aiff -
audio/aac -
audio/ogg -
audio/flac -
audio/mpeg -
audio/m4a -
audio/l16 -
audio/opus -
audio/alaw -
audio/mulaw
音訊取樣率。
音訊聲道數。
DocumentContent
文件內容區塊。
未提供說明。
一律設為 "document"。
文件內容。
文件的 URI。
文件的 MIME 類型。
可能的值:
-
application/pdf
VideoContent
影片內容區塊。
未提供說明。
一律設為 "video"。
影片內容。
影片的 URI。
影片的 MIME 類型。
可能的值:
-
video/mp4 -
video/mpeg -
video/mpg -
video/mov -
video/avi -
video/x-flv -
video/webm -
video/wmv -
video/3gpp
resolution MediaResolution (optional)
媒體的解析度。
可能的值:
-
low -
medium -
high -
ultra_high
ThoughtContent
想法內容區塊。
未提供說明。
一律設為 "thought"。
與要納入生成作業的後端來源相符的簽章。
summary ThoughtSummaryContent (選填)
想法摘要。
可能類型
多型鑑別器:type
TextContent
文字內容區塊。
未提供說明。
一律設為 "text"。
必填。文字內容。
annotations Annotation (optional)
模型生成內容的引用資訊。
可能類型
多型鑑別器:type
UrlCitation
網址引用註解。
未提供說明。
一律設為 "url_citation"。
網址。
網址的標題。
歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭,以位元組為單位。
歸因區隔的結束時間 (不含)。
FileCitation
檔案引用註解。
未提供說明。
一律設為 "file_citation"。
檔案的 URI。
檔案名稱。
歸因於部分文字的來源。
歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭,以位元組為單位。
歸因區隔的結束時間 (不含)。
PlaceCitation
地點引用註解。
未提供說明。
一律設為 "place_citation"。
地點 ID,格式為 `places/{place_id}`。
地點名稱。
地點的 URI 參照。
review_snippets ReviewSnippet (optional)
評論片段,用於生成 Google 地圖中特定地點功能相關的答案。
欄位
評論標題。
與 Google 地圖上的使用者評論相應的連結。
評論摘錄的 ID。
歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭,以位元組為單位。
歸因區隔的結束時間 (不含)。
ImageContent
圖片內容區塊。
未提供說明。
一律設為 "image"。
圖片內容。
圖片的 URI。
圖片的 MIME 類型。
可能的值:
-
image/png -
image/jpeg -
image/webp -
image/heic -
image/heif -
image/gif -
image/bmp -
image/tiff
resolution MediaResolution (optional)
媒體的解析度。
可能的值:
-
low -
medium -
high -
ultra_high
FunctionCallContent
函式工具呼叫內容區塊。
未提供說明。
一律設為 "function_call"。
必填。要呼叫的工具名稱。
必填。要傳遞至函式的引數。
必填。這個特定工具呼叫的專屬 ID。
用於後端驗證的簽章雜湊。
CodeExecutionCallContent
程式碼執行內容。
未提供說明。
一律設為 "code_execution_call"。
arguments CodeExecutionCallArguments (必要)
必填。要傳遞至程式碼執行的引數。
欄位
`code` 的程式設計語言。
可能的值:
-
python
要執行的程式碼。
必填。這個特定工具呼叫的專屬 ID。
用於後端驗證的簽章雜湊。
UrlContextCallContent
網址背景資訊內容。
未提供說明。
一律設為 "url_context_call"。
arguments UrlContextCallArguments (必要)
必填。要傳遞至網址環境的引數。
欄位
要擷取的網址。
必填。這個特定工具呼叫的專屬 ID。
用於後端驗證的簽章雜湊。
McpServerToolCallContent
MCPServer 工具呼叫內容。
未提供說明。
一律設為 "mcp_server_tool_call"。
必填。所呼叫工具的名稱。
必填。所用 MCP 伺服器的名稱。
必填。函式引數的 JSON 物件。
必填。這個特定工具呼叫的專屬 ID。
用於後端驗證的簽章雜湊。
GoogleSearchCallContent
Google 搜尋內容。
未提供說明。
一律設為 "google_search_call"。
arguments GoogleSearchCallArguments (必要)
必填。要傳遞給 Google 搜尋的引數。
欄位
用於後續網頁搜尋的網頁搜尋查詢。
已啟用的搜尋基準建立功能類型。
可能的值:
-
web_search -
image_search -
enterprise_web_search
必填。這個特定工具呼叫的專屬 ID。
用於後端驗證的簽章雜湊。
FileSearchCallContent
檔案搜尋內容。
未提供說明。
一律設為 "file_search_call"。
必填。這個特定工具呼叫的專屬 ID。
用於後端驗證的簽章雜湊。
GoogleMapsCallContent
Google 地圖內容。
未提供說明。
一律設為 "google_maps_call"。
arguments GoogleMapsCallArguments (optional)
要傳遞至 Google 地圖工具的引數。
欄位
要執行的查詢。
必填。這個特定工具呼叫的專屬 ID。
用於後端驗證的簽章雜湊。
FunctionResultContent
函式工具結果內容區塊。
未提供說明。
一律設為 "function_result"。
所呼叫工具的名稱。
工具呼叫是否發生錯誤。
必填。ID,與函式呼叫區塊中的 ID 相符。
用於後端驗證的簽章雜湊。
工具呼叫的結果。
CodeExecutionResultContent
程式碼執行結果內容。
未提供說明。
一律設為 "code_execution_result"。
必填。程式碼執行作業的輸出內容。
程式碼執行是否發生錯誤。
必填。ID,與函式呼叫區塊中的 ID 相符。
用於後端驗證的簽章雜湊。
UrlContextResultContent
網址背景資訊結果內容。
未提供說明。
一律設為 "url_context_result"。
result UrlContextResult (必要)
必填。網址環境的結果。
欄位
擷取的網址。
網址擷取狀態。
可能的值:
-
success -
error -
paywall -
unsafe
網址脈絡是否發生錯誤。
必填。ID,與函式呼叫區塊中的 ID 相符。
用於後端驗證的簽章雜湊。
GoogleSearchResultContent
Google 搜尋結果內容。
未提供說明。
一律設為 "google_search_result"。
result GoogleSearchResult (必要)
必填。Google 搜尋結果。
欄位
可嵌入網頁或應用程式 WebView 的網頁內容程式碼片段。
Google 搜尋是否發生錯誤。
必填。ID,與函式呼叫區塊中的 ID 相符。
用於後端驗證的簽章雜湊。
McpServerToolResultContent
MCPServer 工具結果內容。
未提供說明。
一律設為 "mcp_server_tool_result"。
針對這項特定工具呼叫所呼叫的工具名稱。
所用 MCP 伺服器的名稱。
必填。ID,與函式呼叫區塊中的 ID 相符。
用於後端驗證的簽章雜湊。
MCP 伺服器呼叫的輸出內容。可以是簡單文字或多媒體內容。
FileSearchResultContent
檔案搜尋結果內容。
未提供說明。
一律設為 "file_search_result"。
result FileSearchResult (必要)
必填。檔案搜尋結果。
欄位
使用者提供的 FileSearchResult 中繼資料。
必填。ID,與函式呼叫區塊中的 ID 相符。
用於後端驗證的簽章雜湊。
GoogleMapsResultContent
Google 地圖結果內容。
未提供說明。
一律設為 "google_maps_result"。
result GoogleMapsResult (必要)
必填。Google 地圖的搜尋結果。
欄位
地點 地點 (選填)
找到的地點。
欄位
地點 ID,格式為 `places/{place_id}`。
地點名稱。
地點的 URI 參照。
review_snippets ReviewSnippet (optional)
評論片段,用於生成 Google 地圖中特定地點功能相關的答案。
欄位
評論標題。
與 Google 地圖上的使用者評論相應的連結。
評論摘錄的 ID。
Google 地圖小工具情境權杖的資源名稱。
必填。ID,與函式呼叫區塊中的 ID 相符。
用於後端驗證的簽章雜湊。
範例
文字
{ "type": "text", "text": "Hello, how are you?" }
圖片
{ "type": "image", "data": "BASE64_ENCODED_IMAGE", "mime_type": "image/png" }
音訊
{ "type": "audio", "data": "BASE64_ENCODED_AUDIO", "mime_type": "audio/wav" }
文件
{ "type": "document", "data": "BASE64_ENCODED_DOCUMENT", "mime_type": "application/pdf" }
影片
{ "type": "video", "uri": "https://www.youtube.com/watch?v=9hE5-98ZeCg" }
思路
{ "type": "thought", "summary": [ { "type": "text", "text": "The user is asking about the weather. I should use the get_weather tool." } ], "signature": "CoMDAXLI2nynRYojJIy6B1Jh9os2crpWLfB0+19xcLsGG46bd8wjkF/6RNlRUdvHrXyjsHkG0BZFcuO/bPOyA6Xh5jANNgx82wPHjGExN8A4ZQn56FlMwyZoqFVQz0QyY1lfibFJ2zU3J87uw26OewzcuVX0KEcs+GIsZa3EA6WwqhbsOd3wtZB3Ua2Qf98VAWZTS5y/tWpql7jnU3/CU7pouxQr/Bwft3hwnJNesQ9/dDJTuaQ8Zprh9VRWf1aFFjpIueOjBRrlT3oW6/y/eRl/Gt9BQXCYTqg/38vHFUU4Wo/d9dUpvfCe/a3o97t2Jgxp34oFKcsVb4S5WJrykIkw+14DzVnTpCpbQNFckqvFLuqnJCkL0EQFtunBXI03FJpPu3T1XU6id8S7ojoJQZSauGUCgmaLqUGdMrd08oo81ecoJSLs51Re9N/lISGmjWFPGpqJLoGq6uo4FHz58hmeyXCgHG742BHz2P3MiH1CXHUT2J8mF6zLhf3SR9Qb3lkrobAh" }
函式呼叫
{ "type": "function_call", "name": "get_weather", "id": "gth23981", "arguments": { "location": "Boston, MA" } }
程式碼執行呼叫
{ "type": "code_execution_call", "id": "call_123456", "arguments": { "language": "python", "code": "print('hello world')" } }
網址背景資訊呼叫
{ "type": "url_context_call", "id": "call_123456", "arguments": { "urls": [ "https://www.example.com" ] } }
MCP 伺服器工具呼叫
{ "type": "mcp_server_tool_call", "id": "call_123456", "name": "get_forecast", "server_name": "weather_server", "arguments": { "city": "London" } }
Google 搜尋電話
{ "type": "google_search_call", "id": "call_123456", "arguments": { "queries": [ "weather in Boston" ] } }
檔案搜尋呼叫
{ "type": "file_search_call", "id": "call_123456" }
Google 地圖通話
{ "type": "google_maps_call", "id": "call_123456", "arguments": { "query": "best food near me" } }
函式結果
{ "type": "function_result", "name": "get_weather", "call_id": "gth23981", "result": [ { "type": "text", "text": "{\"weather\":\"sunny\"}" } ] }
程式碼執行結果
{ "type": "code_execution_result", "call_id": "call_123456", "result": "hello world" }
網址背景資訊結果
{ "type": "url_context_result", "call_id": "call_123456", "result": [ { "url": "https://www.example.com", "status": "SUCCESS" } ] }
Google 搜尋結果
{ "type": "google_search_result", "call_id": "call_123456", "result": [ { "url": "https://www.google.com/search?q=weather+in+Boston", "title": "Weather in Boston" } ] }
MCP 伺服器工具結果
{ "type": "mcp_server_tool_result", "name": "get_forecast", "server_name": "weather_server", "call_id": "call_123456", "result": "sunny" }
檔案搜尋結果
{ "type": "file_search_result", "call_id": "call_123456", "result": [ { "text": "search result chunk", "file_search_store": "file_search_store" } ] }
Google 地圖結果
{ "type": "google_maps_result", "call_id": "call_123456", "result": [ { "places": [ { "url": "https://www.google.com/maps/search/best+food+near+me", "name": "Tasty Restaurant" } ] } ] }
工具
模型可使用的工具。
可能類型
多型鑑別器:type
功能
模型可使用的工具。
未提供說明。
一律設為 "function"。
函式名稱。
函式說明。
函式參數的 JSON 結構定義。
CodeExecution
模型可用來執行程式碼的工具。
未提供說明。
一律設為 "code_execution"。
UrlContext
模型可用來擷取網址內容的工具。
未提供說明。
一律設為 "url_context"。
ComputerUse
模型可用來與電腦互動的工具。
未提供說明。
一律設為 "computer_use"。
運作環境。
可能的值:
-
browser
從模型呼叫中排除的預先定義函式清單。
McpServer
MCPServer 是模型可呼叫的伺服器,用於執行動作。
未提供說明。
一律設為 "mcp_server"。
MCPServer 的名稱。
MCPServer 端點的完整網址。 例如:「https://api.example.com/mcp」
選用:視需要填寫驗證標頭、逾時等欄位。
allowed_tools AllowedTools (選用)
允許使用的工具。
欄位
mode ToolChoiceType (optional)
工具選擇模式。
可能的值:
-
auto -
any -
none -
validated
允許使用的工具名稱。
GoogleSearch
模型可用來搜尋 Google 的工具。
未提供說明。
一律設為 "google_search"。
要啟用的搜尋基準建立功能類型。
可能的值:
-
web_search -
image_search -
enterprise_web_search
FileSearch
模型可用來搜尋檔案的工具。
未提供說明。
一律設為 "file_search"。
要搜尋的檔案搜尋商店名稱。
要擷取的語意擷取區塊數量。
要套用至語意擷取文件和區塊的中繼資料篩選器。
GoogleMaps
模型可用來呼叫 Google 地圖的工具。
未提供說明。
一律設為 "google_maps"。
是否要在回應的工具呼叫結果中傳回小工具內容權杖。
使用者所在位置的緯度。
使用者所在位置的經度。
擷取
模型可用來擷取檔案的工具。
未提供說明。
一律設為 "retrieval"。
要啟用的檔案擷取類型。
可能的值:
-
vertex_ai_search
vertex_ai_search_config VertexAISearchConfig (optional)
用於指定 VertexAISearch 的設定。
欄位
(選用步驟) 用於指定 Vertex AI Search 引擎。
(選用步驟) 用於指定 Vertex AI Search 資料存放區。
範例
函式
CodeExecution
UrlContext
ComputerUse
McpServer
GoogleSearch
FileSearch
GoogleMaps
擷取
這個類型沒有可用的範例。
啟用或停用
範例
使用者回合
{ "role": "user", "content": [ { "type": "text", "text": "user turn" } ] }
模型回合
{ "role": "model", "content": [ { "type": "text", "text": "model turn" } ] }
InteractionSseEvent
可能類型
多型鑑別器:event_type
InteractionStartEvent
未提供說明。
一律設為 "interaction.start"。
未提供說明。
用於從這個事件繼續互動串流的 event_id 權杖。
InteractionCompleteEvent
未提供說明。
一律設為 "interaction.complete"。
必填。完成互動,但輸出內容為空白,以減少酬載大小。 使用上述 ContentDelta 事件做為實際輸出內容。
用於從這個事件繼續互動串流的 event_id 權杖。
InteractionStatusUpdate
未提供說明。
一律設為 "interaction.status_update"。
未提供說明。
未提供說明。
可能的值:
-
in_progress -
requires_action -
completed -
failed -
cancelled -
incomplete
用於從這個事件繼續互動串流的 event_id 權杖。
ContentStart
未提供說明。
一律設為 "content.start"。
未提供說明。
未提供說明。
用於從這個事件繼續互動串流的 event_id 權杖。
ContentDelta
未提供說明。
一律設為 "content.delta"。
未提供說明。
delta ContentDeltaData (required)
未提供說明。
可能類型
多型鑑別器:type
TextDelta
未提供說明。
一律設為 "text"。
未提供說明。
ImageDelta
未提供說明。
一律設為 "image"。
未提供說明。
未提供說明。
未提供說明。
可能的值:
-
image/png -
image/jpeg -
image/webp -
image/heic -
image/heif -
image/gif -
image/bmp -
image/tiff
resolution MediaResolution (optional)
媒體的解析度。
可能的值:
-
low -
medium -
high -
ultra_high
AudioDelta
未提供說明。
一律設為 "audio"。
未提供說明。
未提供說明。
未提供說明。
可能的值:
-
audio/wav -
audio/mp3 -
audio/aiff -
audio/aac -
audio/ogg -
audio/flac -
audio/mpeg -
audio/m4a -
audio/l16 -
audio/opus -
audio/alaw -
audio/mulaw
音訊取樣率。
音訊聲道數。
DocumentDelta
未提供說明。
一律設為 "document"。
未提供說明。
未提供說明。
未提供說明。
可能的值:
-
application/pdf
VideoDelta
未提供說明。
一律設為 "video"。
未提供說明。
未提供說明。
未提供說明。
可能的值:
-
video/mp4 -
video/mpeg -
video/mpg -
video/mov -
video/avi -
video/x-flv -
video/webm -
video/wmv -
video/3gpp
resolution MediaResolution (optional)
媒體的解析度。
可能的值:
-
low -
medium -
high -
ultra_high
ThoughtSummaryDelta
未提供說明。
一律設為 "thought_summary"。
content ThoughtSummaryContent (選用)
要新增至想法的新摘要項目。
可能類型
多型鑑別器:type
TextContent
文字內容區塊。
未提供說明。
一律設為 "text"。
必填。文字內容。
annotations Annotation (optional)
模型生成內容的引用資訊。
可能類型
多型鑑別器:type
UrlCitation
網址引用註解。
未提供說明。
一律設為 "url_citation"。
網址。
網址的標題。
歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭,以位元組為單位。
歸因區隔的結束時間 (不含)。
FileCitation
檔案引用註解。
未提供說明。
一律設為 "file_citation"。
檔案的 URI。
檔案名稱。
歸因於部分文字的來源。
歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭,以位元組為單位。
歸因區隔的結束時間 (不含)。
PlaceCitation
地點引用註解。
未提供說明。
一律設為 "place_citation"。
地點 ID,格式為 `places/{place_id}`。
地點名稱。
地點的 URI 參照。
review_snippets ReviewSnippet (optional)
評論片段,用於生成 Google 地圖中特定地點功能相關的答案。
欄位
評論標題。
與 Google 地圖上的使用者評論相應的連結。
評論摘錄的 ID。
歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭,以位元組為單位。
歸因區隔的結束時間 (不含)。
ImageContent
圖片內容區塊。
未提供說明。
一律設為 "image"。
圖片內容。
圖片的 URI。
圖片的 MIME 類型。
可能的值:
-
image/png -
image/jpeg -
image/webp -
image/heic -
image/heif -
image/gif -
image/bmp -
image/tiff
resolution MediaResolution (optional)
媒體的解析度。
可能的值:
-
low -
medium -
high -
ultra_high
ThoughtSignatureDelta
未提供說明。
一律設為 "thought_signature"。
與要納入生成作業的後端來源相符的簽章。
FunctionCallDelta
未提供說明。
一律設為 "function_call"。
未提供說明。
未提供說明。
必填。這個特定工具呼叫的專屬 ID。
用於後端驗證的簽章雜湊。
CodeExecutionCallDelta
未提供說明。
一律設為 "code_execution_call"。
arguments CodeExecutionCallArguments (必要)
未提供說明。
欄位
`code` 的程式設計語言。
可能的值:
-
python
要執行的程式碼。
必填。這個特定工具呼叫的專屬 ID。
用於後端驗證的簽章雜湊。
UrlContextCallDelta
未提供說明。
一律設為 "url_context_call"。
arguments UrlContextCallArguments (必要)
未提供說明。
欄位
要擷取的網址。
必填。這個特定工具呼叫的專屬 ID。
用於後端驗證的簽章雜湊。
GoogleSearchCallDelta
未提供說明。
一律設為 "google_search_call"。
arguments GoogleSearchCallArguments (必要)
未提供說明。
欄位
用於後續網頁搜尋的網頁搜尋查詢。
必填。這個特定工具呼叫的專屬 ID。
用於後端驗證的簽章雜湊。
McpServerToolCallDelta
未提供說明。
一律設為 "mcp_server_tool_call"。
未提供說明。
未提供說明。
未提供說明。
必填。這個特定工具呼叫的專屬 ID。
用於後端驗證的簽章雜湊。
FileSearchCallDelta
未提供說明。
一律設為 "file_search_call"。
必填。這個特定工具呼叫的專屬 ID。
用於後端驗證的簽章雜湊。
GoogleMapsCallDelta
未提供說明。
一律設為 "google_maps_call"。
arguments GoogleMapsCallArguments (optional)
要傳遞至 Google 地圖工具的引數。
欄位
要執行的查詢。
必填。這個特定工具呼叫的專屬 ID。
用於後端驗證的簽章雜湊。
FunctionResultDelta
未提供說明。
一律設為 "function_result"。
未提供說明。
未提供說明。
必填。ID,與函式呼叫區塊中的 ID 相符。
用於後端驗證的簽章雜湊。
未提供說明。
CodeExecutionResultDelta
未提供說明。
一律設為 "code_execution_result"。
未提供說明。
未提供說明。
必填。ID,與函式呼叫區塊中的 ID 相符。
用於後端驗證的簽章雜湊。
UrlContextResultDelta
未提供說明。
一律設為 "url_context_result"。
result UrlContextResult (必要)
未提供說明。
欄位
擷取的網址。
網址擷取狀態。
可能的值:
-
success -
error -
paywall -
unsafe
未提供說明。
必填。ID,與函式呼叫區塊中的 ID 相符。
用於後端驗證的簽章雜湊。
GoogleSearchResultDelta
未提供說明。
一律設為 "google_search_result"。
result GoogleSearchResult (必要)
未提供說明。
欄位
可嵌入網頁或應用程式 WebView 的網頁內容程式碼片段。
未提供說明。
必填。ID,與函式呼叫區塊中的 ID 相符。
用於後端驗證的簽章雜湊。
McpServerToolResultDelta
未提供說明。
一律設為 "mcp_server_tool_result"。
未提供說明。
未提供說明。
必填。ID,與函式呼叫區塊中的 ID 相符。
用於後端驗證的簽章雜湊。
未提供說明。
FileSearchResultDelta
未提供說明。
一律設為 "file_search_result"。
result FileSearchResult (必要)
未提供說明。
欄位
使用者提供的 FileSearchResult 中繼資料。
必填。ID,與函式呼叫區塊中的 ID 相符。
用於後端驗證的簽章雜湊。
GoogleMapsResultDelta
未提供說明。
一律設為 "google_maps_result"。
result GoogleMapsResult (optional)
Google 地圖的搜尋結果。
欄位
地點 地點 (選填)
找到的地點。
欄位
地點 ID,格式為 `places/{place_id}`。
地點名稱。
地點的 URI 參照。
review_snippets ReviewSnippet (optional)
評論片段,用於生成 Google 地圖中特定地點功能相關的答案。
欄位
評論標題。
與 Google 地圖上的使用者評論相應的連結。
評論摘錄的 ID。
Google 地圖小工具情境權杖的資源名稱。
必填。ID,與函式呼叫區塊中的 ID 相符。
用於後端驗證的簽章雜湊。
TextAnnotationDelta
未提供說明。
一律設為 "text_annotation"。
annotations Annotation (optional)
模型生成內容的引用資訊。
可能類型
多型鑑別器:type
UrlCitation
網址引用註解。
未提供說明。
一律設為 "url_citation"。
網址。
網址的標題。
歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭,以位元組為單位。
歸因區隔的結束時間 (不含)。
FileCitation
檔案引用註解。
未提供說明。
一律設為 "file_citation"。
檔案的 URI。
檔案名稱。
歸因於部分文字的來源。
歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭,以位元組為單位。
歸因區隔的結束時間 (不含)。
PlaceCitation
地點引用註解。
未提供說明。
一律設為 "place_citation"。
地點 ID,格式為 `places/{place_id}`。
地點名稱。
地點的 URI 參照。
review_snippets ReviewSnippet (optional)
評論片段,用於生成 Google 地圖中特定地點功能相關的答案。
欄位
評論標題。
與 Google 地圖上的使用者評論相應的連結。
評論摘錄的 ID。
歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭,以位元組為單位。
歸因區隔的結束時間 (不含)。
用於從這個事件繼續互動串流的 event_id 權杖。
ContentStop
未提供說明。
一律設為 "content.stop"。
未提供說明。
用於從這個事件繼續互動串流的 event_id 權杖。
ErrorEvent
未提供說明。
一律設為 "error"。
error Error (optional)
未提供說明。
欄位
用於識別錯誤類型的 URI。
使用者可理解的錯誤訊息。
用於從這個事件繼續互動串流的 event_id 權杖。
範例
互動開始
{ "event_type": "interaction.start", "interaction": { "id": "v1_ChdTMjQ0YWJ5TUF1TzcxZThQdjRpcnFRcxIXUzI0NGFieU1BdU83MWU4UHY0aXJxUXM", "model": "gemini-3-flash-preview", "object": "interaction", "status": "in_progress" } }
互動完成
{ "event_type": "interaction.complete", "interaction": { "created": "2025-12-09T18:45:40Z", "id": "v1_ChdTMjQ0YWJ5TUF1TzcxZThQdjRpcnFRcxIXUzI0NGFieU1BdU83MWU4UHY0aXJxUXM", "model": "gemini-3-flash-preview", "object": "interaction", "role": "model", "status": "completed", "updated": "2025-12-09T18:45:40Z", "usage": { "input_tokens_by_modality": [ { "modality": "text", "tokens": 11 } ], "total_cached_tokens": 0, "total_input_tokens": 11, "total_output_tokens": 364, "total_thought_tokens": 1120, "total_tokens": 1495, "total_tool_use_tokens": 0 } } }
互動狀態更新
{ "event_type": "interaction.status_update", "interaction_id": "v1_ChdTMjQ0YWJ5TUF1TzcxZThQdjRpcnFRcxIXUzI0NGFieU1BdU83MWU4UHY0aXJxUXM", "status": "in_progress" }
內容開始
{ "event_type": "content.start", "content": { "type": "text" }, "index": 1 }
內容差異遷移
{ "event_type": "content.delta", "delta": { "type": "text", "text": "Elara\u2019s life was a symphony of quiet moments. A librarian, she found solace in the hushed aisles, the scent of aged paper, and the predictable rhythm of her days. Her small apartment, meticulously ordered, reflected this internal calm, save" }, "index": 1 }
內容停止
{ "event_type": "content.stop", "index": 1 }
錯誤事件
{ "event_type": "error", "error": { "message": "Failed to get completed interaction: Result not found.", "code": "not_found" } }