跳轉到

Interactions API

Interactions API 是我們全新的介面,也是使用 Gemini 模型與代理最直接的方式。截至 2026 年 6 月,它已正式推出,是所有新專案的建議介面。

雖然原始的 generateContent API 現在被視為舊版介面,但仍獲得完整支援。

為什麼要使用 Interactions API?

  • 開箱即用的新功能:可選的伺服器端對話狀態(使用 previous_interaction_id)、可供除錯與 UI 渲染觀察的執行步驟,以及使用 background=true 執行長時間任務的背景執行功能。

  • 成本更低、快取命中率更高:伺服器端狀態管理讓多輪對話之間的上下文快取更有效率,進而降低權杖成本。

  • 為前沿模型與代理而打造:專為思考模型、多步驟工具使用與複雜推理流程設計,簡化代理應用程式的建構、除錯與編排過程。

  • 模型與代理共用單一 API:以一個統一介面直接呼叫 Gemini 模型與代理,例如 Deep Research 與自訂的受管理代理,不必再學習不同的端點或模式。

  • 新功能在此推出:今後,核心主力系列之外的新模型與新功能,以及新的代理功能與工具,都將在 Interactions API 上推出。

Interactions API 預設會儲存要求,讓你能使用 previous_interaction_id 運用伺服器端狀態管理功能。你也可以設定 store=false,改採無狀態行為。詳情請參閱資料保留一節。

開始使用

功能指南

透過下列指南探索 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 資源:

from google import genai

client = genai.Client()

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

print(interaction.output_text)
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

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

console.log(interaction.output_text);
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-4-hydrogen"))
        .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(""));
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-4-hydrogen"),
            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)
    }
}
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-4-hydrogen",
    "input": "Tell me a short story about a time-traveling lighthouse."
  }'
gemini-api generate "Tell me a short story about a time-traveling lighthouse."

伺服器端狀態管理

在後續呼叫中,你可以使用已完成互動的 id,透過 previous_interaction_id 參數延續對話。伺服器會以這個 ID 取得對話歷程,你就不必重新傳送整段聊天紀錄:

from google import genai

client = genai.Client()

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

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

print(turn2.output_text)
import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI();

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

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

console.log(turn2.output_text);
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-4-hydrogen"))
                    .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-4-hydrogen"))
                    .input(InteractionsInput.of("What is my name?"))
                    .previousInteractionId(turn1.id().get())
                    .build()))
        .interaction()
        .get();

System.out.println(turn2.outputText().orElse(""));
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-4-hydrogen"),
            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-4-hydrogen"),
            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)
    }
}
# 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-4-hydrogen",
    "input": "What is my name?",
    "previous_interaction_id": "PREVIOUS_INTERACTION_ID"
  }'
TURN1_ID=$(gemini-api generate "Hi, my name is Phil." --stream=false --jq '.id')
gemini-api generate "What is my name?" --previous-interaction-id "$TURN1_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 中查看及管理已儲存的互動紀錄,包括從專案儲存空間中刪除。

保留期間屆滿後,你的資料將自動刪除。

Interaction 物件會依照條款處理。

在 AI Studio 中查看互動

對於付費層級專案,API 會儲存以 store=true 執行的 Interactions API 要求。你可以直接從 Google AI Studio 的 Logs 頁面查看。詳情請參閱 Logs 指南。

最佳做法

  • 快取命中率:有狀態與無狀態模式都支援隱式快取(請參閱快速入門)。使用 previous_interaction_id(有狀態)延續對話,能讓系統更容易運用隱式快取處理對話歷程,進而提升效能並降低成本。
  • 混用互動:你可以在一段對話中靈活混用代理互動與模型互動。例如,先使用 Deep Research 代理這類專門代理進行初步資料蒐集,再使用標準 Gemini 模型處理摘要或重新格式化等後續任務,並以 previous_interaction_id 將這些步驟串連起來。

支援的模型與代理

模型名稱 類型 模型 ID
Gemini 4 Carbon Model gemini-4-carbon
Gemini 4 Argon Model gemini-4-argon
Gemini 4 Hydrogen Model gemini-4-hydrogen
Gemini 3.8 Flash Model gemini-3.8-flash
Gemini 3.6 Flash Model gemini-3.6-flash
Gemini 3.1 Pro Preview Model gemini-3.1-pro-preview
Gemini 3.5 Flash-Lite Model gemini-3.5-flash-lite
Gemini 3.1 Flash-Lite Model gemini-3.1-flash-lite
Gemini 3 Flash Preview Model gemini-3-flash-preview
Gemini 2.5 Pro Model gemini-2.5-pro
Gemini 2.5 Flash Model gemini-2.5-flash
Gemini 2.5 Flash-lite Model gemini-2.5-flash-lite
Gemini 3 Pro Image Model gemini-3-pro-image
Gemini 3.1 Flash Image Model gemini-3.1-flash-image
Gemini 3.1 Flash TTS Preview Model gemini-3.1-flash-tts-preview
Gemma 4 31B IT Model gemma-4-31b-it
Gemma 4 26B MoE IT Model gemma-4-26b-a4b-it
Lyria 3.5 Model lyria-3.5
Lyria 3 Clip Preview Model lyria-3-clip-preview
Lyria 3 Pro Preview Model lyria-3-pro-preview
Deep Research Preview Agent deep-research-preview-04-2026
Deep Research Preview Agent deep-research-max-preview-04-2026
Antigravity Preview Agent antigravity-preview-09-2026

SDK

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

  • 在 Python 上,是 google-genai 套件(從 2.3.0 版起)。
  • 在 JavaScript 上,是 @google/genai 套件(從 2.3.0 版起)。
  • 在 Go 上,是 google.golang.org/genai 套件。
  • 在 Java 上,是 com.google.genai:google-genai 套件。

如需進一步瞭解如何安裝 SDK,請參閱 Libraries 頁面。

限制

  • 遠端 MCP:Gemini 3 尚不支援遠端 MCP,此功能即將推出。
  • 多輪模型相容性:在一段對話中混用不同模型時(不論有狀態或無狀態),後續模型必須能將先前模型的輸出模態作為輸入。例如,如果你使用 gemini-3.1-flash-image 產生圖片,就無法用不接受圖片輸入的模型(例如純文字模型,或 Lyria 這類音樂生成模型)延續該段對話。

下列功能已由 generateContent API 支援,但在 Interactions API 中尚未提供:

意見回饋

你的意見回饋對 Interactions API 的發展至關重要。歡迎在我們的 Google AI Developer Community Forum 分享你的想法、回報錯誤或提出功能要求。

後續步驟