Interactions API 是使用 Gemini 模型和智能体进行构建的最佳方式。截至 2026 年 6 月，该 API 已正式发布，建议所有新项目都使用它。虽然它现在被视为旧版 API，但原始
generateContent API
仍然完全受支持。
为什么要使用 Interactions API？
- 适用于所有应用的通用接口：该 API 被设计为适用于所有用例的标准 接口，包括单轮文本生成、 多模态理解能力、结构化输出、工具编排和 Agentic Workflows。
- 适用于模型和智能体的单个 API：一个统一的端点和模式，用于 直接调用标准 Gemini 模型以及专用智能体（例如 Deep Research 智能体和自定义托管智能体）。
- 开箱即用的新功能：例如，使用
previous_interaction_id的可选服务器端 对话状态、用于调试和界面呈现的可观测执行 步骤，以及使用background=true的长时间运行任务的 后台 执行。 - 费用更低，缓存命中率更高：使用多轮 对话时，可选的服务器端状态管理可在多轮对话中实现更高效的 上下文缓存，从而降低令牌费用。
- 新功能发布平台：今后，所有新模型、多模态 功能、工具和智能体功能都将在 Interactions API 上发布。
默认情况下，Interactions API 会存储请求，因此您可以使用 previous_interaction_id 来利用服务器端状态管理功能。您可以通过设置 store=false 来选择无状态行为。如需了解详情，请参阅数据保留部分。
开始使用
- 设置编码智能体：连接到 Gemini Docs MCP 并安装
gemini-api-dev技能，让您的助理可以直接访问 最新的开发者文档和最佳实践。如需了解详细步骤，请参阅 设置编码智能体指南 - 从
generateContent迁移** ：如果您有现有集成， 请按照 迁移指南 迁移到 Interactions API。 - 开始使用：按照 Interactions 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."
}'
服务器端状态管理
您可以在后续调用中使用已完成交互的 id，并使用
previous_interaction_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 保留对话历史记录（输入和输出）。其他参数是交互范围 的，仅适用于您当前生成的特定交互：
toolssystem_instructiongeneration_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中查看和管理存储的
交互日志，包括从项目存储空间中删除日志。
保留期限到期后，您的数据将被自动删除。
系统会根据条款处理 Interactions 对象。
在 AI Studio 中查看交互
对于付费层级项目，API 会存储使用 store=true 执行的 Interactions API 请求。您可以直接从 Google AI Studio 的
“日志”页面查看这些请求。如需了解详情，请参阅
日志指南。
最佳做法
- 缓存命中率：有状态模式和
无状态模式均支持隐式缓存（请参阅
快速入门）。使用
previous_interaction_id（有状态）继续对话可让系统更轻松地利用对话历史记录的隐式缓存，从而提高性能并降低费用。 - 混合交互：您可以灵活地在对话中混合搭配智能体交互和
模型交互。例如，您可以使用专用智能体（例如 Deep Research 智能体）进行初始数据收集，然后使用标准 Gemini 模型执行后续任务（例如总结或重新格式化），并使用
previous_interaction_id将这些步骤关联起来。
支持的模型和智能体
| 模型名称 | 类型 | 模型 ID |
|---|---|---|
| Gemini 4 Argon | 模型 | gemini-4-argon |
| Gemini 3.8 Flash | 模型 | gemini-3.8-flash |
| Gemini 3.6 Flash | 模型 | gemini-3.6-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 Clip 预览版 | 模型 | 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 尚不支持 ：
- 批量 API
- 自动函数调用 (Python)
- 显式缓存：请注意，Interactions API
中可通过
previous_interaction_id使用服务器端隐式缓存。 - 安全设置：Interactions API 不支持自定义安全 设置。
反馈
您的反馈对于 Interactions API 的开发至关重要。 欢迎在 Google AI 开发者社区论坛上分享您的想法、报告 bug 或请求功能。