Gemini API

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

建立互動

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

建立新的互動。

要求主體

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

model ModelOption  (選用)

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

可能的值:

  • gemini-2.5-pro

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

  • gemini-2.5-flash

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

  • gemini-2.5-flash-preview-09-2025

    以 2.5 Flash 模型為基礎的最新模型。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-preview-native-audio-dialog

    我們的原生語音模型經過最佳化調整,可以輸出更優質的音訊,在節奏、語音自然程度、詳細程度和情緒方面都更為出色。

  • gemini-2.5-flash-image-preview

    我們原生的圖像生成模型,經過最佳化調整,可提升速度、彈性和背景資訊理解能力。文字輸入和輸出內容的價格與 2.5 Flash 相同。

  • gemini-2.5-pro-preview-tts

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

  • gemini-3-pro-preview

    這是 Google 最聰明的模型,具備最先進的推論和多模態理解能力,以及強大的代理功能和直覺式程式開發功能。

用來完成提示的模型。\n\n 如需更多詳細資料,請參閱 [模型](https://ai.google.dev/gemini-api/docs/models)。

agent AgentOption  (optional)

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

可能的值:

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

    Gemini Deep Research Agent

要互動的代理程式。

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

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

system_instruction 字串  (選用)

互動的系統指令。

tools 陣列 (Tool)  (選用)

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

response_format object  (選用)

強制生成的 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 整數  (選用)

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

stop_sequences 陣列 (字串)  (選用)

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

tool_choice ToolChoice  (選用)

互動使用的工具。

工具選擇的設定。

可能類型

ToolChoiceType

這類項目沒有特定欄位。

ToolChoiceConfig

allowed_tools AllowedTools  (選用)

未提供說明。

允許使用的工具設定。

欄位

mode ToolChoiceType  (optional)

工具選擇模式。

可能的值:

  • auto
  • any
  • none
  • validated

tools 陣列 (字串)  (選填)

允許使用的工具名稱。

thinking_level ThinkingLevel  (選用)

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

可能的值:

  • low
  • high

thinking_summaries ThinkingSummaries  (選用)

是否要在回覆中加入思考摘要。

可能的值:

  • auto
  • none

max_output_tokens integer  (選用)

回覆中可納入的詞元數量上限。

speech_config SpeechConfig  (optional)

語音互動設定。

語音互動的設定。

欄位

voice string  (選填)

說話者的聲音。

language string  (選用)

語音的語言。

speaker string  (選填)

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

agent_config object  (optional)

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

可能類型

多型鑑別器:type

DynamicAgentConfig

動態代理程式的設定。

type string  (選填)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "dynamic"

DeepResearchAgentConfig

Deep Research 代理的設定。

type string  (選填)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "deep-research"

thinking_summaries ThinkingSummaries  (選用)

是否要在回覆中加入思考摘要。

可能的值:

  • auto
  • none

previous_interaction_id 字串  (選用)

先前的互動 ID (如有)。

response_modalities ResponseModality  (optional)

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

可能的值:

  • text
  • image
  • audio

回應

傳回 Interaction 資源。

簡單要求

回應範例

{
  "created": "2025-11-26T12:25:15Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-2.5-flash",
  "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_reasoning_tokens": 22,
    "total_tokens": 49,
    "total_tool_use_tokens": 0
  }
}

多輪

回應範例

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-2.5-flash",
  "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_reasoning_tokens": 0,
    "total_tokens": 60,
    "total_tool_use_tokens": 0
  }
}

輸入圖片

回應範例

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-2.5-flash",
  "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_reasoning_tokens": 0,
    "total_tokens": 288,
    "total_tool_use_tokens": 0
  }
}

函式呼叫

回應範例

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-2.5-flash",
  "status": "requires_action",
  "object": "interaction",
  "created": "2025-11-26T12:22:47Z",
  "updated": "2025-11-26T12:22:47Z",
  "role": "model",
  "outputs": [
    {
      "type": "function_call",
      "function_call": {
        "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_reasoning_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": "model",
  "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_reasoning_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 時才能使用。

api_version 字串  (選用)

要使用的 API 版本。

回應

傳回 Interaction 資源。

取得互動

回應範例

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-2.5-flash",
  "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?"
    }
  ]
}

