如果你要开始一个新的 Gemini 项目,或者想把已有的 generateContent 调用迁过来,这篇适合你。读完你能发出第一次 Interactions API 请求,知道服务端会话状态怎么用、数据保留多久、哪些参数不会自动延续,以及什么时候该改用无状态模式。
Interactions API 是什么
Interactions API 在 2026 年 6 月正式开放使用,是 Google 为新项目推荐的接口。generateContent 被视为旧接口,但仍完整支持[1]。它相比旧接口多了三样东西:服务端保存会话状态(用 previous_interaction_id 串起多轮对话)、可以观察每一步执行过程(方便调试和界面展示),以及通过 background=true 运行长时间任务[1]。
接口的核心资源叫 Interaction。一个 Interaction 代表一次完整的对话轮次或任务,里面是按时间排列的执行步骤。步骤包括模型的思考、工具调用和结果(比如 function_call 和 function_result),以及最后的 model_output[1]。注意,interactions.create 的返回里只有模型生成的步骤,而 interactions.get 还会包含用户输入的 user_input 步骤[1]。
步骤列表的用处在于排查问题。拿到一个不理想的回答时,可以顺着步骤看模型是先思考、先调用了哪个工具,还是直接给出了结论,而不必只盯着最终文本。做界面时,也能把工具调用和返回结果按先后顺序展示给用户[1]。
第一次请求
下面的 Python 例子创建一个 Interaction,传入模型和一句输入,然后打印 output_text[1]:
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)Google 的 SDK 在不同语言里的名字不同:Python 需要 google-genai 2.3.0 或更高版本,JavaScript 需要 @google/genai 2.3.0 或更高版本。Go 用 google.golang.org/genai,Java 用 com.google.genai:google-genai[1]。
支持的模型里有 Gemini 4 Neon,模型 ID 是 gemini-4-neon,和 Gemini 4 Carbon、Argon、Hydrogen 排在一起[1]。Google 还表示,今后主线之外的新模型和新能力,以及新的智能体能力和工具,都会先在这个接口上线[1]。
多轮对话:服务端保存历史
如果不想每次都把完整聊天记录发回去,可以把上一轮的 Interaction ID 放进 previous_interaction_id。服务端会根据它取出对话历史,你只需发送新的输入[1]。下面的例子先告诉模型名字,再询问,第二轮就能答出来[1]:
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)这里有一个容易踩的坑:previous_interaction_id 只保留对话的输入和输出。tools、system_instruction 和 generation_config(包括 thinking_level 和 temperature)都只作用于当前这一次 Interaction。每一轮想让它们生效,都得重新传一遍[1]。这样设计的好处是,每一轮都能单独调整工具和思考档位,比如前几轮用较低的档位收集信息,最后一轮再换成更深的推理。代价是调用方必须记得每轮重新传参,否则工具会在后续轮次里悄悄消失[1]。
不想存数据:无状态模式
Interactions API 默认会保存每一次请求(store=true),这样才能用 previous_interaction_id、后台执行和查看执行记录。如果不希望保存,可以设 store=false,然后每次请求都把完整对话历史发过去,这就是无状态模式[1]。它适合对话内容不能留在服务端的场景,比如内部资料或私人用户会话。代价是历史要由你的程序保存、在变长时裁剪,并在每次请求时重新发送,对话越长,每次请求的输入也越大。
需要注意两点:store=false 和后台执行不能同时用,而且会让你无法再用 previous_interaction_id[1]。无状态模式下,缓存仍然可以生效,因为隐式缓存在两种模式下都支持[1]。
数据保留多久
付费层级的项目,交互记录保留 55 天;免费层级只保留 1 天[1]。付费项目可以在 AI Studio 里设置保留期,选择 7、14、28 或 55 天后自动标记删除。保留期缩短后,可能会影响你查询历史对话的能力[1]。
如果想提前删除,可以用 delete 方法,传入交互 ID 删除。到期后数据也会自动删除。在 AI Studio 的日志页面,也能查看和管理保存下来的交互[1]。
缓存和混用智能体
使用 previous_interaction_id 串联对话时,系统更容易复用对话历史的隐式缓存,性能更好,成本也更低[1]。同一段对话里还可以混用智能体和模型。例如先让 Deep Research 智能体收集资料,再用普通的 Gemini 模型做摘要或改写,两步之间通过 previous_interaction_id 连起来[1]。长对话尤其能从中受益:每一轮不必重新发送整段历史,缓存更容易命中;但工具和思考档位仍要每轮重新指定。
从 generateContent 迁移前先想清楚
迁移前,先把现有调用里用到的参数逐一列出来,分清哪些是会话级的、哪些是每次都要重新指定的。然后判断数据能不能存在服务端:能存,就用默认的有状态模式,让服务端承担历史管理;不能存,就用 store=false 加无状态模式,并自己负责保存历史[1]。两种模式的取舍,主要在于是否需要后台执行和 previous_interaction_id。
限制
- 远程 MCP:Gemini 3 目前还不支持远程 MCP[1]。
- 模态兼容:在一段对话里换用不同模型时,后面的模型要能接收前面模型输出的模态。例如用
gemini-3.1-flash-image生成了图片,就不能再接到只接受文本的模型上继续[1]。 - 尚未提供的功能:Batch API 和 Python 的自动函数调用还不能在 Interactions API 上使用。显式缓存也还没有,不过服务端的隐式缓存可以通过
previous_interaction_id使用[1]。
下一步
新项目可以直接从这个接口开始。已有的 generateContent 集成需要迁移时,先在一个小功能上试,确认输入、输出和缓存行为符合预期,再逐步替换。模型列表和智能体列表会随时间变化,以官方页面为准[1]。
来源
- 1Interactions APIGemini API docs
引用本页: Gemini Interactions API 入门. TellWorld, https://www.tellworld.net/zh/practice/practice-gemini-interactions-api. 更新于 2026-11-20