Gemini API

Gemini Interactions API 是實驗性 API，可讓開發人員使用 Gemini 模型建構生成式 AI 應用程式。Gemini 是 Google 最強大的模型，打從設計之初就具有多模態的特質。可歸納內容，完美解讀、操作及結合語言、圖片、音訊、影片和程式碼等不同類型的資訊。您可以使用 Gemini API 處理各種用途，例如：跨文字和圖片進行推論、生成內容、對話式代理程式、摘要和分類系統等。

以 Markdown 格式查看 查看 OpenAPI 規格

建立互動

post https://generativelanguage.googleapis.com/v1beta/interactions

建立新的互動。

要求主體

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

model ModelOption  (選用)

用於生成互動的 `Model` 名稱。
如未提供 `agent`，則為必要。

可能的值：

  • gemini-2.5-computer-use-preview-10-2025

    專為直接介面互動設計的代理功能模型，可讓 Gemini 感知及瀏覽數位環境。

  • gemini-2.5-flash

    這是我們第一個混合式推論模型，支援 100 萬個詞元的脈絡窗口，並具有思考預算。

  • gemini-2.5-flash-image

    Google 的原生圖像生成模型，專為速度、彈性和情境理解而設計。文字輸入和輸出內容的價格與 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-pro

    Google 最先進的多功能模型，擅長程式設計和複雜的推論工作。

  • gemini-2.5-pro-preview-tts

    2.5 Pro 文字轉語音模型經過最佳化調整，可產生強大且低延遲的語音，輸出內容更自然，提示也更容易引導。

  • gemini-3-flash-preview

    這是我們最聰明的模型，專為快速處理任務而打造，結合了前沿智慧與卓越的搜尋和基礎功能。

  • 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-preview

    Google 最經濟實惠的模型，適用於處理大量代理工作、翻譯和簡單的資料處理作業。

  • gemini-3.1-flash-tts-preview

    Gemini 3.1 Flash TTS：功能強大，延遲時間短的語音生成模型。享受自然輸出內容、可導向的提示，以及新的表現力音訊標記，精確控制旁白。

  • lyria-3-clip-preview

    這款低延遲音樂生成模型經過最佳化調整，可生成高傳真音訊片段，並精確控制節奏。

  • lyria-3-pro-preview

    這款進階的全曲生成模型具備深入的作曲理解能力，經過最佳化調整，可精確控制結構，並在各種音樂風格之間進行複雜的轉場。

用來完成提示的模型。\n\n 詳情請參閱 [模型](https://ai.google.dev/gemini-api/docs/models)。

agent AgentOption  (optional)

用於生成互動的 `Agent` 名稱。
如未提供 `model`，則為必要。

可能的值：

  • deep-research-pro-preview-12-2025

    Gemini Deep Research 代理

  • deep-research-preview-04-2026

    Gemini Deep Research 代理

  • deep-research-max-preview-04-2026

    Gemini Deep Research Max 代理

要互動的代理程式。

input Content 或陣列 (Content) 或陣列 (Step) 或字串  (必要)

互動的輸入內容 (模型和代理程式共用)。

system_instruction 字串  (選用)

互動的系統指令。

tools 陣列 (Tool)  (選用)

模型在互動期間可能會呼叫的工具宣告清單。

response_format ResponseFormat 或 ResponseFormatList  (選用)

強制生成的 JSON 物件回覆必須符合這個欄位中指定的 JSON 結構定義。

response_mime_type 字串  (選用)

回應的 MIME 類型。如果已設定 response_format，就必須提供這個屬性。

stream boolean  (選填)

僅限輸入。互動是否會串流。

store boolean  (選填)

僅限輸入。是否要儲存回覆和要求，以供日後擷取。

background boolean  (選填)

僅限輸入。是否要在背景執行模型互動。

generation_config GenerationConfig  (optional)

模型設定
模型互動的設定參數。
`agent_config` 的替代方案。僅適用於設定 `model` 時。

模型互動的設定參數。

欄位

temperature number  (選用)

控制輸出內容的隨機程度。

top_p 數字  (選用)

取樣時要考慮的符記累積分數上限。

seed integer  (選填)

用於解碼的種子，確保可重現結果。

stop_sequences 陣列 (字串)  (選用)

會停止輸出互動的字元序列清單。

thinking_level ThinkingLevel  (optional)

模型應生成的思考權杖數量。

可能的值：

  • minimal
  • low
  • medium
  • high

thinking_summaries ThinkingSummaries  (選用)

是否要在回覆中加入想法摘要。

可能的值：

  • auto
  • none

max_output_tokens integer  (optional)

回覆中可包含的詞元數量上限。

speech_config SpeechConfig  (optional)

語音互動設定。

語音互動的設定。

欄位

voice string  (選填)

說話者的聲音。

language string  (選用)

語音的語言。

speaker string  (選填)

說話者姓名，應與提示中提供的說話者姓名相符。

image_config ImageConfig  (optional)

圖片互動設定。

圖片互動的設定。

欄位

aspect_ratio 列舉 (字串)  (選用)

未提供說明。

可能的值：

  • 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
image_size 列舉 (字串)  (選用)

未提供說明。

可能的值：

  • 1K
  • 2K
  • 4K
  • 512
tool_choice ToolChoiceConfig 或 ToolChoiceType  (選填)

工具選擇設定。

agent_config object  (optional)

代理程式設定
代理程式的設定。
`generation_config` 的替代方案。僅適用於設定 `agent` 時。

可能類型

多型鑑別器：type

DynamicAgentConfig

動態代理程式的設定。

type object  (必要)

未提供說明。

一律設為 "dynamic"。

DeepResearchAgentConfig

Deep Research 代理的設定。

type object  (必要)

未提供說明。

一律設為 "deep-research"。

thinking_summaries ThinkingSummaries  (選用)

是否要在回覆中加入想法摘要。

可能的值：

  • auto
  • none

visualization enum (string)  (optional)

是否要在回覆中加入視覺化內容。

可能的值：

  • off
  • auto
collaborative_planning boolean  (選填)

為 Deep Research 代理啟用人機迴圈規劃。如果設為 true，Deep Research 代理會在回覆中提供研究計畫。使用者在下一個回合確認方案後，代理程式才會繼續執行。

previous_interaction_id 字串  (選用)

先前的互動 ID (如有)。

response_modalities ResponseModality  (optional)

要求的回覆模態 (TEXT、IMAGE、AUDIO)。

可能的值：

  • text
  • image
  • audio
  • video
  • document

service_tier ServiceTier  (選填)

互動的服務層級。

可能的值：

  • flex
  • standard
  • priority

webhook_config WebhookConfig  (optional)

(選用步驟) Webhook 設定，用於在互動完成時接收通知。

訊息：設定要求的 Webhook 事件。

欄位

uris 陣列 (字串)  (選填)

(選用步驟) 如果設定了這些 Webhook URI，系統就會使用這些 URI 處理 Webhook 事件，而非已註冊的 Webhook。

user_metadata object  (選用)

(選用步驟) 系統會在每次事件傳送至 Webhook 時，傳回使用者中繼資料。

回應

傳回 Interaction 資源。

簡單要求

回應範例

{
  "created": "2025-11-26T12:25:15Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3-flash-preview",
  "object": "interaction",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Hello! I'm functioning perfectly and ready to assist you.\n\nHow are you doing today?"
        }
      ]
    }
  ],
  "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",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "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",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "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",
  "steps": [
    {
      "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",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "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
  }
}

