# Interactions API

Interactions API 是我们的新界面，也是使用 Gemini 模型和智能体进行构建的最直接方法。截至 6 月，2026, 已全面上市，并且是所有新项目的推荐接口。

虽然它现在被认为是遗产，但原来的 [`generateContent`](/docs/text-generation?generate-content=true) API 仍然得到完全支持。

## 为什么使用Interactions API？  {% #why-interactions %}

* **开箱即用的新功能**：可选的服务器端会话状态使用 `previous_interaction_id`，用于调试和 UI 渲染的可观察执行步骤，以及使用长时间运行任务的后台执行 `background=true`.

* **成本更低，缓存命中率更高**：服务器端状态管理可实现更高效的上下文缓存跨轮对话，降低 token 多轮对话的成本。

* **专为前沿型号和智能体打造**：专为思维模型、多步骤工具使用和复杂推理流程而构建 - 简化构建、调试和编排智能体应用程序的过程。

* **型号为单个 API 和智能体**：一个统一的接口，用于直接调用 Gemini 模型和智能体，例如 Deep Research 和自定义托管智能体 — 无需学习单独的端点或模式。

* **新事物诞生的地方**：展望未来，核心主线系列之外的新模型和功能以及新的智能体功能和工具将在 Interactions API 上推出。

默认情况下，Interactions API 存储请求，因此您可以使用服务器端状态管理功能 `previous_interaction_id`。您可以通过设置选择无状态行为 `store=false`。请参阅 [数据保留](/docs/interactions-overview#data-storage-retention) 部分了解详细信息。

## 快速入门  {% #get-started %}

* **设置您的编码智能体**：连接到 **Gemini Docs MCP** 并安装 `gemini-api-dev` 让您的助手直接访问最新的开发人员文档和最佳实践的技能。 [设置您的编码智能体 →](/docs/coding-agents)

* **迁移自 `generateContent`**：如果您有现有集成，请按照 [迁移指南](/docs/migrate-to-interactions) 过渡到 Interactions API。

* **快速入门**: 开始在 [Interactions API 入门指南](/docs/get-started).

### 功能指南  {% #feature-guides %}

通过这些指南探索 Interactions API 的具体功能。您可以使用这些页面上的切换按钮在generateContent 和Interactions API 之间切换：

* [文本生成](/docs/text-generation)
* [图像生成](/docs/image-generation)
* [图像理解](/docs/image-understanding)
* [音频理解](/docs/audio)
* [视频理解](/docs/video-understanding)
* [文件处理](/docs/document-processing)
* [函数调用](/docs/function-calling)
* [结构化输出](/docs/structured-output)
* [Deep Research 智能体](/docs/deep-research)
* [弹性推理](/docs/flex-inference)
* [优先推理](/docs/priority-inference)

## Interactions API 的工作原理  {% #how-it-works %}

Interactions API 围绕一个核心资源： [**`Interaction`**](/api-reference/interactions-api#Resource:Interaction)。一个 `Interaction` 代表对话或任务的完整转变。它充当会话记录，包含按时间顺序排列的整个交互历史记录 **执行步骤**。这些步骤包括模型思想、服务器端或客户端工具调用和结果（例如 `function_call` 和 `function_result`），以及最后的 `model_output`。存储的资源（通过检索 `interactions.get`）还包括 `user_input` 完整上下文的步骤，尽管 `interactions.create` 响应仅返回模型生成的步骤。

当您拨打电话时 [`interactions.create`](/api-reference/interactions-api/create-interaction)，你正在创建一个新的 `Interaction` 资源：

{% tabs %}
{% tab label="Python" %}
```python
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)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
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);
```
{% /tab %}

{% tab label="Java" %}
```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-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(""));
```
{% /tab %}

{% tab label="Go" %}
```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-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)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
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."
  }'
```
{% /tab %}

{% tab label="CLI" %}
```bash
gemini-api generate "Tell me a short story about a time-traveling lighthouse."
```
{% /tab %}
{% /tabs %}

### 服务器端状态管理  {% #server-side-state %}

您可以使用 `id` 使用以下方法在后续调用中完成交互 `previous_interaction_id` 参数以继续对话。服务器使用此 ID 检索对话历史记录，使您无需重新发送整个聊天历史记录：

{% tabs %}
{% tab label="Python" %}
```python
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)
```
{% /tab %}

{% tab label="JavaScript" %}
```javascript
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);
```
{% /tab %}

{% tab label="Java" %}
```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-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(""));
```
{% /tab %}

{% tab label="Go" %}
```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-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)
    }
}
```
{% /tab %}

{% tab label="REST" %}
```bash
# 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"
  }'
```
{% /tab %}

{% tab label="CLI" %}
```bash
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"
```
{% /tab %}
{% /tabs %}

该 `previous_interaction_id` 参数仅保留对话历史记录（输入和输出） `previous_interaction_id`。其他参数是 **互动范围** 并仅适用于您当前生成的特定交互：

- `tools`
- `system_instruction`
- `generation_config` （包括 `thinking_level`, `temperature`等）

这意味着如果您希望应用这些参数，则必须在每个新交互中重新指定这些参数。这种服务器端状态管理是可选的；您还可以通过在每个请求中发送完整的对话历史记录来在无状态模式下进行操作。

### 数据存储和保留  {% #data-storage-retention %}

默认情况下，API 存储所有交互对象（`store=true`）以简化服务器端状态管理功能的使用（带有 `previous_interaction_id`），后台执行（使用 `background=true`）和可观察性目的。

- **付费等级**：系统保留交互 **55天**.
- **免费套餐**：系统保留交互 **1日**.

如果你不想这样，你可以设置 `store=false` 在你的要求中。这种控制与状态管理是分开的；您可以选择退出任何交互的存储。但请注意 `store=false` 不兼容 [后台执行](/docs/background-execution) 并防止使用 `previous_interaction_id` 用于后续回合。

对于付费层级项目，您可以在以下位置配置保留窗口： [人工智能工作室](https://aistudio.google.com/logs) 在 7, 14, 28, 或 55 天后自动将日志标记为从项目存储中删除。较短的保留时间可能会影响对过去对话的检索。

您可以随时使用以下命令删除存储的交互 [`delete`](/api-reference/interactions-api/delete-interaction) 以编程方式调用方法，这需要交互 ID。您还可以查看和管理存储的交互日志，包括从项目存储中删除， [人工智能工作室](https://aistudio.google.com/logs).

保留期到期后，您的数据将被自动删除。

交互对象根据 [条款](/docs/terms).

### 查看 AI Studio 中的交互  {% #viewing-interactions-in-ai-studio %}

API 存储使用以下命令执行的 Interactions API 请求 `store=true` 对于付费层的项目。您可以直接从 [Google AI Studio 中的日志页面](https://aistudio.google.com/logs)。请参阅 [日志指南](/docs/logs-datasets) 了解更多。

## 最佳实践  {% #best-practices %}

* **缓存命中率**：有状态和无状态模式都支持隐式缓存（请参阅 [快速入门](/docs/get-started#4-multi-turn-conversations)）。使用 `previous_interaction_id` （有状态）继续对话允许系统更轻松地利用对话历史记录的隐式缓存，从而提高性能并降低成本。
* **混合互动**：您可以灵活地在对话中混合和匹配智能体和模型交互。例如，您可以使用专门的智能体（如 Deep Research 智能体）进行初始数据收集，然后使用标准 Gemini 模型进行后续任务（例如汇总或重新格式化），将这些步骤与 `previous_interaction_id`.

## 支持的型号 & 智能体  {% #supported-models-agents %}

| 型号名称                         | 类型  | 型号编号                                |
| ---------------------------- | --- | ----------------------------------- |
| Gemini 4 Carbon              | 模型  | `gemini-4-carbon`                   |
| Gemini 4 Argon               | 模型  | `gemini-4-argon`                    |
| Gemini 4 Hydrogen            | 模型  | `gemini-4-hydrogen`                 |
| Gemini 3.8 Flash             | 模型  | `gemini-3.8-flash`                  |
| Gemini 3.6 Flash             | 模型  | `gemini-3.6-flash`                  |
| Gemini 3.1 Pro Preview       | 模型  | `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 Preview       | 模型  | `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 Preview | 模型  | `gemini-3.1-flash-tts-preview`      |
| 杰玛 4 31B IT                  | 模型  | `gemma-4-31b-it`                    |
| Gemma 4 26B 教育部 IT           | 模型  | `gemma-4-26b-a4b-it`                |
| Lyria 3.5                    | 模型  | `lyria-3.5`                         |
| Lyria 3 Clip Preview         | 模型  | `lyria-3-clip-preview`              |
| Lyria 3 Pro Preview          | 模型  | `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 上，这是 `google-genai` 包裹来自 `2.3.0` 版本开始。
* 在 JavaScript 上，这是 `@google/genai` 包裹来自 `2.3.0` 版本开始。
* 在 Go 上，这是 `google.golang.org/genai` 包。
* 在 Java 上，这是 `com.google.genai:google-genai` 包。

您可以了解有关如何安装 SDK 的更多信息 [SDK 与库](/docs/libraries)
页。

## 限制  {% #limitations %}

* **远程 MCP**：Gemini 3 不支持远程 MCP，即将推出。
* **多圈模型兼容性**：在对话中混合不同模型（有状态或无状态）时，后续模型必须支持先前模型的输出模式作为输入。例如，如果您使用生成图像 `gemini-3.1-flash-image`，您无法与不接受图像输入的模型（例如纯文本模型或 Lyria 等音乐生成模型）继续进行对话。

支持以下功能 [`generateContent`](/docs/text-generation?generate-content=true) API 但都是 **尚不可用** 在 Interactions API 中：

* **[Batch API](/docs/batch-api)**
* **[自动函数调用 (Python)](/docs/function-calling?example=meeting&generate-content=true#automatic_function_calling_python_only)**  *   **[显式缓存](/docs/caching)**：请注意，服务器端隐式缓存可在 Interactions API 中通过 `previous_interaction_id`.

## 反馈信息  {% #feedback %}

您的反馈对于 Interactions API 的开发至关重要。在我们的网站上分享您的想法、报告错误或请求功能 [谷歌人工智能开发者社区论坛](https://discuss.ai.google.dev/c/gemini-api/4).

## 后续步骤  {% #whats-next %}

* 尝试一下 [Interactions API快速入门笔记本](https://colab.sandbox.google.com/github/google-gemini/cookbook/blob/main/quickstarts/Get_started_interactions_api.ipynb)。  * 了解更多关于 [Gemini Deep Research 智能体](/docs/deep-research).