刪除互動

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

依 ID 刪除互動。

路徑 / 查詢參數

id string  (必要)

要刪除的互動專屬 ID。

api_version 字串  (選用)

要使用的 API 版本。

回應

如果成功,回應會留白。

刪除互動

取消互動

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

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

路徑 / 查詢參數

id string  (必要)

要擷取的互動專屬 ID。

api_version 字串  (選用)

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

資源

互動

Interaction 資源。

欄位

model ModelOption  (選用)

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

可能的值:

  • gemini-2.5-pro

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

  • gemini-2.5-flash

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

  • gemini-2.5-flash-preview-09-2025

    以 2.5 Flash 模型為基礎的最新模型。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-preview-native-audio-dialog

    我們的原生語音模型經過最佳化調整,可以輸出更優質的音訊,在節奏、語音自然程度、詳細程度和情緒方面都更為出色。

  • gemini-2.5-flash-image-preview

    我們原生的圖像生成模型,經過最佳化調整,可提升速度、彈性和背景資訊理解能力。文字輸入和輸出內容的價格與 2.5 Flash 相同。

  • gemini-2.5-pro-preview-tts

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

  • gemini-3-pro-preview

    這是 Google 最聰明的模型,具備最先進的推論和多模態理解能力,以及強大的代理功能和直覺式程式開發功能。

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

agent AgentOption  (選填)

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

可能的值:

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

    Gemini Deep Research Agent

要互動的代理程式。

id string  (選用)

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

status enum (string)  (optional)

僅供輸出。互動狀態。

可能的值:

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

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

updated string  (選填)

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

role string  (選填)

僅供輸出。互動的角色。

outputs 陣列 (Content)  (選填)

僅供輸出。模型的回覆。

object string  (選用)

僅供輸出。互動的物件類型。一律設為 `interaction`。

一律設為 "interaction"

usage Usage  (選填)

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

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

欄位

total_input_tokens integer  (optional)

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

input_tokens_by_modality ModalityTokens  (optional)

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

單一回覆模式的權杖數量。

欄位

modality ResponseModality  (optional)

與權杖數相關聯的模態。

可能的值:

  • text
  • image
  • audio

tokens 整數  (選填)

模態的權杖數量。

total_cached_tokens integer  (optional)

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

cached_tokens_by_modality ModalityTokens  (optional)

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

單一回覆模式的權杖數量。

欄位

modality ResponseModality  (optional)

與權杖數相關聯的模態。

可能的值:

  • text
  • image
  • audio

tokens 整數  (選填)

模態的權杖數量。

total_output_tokens 整數  (選用)

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

output_tokens_by_modality ModalityTokens  (選用)

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

單一回覆模態的權杖數量。

欄位

modality ResponseModality  (optional)

與權杖數相關聯的模態。

可能的值:

  • text
  • image
  • audio

tokens 整數  (選填)

模態的權杖數量。

total_tool_use_tokens integer  (optional)

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

tool_use_tokens_by_modality ModalityTokens  (選用)

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

單一回覆模態的權杖數量。

欄位

modality ResponseModality  (optional)

與權杖數相關聯的模態。

可能的值:

  • text
  • image
  • audio

tokens 整數  (選填)

模態的權杖數量。

total_reasoning_tokens integer  (選用)

思考模型思考時的權杖數量。

total_tokens 整數  (選用)

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

previous_interaction_id 字串  (選用)

先前的互動 ID (如有)。

範例

範例

{
  "created": "2025-12-04T15:01:45Z",
  "id": "v1_ChdXS0l4YWZXTk9xbk0xZThQczhEcmlROBIXV0tJeGFmV05PcW5NMWU4UHM4RHJpUTg",
  "model": "gemini-2.5-flash",
  "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_reasoning_tokens": 49,
    "total_tokens": 79,
    "total_tool_use_tokens": 0
  }
}