擷取互動

get https://generativelanguage.googleapis.com/v1beta/interactions/{id}

根據 `Interaction.id` 擷取單一互動的完整詳細資料。

路徑 / 查詢參數

id string  (必要)

要擷取的互動專屬 ID。

stream boolean  (選填)

如果設為 True，系統會以串流方式逐步提供生成的內容。

預設值：False

last_event_id string  (optional)

(選用步驟) 如果已設定，則從事件 ID 標示的事件後，繼續互動串流的下一個區塊。只有在 `stream` 為 true 時才能使用。

include_input boolean  (選用)

如果設為 true，回應會包含輸入內容。

預設值：False

api_version string  (optional)

要使用的 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",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "I'm doing great, thank you for asking! How can I help you today?"
        }
      ]
    }
  ]
}

刪除互動

delete https://generativelanguage.googleapis.com/v1beta/interactions/{id}

依 ID 刪除互動。

路徑 / 查詢參數

id string  (必要)

要刪除的互動專屬 ID。

api_version string  (optional)

要使用的 API 版本。

回應

如果成功，回應會留白。

刪除互動

取消互動

post https://generativelanguage.googleapis.com/v1beta/interactions/{id}/cancel

依 ID 取消互動。這項設定只適用於仍在執行的背景互動。

路徑 / 查詢參數

id string  (必要)

要取消的互動專屬 ID。

api_version string  (optional)

要使用的 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"
}

資源

互動

Interaction 資源。

欄位

model ModelOption  (選用)

用於生成互動的 `Model` 名稱。

可能的值：

  • gemini-2.5-computer-use-preview-10-2025

    專為直接介面互動設計的代理功能模型，可讓 Gemini 感知及瀏覽數位環境。

  • gemini-2.5-flash

    這是我們第一個混合式推論模型，支援 100 萬個詞元的脈絡窗口，並具有思考預算。

  • gemini-2.5-flash-image

    Google 的原生圖像生成模型，專為速度、彈性和情境理解而設計。文字輸入和輸出內容的價格與 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-pro

    Google 最先進的多功能模型，擅長程式設計和複雜的推論工作。

  • gemini-2.5-pro-preview-tts

    2.5 Pro 文字轉語音模型經過最佳化調整，可產生強大且低延遲的語音，輸出內容更自然，提示也更容易引導。

  • gemini-3-flash-preview

    這是我們最聰明的模型，專為快速處理任務而打造，結合了前沿智慧與卓越的搜尋和基礎功能。

  • 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-preview

    Google 最經濟實惠的模型，適用於處理大量代理工作、翻譯和簡單的資料處理作業。

  • gemini-3.1-flash-tts-preview

    Gemini 3.1 Flash TTS：功能強大，延遲時間短的語音生成模型。享受自然輸出內容、可導向的提示，以及新的表現力音訊標記，精確控制旁白。

  • lyria-3-clip-preview

    這款低延遲音樂生成模型經過最佳化調整，可生成高傳真音訊片段，並精確控制節奏。

  • lyria-3-pro-preview

    這款進階的全曲生成模型具備深入的作曲理解能力，經過最佳化調整，可精確控制結構，並在各種音樂風格之間進行複雜的轉場。

