Interactions API

Interactions API 是我们新推出的接口，也是使用 Gemini 模型和智能体进行构建的最直接方式。自 2026 年 6 月起，该界面已正式版发布，是所有新项目的推荐界面。

虽然现在已将其视为旧版 API，但原始的 generateContent API 仍完全受支持。

为什么要使用 Interactions API？

  • 开箱即用的新功能：使用 previous_interaction_id 的可选服务器端对话状态、用于调试和界面渲染的可观测执行步骤，以及使用 background=true 的长时间运行任务的后台执行。
  • 以更低的费用实现更高的缓存命中率：服务器端状态管理可在多轮对话中更高效地缓存上下文，从而降低令牌费用。
  • 专为前沿模型和智能体打造：专为思维模型、多步骤工具使用和复杂的推理流程而打造，可简化智能体应用的构建、调试和编排流程。
  • 适用于模型和智能体的单一 API：一个统一的界面，可直接调用 Gemini 模型和智能体（例如 Deep Research 和自定义托管智能体），无需学习单独的端点或模式。
  • 新功能发布平台：未来，除了核心 Mainline 系列之外的新模型和功能，以及新的智能体功能和工具，都将通过 Interactions API 发布。

默认情况下，Interactions API 会存储请求，以便您可以使用 previous_interaction_id 来利用服务器端状态管理功能。您可以通过设置 store=false 来选择无状态行为。如需了解详情，请参阅数据保留部分。

开始使用

  • 设置编码助理：连接到 Gemini 文档 MCP 并安装 gemini-interactions-api 技能，以便助理直接访问最新的开发者文档和最佳实践。 设置编码智能体 →
  • 从 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 资源。

服务器端状态管理

您可以在后续调用中使用已完成互动的 id，通过 previous_interaction_id 参数继续对话。服务器会使用此 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 与 background=true 不兼容，并且会阻止在后续回合中使用 previous_interaction_id。

您可以随时使用 API 参考中提供的删除方法删除存储的互动记录。只有在知道互动 ID 的情况下，您才能删除互动。

保留期限结束后，系统会自动删除您的数据。

系统会根据条款处理 Interaction 对象。

最佳做法

  • 缓存命中率：使用 previous_interaction_id 继续对话可让系统更轻松地利用对话记录的隐式缓存，从而提高性能并降低费用。
  • 混合互动：您可以灵活地在对话中混合使用代理和模型互动。例如，您可以使用 Deep Research 智能体等专业智能体进行初始数据收集，然后使用标准 Gemini 模型执行后续任务，例如总结或重新格式化，并通过 previous_interaction_id 将这些步骤关联起来。

支持的模型和代理

模型名称 类型 模型 ID
Gemini 3.1 Flash-Lite 模型 gemini-3.1-flash-lite
Gemini 3.1 Flash-Lite 预览版 模型 gemini-3.1-flash-lite-preview
Gemini 3 Pro 预览版 模型 gemini-3.1-pro-preview
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
Lyria 3 Clip 预览版 模型 lyria-3-clip-preview
Lyria 3 Pro 预览版 模型 lyria-3-pro-preview
Deep Research 预览版 代理 deep-research-pro-preview-12-2025
Deep Research 预览版 代理 deep-research-preview-04-2026
Deep Research 预览版 代理 deep-research-max-preview-04-2026
Antigravity 预览 代理 antigravity-preview-05-2026

SDK

您可以使用最新版本的 Google GenAI SDK 来访问 Interactions API。

  • 在 Python 中，这是 1.55.0 版本及更高版本中的 google-genai 软件包。
  • 在 JavaScript 中，这是 1.33.0 版本及更高版本的 @google/genai 软件包。

如需详细了解如何在库页面上安装 SDK，请参阅相关文档。

限制

  • 远程 MCP：Gemini 3 不支持远程 MCP，但很快就会支持。

generateContent API 支持以下功能，但 Interactions API 尚不支持这些功能：

反馈

您的反馈对于开发 Interactions API 至关重要。 欢迎在我们的 Google AI 开发者社区论坛上分享您的想法、报告 bug 或提出功能请求。

后续步骤