互動 API

如要使用 Gemini 模型和代理程式建構應用程式，最佳方式是使用 Interactions API。這項功能已於 2026 年 6 月正式推出，建議所有新專案使用。雖然現在已視為舊版，但原始的 generateContent API 仍完全支援。

為什麼要使用 Interactions API？

  • 適用於所有應用程式的通用介面：這個介面是為各種用途設計的標準介面，包括單輪文字生成、多模態理解、結構化輸出、工具協調和代理工作流程。
  • 模型和代理程式共用單一 API：透過統一的端點和模式，直接呼叫標準 Gemini 模型和專用代理程式 (例如 Deep Research 和自訂管理型代理程式)。
  • 現成的新功能：包括使用 previous_interaction_id 的選用伺服器端對話狀態、可觀測的執行步驟 (用於偵錯和 UI 算繪)，以及使用 background=true 執行長時間工作時的背景執行。
  • 降低成本，提高快取命中率：使用多輪對話時，選用的伺服器端狀態管理功能可跨輪次更有效率地快取內容，進而降低權杖成本。
  • 新功能推出平台：今後所有新模型、多模態功能、工具和代理功能，都會在 Interactions API 上推出。

根據預設，Interactions API 會儲存要求，因此您可以使用 previous_interaction_id，運用伺服器端狀態管理功能。您可以設定 store=false，選擇採用無狀態行為。詳情請參閱「資料保留」一節。

開始使用

  • 設定程式設計代理：連線至 Gemini 文件 MCP 並安裝 gemini-api-dev 技能，讓助理直接存取最新的開發人員文件和最佳做法。如需詳細步驟，請參閱「設定程式碼編寫代理程式指南」
  • 從 generateContent 遷移：如果您已有整合項目，請按照遷移指南操作，改用 Interactions API。
  • 開始使用：按照互動式 API 快速入門指南中的步驟操作。

功能指南

請參閱下列指南，瞭解 Interactions API 的具體功能。您可以在這些頁面使用切換鈕，在 generateContent 和 Interactions API 之間切換：

Interactions API 的運作方式

Interactions API 的核心資源是 Interaction。Interaction 代表對話或工作中的完整回合。這份記錄會依時間順序記錄整個互動過程的執行步驟。這些步驟包括模型想法、伺服器端或用戶端工具呼叫和結果 (例如 function_call 和 function_result)，以及最終 model_output。儲存的資源 (透過 interactions.get 擷取) 也包含完整情境的 user_input 步驟，但 interactions.create 回應只會傳回模型生成的步驟。

呼叫 interactions.create 時，您會建立新的 Interaction 資源：

Python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a short story about a time-traveling lighthouse."
)

print(interaction.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Tell me a short story about a time-traveling lighthouse.",
});

console.log(interaction.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

CreateModelInteraction params =
    CreateModelInteraction.builder()
        .model(Model.of("gemini-3.8-flash"))
        .input(InteractionsInput.of("Tell me a short story about a time-traveling lighthouse."))
        .build();

Interaction interaction =
    client.interactions.create(CreateInteractionRequestBody.of(params)).interaction().get();

System.out.println(interaction.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    res, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Tell me a short story about a time-traveling lighthouse."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.Interaction.OutputText != nil {
        fmt.Println(*res.Interaction.OutputText)
    }
}

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me a short story about a time-traveling lighthouse."
  }'

伺服器端狀態管理

您可以在後續呼叫中使用 previous_interaction_id 參數，藉此使用已完成互動的 id 繼續對話。伺服器會使用這組 ID 擷取對話記錄，因此您不必重新傳送完整的對話記錄：

Python

from google import genai

client = genai.Client()

# 1. First turn
turn1 = client.interactions.create(
    model="gemini-3.8-flash",
    input="Hi, my name is Phil."
)

# 2. Second turn (chained using previous_interaction_id)
turn2 = client.interactions.create(
    model="gemini-3.8-flash",
    input="What is my name?",
    previous_interaction_id=turn1.id
)