用來完成提示的模型。\n\n 詳情請參閱 [模型](https://ai.google.dev/gemini-api/docs/models)。

agent AgentOption  (選填)

用於生成互動的 `Agent` 名稱。

可能的值：

  • deep-research-pro-preview-12-2025

    Gemini Deep Research 代理

  • deep-research-preview-04-2026

    Gemini Deep Research 代理

  • deep-research-max-preview-04-2026

    Gemini Deep Research Max 代理

要互動的代理程式。

id string  (選用)

必填。僅供輸出。互動完成的專屬 ID。

status enum (string)  (optional)

必填。僅供輸出。互動狀態。

可能的值：

  • in_progress
  • requires_action
  • completed
  • failed
  • cancelled
  • incomplete
created string  (選用)

必填。僅供輸出。回覆的建立時間，採用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。

updated string  (選填)

必填。僅供輸出。回應上次更新的時間，採用 ISO 8601 格式 (YYYY-MM-DDThh:mm:ssZ)。

role string  (選填)

僅供輸出。互動的角色。

system_instruction 字串  (選用)

互動的系統指令。

tools 陣列 (Tool)  (選用)

模型在互動期間可能會呼叫的工具宣告清單。

usage Usage  (選填)

僅供輸出。互動要求的權杖用量統計資料。

互動要求的權杖用量統計資料。

欄位

total_input_tokens integer  (optional)

提示 (脈絡) 中的權杖數量。

input_tokens_by_modality ModalityTokens  (optional)

依模式細分的輸入權杖用量。

單一回覆模態的權杖數。

欄位

modality ResponseModality  (optional)

與權杖數相關聯的模態。

可能的值：

  • text
  • image
  • audio
  • video
  • document

tokens 整數  (選填)

模態的權杖數量。

total_cached_tokens integer  (optional)

提示快取部分的權杖數量 (快取內容)。

cached_tokens_by_modality ModalityTokens  (optional)

依模式細分快取權杖用量。

單一回覆模態的權杖數。

欄位

modality ResponseModality  (optional)

與權杖數相關聯的模態。

可能的值：

  • text
  • image
  • audio
  • video
  • document

tokens 整數  (選填)

模態的權杖數量。

total_output_tokens integer  (optional)

所有生成回覆的詞元總數。

output_tokens_by_modality ModalityTokens  (選用)

依模式細分的輸出權杖用量。

單一回覆模態的權杖數。

欄位

modality ResponseModality  (optional)

與權杖數相關聯的模態。

可能的值：

  • text
  • image
  • audio
  • video
  • document

tokens 整數  (選填)

模態的權杖數量。

total_tool_use_tokens integer  (optional)

工具使用提示中的權杖數量。

tool_use_tokens_by_modality ModalityTokens  (選用)

依模式細分工具使用權杖用量。

單一回覆模態的權杖數。

欄位

modality ResponseModality  (optional)

與權杖數相關聯的模態。

可能的值：

  • text
  • image
  • audio
  • video
  • document

tokens 整數  (選填)

模態的權杖數量。

total_thought_tokens integer  (optional)

思考模型想法的權杖數。

total_tokens 整數  (選用)

互動要求的權杖總數 (提示 + 回覆 + 其他內部權杖)。

grounding_tool_count GroundingToolCount  (optional)

基礎工具數量。

接地工具的數量。

欄位

type enum (string)  (選填)

與計數相關聯的基礎工具類型。

可能的值：

  • google_search
  • google_maps
  • retrieval
count integer  (選填)

接地工具的數量。

response_modalities ResponseModality  (optional)

要求的回覆模態 (TEXT、IMAGE、AUDIO)。

可能的值：

  • text
  • image
  • audio
  • video
  • document

response_mime_type 字串  (選用)

回應的 MIME 類型。如果已設定 response_format，就必須提供這個屬性。

previous_interaction_id 字串  (選用)

先前的互動 ID (如有)。

service_tier ServiceTier  (選填)

互動的服務層級。

可能的值：

  • flex
  • standard
  • priority

webhook_config WebhookConfig  (optional)

(選用步驟) Webhook 設定，用於在互動完成時接收通知。

訊息：設定要求的 Webhook 事件。

欄位

uris 陣列 (字串)  (選填)

(選用步驟) 如果設定了這些 Webhook URI，系統就會使用這些 URI 處理 Webhook 事件，而非已註冊的 Webhook。

user_metadata object  (選用)

(選用步驟) 系統會在每次事件傳送至 Webhook 時，傳回使用者中繼資料。

步驟 步驟  (選用)

僅供輸出。構成互動的步驟。

互動中的步驟。

可能類型

多型鑑別器：type

UserInputStep

使用者提供的輸入內容。

type object  (必要)

未提供說明。

一律設為 "user_input"。

content array (Content)  (選填)

未提供說明。

ModelOutputStep

模型生成的輸出內容。

type object  (必要)

未提供說明。

一律設為 "model_output"。

content array (Content)  (選填)

未提供說明。

ThoughtStep

思考步驟。

type object  (必要)

未提供說明。

一律設為 "thought"。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

summary ThoughtSummaryContent  (選填)

想法摘要。

可能類型

多型鑑別器：type

TextContent

文字內容區塊。

type object  (必要)

未提供說明。

一律設為 "text"。

text string  (必要)

必填。文字內容。

annotations Annotation  (optional)

模型生成內容的引用資訊。

模型生成內容的引用資訊。

可能類型

多型鑑別器：type

UrlCitation

網址引用註解。

type object  (必要)

未提供說明。

一律設為 "url_citation"。

url string  (optional)

網址。

title string  (選用)

網址的標題。

start_index integer  (optional)

歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭，以位元組為單位。

end_index integer  (optional)

歸因區隔的結束時間 (不含)。

FileCitation

檔案引用註解。

type object  (必要)

未提供說明。

一律設為 "file_citation"。

document_uri string  (選用)

檔案的 URI。

file_name string  (optional)

檔案名稱。

source string  (選填)

歸因於部分文字的來源。

custom_metadata object  (選用)

使用者提供的中繼資料，用於說明擷取的脈絡。

page_number 整數  (選填)

引用文件的頁碼 (如適用)。

media_id string  (optional)

圖片引用時的媒體 ID (如適用)。

start_index integer  (optional)

歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭，以位元組為單位。

end_index integer  (optional)

歸因區隔的結束時間 (不含)。

PlaceCitation

地點引用註解。

type object  (必要)

未提供說明。

一律設為 "place_citation"。

place_id string  (選用)

地點 ID，格式為 `places/{place_id}`。

名稱 字串  (選用)

地點名稱。

url string  (optional)

地點的 URI 參照。

review_snippets ReviewSnippet  (optional)

評論片段，用於生成 Google 地圖中特定地點功能相關的答案。

封裝使用者評論片段，回答 Google 地圖中特定地點功能的問題。

欄位

title string  (選用)

評論標題。

url string  (optional)

與 Google 地圖上的使用者評論相應的連結。

review_id string  (選用)

評論摘錄的 ID。

start_index integer  (optional)

歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭，以位元組為單位。

end_index integer  (optional)

歸因區隔的結束時間 (不含)。

ImageContent

圖片內容區塊。

type object  (必要)

未提供說明。

一律設為 "image"。

data string  (選填)

圖片內容。

uri string  (選填)

圖片的 URI。

mime_type 列舉 (字串)  (選用)

圖片的 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

FunctionCallStep

函式工具呼叫步驟。

type object  (必要)

未提供說明。

一律設為 "function_call"。

name string  (必要)

必填。要呼叫的工具名稱。

引數 object  (必填)

必填。要傳遞至函式的引數。

id string  (必要)

必填。這個特定工具呼叫的專屬 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

CodeExecutionCallStep

程式碼執行呼叫步驟。

type object  (必要)

未提供說明。

一律設為 "code_execution_call"。

arguments CodeExecutionCallStepArguments  (必要)

必填。要傳遞至程式碼執行的引數。

要傳遞至程式碼執行的引數。

欄位

language enum (string)  (optional)

`code` 的程式設計語言。

可能的值：

  • python
code string  (選用)

要執行的程式碼。

id string  (必要)

必填。這個特定工具呼叫的專屬 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

UrlContextCallStep

網址情境呼叫步驟。

type object  (必要)

未提供說明。

一律設為 "url_context_call"。

arguments UrlContextCallStepArguments  (必要)

必填。要傳遞至網址環境的引數。

要傳遞至網址環境的引數。

欄位

urls 陣列 (字串)  (選填)

要擷取的網址。

id string  (必要)

必填。這個特定工具呼叫的專屬 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

McpServerToolCallStep

MCPServer 工具呼叫步驟。

type object  (必要)

未提供說明。

一律設為 "mcp_server_tool_call"。

name string  (必要)

必填。所呼叫工具的名稱。

server_name string  (required)

必填。所用 MCP 伺服器的名稱。

引數 object  (必填)

必填。函式引數的 JSON 物件。

id string  (必要)

必填。這個特定工具呼叫的專屬 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

GoogleSearchCallStep

Google 搜尋通話步驟。

type object  (必要)

未提供說明。

一律設為 "google_search_call"。

arguments GoogleSearchCallStepArguments  (必要)

必填。要傳遞給 Google 搜尋的引數。

要傳遞給 Google 搜尋的引數。

欄位

queries array (string)  (optional)

用於後續網頁搜尋的網頁搜尋查詢。

search_type 列舉 (字串)  (選用)

已啟用的搜尋基準建立功能類型。

可能的值：

  • web_search
  • image_search
  • enterprise_web_search
id string  (必要)

必填。這個特定工具呼叫的專屬 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

FileSearchCallStep

檔案搜尋通話步驟。

type object  (必要)

未提供說明。

一律設為 "file_search_call"。

id string  (必要)

必填。這個特定工具呼叫的專屬 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

GoogleMapsCallStep

Google 地圖通話步驟。

type object  (必要)

未提供說明。

一律設為 "google_maps_call"。

arguments GoogleMapsCallStepArguments  (optional)

要傳遞至 Google 地圖工具的引數。

要傳遞至 Google 地圖工具的引數。

欄位

queries array (string)  (optional)

要執行的查詢。

id string  (必要)

必填。這個特定工具呼叫的專屬 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

FunctionResultStep

函式工具呼叫的結果。

type object  (必要)

未提供說明。

一律設為 "function_result"。

名稱 字串  (選用)

所呼叫工具的名稱。

is_error boolean  (optional)

工具呼叫是否發生錯誤。

call_id string  (必要)

必填。與函式呼叫區塊中的 ID 相符的 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

result 陣列 (FunctionResultSubcontent) 或字串  (必要)

工具呼叫的結果。

CodeExecutionResultStep

程式碼執行結果步驟。

type object  (必要)

未提供說明。

一律設為 "code_execution_result"。

結果 字串  (必要)

必填。程式碼執行作業的輸出內容。

is_error boolean  (optional)

程式碼執行作業是否發生錯誤。

call_id string  (必要)

必填。與函式呼叫區塊中的 ID 相符的 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

UrlContextResultStep

網址背景資訊結果步驟。

type object  (必要)

未提供說明。

一律設為 "url_context_result"。

result UrlContextResultItem  (必要)

必填。網址環境的結果。

網址環境的結果。

欄位

url string  (optional)

擷取的網址。

status enum (string)  (optional)

網址擷取狀態。

可能的值：

  • success
  • error
  • paywall
  • unsafe
is_error boolean  (optional)

網址脈絡是否發生錯誤。

call_id string  (必要)

必填。與函式呼叫區塊中的 ID 相符的 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

GoogleSearchResultStep

Google 搜尋結果步驟。

type object  (必要)

未提供說明。

一律設為 "google_search_result"。

result GoogleSearchResultItem  (必要)

必填。Google 搜尋結果。

Google 搜尋結果。

欄位

search_suggestions string  (選用)

可嵌入網頁或應用程式 WebView 的網頁內容程式碼片段。

is_error boolean  (optional)

Google 搜尋是否發生錯誤。

call_id string  (必要)

必填。與函式呼叫區塊中的 ID 相符的 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

McpServerToolResultStep

MCPServer 工具結果步驟。

type object  (必要)

未提供說明。

一律設為 "mcp_server_tool_result"。

名稱 字串  (選用)

針對這項特定工具呼叫所呼叫的工具名稱。

server_name string  (optional)

所用 MCP 伺服器的名稱。

call_id string  (必要)

必填。與函式呼叫區塊中的 ID 相符的 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

result 陣列 (FunctionResultSubcontent) 或字串  (必要)

MCP 伺服器呼叫的輸出內容。可以是簡單文字或多媒體內容。

FileSearchResultStep

檔案搜尋結果步驟。

type object  (必要)

未提供說明。

一律設為 "file_search_result"。

call_id string  (必要)

必填。與函式呼叫區塊中的 ID 相符的 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

GoogleMapsResultStep

Google 地圖結果步驟。

type object  (必要)

未提供說明。

一律設為 "google_maps_result"。

result GoogleMapsResultItem  (必填)

未提供說明。

Google 地圖的結果。

欄位

places GoogleMapsResultPlaces  (optional)

未提供說明。

欄位

place_id string  (選用)

未提供說明。

名稱 字串  (選用)

未提供說明。

url string  (optional)

未提供說明。

review_snippets ReviewSnippet  (optional)

未提供說明。

封裝使用者評論片段，回答 Google 地圖中特定地點功能的問題。

欄位

title string  (選用)

評論標題。

url string  (optional)

與 Google 地圖上的使用者評論相應的連結。

review_id string  (選用)

評論摘錄的 ID。

widget_context_token 字串  (選用)

未提供說明。

call_id string  (必要)

必填。與函式呼叫區塊中的 ID 相符的 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

input Content 或陣列 (Content) 或陣列 (Step) 或字串  (選用)

互動的輸入內容。

response_format ResponseFormat 或 ResponseFormatList  (選用)

強制生成的 JSON 物件回覆必須符合這個欄位中指定的 JSON 結構定義。

agent_config object  (optional)

代理程式互動的設定參數。

可能類型

多型鑑別器：type

DynamicAgentConfig

動態代理程式的設定。

type object  (必要)

未提供說明。

一律設為 "dynamic"。

DeepResearchAgentConfig

Deep Research 代理的設定。

type object  (必要)

未提供說明。

一律設為 "deep-research"。

thinking_summaries ThinkingSummaries  (選用)

是否要在回覆中加入想法摘要。

可能的值：

  • auto
  • none

visualization enum (string)  (optional)

是否要在回覆中加入視覺化內容。

可能的值：

  • off
  • auto
collaborative_planning boolean  (選填)

為 Deep Research 代理啟用人機迴圈規劃。如果設為 true，Deep Research 代理會在回覆中提供研究計畫。使用者在下一個回合確認方案後，代理程式才會繼續執行。

範例

範例

{
  "created": "2025-12-04T15:01:45Z",
  "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg",
  "model": "gemini-3-flash-preview",
  "object": "interaction",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Hello! I'm doing well, functioning as expected. Thank you for asking! How are you doing today?"
        }
      ]
    }
  ],
  "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

