Gemini Interactions 与 generateContent 怎么选

Interactions API 是 Google 推荐的新项目默认接口，比 generateContent 多了服务端会话、可观测步骤与后台执行；后者已列 legacy。（核验 2026-11-05，F3、F4、F61）

一、Interactions API 值不值得换：问题不是哪个更新，而是多轮和长任务怎么处理

你可能遇到过这种情况：照着一篇教程，用 generateContent 跑通了单轮问答，感觉已经会用 Gemini 了。真做功能时，三件事立刻卡住。

用户追问第二句，你要自己把前面所有轮次重新拼进请求；要跑十分钟的批量任务，只能挂着连接干等；想知道模型中间判断了什么，拿不到任何结构化记录。

这三件事都不是「模型能力不够」，是旧接口没提供现成机制。

官方现在的口径很明确：Interactions API 是所有新项目的推荐接口（F3）；generateContent 仍然完全支持，但已被列为 legacy（F4）。legacy 不等于下线，它的意思是「能跑，但新东西不往这儿放」。

同一页文档列了三样开箱能力（F61）。把两者摆在一起，区别只有三行：

第一行决定你少写多少代码，第二行决定出问题能不能查，第三行决定架构撑不撑得住——长任务挂连接在生产里迟早出事。

还有一个更现实的理由：新模型和新 agent 能力会优先在 Interactions API 上线。也就是说，继续用旧接口不是「稳定」，是慢慢拿不到新东西。

所以本教程主线用它，不是追新，是少写三套脚手架。

二、generateContent 与 Interactions 的请求体对照：最小可运行示例

把同一段三轮对话，用两种写法各拼一次请求，差别一眼能看出来。下面这段代码不联网，只对比「第三轮请求里带什么」。

## EXPECT: 第 3 轮 | 旧写法重传 2 条历史 | 新写法只带 1 个 previous_interaction_id
## 示意结构，不是真实请求体；字段见 2.2，迁移对照见 12.1
TURNS = ["这张截图报什么错", "那我该怎么修", "给我一段示例代码"]

def legacy_payload_sketch(turn):
    # 旧写法：每轮把前面所有对话重新带上
    return {"input": TURNS[turn], "history": TURNS[:turn]}

def interactions_payload_sketch(turn):
    # 新写法：只带本轮输入 + 上一轮的 id
    return {"input": TURNS[turn], "previous_interaction_id": f"int_{turn - 1}" if turn else None}

last = len(TURNS) - 1
old = legacy_payload_sketch(last)
new = interactions_payload_sketch(last)
out = f"第 {last + 1} 轮 | 旧写法重传 {len(old['history'])} 条历史 | 新写法只带 1 个 previous_interaction_id"
assert len(old["history"]) == last
assert new["previous_interaction_id"] and new["input"] == TURNS[last]
print(out)

history 是示意字段：真实请求字段见 2.2，完整迁移对照见 12.1。这里只看一件事：旧写法每轮都要把前面的对话重新带上，新写法只带一个 id。对话越长差距越大——这也是官方说服务端状态能提升缓存命中、降低多轮成本的原因（F61）。

三、解释与边界：什么时候该换，什么时候别急着换

换之前先理清版本，这里最容易混。Interactions API 及核心特性在 v1 已 GA（F6）；但 SDK 默认仍走 v1beta（F7），要用稳定版得显式指定。REST 创建交互的端点是 /v1/interactions（F8）。Live API、Agents API、Webhooks、Context Caching、Audio Output 只在 beta 提供（F10），要用它们就得留在 beta——具体怎么选见 2.3。

三种情况值得换：新项目，没有历史包袱；要做多轮对话或长任务；要跟新模型和新 agent 能力。前两种是能力驱动，第三种是时间驱动。

两种情况可以先不动：现有系统大量依赖 generateContent 的字段和行为，迁移成本高于收益；或者你的功能主要靠 beta 独占能力，而 Interactions 那边的支持还没铺开。迁移不是改个函数名，字段对照和回归测试都得做（见 12.1）。

边界也要说清：本节只讲为什么选它，不真调接口，也不教迁移；示例里的字段是示意，字段口径见 2.2，迁移步骤见 12.1。

四、预期输出与异常分支：三种误读

在本地跑上面那段代码，输出是：

第 3 轮 | 旧写法重传 2 条历史 | 新写法只带 1 个 previous_interaction_id

三种误判，根源都是文档读快了一句。

• 把 legacy 读成下线。 generateContent 仍完全支持（F4），老项目不会被强制关停。
• 以为换了 API 就不用管历史。 服务端状态默认开着（store=true），但可以关掉（store=false，F62）；一旦关掉，历史还得自己带（见 4.1）。
• 以为换 API 能解决区域或配额问题。 完全不相关：区域看官方清单（F40，见 1.2），配额看付费层（见 10.2）。

五、判据卡：新项目与存量项目分别怎么选

六、来源与核验：官方页与 F 编号

• https://aistudio.google.com/docs/interactions-overview.md（核验 2026-11-05，F3、F4、F61）
• https://aistudio.google.com/api-reference/api-versions.md（核验 2026-11-05，F6、F7、F8、F10）
• https://aistudio.google.com/docs/migrate-to-interactions.md（核验 2026-11-05，F62）
• https://aistudio.google.com/docs/available-regions.md（核验 2026-11-05，F40）
• https://aistudio.google.com/docs/terms.md（核验 2026-11-05，F59，待核）

待核说明：本节不涉及许可条款，F59 仅登记备查。

七、动手试：三个可验收练习

1. 先跑一行代码确认这件事：TURNS = [f"第 {i} 轮" for i in range(1, 11)]，然后 print(len(legacy_payload_sketch(9)["history"]))。预期输出 9；如果你数成 10，是把当前轮也算进去了。
2. 把示例里的 TURNS 加到 5 条，重跑。看旧写法重传几条、新写法带几个 id——数字会变，结论不变。
3. 用一句话说出你项目里「最想摆脱的脚手架」是哪一件：历史拼接、长任务等待，还是中间过程不可见。写下这句话，并标注它对应哪一节（多轮拼接见 4.1、长任务见 9.3）。