Interactions API 總覽

Interactions API 提供統一的具狀態介面，可使用 Gemini 模型和 Gemini Enterprise Agent Platform 託管的代理程式，建構生成式 AI 應用程式和代理工作流程。雖然現有的 generateContent API 與 generateContent API 有功能重疊之處，但我們仍會全面支援 generateContent API。

為什麼要使用 Interactions API？

建構生成式 AI 應用程式和代理工作流程時，Interactions API 可提供下列主要優勢：

  • 模型和代理程式的單一 API：透過統一的端點和模式，直接呼叫標準 Gemini 模型和專用代理程式 (例如 Gemini Deep Research Agent 和自訂管理型代理程式)。
  • 全新功能：包括使用 previous_interaction_id 的選用伺服器端對話狀態、可觀測的執行步驟 (用於偵錯和 UI 算繪)，以及使用 background=true 執行長時間執行的工作。
  • 新功能推出平台：日後所有新模型、多模態功能、工具和代理程式功能，都將透過 Interactions API 提供支援。

Interactions API 的運作方式

Interactions API 的核心是 Interaction 資源。Interaction 代表對話或工作中的完整回合，並做為包含執行時間順序的會期記錄 steps：

  • user_input：輪流對話時提供的輸入訊息、多模態檔案或工具結果。使用 interactions.get 擷取的已儲存互動包含 user_input 步驟，可提供完整情境，而 interactions.create 回覆只會傳回該回合中生成的步驟。
  • thought：模型或代理程式在規劃回覆時生成的中間推論摘要。
  • 工具呼叫和結果步驟：用戶端或伺服器端工具的叫用和輸出內容 (例如 function_call 和 function_result)。
  • model_output：模型或代理程式產生的最終文字、結構化 JSON 或多模態內容。

呼叫 interactions.create 時，Agent Platform 會處理您的輸入內容、執行任何已設定的伺服器端工具或代理程式迴圈，並傳回產生的 Interaction 資源。如需 Python、TypeScript/JavaScript 和 REST 的程式碼範例，請參閱 Interactions API 開發人員指南。

支援的模型

下列 Gemini 模型支援 Interactions API：

按一下即可展開支援的機型

除了上述模型，Interactions API 還支援下列專業的多模態和音訊生成模型：

  • gemini-omni-flash-preview：高效能多模態模型，可透過對話生成及編輯影片，並控制電影效果。
  • lyria-3-clip-preview 和 lyria-3-pro-preview：生成音樂模型，可生成高傳真音訊片段和完整歌曲 (僅支援與 store=false 的無狀態互動)。

支援的代理程式

您可以透過 Interactions API 呼叫下列代理程式，方法是指定 agent 參數，而非 model：

  • antigravity-preview-05-2026：一般用途自主代理程式，可執行多步驟推論、程式設計、檔案作業和使用工具。
  • deep-research-preview-04-2026： Gemini Deep Research Agent 專為自主式多步驟網路研究和綜合分析而設計。
  • 在 Agent Platform 部署的自訂代管代理。

功能和規格

以下各節說明 Interactions API 的核心功能、技術規格和作業考量。

狀態管理

根據預設，Interactions API 會儲存要求，因此您可以使用 previous_interaction_id，運用伺服器端狀態管理功能。您可以設定 store=false，選擇無狀態行為。

支援的工具和建立基準

Interactions API 中的 Gemini 3 模型支援下列內建工具、基礎提供者和搜尋功能：

  • 以 Google 搜尋強化事實基礎和以企業適用的網路內容建立基準： 根據 Google 搜尋或以企業適用的網路內容建立基準，提供即時網路資訊，鞏固模型回覆的事實基礎。
  • Gemini Enterprise Agent Platform 的 Agent Search 和 RAG Engine：使用 Agent Search 和 RAG Engine，根據私人企業資料存放區和文件存放區，提供模型回覆內容。
  • xAI 搜尋：將模型連結至即時社群搜尋和知識基礎。
  • 平行搜尋：根據 Parallel Web Systems 搜尋 API 提供的即時公開網路資料，建立模型回覆基準。
  • 執行程式碼：模型可在安全的沙箱環境中生成及執行 Python 程式碼。
  • 函式呼叫：模型可傳回結構化函式引數，藉此連結至外部工具、API 和資料庫。

Interactions API 支援企業版適用的網頁基準功能，以及以 Google 搜尋強化事實基礎。使用這些功能時，還須遵守服務專屬條款。

帳單

系統會根據權杖用量，收取 Interactions API 使用費。

如果要求中斷或未完成，計費方式如下：

  • 手動取消：如果互動在完成前取消 (例如傳送取消要求)，系統會針對取消前消耗的權杖向您收費。
  • 要求失敗：如果互動要求因內部系統錯誤或後端故障而失敗，您不必支付失敗要求費用。

安全性與法規遵循

在預先發布版期間，使用 Interactions API 時請注意下列安全性、法規遵循和資料落地注意事項：

  • 安全與法規遵循認證：Interactions API 搶先版不支援 FedRAMP 或客戶管理的加密金鑰 (CMEK)，也不符合美國國防部 (DoD) 影響層級 5 (IL5) 或《國際武器貿易條例》(ITAR) 的規定。
  • VPC Service Controls：Interactions API 搶先版支援 VPC Service Controls (VPC-SC)，可保護 API 範圍。
  • 資料落地：Interactions API 搶先版不支援資料落地，也不會對工作階段儲存空間做出任何承諾。
  • 端點：Interactions API 預覽版僅支援全域端點 (locations/global)。

支援的 SDK

您可以透過統一的 Google Gen AI SDK 或直接 REST 呼叫，存取 Interactions API：

  • Python：google-genai 或更新版本2.3.0
  • TypeScript / JavaScript：@google/genai 版本 2.3.0 以上
  • 前往：google.golang.org/genai
  • Java：com.google.genai:google-genai

舊版 SDK (google-cloud-aiplatform、@google-cloud/vertexai 和 google-generativeai) 不支援 Interactions API。

後續步驟