Interactions API 提供統一的有狀態介面,可使用 Gemini Enterprise Agent Platform 託管的 Gemini 模型和 Agentic Workflows,建構生成式 AI 應用程式和代理工作流程。generateContent API 仍與 Interactions API 一起提供完整支援。
為什麼要使用 Interactions API?
Interactions API 在建構生成式 AI 應用程式和 Agentic Workflows 方面,具備幾項主要優勢:
- 模型和代理的單一 API:一個統一的端點和模式,可直接呼叫標準 Gemini 模型和專門代理 (例如 Gemini Deep Research 代理和自訂代管代理)。
- 現成的新功能:包括使用
previous_interaction_id的選用伺服器端對話狀態、用於偵錯和 UI 轉譯的可觀測執行步驟,以及使用background=true的長時間執行工作背景執行。
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:
按一下即可展開支援的模型
- Gemini Omni Flash
- Gemini Omni 1.2 Flash
- Gemini Omni 1.1 Flash
- Gemini 4 Hydrogen
- Gemini 4 Carbon for cyber
- Gemini 4 Carbon
- Gemini 4 Argon Cyber Permissive
- Gemini 4 Argon
- Gemini 3.8 Flash Cyber
- Gemini 3.8 Flash
- Gemini 3.7 Flash
- Gemini 3.6 Flash
- Gemini 3.5 Flash-Lite
- Gemini 3.5 Flash
- Gemini 3.1 Pro
- Gemini 3.1 Flash-Lite
除了上述清單中的 Gemini 模型外,Interactions API 也支援下列生成式音樂模型:
* 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 會將互動內容儲存在伺服器 (store=true) 7 天,以便您使用 previous_interaction_id 串連多輪對話,並執行非同步背景工作 (background=true)。如要選擇無狀態執行,並支援零資料保留 (ZDR) 工作流程,請設定 store=false。詳情請參閱「管理工作階段儲存空間和對話狀態」。
要求和多模態限制
Interactions API 會強制執行下列要求酬載和多模態輸入限制:
- 要求酬載限制:同步和串流
interactions.create要求的壓縮 HTTP 要求酬載不得超過 256 MiB。如果service_tier設為deferred(background和store都必須為true),未壓縮的要求不得超過 9.75 MiB。 - Cloud Storage 檔案的 URI 限制:標準 Gemini 模型互動要求支援每項要求最多 100 個不同的 Cloud Storage (
gs://) URI,包括透過previous_interaction_id從先前對話回合沿用的 URI。代管代理互動、Gemini Omni 模型和 Lyria 3 模型不受這項 100 個 URI 的限制。如要瞭解權限和多輪 URI 處理方式,請參閱「存取上傳的 Cloud Storage 檔案」。 - 多模態項目和詞元限制:標準 Gemini 模型接受的各模態項目數量與
generateContent相同 (最多 3,000 張圖片和 PDF 檔案、1,000 個音訊檔案、10 部影片,以及最多 6,500 個多模態檔案,包括純文字檔案),受限於模型的 1,048,576 個詞元脈絡窗口。個別 Cloud Storage 檔案不得超過 2 GiB 減 500 KiB,公開 HTTP 或 HTTPS 網址不得超過 15 MiB。如要在單一要求中傳送超過 100 個檔案,請在要求酬載限制內傳遞其他內嵌附件,或呼叫generateContent。
支援的工具和建立基準
Interactions API 中的 Gemini 3 模型支援下列內建工具、基準建立服務供應商和搜尋功能:
- 以 Google 搜尋建立基準和以企業適用的網路內容建立基準:使用 Google 搜尋或企業適用的網路內容建立基準,根據即時網路資訊建立模型回覆基準。
- Gemini Enterprise Agent Platform 的 Agent Search 和 RAG Engine:使用 Agent Search 和 RAG Engine,以私人企業資料儲存庫和文件存放區為基準,生成模型回覆。
- Exa 網頁搜尋:使用 Exa 搜尋 API 的網頁搜尋結果,建立模型回覆的基準。
- Parallel Web Search:使用 Parallel Web Systems 搜尋 API 提供的即時公開網路資料,建立模型回覆基準。
- 網址背景資訊:擷取並分析提示詞中公開網頁網址的內容。
- 執行程式碼:模型可在安全的沙箱環境中生成及執行 Python 程式碼。
- 電腦使用:啟用瀏覽器和使用者介面自動化工作流程。
- 呼叫函式:模型可傳回結構化函式引數,連結至外部工具、API 和資料庫。
Interactions API 支援 Enterprise 網路基準建立和以 Google 搜尋強化事實基礎。使用這些功能時,也必須遵守服務專屬條款。
帳單
Interactions API 的費用是依據詞元用量計算。
中斷或未完成的要求,計費方式如下:
- 手動取消:如果在互動完成前取消 (例如傳送取消要求),系統會依據取消前耗用的權杖數量收費。
- 失敗的要求:如果互動要求因內部系統錯誤或後端失敗而失敗,您不需支付失敗要求的費用。
安全性與法規遵循
Interactions API 支援下列安全控管措施、法規遵循認證和端點設定:
- 端點:Interactions API 支援全域端點 (
aiplatform.googleapis.com上的locations/global),以及us和eu多區域端點 (aiplatform.us.rep.googleapis.com上的locations/us和aiplatform.eu.rep.googleapis.com上的locations/eu)。不支援單一區域端點 (例如us-central1或europe-west1)。 - 資料落地:使用
us和eu多區域端點 (locations/us和locations/eu) 時,Interactions API 支援 ML 處理 (使用中) 和儲存的互動資料靜態 (store=true) 資料落地。傳送至global端點的要求不提供資料落地保證。 - 客戶自行管理的加密金鑰 (CMEK):Interactions API 支援儲存互動資料的 CMEK,方法是在
us和eu多區域中,透過服務設定檔 (scope設為INTERACTIONS_API) 進行。global端點不支援 CMEK。 - VPC Service Controls (VPC-SC):Interactions API 支援 VPC-SC,可協助保護 API 邊界,降低資料竊取風險。
- 資料存取透明化控管機制 (AXT):Interactions API 支援 AXT 記錄,可在 Google 人員存取儲存的互動內容時,近乎即時地提供資訊。
- 安全性與法規遵循認證:Interactions API 符合 Google Cloud FedRAMP High 授權範圍內的 FedRAMP High 規定。Interactions API 不符合美國國防部 (DoD) 影響等級 5 (IL5) 或《國際武器貿易條例》(ITAR) 規定。
支援的 SDK
您可以使用統一的 Google Gen AI SDK 或直接發出 REST 呼叫,存取 Interactions API:
- Python:
google-genai2.3.0以上版本 - TypeScript/JavaScript:
@google/genai2.3.0以上版本 - Go:
google.golang.org/genai - Java:
com.google.genai:google-genai
舊版 SDK (google-cloud-aiplatform、@google-cloud/vertexai 和 google-generativeai) 不支援 Interactions API。
後續步驟
- 請參閱 Interactions API 開發人員指南,瞭解如何安裝 Google Gen AI SDK 並執行第一個要求。
- 試用 Interactions API 快速入門筆記本。
- 請參閱 Interactions API 參考資料,瞭解方法和資源結構定義。
- 瞭解如何與代管代理互動,以及使用 Gemini Deep Research 代理。