打開 Gemini 官方文檔，尤其是 Nano Banana 圖片生成這類頁面，你可能會注意到頁面頂部多了一個切換開關——一邊是 Interactions API，一邊是 generateContent API。這不是文檔改版這麼簡單，而是 Google 在 2026 年 6 月正式把 Interactions API 推上了 GA（正式可用）的位置，並建議所有新項目優先採用。本文結合官方文檔和 API易 網關的實測結論，把兩者的核心差異、能力缺口和實際調用建議一次講清楚。
核心價值: 讀完本文，你會明確 Interactions API 和 generateContent 在設計理念、狀態管理、能力覆蓋上的具體差異，並知道經 API易 中轉調用 Gemini 時該選哪一種範式。
Interactions API 與 generateContent 核心差異
先說結論：這兩個 API 不是簡單的版本升級關係，而是兩套不同的設計理念。generateContent 是無狀態的“一次請求一次響應”模式，客戶端需要自己維護完整的對話歷史；Interactions API 則把狀態管理下放到服務端，圍繞“Interaction”這個新概念重新設計了整套交互方式。
官方文檔把一個 Interaction 定義爲“一次完整的對話或任務輪次”，內部由一系列按時間順序排列的執行步驟組成，包括模型的思考過程、工具調用與返回結果，以及最終的模型輸出。這意味着 Interactions API 天生就是爲多輪對話和 agent 類任務設計的，而不只是單次問答。
這也解釋了爲什麼 Google 會用“正式可用”這樣的措辭而不是簡單的“新增功能”。Interactions API 於 2025 年 12 月進入公測，2026 年 6 月正式官宣 GA，官方博客明確寫道：“我們建議所有新項目和應用都使用 Interactions API”，同時全部官方文檔已經默認展示這套新範式，並且 Google 正在推動第三方 SDK 和生態夥伴也把它作爲默認接口。換句話說，這不是一次可選的功能更新，而是 Google 對“如何調用 Gemini”這件事的重新定義，只是配套發佈了遷移指南，允許開發者按自己的節奏逐步過渡，不強制一刀切。
| 對比維度 | generateContent（legacy） | Interactions API |
|---|---|---|
| 當前狀態 | 遺留但完全支持 | 2026年6月起正式GA |
| 官方推薦 | 現有項目可繼續使用 | 建議所有新項目優先採用 |
| 核心方法 | generateContent | interactions.create / get / delete |
| 設計理念 | 無狀態單次請求 | 圍繞Interaction的狀態化任務輪次 |
| 未來新能力 | 仍會獲得新主線模型 | 前沿agent能力優先登陸 |
🎯 技術建議: 如果你正在通過 API易 apiyi.com 調用 Gemini 系列模型，建議先花幾分鐘對照官方文檔確認自己項目當前使用的是哪一種範式，再決定是否需要跟進遷移，避免因爲文檔默認展示 Interactions API 而誤以爲原有代碼已經過時。
請求方式與狀態管理：兩套範式的本質區別
理解兩者差異的關鍵在於“誰來維護對話歷史”。generateContent 要求客戶端每次請求都完整拼接歷史消息數組，哪怕是第十輪對話，也要把前九輪的內容原樣帶上；這種方式簡單直接，但隨着對話輪次增多，請求體會越來越大，重複傳輸的歷史內容也會重複計費。
Interactions API 提供了一個解法：把上一次調用返回的 interaction id，作爲 previous_interaction_id 參數傳入下一次請求，服務端會自動取回完整的對話歷史，客戶端不再需要手動拼接和重傳。官方文檔還提供了 background=true 參數用於長時間運行的任務，以及“可觀測執行步驟”能力，方便在調試和前端 UI 中展示模型的中間思考過程，這對構建 agent 類產品尤其有價值。
不過服務端狀態管理並非沒有代價。默認情況下 store 參數爲 true，系統會保留 interaction 記錄——付費賬戶保留 55 天，免費賬戶只保留 1 天；如果出於隱私或合規考慮把 store 設爲 false，雖然可以關閉存儲，但同時也會失去 previous_interaction_id 續接對話和後臺執行這兩項能力，這是一個需要提前權衡的取捨點。
從成本角度看，官方也給出了明確的價值主張：服務端維護狀態之後，同一個對話的歷史內容不需要每次都重新計入輸入 token，緩存命中率因此會明顯提升，官方原話是“更低成本、更高的緩存命中率”。對於客服機器人、長文檔問答這類需要維持大量上下文的場景，這個差異在調用量上去之後會體現得比較明顯；但對於單輪生成、批處理這類天然無狀態的任務，這部分成本優勢基本無用武之地。
還有一個容易被忽略的細節： tools、system_instruction、generation_config（包括 thinking_level、temperature 等字段）這些參數是“按次設置”的，即便你用 previous_interaction_id 續接了上一輪對話，這些配置也不會自動繼承，每次請求都需要重新顯式傳入。
| 能力項 | generateContent | Interactions API |
|---|---|---|
| 對話歷史維護 | 客戶端手動拼接全部歷史 | 服務端通過previous_interaction_id自動取回 |
| 長任務後臺執行 | 不支持 | 支持background=true |
| 中間執行步驟可見性 | 需自行解析 | 提供observable execution steps |
| 記錄保留策略 | 無此概念 | 默認保留，付費55天/免費1天 |
| 工具與生成參數繼承 | 每次顯式傳入 | 每次顯式傳入，不自動繼承 |
💡 選擇建議: 對於需要頻繁多輪對話或構建 agent 工作流的項目，Interactions API 的狀態管理機制確實能省去不少膠水代碼；但如果你的調用場景以單次生成爲主，這部分優勢不一定能體現出來，我們建議通過 API易 apiyi.com 平臺先做小流量對比測試，再決定是否值得遷移。
兩者的能力缺口：誰能做，誰還不能做
Interactions API 雖然是新範式，但官方文檔也明確列出了當前還不支持的能力，這一點在選型時必須納入考慮，不能只看“更新”就默認它更全面。
官方明確寫道，Interactions API 目前還不支持視頻理解中的 video metadata 字段、Batch API、Python 的自動函數調用（automatic function calling），以及顯式緩存（explicit caching）——不過通過 previous_interaction_id 實現的隱式緩存是支持的。相對地，generateContent 完整支持流式輸出、函數調用、Batch API、顯式緩存，以及文本、圖片、音頻、視頻、文檔在內的全量多模態輸入。
| 能力 | generateContent | Interactions API |
|---|---|---|
| Batch API | ✅ 支持 | ❌ 暫不支持 |
| 顯式緩存（explicit caching） | ✅ 支持 | ⚠️ 僅隱式緩存 |
| 視頻 metadata 字段 | ✅ 支持 | ❌ 暫不支持 |
| Python 自動函數調用 | ✅ 支持 | ❌ 暫不支持 |
| 流式輸出 / 函數調用 | ✅ 支持 | ✅ 支持 |
| 聲稱的成本與緩存命中率 | 常規計費 | 官方稱成本更低、命中率更高 |
以 Nano Banana 圖片生成這個具體場景爲例，兩種範式最直觀的差異體現在取結果的方式上。Interactions API 提供了 interaction.output_image、interaction.output_text 這類便捷屬性，可以直接拿到最後生成的圖片或文本塊；而 generateContent 走的是更底層的 candidates[0].content.parts 數組遍歷方式，需要自己判斷每個 part 的類型。對已經寫好 generateContent 解析邏輯的項目來說，這種底層結構差異往往意味着一次不小的代碼改造，不是簡單換個 endpoint 就能完事。
這幾項缺口並不是無關緊要的邊角能力。Batch API 通常是成本敏感型項目批量處理離線任務的核心手段，一旦遷移後發現新範式不支持，相當於要重新設計整條離線處理鏈路；顯式緩存則直接關係到長上下文場景的調用成本，如果業務裏有大段固定的 system prompt 或參考資料需要反覆複用，缺少顯式緩存意味着無法精確控制哪些內容被緩存、緩存多久。這也是爲什麼官方文檔會同時保留兩條技術路線，而不是直接讓 generateContent 退役——至少在這幾項能力補齊之前，它仍然是無法被替代的。
🔧 實踐建議: 如果你的業務重度依賴 Batch API 批量處理或顯式緩存降本，現階段貿然切到 Interactions API 可能會丟失這些能力，建議繼續觀察官方遷移指南的更新節奏，而不是急於替換生產環境代碼。
API易網關實測：當前該用哪個範式
結論說在前面：截至 2026 年 7 月 4 日的實測，經 API易 網關調用 Gemini，應當繼續使用 generateContent 原生格式。
API易 技術團隊針對 Interactions API 的關鍵路徑做了直接測試，覆蓋了兩種主流鑑權方式，結果如下。
| 測試端點 | 鑑權方式 | 結果 |
|---|---|---|
| POST /v1beta2/interactions | Bearer token | ❌ 404（Invalid URL） |
| POST /v1beta/interactions | Bearer token | ❌ 404（Invalid URL） |
| POST /v1beta2/interactions | x-goog-api-key header | ❌ 404（Invalid URL） |
| POST /v1beta/models/{model}:generateContent | Bearer token | ✅ 正常返回 |
API易 官方文檔原話是：“API易 網關暫不支持 Interactions API 中轉——/v1beta2/interactions 與 /v1beta/interactions 路徑均返回 404”，並給出明確建議：“經 API易 調用 Gemini 請繼續使用 generateContent 原生格式”。這也是爲什麼 API易 站內目前全部 Gemini 相關文檔都統一基於 generateContent 格式編寫，這樣能保證讀者複製代碼就能直接跑通，不會遇到路徑 404 的問題。
需要強調的是，這是一個動態狀態，而不是永久限制。隨着 Interactions API 逐漸成爲官方默認範式，網關側後續大概率會跟進支持；屆時 API易 會更新對應文檔，目前可以關注 docs.apiyi.com/api-capabilities/gemini/interactions-api 這個頁面獲取最新的支持狀態，不需要每次都自己動手測試端點。
這組測試結果也提醒了一個容易被忽視的現實：官方文檔層面的“正式可用”，和某個具體中轉網關或第三方 SDK 是否已經完成適配，完全是兩回事。開發者如果只看官方文檔的默認展示，直接照抄 Interactions API 的代碼示例塞進現有的中轉配置裏，大概率會先撞上 404，再花時間排查究竟是自己的代碼寫錯了，還是網關本身還沒跟上。遇到類似情況時，先確認自己的調用鏈路（直連官方還是經第三方中轉）對新範式的支持狀態，往往比反覆檢查業務代碼更快定位問題。
🚀 快速開始: 如果你現在就想驗證自己的 Gemini 調用鏈路是否正常，推薦直接使用 API易 apiyi.com 的 generateContent 格式接入，該平臺提供統一的 base_url，支持文本、圖片等多種 Gemini 模型的調用，不需要額外處理認證細節。
該怎麼選：場景化決策建議
結合前面的能力對比和實測結論，給出一份簡單的場景化建議表。
| 使用場景 | 推薦方案 | 理由 |
|---|---|---|
| 經 API易 網關調用 Gemini | generateContent | 網關當前僅支持該格式，Interactions API 路徑返回404 |
| 依賴 Batch API 批量處理 | generateContent | Interactions API 暫不支持 Batch API |
| 需要顯式緩存降低成本 | generateContent | Interactions API 目前只有隱式緩存 |
| 構建多輪對話 agent，直連官方API | 可評估 Interactions API | 服務端狀態管理能省去歷史拼接邏輯 |
| 需要觀察模型中間執行步驟調試 | Interactions API | 提供observable execution steps原生支持 |
| 現有項目已用generateContent跑通 | 暫不遷移 | legacy仍完全支持，短期內還會獲得新模型 |
簡單來說，是否遷移不取決於“新不新”，而取決於你的具體依賴是否被 Interactions API 完整覆蓋，以及你調用 Gemini 的鏈路（直連官方還是經中轉網關）當前是否已經支持這套新範式。對大多數經 API易 中轉調用的開發者來說，現階段維持 generateContent 是更穩妥的選擇。
常見問題
Q1: generateContent 會被下線嗎？現在還值得基於它開發新項目嗎？
短期內不會。官方明確表示 generateContent 雖然被標記爲 legacy，但“仍然完全支持”，並且在可預見的未來還會持續獲得新的主線 Gemini 模型。如果你經 API易 apiyi.com 調用 Gemini，現階段基於 generateContent 開發新項目完全沒有問題，不必因爲文檔默認展示 Interactions API 就產生焦慮。
Q2: API易 網關什麼時候會支持 Interactions API？
目前沒有確切時間表，這取決於該範式在官方生態的普及程度和網關側的適配進度。建議關注 API易 apiyi.com 平臺的官方文檔更新，一旦支持 Interactions API 中轉，相關文檔會第一時間同步更新，不需要自行反覆測試端點狀態。
Q3: 兩種 API 可以在同一個項目裏混用嗎？
從技術上講，只要調用鏈路支持，兩種範式可以並存，比如用 generateContent 處理 Batch API 批量任務，同時在直連官方 API 的多輪對話場景試用 Interactions API。但經 API易 網關調用時，由於 Interactions API 路徑當前返回 404，建議暫時統一使用 generateContent 格式，避免同一項目裏出現兩套不一致的調用邏輯增加維護成本。
總結
Interactions API 在 2026 年 6 月轉正後，確實代表了 Google 對 Gemini 調用方式的長期方向，服務端狀態管理、可觀測執行步驟這些能力對 agent 類應用很有吸引力，但它在 Batch API、顯式緩存、視頻 metadata 等方面還有明顯缺口，generateContent 依舊完全支持且短期內還會持續更新。更重要的是，經 API易 網關調用 Gemini 時，截至目前的實測結果是 Interactions API 相關路徑均返回 404，generateContent 纔是當前唯一可用的格式。如果你需要穩定可靠地調用 Gemini 系列模型，推薦通過 API易 apiyi.com 使用 generateContent 原生格式接入，後續網關支持新範式後會及時更新文檔。
本文實測數據和官方信息覈實均由 API易 技術團隊完成，如需瞭解 Gemini 系列模型更多調用細節，歡迎通過 API易 apiyi.com 聯繫技術支持。
參考資料
-
Google AI for Developers – Interactions API 概覽: Interaction 概念、核心方法與能力說明
- 鏈接：
ai.google.dev/gemini-api/docs/interactions-overview
- 鏈接：
-
Google AI for Developers – generateContent（Legacy）: 遺留API的支持狀態與能力範圍
- 鏈接：
ai.google.dev/gemini-api/docs/interactions
- 鏈接：
-
API易官方文檔 – Gemini Interactions API 支持狀態: 網關實測端點結果與調用建議
- 鏈接：
docs.apiyi.com/api-capabilities/gemini/interactions-api
- 鏈接：