資料模型

內容

回覆內容。

可能類型

多型鑑別器:type

TextContent

文字內容區塊。

text string  (選填)

文字內容。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "text"

annotations Annotation  (optional)

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

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

欄位

start_index 整數  (選用)

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

end_index 整數  (選用)

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

source string  (選填)

歸因於部分文字的來源。可以是網址、標題或其他 ID。

ImageContent

圖片內容區塊。

data string  (選填)

未提供說明。

uri string  (選填)

未提供說明。

mime_type ImageMimeTypeOption  (optional)

未提供說明。

可能的值:

  • image/png
  • image/jpeg
  • image/webp
  • image/heic
  • image/heif

圖片的 MIME 類型。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "image"

resolution MediaResolution  (optional)

媒體的解析度。

可能的值:

  • low
  • medium
  • high

AudioContent

音訊內容區塊。

data string  (選填)

未提供說明。

uri string  (選填)

未提供說明。

mime_type AudioMimeTypeOption  (optional)

未提供說明。

可能的值:

  • audio/wav
  • audio/mp3
  • audio/aiff
  • audio/aac
  • audio/ogg
  • audio/flac

音訊的 MIME 類型。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "audio"

DocumentContent

文件內容區塊。

data string  (選填)

未提供說明。

uri string  (選填)

未提供說明。

mime_type 字串  (選用)

未提供說明。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "document"

VideoContent

影片內容區塊。

data string  (選填)

未提供說明。

uri string  (選填)

未提供說明。

mime_type VideoMimeTypeOption  (optional)

未提供說明。

可能的值:

  • video/mp4
  • video/mpeg
  • video/mov
  • video/avi
  • video/x-flv
  • video/mpg
  • video/webm
  • video/wmv
  • video/3gpp

影片的 MIME 類型。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "video"

resolution MediaResolution  (optional)

媒體的解析度。

可能的值:

  • low
  • medium
  • high

ThoughtContent

想法內容區塊。

簽章 字串  (選填)

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

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "thought"

摘要 ThoughtSummary  (選填)

想法摘要。

想法摘要。

FunctionCallContent

函式工具呼叫內容區塊。

name string  (必要)

要呼叫的工具名稱。

引數 object  (必填)

要傳遞至函式的引數。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "function_call"

id string  (必要)

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

FunctionResultContent

函式工具結果內容區塊。

名稱 字串  (選用)

所呼叫工具的名稱。

is_error boolean  (optional)

工具呼叫是否發生錯誤。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "function_result"

結果 物件或字串  (必要)

工具呼叫的結果。

call_id string  (必要)

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

CodeExecutionCallContent

程式碼執行內容。

arguments CodeExecutionCallArguments  (選用)

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

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

欄位

language enum (string)  (optional)

`code` 的程式設計語言。

可能的值:

  • python
code string  (選填)

要執行的程式碼。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "code_execution_call"

id string  (選用)

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

CodeExecutionResultContent

程式碼執行結果內容。

result string  (選用)

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

is_error boolean  (optional)

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

簽章 字串  (選填)

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

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "code_execution_result"

call_id string  (optional)

與程式碼執行呼叫區塊中的 ID 相符的 ID。

UrlContextCallContent

網址背景資訊內容。

arguments UrlContextCallArguments  (optional)

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

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

欄位

urls 陣列 (字串)  (選填)

要擷取的網址。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "url_context_call"

id string  (選用)

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

UrlContextResultContent

網址背景資訊結果內容。

簽章 字串  (選填)

網址內容結果的簽章。

result UrlContextResult  (選填)

網址環境的結果。

網址環境的結果。

欄位

url string  (optional)

擷取的網址。

status enum (string)  (optional)

網址擷取狀態。

可能的值:

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

網址環境是否發生錯誤。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "url_context_result"

call_id string  (optional)