文字內容區塊。

type object  (必要)

未提供說明。

一律設為 "text"。

text string  (必要)

必填。文字內容。

annotations Annotation  (optional)

模型生成內容的引用資訊。

模型生成內容的引用資訊。

可能類型

多型鑑別器：type

UrlCitation

網址引用註解。

type object  (必要)

未提供說明。

一律設為 "url_citation"。

url string  (optional)

網址。

title string  (選用)

網址的標題。

start_index integer  (optional)

歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭，以位元組為單位。

end_index integer  (optional)

歸因區隔的結束時間 (不含)。

FileCitation

檔案引用註解。

type object  (必要)

未提供說明。

一律設為 "file_citation"。

document_uri string  (選用)

檔案的 URI。

file_name string  (optional)

檔案名稱。

source string  (選填)

歸因於部分文字的來源。

custom_metadata object  (選用)

使用者提供的中繼資料，用於說明擷取的脈絡。

page_number 整數  (選填)

引用文件的頁碼 (如適用)。

media_id string  (optional)

圖片引用時的媒體 ID (如適用)。

start_index integer  (optional)

歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭，以位元組為單位。

end_index integer  (optional)

歸因區隔的結束時間 (不含)。

PlaceCitation

地點引用註解。

type object  (必要)

未提供說明。

