Interactions API 總覽

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

為什麼要使用 Interactions API？

Interactions API 具備多項重要優勢，可協助建構生成式 AI 應用程式和 Agentic Workflows：

  • 模型和代理的單一 API：一個統一的端點和模式，可直接呼叫標準 Gemini 模型和專門代理 (例如 Gemini Deep Research 代理和自訂代管代理)。
  • 現成的新功能：可選用 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 支援 Enterprise 網路基準和以 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-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。

後續步驟