與網址內容呼叫區塊中的 ID 相符的 ID。

GoogleSearchCallContent

Google 搜尋內容。

arguments GoogleSearchCallArguments  (optional)

要傳遞給 Google 搜尋的引數。

要傳遞給 Google 搜尋的引數。

欄位

queries array (string)  (optional)

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

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "google_search_call"

id string  (選用)

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

GoogleSearchResultContent

Google 搜尋結果內容。

簽章 字串  (選填)

Google 搜尋結果的簽章。

result GoogleSearchResult  (optional)

Google 搜尋結果。

Google 搜尋結果。

欄位

url string  (optional)

搜尋結果的 URI 參照。

title string  (選用)

搜尋結果的標題。

rendered_content string  (選用)

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

is_error boolean  (optional)

Google 搜尋是否發生錯誤。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "google_search_result"

call_id string  (optional)

ID,與 Google 搜尋通話封鎖的 ID 相符。

McpServerToolCallContent

MCPServer 工具呼叫內容。

name string  (必要)

所呼叫工具的名稱。

server_name string  (required)

所用 MCP 伺服器的名稱。

引數 object  (必填)

函式引數的 JSON 物件。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "mcp_server_tool_call"

id string  (必要)

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

McpServerToolResultContent

MCPServer 工具結果內容。

name string  (optional)

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

server_name string  (選用)

所用 MCP 伺服器的名稱。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "mcp_server_tool_result"

結果 物件或字串  (必要)

工具呼叫的結果。

call_id string  (必要)

ID,與 MCP 伺服器工具呼叫區塊中的 ID 相符。

FileSearchResultContent

檔案搜尋結果內容。

result FileSearchResult  (optional)

檔案搜尋結果。

檔案搜尋結果。

欄位

title string  (選用)

搜尋結果的標題。

text string  (選填)

搜尋結果的文字。

file_search_store string  (optional)

檔案搜尋商店的名稱。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "file_search_result"

範例

文字

{
  "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": "function_result",
  "name": "get_weather",
  "call_id": "gth23981",
  "result": {
    "weather": "sunny"
  }
}

程式碼執行呼叫

{
  "type": "code_execution_call",
  "id": "call_123456",
  "arguments": {
    "language": "python",
    "code": "print('hello world')"
  }
}

程式碼執行結果

{
  "type": "code_execution_result",
  "call_id": "call_123456",
  "result": "hello world\n"
}

網址背景資訊呼叫

{
  "type": "url_context_call",
  "id": "call_123456",
  "arguments": {
    "urls": [
      "https://www.example.com"
    ]
  }
}

網址背景資訊結果

{
  "type": "url_context_result",
  "call_id": "call_123456",
  "result": [
    {
      "url": "https://www.example.com",
      "status": "SUCCESS"
    }
  ]
}

Google 搜尋電話

{
  "type": "google_search_call",
  "id": "call_123456",
  "arguments": {
    "queries": [
      "weather in Boston"
    ]
  }
}

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_call",
  "id": "call_123456",
  "name": "get_forecast",
  "server_name": "weather_server",
  "arguments": {
    "city": "London"
  }
}

MCP 伺服器工具結果

{
  "type": "mcp_server_tool_result",
  "name": "get_forecast",
  "server_name": "weather_server",
  "call_id": "call_123456",
  "result": "sunny"
}

檔案搜尋結果

{
  "type": "file_search_result",
  "result": [
    {
      "text": "search result chunk",
      "file_search_store": "file_search_store"
    }
  ]
}

工具

可能類型

多型鑑別器:type

功能

模型可使用的工具。

名稱 字串  (選用)

函式名稱。

description string  (選用)

函式說明。

parameters object  (選用)

函式參數的 JSON 結構定義。

類型 字串  (必要)

未提供說明。

一律設為 "function"

GoogleSearch

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

類型 字串  (必要)

未提供說明。

一律設為 "google_search"

CodeExecution

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

類型 字串  (必要)

未提供說明。

一律設為 "code_execution"