一律設為 "place_citation"。

place_id string  (選用)

地點 ID，格式為 `places/{place_id}`。

名稱 字串  (選用)

地點名稱。

url string  (optional)

地點的 URI 參照。

review_snippets ReviewSnippet  (optional)

評論片段，用於生成 Google 地圖中特定地點功能相關的答案。

封裝使用者評論片段，回答 Google 地圖中特定地點功能的問題。

欄位

title string  (選用)

評論標題。

url string  (optional)

與 Google 地圖上的使用者評論相應的連結。

review_id string  (選用)

評論摘錄的 ID。

start_index integer  (optional)

歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭，以位元組為單位。

end_index integer  (optional)

歸因區隔的結束時間 (不含)。

ImageContent

圖片內容區塊。

type object  (必要)

未提供說明。

一律設為 "image"。

data string  (選填)

圖片內容。

uri string  (選填)

圖片的 URI。

mime_type 列舉 (字串)  (選用)

圖片的 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

音訊內容區塊。

type object  (必要)

未提供說明。

一律設為 "audio"。

data string  (選填)

音訊內容。

uri string  (選填)

音訊的 URI。

mime_type 列舉 (字串)  (選用)

音訊的 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
channels integer  (選填)

音訊聲道數。

sample_rate 整數  (選用)

音訊的取樣率。

DocumentContent

文件內容區塊。

type object  (必要)

未提供說明。

一律設為 "document"。

data string  (選填)

文件內容。

uri string  (選填)

文件的 URI。

mime_type 列舉 (字串)  (選用)

文件的 MIME 類型。

可能的值：

  • application/pdf
VideoContent

影片內容區塊。

type object  (必要)

未提供說明。

一律設為 "video"。

data string  (選填)

影片內容。

uri string  (選填)

影片的 URI。

mime_type 列舉 (字串)  (選用)

影片的 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

範例

文字

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

功能

模型可使用的工具。

type object  (必要)

未提供說明。

一律設為 "function"。

名稱 字串  (選用)

函式名稱。

description string  (選用)

函式說明。

parameters object  (選用)

函式參數的 JSON 結構定義。

CodeExecution

模型可用來執行程式碼的工具。

type object  (必要)

未提供說明。

一律設為 "code_execution"。

UrlContext

模型可用來擷取網址內容的工具。

type object  (必要)

未提供說明。

一律設為 "url_context"。

ComputerUse

模型可用來與電腦互動的工具。

type object  (必要)

未提供說明。

一律設為 "computer_use"。

environment enum (string)  (optional)

運作中的環境。

可能的值：

  • browser
excluded_predefined_functions 陣列 (字串)  (選用)

從模型呼叫中排除的預先定義函式清單。

McpServer

MCPServer 是模型可呼叫的伺服器，用於執行動作。

type object  (必要)

未提供說明。

一律設為 "mcp_server"。

名稱 字串  (選用)

MCPServer 的名稱。

url string  (optional)

MCPServer 端點的完整網址。 例如：「https://api.example.com/mcp」

headers object  (optional)

選用：視需要填寫驗證標頭、逾時等欄位。

allowed_tools AllowedTools  (選用)

允許使用的工具。

允許使用的工具設定。

欄位

mode ToolChoiceType  (optional)

工具選擇模式。

可能的值：

  • auto
  • any
  • none
  • validated

tools array (string)  (optional)

允許使用的工具名稱。

GoogleSearch

模型可用來搜尋 Google 的工具。

type object  (必要)

未提供說明。

一律設為 "google_search"。

search_types 陣列 (列舉 (字串))  (選用)

要啟用的搜尋基準建立功能類型。

可能的值：

  • web_search
  • image_search
  • enterprise_web_search
FileSearch

模型可用來搜尋檔案的工具。

type object  (必要)

未提供說明。

一律設為 "file_search"。

file_search_store_names array (string)  (optional)

要搜尋的檔案搜尋商店名稱。

top_k 整數  (選用)

要擷取的語意擷取區塊數量。

metadata_filter string  (選用)

要套用至語意擷取文件和區塊的中繼資料篩選器。

GoogleMaps

模型可用來呼叫 Google 地圖的工具。

type object  (必要)

未提供說明。

一律設為 "google_maps"。

enable_widget boolean  (選用)

是否要在回應的工具呼叫結果中傳回小工具內容權杖。

latitude number  (選用)

使用者所在位置的緯度。

longitude number  (選填)

使用者所在位置的經度。

擷取

模型可用來擷取檔案的工具。

type object  (必要)

未提供說明。

一律設為 "retrieval"。

retrieval_types 陣列 (列舉 (字串))  (選用)

要啟用的檔案擷取類型。

可能的值：

  • vertex_ai_search
vertex_ai_search_config VertexAISearchConfig  (optional)

用於指定 VertexAISearch 的設定。

用於指定 VertexAISearch 的設定。

欄位

engine string  (選填)

(選用步驟) 用於指定 Vertex AI Search 引擎。

datastores array (string)  (optional)

(選用步驟) 用於指定 Vertex AI Search 資料存放區。

範例

函式

CodeExecution

UrlContext

ComputerUse

McpServer

GoogleSearch

FileSearch

GoogleMaps

擷取

