Interactions API 是我们的新接口，也是使用 Gemini 模型和智能体进行构建的最直接方式。截至 2026 年 6 月，该接口已正式发布，是所有新项目的推荐接口。
虽然现在被视为旧版，但原始
generateContent API
仍完全受支持。
为什么要使用 Interactions API？
- 开箱即用的新功能：使用
previous_interaction_id的可选服务器端对话 状态、用于调试和界面呈现的可观测执行步骤，以及使用background=true的长时间运行 任务的后台执行。 - 缓存命中率更高，费用更低：服务器端状态管理 可实现更高效的跨轮次上下文缓存，从而降低多轮对话的令牌费用 。
- 专为前沿模型和智能体而打造：专为思考 模型、多步骤工具使用和复杂的推理流程而打造，可简化 智能体应用的构建、调试和编排过程。
- 适用于模型和智能体的单个 API：一个统一的接口，可直接调用 Gemini 模型和智能体（例如 Deep Research 和自定义 托管智能体），无需学习单独的端点或模式。
- 新功能的发布平台：未来，除了核心主线系列之外的新模型和功能 以及新的智能体功能 和工具，都将在 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 资源。
服务器端状态管理
您可以在后续调用中使用
previous_interaction_id 参数，使用已完成互动的 id 继续对话。服务器使用此 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 与 background=true 不兼容，并且会阻止在后续轮次中使用 previous_interaction_id。
您可以随时使用 API 参考文档中的删除方法删除存储的互动。只有在知道互动 ID 的情况下，您才能删除互动。
保留期限结束后，系统会自动删除您的数据。
系统会根据 条款 处理 Interaction 对象。
最佳实践
- 缓存命中率：使用
previous_interaction_id继续 对话可让系统更轻松地利用 对话记录的隐式缓存，从而提高性能并降低费用。 - 混合互动：您可以灵活地在对话中混合搭配智能体和
模型互动。例如，您可以使用专业智能体（例如 Deep Research 智能体）进行初始数据收集，然后使用标准 Gemini 模型执行后续任务（例如总结或重新格式化），并使用
previous_interaction_id将这些步骤关联起来。
支持的模型和智能体
| 模型名称 | 类型 | 模型 ID |
|---|---|---|
| Gemini 3.5 Flash | 模型 | gemini-3.5-flash |
| Gemini 3.1 Pro 预览版 | 模型 | gemini-3.1-pro-preview |
| 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 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-05-2026 |
SDK
您可以使用最新版本的 Google GenAI SDK 来访问 Interactions API。
- 在 Python 上，这是
2.3.0及更高版本的google-genai软件包。 - 在 JavaScript 上，这是
2.3.0及更高版本的@google/genai软件包。
如需详细了解如何在 库页面上安装 SDK，请参阅此页面。
限制
- 远程 MCP：Gemini 3 不支持远程 MCP，此功能即将推出。
generateContent API 支持以下功能，但 Interactions API 尚不支持 ：
- 视频元数据：
video_metadata字段，用于为视频理解设置剪辑 间隔和自定义帧速率。 - 批量 API
- 自动函数调用 (Python)
- 显式缓存：请注意，Interactions API
中可通过
previous_interaction_id使用服务器端隐式缓存。
反馈
您的反馈对于 Interactions API 的开发至关重要。 欢迎在 Google AI 开发者社区论坛上分享您的想法、报告 bug 或请求功能。