UrlContext

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

類型 字串  (必要)

未提供說明。

一律設為 "url_context"

ComputerUse

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

類型 字串  (必要)

未提供說明。

一律設為 "computer_use"

environment enum (string)  (optional)

運作中的環境。

可能的值:

  • browser
excludedPredefinedFunctions array (string)  (optional)

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

McpServer

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

類型 字串  (必要)

未提供說明。

一律設為 "mcp_server"

名稱 字串  (選用)

MCPServer 的名稱。

url string  (optional)

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

headers object  (選填)

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

allowed_tools AllowedTools  (選用)

允許使用的工具。

允許使用的工具設定。

欄位

mode ToolChoiceType  (optional)

工具選擇模式。

可能的值:

  • auto
  • any
  • none
  • validated

tools 陣列 (字串)  (選填)

允許使用的工具名稱。

FileSearch

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

file_search_store_names array (string)  (optional)

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

top_k 整數  (選用)

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

metadata_filter string  (選用)

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

類型 字串  (必要)

未提供說明。

一律設為 "file_search"

範例

函式

GoogleSearch

CodeExecution

UrlContext

ComputerUse

McpServer

FileSearch

啟用或停用

欄位

role string  (選填)

這個回合的發起者。必須是模型輸入的使用者或模型輸出。

content 陣列 (Content) 或字串  (選用)

輪流對話的內容。

範例

使用者回合

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "user turn"
    }
  ]
}

Model Turn

{
  "role": "model",
  "content": [
    {
      "type": "text",
      "text": "model turn"
    }
  ]
}

InteractionSseEvent

可能類型

多型鑑別器:event_type

InteractionEvent

event_type enum (string)  (optional)

未提供說明。

可能的值:

  • interaction.start
  • interaction.complete
互動 互動  (選填)

未提供說明。

event_id string  (選用)

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

InteractionStatusUpdate

interaction_id string  (選用)

未提供說明。

status enum (string)  (選用)

未提供說明。

可能的值:

  • in_progress
  • requires_action
  • completed
  • failed
  • cancelled
event_type string  (選用)

未提供說明。

一律設為 "interaction.status_update"

event_id string  (選用)

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

ContentStart

index integer  (選填)

未提供說明。

content 內容  (選填)

未提供說明。

event_type string  (選用)

未提供說明。

一律設為 "content.start"

event_id string  (選用)

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

ContentDelta

index integer  (選填)

未提供說明。

event_type string  (選用)

未提供說明。

一律設為 "content.delta"

event_id string  (選用)

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

delta object  (選填)

未提供說明。

可能類型

多型鑑別器:type

TextDelta

text string  (選填)

未提供說明。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "text"

annotations Annotation  (optional)

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

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

欄位

start_index 整數  (選用)

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

end_index 整數  (選用)

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

source string  (選填)

歸因於部分文字的來源。可以是網址、標題或其他 ID。

ImageDelta

data string  (選填)

未提供說明。

uri string  (選填)

未提供說明。

mime_type ImageMimeTypeOption  (optional)

未提供說明。

可能的值:

  • image/png
  • image/jpeg
  • image/webp
  • image/heic
  • image/heif

圖片的 MIME 類型。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "image"

resolution MediaResolution  (optional)

媒體的解析度。

可能的值:

  • low
  • medium
  • high

AudioDelta

data string  (選填)

未提供說明。

uri string  (選填)

未提供說明。

mime_type AudioMimeTypeOption  (optional)

未提供說明。

可能的值:

  • audio/wav
  • audio/mp3
  • audio/aiff
  • audio/aac
  • audio/ogg
  • audio/flac

音訊的 MIME 類型。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "audio"

DocumentDelta

data string  (選填)

未提供說明。

uri string  (選填)

未提供說明。

mime_type 字串  (選用)

未提供說明。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "document"

VideoDelta

data string  (選填)

未提供說明。

uri string  (選填)

未提供說明。

mime_type VideoMimeTypeOption  (optional)