這個類型沒有可用的範例。

InteractionSseEvent

可能類型

多型鑑別器：event_type

InteractionCreatedEvent

event_type object  (必要)

未提供說明。

一律設為 "interaction.created"。

互動 互動  (必填)

未提供說明。

event_id string  (選用)

用於從這個事件繼續互動串流的 event_id 權杖。

InteractionCompletedEvent

event_type object  (必要)

未提供說明。

一律設為 "interaction.completed"。

互動 互動  (必填)

必填。完成互動，但輸出內容為空白，以減少酬載大小。 使用上述 ContentDelta 事件做為實際輸出內容。

event_id string  (選用)

用於從這個事件繼續互動串流的 event_id 權杖。

InteractionStatusUpdate

event_type object  (必要)

未提供說明。

一律設為 "interaction.status_update"。

interaction_id string  (required)

未提供說明。

status enum (string)  (required)

未提供說明。

可能的值：

  • in_progress
  • requires_action
  • completed
  • failed
  • cancelled
  • incomplete
event_id string  (選用)

用於從這個事件繼續互動串流的 event_id 權杖。

ErrorEvent

event_type object  (必要)

未提供說明。

一律設為 "error"。

error Error  (optional)

未提供說明。

互動中的錯誤訊息。

欄位

code string  (選用)

用於識別錯誤類型的 URI。

message string  (選填)

使用者可理解的錯誤訊息。

event_id string  (選用)

用於從這個事件繼續互動串流的 event_id 權杖。

StepStart

event_type object  (必要)

未提供說明。

一律設為 "step.start"。

index 整數  (必要)

未提供說明。

步驟 步驟  (必要)

未提供說明。

互動中的步驟。

可能類型

多型鑑別器：type

UserInputStep

使用者提供的輸入內容。

type object  (必要)

未提供說明。

一律設為 "user_input"。

content array (Content)  (選填)

未提供說明。

ModelOutputStep

模型生成的輸出內容。

type object  (必要)

未提供說明。

一律設為 "model_output"。

content array (Content)  (選填)

未提供說明。

ThoughtStep

思考步驟。

type object  (必要)

未提供說明。

一律設為 "thought"。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

summary ThoughtSummaryContent  (選填)

想法摘要。

可能類型

多型鑑別器：type

TextContent

文字內容區塊。

type object  (必要)

未提供說明。

一律設為 "text"。

text string  (必要)

必填。文字內容。

annotations Annotation  (optional)

模型生成內容的引用資訊。

模型生成內容的引用資訊。

可能類型

多型鑑別器：type

UrlCitation

網址引用註解。

type object  (必要)

未提供說明。

一律設為 "url_citation"。

url string  (optional)

網址。

title string  (選用)

網址的標題。

start_index integer  (optional)

歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭，以位元組為單位。

end_index integer  (optional)

歸因區隔的結束時間 (不含)。

FileCitation

檔案引用註解。

type object  (必要)

未提供說明。

一律設為 "file_citation"。

document_uri string  (選用)

檔案的 URI。

file_name string  (optional)

檔案名稱。

source string  (選填)

歸因於部分文字的來源。

custom_metadata object  (選用)

使用者提供的中繼資料，用於說明擷取的脈絡。

page_number 整數  (選填)

引用文件的頁碼 (如適用)。

media_id string  (optional)

圖片引用時的媒體 ID (如適用)。

start_index integer  (optional)

歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭，以位元組為單位。

end_index integer  (optional)

歸因區隔的結束時間 (不含)。

PlaceCitation

地點引用註解。

type object  (必要)

未提供說明。

一律設為 "place_citation"。

place_id string  (選用)

地點 ID，格式為 `places/{place_id}`。

名稱 字串  (選用)

地點名稱。

url string  (optional)

地點的 URI 參照。

review_snippets ReviewSnippet  (optional)

評論片段，用於生成 Google 地圖中特定地點功能相關的答案。

封裝使用者評論片段，回答 Google 地圖中特定地點功能的問題。

欄位

title string  (選用)

評論標題。

url string  (optional)

與 Google 地圖上的使用者評論相應的連結。

review_id string  (選用)

評論摘錄的 ID。

start_index integer  (optional)

歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭，以位元組為單位。

end_index integer  (optional)

歸因區隔的結束時間 (不含)。

ImageContent

圖片內容區塊。

type object  (必要)

未提供說明。

一律設為 "image"。

data string  (選填)

圖片內容。

uri string  (選填)

圖片的 URI。

mime_type 列舉 (字串)  (選用)

圖片的 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

FunctionCallStep

函式工具呼叫步驟。

type object  (必要)

未提供說明。

一律設為 "function_call"。

name string  (必要)

必填。要呼叫的工具名稱。

引數 object  (必填)

必填。要傳遞至函式的引數。

id string  (必要)

必填。這個特定工具呼叫的專屬 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

CodeExecutionCallStep

程式碼執行呼叫步驟。

type object  (必要)

未提供說明。

一律設為 "code_execution_call"。

arguments CodeExecutionCallStepArguments  (必要)

必填。要傳遞至程式碼執行的引數。

要傳遞至程式碼執行的引數。

欄位

language enum (string)  (optional)

`code` 的程式設計語言。

可能的值：

  • python
code string  (選用)

要執行的程式碼。

id string  (必要)

必填。這個特定工具呼叫的專屬 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

UrlContextCallStep

網址情境呼叫步驟。

type object  (必要)

未提供說明。

一律設為 "url_context_call"。

arguments UrlContextCallStepArguments  (必要)

必填。要傳遞至網址環境的引數。

要傳遞至網址環境的引數。

欄位

urls 陣列 (字串)  (選填)

要擷取的網址。

id string  (必要)

必填。這個特定工具呼叫的專屬 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

McpServerToolCallStep

MCPServer 工具呼叫步驟。

type object  (必要)

未提供說明。

一律設為 "mcp_server_tool_call"。

name string  (必要)

必填。所呼叫工具的名稱。

server_name string  (required)

必填。所用 MCP 伺服器的名稱。

引數 object  (必填)

必填。函式引數的 JSON 物件。

id string  (必要)

必填。這個特定工具呼叫的專屬 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

GoogleSearchCallStep

Google 搜尋通話步驟。

type object  (必要)

未提供說明。

一律設為 "google_search_call"。

arguments GoogleSearchCallStepArguments  (必要)

必填。要傳遞給 Google 搜尋的引數。

要傳遞給 Google 搜尋的引數。

欄位

queries array (string)  (optional)