print(turn2.output_text)

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

// 1. First turn
const turn1 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "Hi, my name is Phil.",
});

// 2. Second turn (chained using previous_interaction_id)
const turn2 = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "What is my name?",
  previous_interaction_id: turn1.id,
});

console.log(turn2.output_text);

Java

import com.google.genai.Client;
import com.google.genai.gaos.models.interactions.CreateModelInteraction;
import com.google.genai.gaos.models.interactions.Interaction;
import com.google.genai.gaos.models.interactions.InteractionsInput;
import com.google.genai.gaos.models.interactions.Model;
import com.google.genai.gaos.models.operations.CreateInteractionRequestBody;

Client client = new Client();

// 1. First turn
Interaction turn1 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("Hi, my name is Phil."))
                    .build()))
        .interaction()
        .get();

// 2. Second turn (chained using previousInteractionId)
Interaction turn2 =
    client
        .interactions
        .create(
            CreateInteractionRequestBody.of(
                CreateModelInteraction.builder()
                    .model(Model.of("gemini-3.8-flash"))
                    .input(InteractionsInput.of("What is my name?"))
                    .previousInteractionId(turn1.id().get())
                    .build()))
        .interaction()
        .get();

System.out.println(turn2.outputText().orElse(""));

Go

package main

import (
    "context"
    "fmt"
    "log"

    "google.golang.org/genai"
    "google.golang.org/genai/interactions/models/interactions"
    "google.golang.org/genai/interactions/models/operations"
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, nil)
    if err != nil {
        log.Fatal(err)
    }

    // 1. First turn
    turn1, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model: interactions.Model("gemini-3.8-flash"),
            Input: interactions.NewInteractionsInput("Hi, my name is Phil."),
        }),
    })
    if err != nil {
        log.Fatal(err)
    }

    // 2. Second turn (chained using PreviousInteractionID)
    turn2, err := client.Interactions.Create(ctx, operations.CreateInteractionRequest{
        Body: operations.NewCreateInteractionRequestBody(interactions.CreateModelInteraction{
            Model:                 interactions.Model("gemini-3.8-flash"),
            Input:                 interactions.NewInteractionsInput("What is my name?"),
            PreviousInteractionID: turn1.Interaction.ID,
        }),
    })
    if err != nil {
        log.Fatal(err)
    }
    if turn2.Interaction.OutputText != nil {
        fmt.Println(*turn2.Interaction.OutputText)
    }
}

REST

# Replace PREVIOUS_INTERACTION_ID with the id returned from the first turn
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "What is my name?",
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID"
  }'

previous_interaction_id 參數只會使用 previous_interaction_id 保留對話記錄 (輸入和輸出內容)。其他參數為互動範圍，且僅適用於目前產生的特定互動：

  • tools
  • system_instruction
  • generation_config (包括 thinking_level、temperature 等)

也就是說，如要套用這些參數，您必須在每次新互動中重新指定。這項伺服器端狀態管理功能為選用功能，您也可以在每個要求中傳送完整對話記錄，以無狀態模式運作。

資料儲存與保留

根據預設，API 會儲存所有 Interaction 物件 (store=true)，以便簡化伺服器端狀態管理功能 (使用 previous_interaction_id)、背景執行作業 (使用 background=true) 和觀測能力功能的使用。

  • 付費方案：系統會保留互動記錄 55 天。
  • 免費方案：系統會保留互動記錄 1 天。

如果不希望系統執行上述作業，可以在要求中store=false。這項控制項與狀態管理功能無關，您可以選擇不儲存任何互動。不過請注意，store=false 與背景執行不相容，且會禁止在後續回合中使用 previous_interaction_id。

如果是付費級專案，您可以在 AI Studio 中設定保留期限，讓系統在 7、14、28 或 55 天後，自動將記錄標示為從專案儲存空間刪除。較短的保留期限可能會影響過往對話的擷取作業。