未提供說明。

可能的值:

  • video/mp4
  • video/mpeg
  • video/mov
  • video/avi
  • video/x-flv
  • video/mpg
  • video/webm
  • video/wmv
  • video/3gpp

影片的 MIME 類型。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "video"

resolution MediaResolution  (optional)

媒體的解析度。

可能的值:

  • low
  • medium
  • high

ThoughtSummaryDelta

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "thought_summary"

content ImageContentTextContent  (選填)

未提供說明。

ThoughtSignatureDelta

簽章 字串  (選填)

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

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "thought_signature"

FunctionCallDelta

名稱 字串  (選用)

未提供說明。

arguments object  (選填)

未提供說明。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "function_call"

id string  (選用)

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

FunctionResultDelta

名稱 字串  (選用)

未提供說明。

is_error boolean  (optional)

未提供說明。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "function_result"

結果 物件或字串  (選用)

工具呼叫結果差異。

call_id string  (optional)

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

CodeExecutionCallDelta

arguments CodeExecutionCallArguments  (選用)

未提供說明。

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

欄位

language enum (string)  (optional)

`code` 的程式設計語言。

可能的值:

  • python
code string  (選填)

要執行的程式碼。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "code_execution_call"

id string  (選用)

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

CodeExecutionResultDelta

result string  (選用)

未提供說明。

is_error boolean  (optional)

未提供說明。

簽章 字串  (選填)

未提供說明。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "code_execution_result"

call_id string  (optional)

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

UrlContextCallDelta

arguments UrlContextCallArguments  (optional)

未提供說明。

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

欄位

urls 陣列 (字串)  (選填)

要擷取的網址。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "url_context_call"

id string  (選用)

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

UrlContextResultDelta

簽章 字串  (選填)

未提供說明。

result UrlContextResult  (選填)

未提供說明。

網址環境的結果。

欄位

url string  (optional)

擷取的網址。

status enum (string)  (optional)

網址擷取狀態。

可能的值:

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

未提供說明。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "url_context_result"

call_id string  (optional)

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

GoogleSearchCallDelta

arguments GoogleSearchCallArguments  (optional)

未提供說明。

要傳遞給 Google 搜尋的引數。

欄位

queries array (string)  (optional)

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

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "google_search_call"

id string  (選用)

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

GoogleSearchResultDelta

簽章 字串  (選填)

未提供說明。

result GoogleSearchResult  (optional)

未提供說明。

Google 搜尋結果。

欄位

url string  (optional)

搜尋結果的 URI 參照。

title string  (選用)

搜尋結果的標題。

rendered_content string  (選用)

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

is_error boolean  (optional)

未提供說明。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "google_search_result"

call_id string  (optional)

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

McpServerToolCallDelta

name string  (optional)

未提供說明。

server_name string  (選用)

未提供說明。

arguments object  (選填)

未提供說明。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "mcp_server_tool_call"

id string  (選用)

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

McpServerToolResultDelta

名稱 字串  (選用)

未提供說明。

server_name string  (選用)

未提供說明。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "mcp_server_tool_result"

結果 物件或字串  (選用)

工具呼叫結果差異。

call_id string  (optional)

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

FileSearchResultDelta

result FileSearchResult  (optional)

未提供說明。

檔案搜尋結果。

欄位

title string  (選用)

搜尋結果的標題。

text string  (選填)

搜尋結果的文字。

file_search_store string  (optional)

檔案搜尋商店的名稱。

類型 字串  (必要)

用做內容 oneof 的 OpenAPI 類型鑑別器。

一律設為 "file_search_result"

ContentStop

index integer  (選填)

未提供說明。

event_type string  (選用)

未提供說明。

一律設為 "content.stop"

event_id string  (選用)

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

ErrorEvent

event_type string  (選用)

未提供說明。

一律設為 "error"

error Error  (optional)

未提供說明。

互動中的錯誤訊息。

欄位

code string  (選填)

用於識別錯誤類型的 URI。

message string  (選填)

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