用於後續網頁搜尋的網頁搜尋查詢。

search_type 列舉 (字串)  (選用)

已啟用的搜尋基準建立功能類型。

可能的值：

  • web_search
  • image_search
  • enterprise_web_search
id string  (必要)

必填。這個特定工具呼叫的專屬 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

FileSearchCallStep

檔案搜尋通話步驟。

type object  (必要)

未提供說明。

一律設為 "file_search_call"。

id string  (必要)

必填。這個特定工具呼叫的專屬 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

GoogleMapsCallStep

Google 地圖通話步驟。

type object  (必要)

未提供說明。

一律設為 "google_maps_call"。

arguments GoogleMapsCallStepArguments  (optional)

要傳遞至 Google 地圖工具的引數。

要傳遞至 Google 地圖工具的引數。

欄位

queries array (string)  (optional)

要執行的查詢。

id string  (必要)

必填。這個特定工具呼叫的專屬 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

FunctionResultStep

函式工具呼叫的結果。

type object  (必要)

未提供說明。

一律設為 "function_result"。

名稱 字串  (選用)

所呼叫工具的名稱。

is_error boolean  (optional)

工具呼叫是否發生錯誤。

call_id string  (必要)

必填。與函式呼叫區塊中的 ID 相符的 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

result 陣列 (FunctionResultSubcontent) 或字串  (必要)

工具呼叫的結果。

CodeExecutionResultStep

程式碼執行結果步驟。

type object  (必要)

未提供說明。

一律設為 "code_execution_result"。

結果 字串  (必要)

必填。程式碼執行作業的輸出內容。

is_error boolean  (optional)

程式碼執行作業是否發生錯誤。

call_id string  (必要)

必填。與函式呼叫區塊中的 ID 相符的 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

UrlContextResultStep

網址背景資訊結果步驟。

type object  (必要)

未提供說明。

一律設為 "url_context_result"。

result UrlContextResultItem  (必要)

必填。網址環境的結果。

網址環境的結果。

欄位

url string  (optional)

擷取的網址。

status enum (string)  (optional)

網址擷取狀態。

可能的值：

  • success
  • error
  • paywall
  • unsafe
is_error boolean  (optional)

網址脈絡是否發生錯誤。

call_id string  (必要)

必填。與函式呼叫區塊中的 ID 相符的 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

GoogleSearchResultStep

Google 搜尋結果步驟。

type object  (必要)

未提供說明。

一律設為 "google_search_result"。

result GoogleSearchResultItem  (必要)

必填。Google 搜尋結果。

Google 搜尋結果。

欄位

search_suggestions string  (選用)

可嵌入網頁或應用程式 WebView 的網頁內容程式碼片段。

is_error boolean  (optional)

Google 搜尋是否發生錯誤。

call_id string  (必要)

必填。與函式呼叫區塊中的 ID 相符的 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

McpServerToolResultStep

MCPServer 工具結果步驟。

type object  (必要)

未提供說明。

一律設為 "mcp_server_tool_result"。

名稱 字串  (選用)

針對這項特定工具呼叫所呼叫的工具名稱。

server_name string  (optional)

所用 MCP 伺服器的名稱。

call_id string  (必要)

必填。與函式呼叫區塊中的 ID 相符的 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

result 陣列 (FunctionResultSubcontent) 或字串  (必要)

MCP 伺服器呼叫的輸出內容。可以是簡單文字或多媒體內容。

FileSearchResultStep

檔案搜尋結果步驟。

type object  (必要)

未提供說明。

一律設為 "file_search_result"。

call_id string  (必要)

必填。與函式呼叫區塊中的 ID 相符的 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

GoogleMapsResultStep

Google 地圖結果步驟。

type object  (必要)

未提供說明。

一律設為 "google_maps_result"。

result GoogleMapsResultItem  (必填)

未提供說明。

Google 地圖的結果。

欄位

places GoogleMapsResultPlaces  (optional)

未提供說明。

欄位

place_id string  (選用)

未提供說明。

名稱 字串  (選用)

未提供說明。

url string  (optional)

未提供說明。

review_snippets ReviewSnippet  (optional)

未提供說明。

封裝使用者評論片段，回答 Google 地圖中特定地點功能的問題。

欄位

title string  (選用)

評論標題。

url string  (optional)

與 Google 地圖上的使用者評論相應的連結。

review_id string  (選用)

評論摘錄的 ID。

widget_context_token 字串  (選用)

未提供說明。

call_id string  (必要)

必填。與函式呼叫區塊中的 ID 相符的 ID。

簽名 字串  (選填)

用於後端驗證的簽章雜湊。

event_id string  (選用)

用於從這個事件繼續互動串流的 event_id 權杖。

StepDelta

event_type object  (必要)

未提供說明。

一律設為 "step.delta"。

index 整數  (必要)

未提供說明。

delta StepDeltaData  (必要)

未提供說明。

可能類型

多型鑑別器：type

TextDelta

type object  (必要)

未提供說明。

一律設為 "text"。

text string  (必要)

未提供說明。

ImageDelta

type object  (必要)

未提供說明。

一律設為 "image"。

data string  (選填)

未提供說明。

uri string  (選填)

未提供說明。

mime_type 列舉 (字串)  (選用)

未提供說明。

可能的值：

  • 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

type object  (必要)

未提供說明。

一律設為 "audio"。

data string  (選填)

未提供說明。

uri string  (選填)

未提供說明。

mime_type 列舉 (字串)  (選用)

未提供說明。

可能的值：

  • audio/wav
  • audio/mp3
  • audio/aiff
  • audio/aac
  • audio/ogg
  • audio/flac
  • audio/mpeg
  • audio/m4a
  • audio/l16
  • audio/opus
  • audio/alaw
  • audio/mulaw
rate 整數  (選填)

已淘汰，請改用 sample_rate。系統會忽略該值。

sample_rate 整數  (選用)

音訊的取樣率。

channels integer  (選填)

音訊聲道數。

DocumentDelta

type object  (必要)

未提供說明。

一律設為 "document"。

data string  (選填)

未提供說明。

uri string  (選填)

未提供說明。

mime_type 列舉 (字串)  (選用)

未提供說明。

可能的值：

  • application/pdf
VideoDelta

type object  (必要)

未提供說明。

一律設為 "video"。

data string  (選填)

未提供說明。

uri string  (選填)

未提供說明。

mime_type 列舉 (字串)  (選用)

未提供說明。

可能的值：

  • 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

type object  (必要)

未提供說明。

