互動 API

Interactions API 是使用 Gemini 建構內容的新標準基本元素，建議用於所有新專案。這項功能經過最佳化，可支援代理工作流程、伺服器端狀態管理，以及複雜的多模態多輪對話。原始 generateContent API 仍完全支援。

為什麼要使用 Interactions API？

  • 伺服器端記錄管理：透過 previous_interaction_id 簡化多輪對話流程。伺服器預設會啟用狀態 (store=true)，但您可以設定 store=false，選擇無狀態行為。
  • 可觀察的執行步驟：輸入步驟可輕鬆偵錯複雜流程，並為中繼事件 (例如想法或搜尋小工具) 算繪 UI。
  • 專為代理功能工作流程打造：透過型別執行步驟，原生支援多步驟工具使用、自動調度管理和複雜的推論流程。
  • 長期執行的工作和背景工作：支援使用 background=true 將耗時的作業 (例如 Deep Think和 Deep Research) 卸載至背景程序。
  • 使用新模型和功能：未來，除了核心主線系列之外，新的模型以及新的代理能力和工具，都只會在 Interactions API 上推出。

如果您要啟動新專案、建構代理程式應用程式，或需要伺服器端對話管理功能，請使用 Interactions API。如果現有的整合功能符合需求，或需要 Interactions API 尚未提供的功能 (例如 Batch API 或明確快取)，請使用 generateContent。

開始使用

功能指南

請參閱下列指南，瞭解 Interactions API 的具體功能。您可以在這些頁面使用切換鈕，在 generateContent 和 Interactions API 之間切換：

Interactions API 的運作方式

Interactions API 的核心資源是 Interaction。Interaction 代表對話或工作中的完整回合。這份記錄會依時間順序記錄整個互動過程的執行步驟。這些步驟包括模型想法、伺服器端或用戶端工具呼叫和結果 (例如 function_call 和 function_result)，以及最終 model_output。儲存的資源 (透過 interactions.get 擷取) 也包含完整情境的 user_input 步驟，但 interactions.create 回應只會傳回模型生成的步驟。

呼叫 interactions.create 時，您會建立新的 Interaction 資源。

伺服器端狀態管理

您可以在後續呼叫中使用 previous_interaction_id 參數，藉此使用已完成互動的 id 繼續對話。伺服器會使用這個 ID 擷取對話記錄，因此您不必重新傳送整個對話記錄。

previous_interaction_id 參數只會使用 previous_interaction_id 保留對話記錄 (輸入和輸出內容)。其他參數則為互動範圍，且僅適用於目前產生的特定互動：

  • tools
  • system_instruction
  • generation_config (包括 thinking_level、temperature 等)

也就是說，如要套用這些參數，您必須在每次新互動中重新指定。這項伺服器端狀態管理功能為選用功能，您也可以在無狀態模式下運作，方法是在每個要求中傳送完整的對話記錄。

資料儲存與保留

根據預設，API 會儲存所有 Interaction 物件 (store=true)，以簡化伺服器端狀態管理功能 (使用 previous_interaction_id)、背景執行作業 (使用 background=true) 和觀測能力用途的使用。

  • 付費層級：系統會保留互動記錄 55 天。
  • 免費方案：系統會保留互動記錄 1 天。

如果不希望系統執行上述作業，可以在要求中設定 store=false。這項控制項與狀態管理功能無關，您可以選擇不儲存任何互動。不過請注意，store=false 與 background=true 不相容，且會禁止在後續回合使用 previous_interaction_id。

您隨時可以使用 API 參考資料中的刪除方法，刪除儲存的互動記錄。只有在知道互動 ID 的情況下，才能刪除互動。

超過保留期限後，系統會自動刪除資料。

系統會根據條款處理 Interaction 物件。

最佳做法

  • 快取命中率：使用 previous_interaction_id 繼續對話時，系統可以更輕鬆地運用對話記錄的隱含快取，進而提升效能並降低費用。
  • 混合互動：您可以在對話中彈性混合搭配代理程式和模型互動。舉例來說，您可以先使用 Deep Research 代理等專用代理收集初步資料，然後使用標準 Gemini 模型執行後續工作，例如摘要或重新格式化，並以 previous_interaction_id 連結這些步驟。

支援的模型和代理程式

模型名稱 類型 模型 ID
Gemini 3.1 Flash-Lite 型號 gemini-3.1-flash-lite
Gemini 3.1 Flash-Lite 預先發布版 型號 gemini-3.1-flash-lite-preview
Gemini 3 Pro 預先發布版 型號 gemini-3.1-pro-preview
Gemini 3 Flash 預先發布版 型號 gemini-3-flash-preview
Gemini 2.5 Pro 型號 gemini-2.5-pro
Gemini 2.5 Flash 型號 gemini-2.5-flash
Gemini 2.5 Flash-lite 型號 gemini-2.5-flash-lite
Lyria 3 剪輯片段預覽 型號 lyria-3-clip-preview
Lyria 3 Pro 預先發布版 型號 lyria-3-pro-preview
Deep Research 預先發布版 代理 deep-research-pro-preview-12-2025
Deep Research 預先發布版 代理 deep-research-preview-04-2026
Deep Research 預先發布版 代理 deep-research-max-preview-04-2026

SDK

您可以使用最新版的 Google GenAI SDK，存取 Interactions API。

  • 在 Python 中，這是 1.55.0 版本以上的 google-genai 套件。
  • 在 JavaScript 中，這是 @google/genai 套件的 1.33.0 版本。

如要進一步瞭解如何安裝 SDK，請參閱「程式庫」頁面。

限制

  • Beta 版狀態：Interactions API 目前為 Beta 版/搶先體驗版。功能和結構定義可能會有所異動。
  • 遠端 MCP：Gemini 3 不支援遠端 MCP，但這項功能即將推出。

generateContent API 支援下列功能，但 Interactions API 尚未提供：

破壞性變更

目前 Interactions API 處於早期 Beta 版階段。我們會根據實際使用情況和開發人員意見回饋，積極開發及改良 API 功能、資源結構定義和 SDK 介面。

因此可能會發生破壞性變更。 更新內容可能包括：

  • 輸入和輸出內容的結構定義。
  • SDK 方法簽章和物件結構。
  • 特定功能行為。

如為正式版工作負載，請繼續使用標準 generateContent API。這仍是穩定部署的建議做法，我們會繼續積極開發及維護。

意見回饋

您的意見回饋對 Interactions API 的開發至關重要。歡迎前往 Google AI 開發人員社群論壇分享想法、回報錯誤或提出功能要求。

後續步驟