event_id string  (選用)

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

範例

互動開始

{
  "event_type": "interaction.start",
  "interaction": {
    "id": "v1_ChdTMjQ0YWJ5TUF1TzcxZThQdjRpcnFRcxIXUzI0NGFieU1BdU83MWU4UHY0aXJxUXM",
    "model": "gemini-2.5-flash",
    "object": "interaction",
    "status": "in_progress"
  }
}

互動完成

{
  "event_type": "interaction.complete",
  "interaction": {
    "created": "2025-12-09T18:45:40Z",
    "id": "v1_ChdTMjQ0YWJ5TUF1TzcxZThQdjRpcnFRcxIXUzI0NGFieU1BdU83MWU4UHY0aXJxUXM",
    "model": "gemini-2.5-flash",
    "object": "interaction",
    "outputs": [
      {
        "signature": "CoMDAXLI2nynRYojJIy6B1Jh9os2crpWLfB0+19xcLsGG46bd8wjkF/6RNlRUdvHrXyjsHkG0BZFcuO/bPOyA6Xh5jANNgx82wPHjGExN8A4ZQn56FlMwyZoqFVQz0QyY1lfibFJ2zU3J87uw26OewzcuVX0KEcs+GIsZa3EA6WwqhbsOd3wtZB3Ua2Qf98VAWZTS5y/tWpql7jnU3/CU7pouxQr/Bwft3hwnJNesQ9/dDJTuaQ8Zprh9VRWf1aFFjpIueOjBRrlT3oW6/y/eRl/Gt9BQXCYTqg/38vHFUU4Wo/d9dUpvfCe/a3o97t2Jgxp34oFKcsVb4S5WJrykIkw+14DzVnTpCpbQNFckqvFLuqnJCkL0EQFtunBXI03FJpPu3T1XU6id8S7ojoJQZSauGUCgmaLqUGdMrd08oo81ecoJSLs51Re9N/lISGmjWFPGpqJLoGq6uo4FHz58hmeyXCgHG742BHz2P3MiH1CXHUT2J8mF6zLhf3SR9Qb3lkrobAh",
        "type": "thought"
      },
      {
        "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",
        "type": "text"
      },
      {
        "text": " for one beloved anomaly: a chipped porcelain teacup, inherited from her grandmother, which held her morning Earl Grey.\n\nOne Tuesday, stirring her tea, Elara paused. At the bottom, nestled against the porcelain, was a star.",
        "type": "text"
      },
      {
        "text": " Not a star-shaped tea leaf, but a miniature, perfectly formed celestial body, radiating a faint, cool luminescence. Before she could gasp, it dissolved, leaving only the amber swirl of her brew. She dismissed it as a trick of",
        "type": "text"
      },
      {
        "text": " tired eyes.\n\nBut the next morning, a gossamer-thin feather, smaller than an eyelash and shimmering with iridescent hues, floated on the surface. It vanished the moment she tried to touch it. A week later, a single,",
        "type": "text"
      },
      {
        "text": " impossibly delicate bloom, like spun moonbeam, unfolded in her cup before fading into nothingness.\n\nThese weren't illusions. Each day, Elara\u2019s chipped teacup offered a fleeting, exquisite secret. A tiny, perfect",
        "type": "text"
      },
      {
        "text": " crystal, a miniature spiral nebula, a fragment of rainbow caught in liquid form. They never lingered, never accumulated, simply *were* and then *weren't*, leaving behind a residue of quiet wonder.\n\nElara never spoke",
        "type": "text"
      },
      {
        "text": " of it. It was her private wellspring, a daily reminder that magic could exist in the smallest, most overlooked corners of the world. Her routine remained unchanged, her external life a picture of calm, but inside, a secret garden blo",
        "type": "text"
      },
      {
        "text": "omed. Each dawn brought not just tea, but the silent promise of extraordinary beauty, waiting patiently in a chipped teacup.",
        "type": "text"
      }
    ],
    "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_reasoning_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"
  }
}