您隨時可以透過程式輔助方式使用 delete 方法刪除儲存的互動記錄，但必須提供互動 ID。您也可以在 AI Studio 中查看及管理儲存的互動記錄，包括從專案儲存空間刪除記錄。

超過保留期限後，系統會自動刪除資料。

系統會根據條款處理互動物件。

在 AI Studio 中查看互動

API 會儲存透過 store=true 執行的 Interactions API 要求，適用於付費級別的專案。您可以直接在 Google AI Studio 的「記錄」頁面中查看。詳情請參閱「記錄檔指南」。

最佳做法

  • 快取命中率：有狀態和無狀態模式都支援隱含快取 (請參閱快速入門)。使用 previous_interaction_id (具狀態) 繼續對話，系統就能更輕鬆地運用對話記錄的隱含快取，進而提升效能並降低費用。
  • 混合互動：您可以在對話中彈性混合搭配代理和模型互動。舉例來說，您可以先使用 Deep Research 代理等專用代理收集初始資料，然後使用標準 Gemini 模型執行後續工作，例如摘要或重新格式化，並使用 previous_interaction_id 連結這些步驟。

支援的模型和代理程式

模型名稱 類型 模型 ID
Gemini 3.8 Flash 模型 gemini-3.8-flash
Gemini 3.7 Flash 模型 gemini-3.7-flash
Gemini 3.6 Flash 模型 gemini-3.6-flash
Gemini 3.5 Flash 模型 gemini-3.5-flash
Gemini 3.1 Pro 預先發布版 模型 gemini-3.1-pro-preview
Gemini 3.5 Flash-Lite 模型 gemini-3.5-flash-lite
Gemini 3.1 Flash-Lite 模型 gemini-3.1-flash-lite
Gemini 3 Flash 預先發布版 模型 gemini-3-flash-preview
Gemini 2.5 Pro 模型 gemini-2.5-pro
Gemini 2.5 Flash 模型 gemini-2.5-flash
Gemini 2.5 Flash-Lite 模型 gemini-2.5-flash-lite
Gemini 3 Pro Image 模型 gemini-3-pro-image
Gemini 3.1 Flash Image 模型 gemini-3.1-flash-image
Gemini 3.1 Flash TTS 預先發布版 模型 gemini-3.1-flash-tts-preview
Gemma 4 31B IT 模型 gemma-4-31b-it
Gemma 4 26B MoE IT 模型 gemma-4-26b-a4b-it
Lyria 3.5 模型 lyria-3.5
Lyria 3 剪輯片段預覽 模型 lyria-3-clip-preview
Lyria 3 Pro 預先發布版 模型 lyria-3-pro-preview
Deep Research 預先發布版 代理 deep-research-preview-04-2026
Deep Research 預先發布版 代理 deep-research-max-preview-04-2026
Antigravity 預覽 代理 antigravity-preview-09-2026

SDK

您可以使用最新版的 Google GenAI SDK，存取 Interactions API。

  • 在 Python 中，這是 2.3.0 版本之後的 google-genai 套件。
  • 在 JavaScript 中，這是 2.3.0 版本以上的 @google/genai 套件。
  • 在 Go 中，這是 google.golang.org/genai 套件。
  • 在 Java 中，這是 com.google.genai:google-genai 套件。

如要進一步瞭解如何安裝 SDK，請參閱「程式庫」頁面。

限制

  • 遠端 MCP：Gemini 3 不支援遠端 MCP，但這項功能即將推出。
  • 多輪模型相容性：在對話中混合使用不同模型 (無論是有狀態或無狀態)，後續模型必須支援先前模型的輸出模態做為輸入內容。舉例來說，如果使用 gemini-3.1-flash-image 生成圖片，就無法繼續與不接受圖片輸入的模型對話 (例如僅限文字的模型，或是 Lyria 等音樂生成模型)。

generateContent API 支援下列功能，但 Interactions API 尚未提供這些功能：

意見回饋

您的意見回饋對 Interactions API 的開發至關重要。歡迎前往 Google AI 開發人員社群論壇分享想法、回報錯誤或提出功能要求。

後續步驟