互動 API

Interactions API 是使用 Gemini 模型和代理程式建構應用程式最簡單且最佳的方式。這項功能已於 2026 年 6 月正式推出，建議用於所有新專案。雖然現在已視為舊版，但原始的 generateContent API 仍完全支援。

為什麼要使用 Interactions API？

  • 適用於所有應用程式的通用介面：這個介面是為各種用途設計的標準介面，包括單輪文字生成、多模態理解、結構化輸出、工具自動化調度管理和代理式工作流程。
  • 單一模型和代理 API：透過單一整合式端點和模式，直接呼叫標準 Gemini 模型和專用代理 (例如 Deep Research 和自訂管理代理)。
  • 內建新功能：包括使用 previous_interaction_id 的選用伺服器端對話狀態、用於偵錯和 UI 算繪的可觀測執行步驟，以及使用 background=true 執行長時間工作時的背景執行。
  • 降低成本，提高快取命中率：使用多輪對話時，選用的伺服器端狀態管理功能可跨輪次更有效率地快取內容，進而降低權杖成本。
  • 新功能推出平台：今後所有新模型、多模態功能、工具和代理程式功能，都會在 Interactions API 上推出。

根據預設，Interactions API 會儲存要求，因此您可以使用 previous_interaction_id，運用伺服器端狀態管理功能。您可以設定 store=false，選擇採用無狀態行為。詳情請參閱「資料保留」一節。

開始使用

  • 設定程式設計代理：連線至 Gemini 文件 MCP 並安裝 gemini-interactions-api 技能，讓助理直接存取最新的開發人員文件和最佳做法。設定程式碼編寫代理 →
  • 從 generateContent 遷移：如果您已整合，請按照遷移指南的說明，改用 Interactions API。
  • 開始使用：請參閱互動式 API 入門指南。

功能指南

請參閱下列指南，瞭解 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 與背景執行不相容，且會禁止在後續回合中使用 previous_interaction_id。

如果是付費級專案，您可以在 AI Studio 中設定保留期限，讓系統在 7、14、28 或 55 天後，自動將記錄標示為從專案儲存空間中刪除。如果保留期限較短，可能無法擷取先前的對話。

您隨時可以使用 delete 方法以程式輔助方式刪除儲存的互動記錄，但必須提供互動 ID。您也可以在 AI Studio 中查看及管理儲存的互動記錄，包括從專案儲存空間刪除記錄。

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

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

在 AI Studio 中查看互動

API 會儲存透過 store=true 執行的 Interactions API 要求，適用於付費級別的專案。您可以直接在 Google AI Studio 的「記錄」頁面中查看。詳情請參閱「記錄檔指南」。

最佳做法

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

支援的模型和代理程式

模型名稱 類型 模型 ID
Gemini 3.5 Flash 模型 gemini-3.5-flash
Gemini 3.1 Pro 預先發布版 模型 gemini-3.1-pro-preview
Gemini 3.1 Flash-Lite 模型 gemini-3.1-flash-lite
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
Gemini 3 Pro Image 模型 gemini-3-pro-image
Gemini 3.1 Flash Image 模型 gemini-3.1-flash-image
Gemini 3.1 Flash TTS 預先發布版 模型 gemini-3.1-flash-tts-preview
Gemma 4 31B IT 模型 gemma-4-31b-it
Gemma 4 26B MoE IT 模型 gemma-4-26b-a4b-it
Lyria 3 剪輯片段預覽 模型 lyria-3-clip-preview
Lyria 3 Pro 預先發布版 模型 lyria-3-pro-preview
Deep Research 預先發布版 代理 deep-research-preview-04-2026
Deep Research 預先發布版 代理 deep-research-max-preview-04-2026
Antigravity 預覽 代理 antigravity-preview-05-2026

SDK

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

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

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

限制

  • 遠端 MCP：Gemini 3 不支援遠端 MCP，但這項功能即將推出。
  • 多輪模型相容性：在對話中混合使用不同模型 (無論是有狀態或無狀態)，後續模型必須支援先前模型的輸出模態做為輸入內容。舉例來說，如果使用 gemini-3.1-flash-image 生成圖片，就無法繼續與不接受圖片輸入內容的模型對話 (例如僅限文字的模型，或是 Lyria 這類音樂生成模型)。

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

意見回饋

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

後續步驟