Interactions API 總覽

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

為什麼要使用 Interactions API？

建構生成式 AI 應用程式和 Agentic Workflows 時，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 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 Search：使用 Parallel Web Systems 搜尋 API 提供的即時公開網路資料，建立模型回覆基準。
  • 執行程式碼：模型可在安全的沙箱環境中生成及執行 Python 程式碼。
  • 函式呼叫：模型可傳回結構化函式引數，連結至外部工具、API 和資料庫。

Interactions API 支援企業版網路基準建立和以 Google 搜尋建立基準。使用這些功能時，您也必須遵守服務專屬條款。

帳單

Interactions API 的費用是依據詞元用量計算。

如果要求中斷或未完成，系統會按照下列方式計費：

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

安全性與法規遵循

在預先發布版期間，Interactions API 有下列安全性、法規遵循和資料落地考量：

  • 安全性與法規遵循認證：Interactions API 預先發布版不支援 FedRAMP，也不符合美國國防部 (DoD) 影響等級 5 (IL5) 或國際武器貿易條例 (ITAR) 規定。
  • 客戶自行管理的加密金鑰 (CMEK)：Interactions API 支援儲存互動資料的 CMEK，方法是在 us 和 eu 多區域中，透過服務設定檔 (scope 設為 INTERACTIONS_API) 進行。
  • VPC Service Controls：Interactions API 預先發布版支援 VPC Service Controls (VPC-SC)，可保護 API 範圍。
  • 資料落地：Interactions API 預先發布版不支援資料落地，也不對工作階段儲存空間做出任何承諾。
  • 端點：Interactions API 預先發布版支援全域端點 (locations/global)，並在使用 CMEK 時支援 us 和 eu 多區域端點 (locations/us 和 locations/eu)。

支援的 SDK

您可以使用統一的 Google Gen AI SDK 或直接發出 REST 呼叫，存取 Interactions API：

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

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

後續步驟