互動 API

Interactions API 是我們推出的全新介面，也是使用 Gemini 模型和代理建構應用程式最直接的方式。2026 年 6 月起，這個介面將全面開放使用，並成為所有新專案的建議介面。

雖然現在已視為舊版，但原始的 generateContent API 仍完全支援。

為什麼要使用 Interactions API？

  • 全新功能開箱即用：使用 previous_interaction_id 選擇性地在伺服器端儲存對話狀態、可觀察的執行步驟，用於偵錯和 UI 算繪，以及使用 background=true 在背景執行長時間執行的工作。
  • 提高快取命中率，降低成本：伺服器端狀態管理可提高回合間的內容快取效率，進而降低多輪對話的權杖成本。
  • 專為前沿模型和代理而建：專為思考模型、多步驟工具使用和複雜的推論流程而建，可簡化代理應用程式的建構、偵錯和自動調度管理程序。
  • 模型和代理程式的單一 API：透過統一介面直接呼叫 Gemini 模型和代理程式，例如 Deep Research 和自訂管理代理程式，不必學習個別端點或模式。
  • 新功能推出平台：未來，除了核心主線系列，新的模型和功能，以及新的代理能力和工具，都會在 Interactions API 上推出。

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

開始使用

  • 設定程式設計代理：連線至 Gemini 文件 MCP 並安裝 gemini-interactions-api 技能，讓助理直接存取最新的開發人員文件和最佳做法。設定程式碼編寫代理 →
  • 從 generateContent 遷移：如果您已整合，請按照遷移指南的說明，改用 Interactions API。
  • 開始使用：請參閱Interactions 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 與 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.1 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
Antigravity 預覽 代理 antigravity-preview-05-2026

SDK

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

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

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

限制

  • 遠端 MCP：Gemini 3 不支援遠端 MCP，但這項功能即將推出。

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

意見回饋

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

後續步驟