一律設為 "thought_summary"。

content ThoughtSummaryContent  (選用)

要新增至想法的新摘要項目。

可能類型

多型鑑別器：type

TextContent

文字內容區塊。

type object  (必要)

未提供說明。

一律設為 "text"。

text string  (必要)

必填。文字內容。

annotations Annotation  (optional)

模型生成內容的引用資訊。

模型生成內容的引用資訊。

可能類型

多型鑑別器：type

UrlCitation

網址引用註解。

type object  (必要)

未提供說明。

一律設為 "url_citation"。

url string  (optional)

網址。

title string  (選用)

網址的標題。

start_index integer  (optional)

歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭，以位元組為單位。

end_index integer  (optional)

歸因區隔的結束時間 (不含)。

FileCitation

檔案引用註解。

type object  (必要)

未提供說明。

一律設為 "file_citation"。

document_uri string  (選用)

檔案的 URI。

file_name string  (optional)

檔案名稱。

source string  (選填)

歸因於部分文字的來源。

custom_metadata object  (選用)

使用者提供的中繼資料，用於說明擷取的脈絡。

page_number 整數  (選填)

引用文件的頁碼 (如適用)。

media_id string  (optional)

圖片引用時的媒體 ID (如適用)。

start_index integer  (optional)

歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭，以位元組為單位。

end_index integer  (optional)

歸因區隔的結束時間 (不含)。

PlaceCitation

地點引用註解。

type object  (必要)

未提供說明。

一律設為 "place_citation"。

place_id string  (選用)

地點 ID，格式為 `places/{place_id}`。

名稱 字串  (選用)

地點名稱。

url string  (optional)

地點的 URI 參照。

review_snippets ReviewSnippet  (optional)

評論片段，用於生成 Google 地圖中特定地點功能相關的答案。

封裝使用者評論片段，回答 Google 地圖中特定地點功能的問題。

欄位

title string  (選用)

評論標題。

url string  (optional)

與 Google 地圖上的使用者評論相應的連結。

review_id string  (選用)

評論摘錄的 ID。

start_index integer  (optional)

歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭，以位元組為單位。

end_index integer  (optional)

歸因區隔的結束時間 (不含)。

ImageContent

圖片內容區塊。

type object  (必要)

未提供說明。

一律設為 "image"。

data string  (選填)

圖片內容。

uri string  (選填)

圖片的 URI。

mime_type 列舉 (字串)  (選用)

圖片的 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

type object  (必要)

未提供說明。

一律設為 "thought_signature"。

簽名 字串  (選填)

與要納入生成作業的後端來源相符的簽章。

TextAnnotationDelta

type object  (必要)

未提供說明。

一律設為 "text_annotation_delta"。

annotations Annotation  (optional)

模型生成內容的引用資訊。

模型生成內容的引用資訊。

可能類型

多型鑑別器：type

UrlCitation

網址引用註解。

type object  (必要)

未提供說明。

一律設為 "url_citation"。

url string  (optional)

網址。

title string  (選用)

網址的標題。

start_index integer  (optional)

歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭，以位元組為單位。

end_index integer  (optional)

歸因區隔的結束時間 (不含)。

FileCitation

檔案引用註解。

type object  (必要)

未提供說明。

一律設為 "file_citation"。

document_uri string  (選用)

檔案的 URI。

file_name string  (optional)

檔案名稱。

source string  (選填)

歸因於部分文字的來源。

custom_metadata object  (選用)

使用者提供的中繼資料，用於說明擷取的脈絡。

page_number 整數  (選填)

引用文件的頁碼 (如適用)。

media_id string  (optional)

圖片引用時的媒體 ID (如適用)。

start_index integer  (optional)

歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭，以位元組為單位。

end_index integer  (optional)

歸因區隔的結束時間 (不含)。

PlaceCitation

地點引用註解。

type object  (必要)

未提供說明。

一律設為 "place_citation"。

place_id string  (選用)

地點 ID，格式為 `places/{place_id}`。

名稱 字串  (選用)

地點名稱。

url string  (optional)

地點的 URI 參照。

review_snippets ReviewSnippet  (optional)

評論片段，用於生成 Google 地圖中特定地點功能相關的答案。

封裝使用者評論片段，回答 Google 地圖中特定地點功能的問題。

欄位

title string  (選用)

評論標題。

url string  (optional)

與 Google 地圖上的使用者評論相應的連結。

review_id string  (選用)

評論摘錄的 ID。

start_index integer  (optional)

歸因於這個來源的回覆片段開頭。 索引會指出區段的開頭，以位元組為單位。

end_index integer  (optional)

歸因區隔的結束時間 (不含)。

ArgumentsDelta

type object  (必要)

未提供說明。

一律設為 "arguments_delta"。

partial_arguments string  (optional)

未提供說明。

event_id string  (選用)

用於從這個事件繼續互動串流的 event_id 權杖。

StepStop

event_type object  (必要)

未提供說明。

一律設為 "step.stop"。

index 整數  (必要)

未提供說明。

event_id string  (選用)

用於從這個事件繼續互動串流的 event_id 權杖。

範例

已建立互動

{
  "event_type": "interaction.created",
  "interaction": {
    "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg",
    "model": "gemini-3-flash-preview",
    "status": "in_progress",
    "created": "2025-12-04T15:01:45Z",
    "updated": "2025-12-04T15:01:45Z"
  },
  "event_id": "evt_123"
}

互動完成

{
  "event_type": "interaction.completed",
  "interaction": {
    "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg",
    "model": "gemini-3-flash-preview",
    "status": "completed",
    "created": "2025-12-04T15:01:45Z",
    "updated": "2025-12-04T15:01:45Z"
  },
  "event_id": "evt_123"
}

互動狀態更新

{
  "event_type": "interaction.status_update",
  "interaction_id": "v1_ChdTMjQ0YWJ5TUF1TzcxZThQdjRpcnFRcxIXUzI0NGFieU1BdU83MWU4UHY0aXJxUXM",
  "status": "in_progress"
}

錯誤事件

{
  "event_type": "error",
  "error": {
    "message": "Failed to get completed interaction: Result not found.",
    "code": "not_found"
  }
}

開始步驟

{
  "event_type": "step.start",
  "index": 0,
  "step": {
    "type": "model_output"
  }
}

步數差異

{
  "event_type": "step.delta",
  "index": 0,
  "delta": {
    "type": "text",
    "text": "Hello"
  }
}

Step Stop

{
  "event_type": "step.stop",
  "index": 0
}