Gemini 中文指南
获取 API 密钥 ↗

Interactions API 不兼容变更迁移指南(2026 年 5 月)

↓ 下载 MarkdownInteractions API

该 v1beta Interactions API 正在引入重大更改,重组 API 形状以支持未来的功能,例如飞行中转向和异步工具调用。此页面说明了更改内容并提供了前后代码示例以帮助您迁移。变更分为两类:

  1. 步骤架构: 一个新的 steps 数组替换 outputs 数组,提供每个交互回合的结构化时间线。
  2. 输出格式配置: 一种新的多态性 response_format 合并所有输出格式控制并删除 response_mime_type.

请按照以下步骤操作 如何迁移到新架构 更新您的集成。

核心变化: outputs 到 steps #

新架构取代了 outputs 数组有一个 steps 数组。

  • 遗产:响应返回平坦 outputs 仅包含模型生成的内容的数组。
  • 新模式:响应返回一个 steps 包含带有类型鉴别器的结构化步骤的数组。

POST /interactions 仅返回输出步骤。 GET /interactions/{id} 返回完整的步骤时间线,包括初始的 user_input 步骤。

基本输入/输出(一元) #

之前(遗留)#

python
# Request
interaction = client.interactions.create(
    model="gemini-3.8-flash", input="Tell me a joke."
)

# Response access
print(interaction.outputs[-1].text)

之后(新架构)#

python
# Request
interaction = client.interactions.create(
    model="gemini-3.8-flash", input="Tell me a joke."
)

# Response access (Recommended sugar)
print(interaction.output_text)

函数调用 #

请求结构保持不变,但响应取代了平面 outputs 具有结构化步骤的内容。

之前(遗留)#

python
# Accessing function call in legacy schema
for output in interaction.outputs:
    if output.type == "function_call":
        print(f"Calling {output.name} with {output.arguments}")

之后(新架构)#

python
# Accessing function call in new steps schema
for step in interaction.steps:
    if step.type == "function_call":
        print(f"Calling {step.name} with {step.arguments}")

服务器端工具 #

服务器端工具(例如 Google 搜索或代码执行)现在可以在 steps 数组。虽然旧架构将这些操作作为特定内容类型返回 outputs 数组,新模式将它们移动到 steps 数组。以下示例使用 Google 搜索。

之前(遗留)#

python
# Accessing search results in legacy schema
for output in interaction.outputs:
    if output.type == "google_search_call":
        print(f"Searched for: {output.arguments.queries}")
    elif output.type == "google_search_result":
        print(f"Found results: {output.result.rendered_content}")

之后(新架构)#

python
# Accessing search results in new steps schema
for step in interaction.steps:
    if step.type == "google_search_call":
        print(f"Searched for: {step.arguments.queries}")
    elif step.type == "google_search_result":
        print(f"Found results: {step.result[0].search_suggestions}")

流式输出 #

流式传输公开了新的事件类型:

新的事件类型 #

  • interaction.created
  • interaction.completed
  • step.start
  • step.delta
  • step.stop

interaction.status_update 是不变的。它承载着新 status (例如 in_progress 或 requires_action)。每个事件都在中命名其类型 event_type JSON 负载的字段,与 SSE 匹配 event: 线。

已弃用的事件类型 #

以下旧事件类型已被上面列出的新事件所取代:

  • interaction.start → interaction.created
  • content.start → step.start
  • content.delta → step.delta
  • content.stop → step.stop
  • interaction.complete → interaction.completed

流函数调用:当您使用函数调用进行流式传输时, step.start 事件传递函数名称,并且 step.delta 事件将参数作为部分 JSON 字符串进行流式传输(使用 arguments_delta)。您必须累积这些增量才能获得完整的参数。这与一元调用不同,在一元调用中您会立即收到完整的函数调用对象。

示例 #

之前(旧版)#
python
# Legacy streaming used content.delta
stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="Explain quantum entanglement in simple terms.",
    stream=True,
)

for chunk in stream:
    if chunk.event_type == "content.delta":
        if chunk.delta.type == "text":
            print(chunk.delta.text, end="", flush=True)
之后(新架构)#
python
# Consuming stream and handling new event types
for event in client.interactions.create(
    model="gemini-3.8-flash",
    input="Tell me a story.",
    stream=True,
):
    if event.event_type == "step.delta":  # CHANGED: step.delta instead of content.delta
        if event.delta.type == "text":
            print(event.delta.text, end="")

无状态会话历史记录 #

如果您在客户端手动管理对话历史记录(无状态用例),则必须更新先前回合的串连方式。

  • 遗产:开发者经常收集 outputs 来自响应的数组并将它们发送回 input 下一个回合的场地。
  • 新模式:您现在应该收集 steps 来自响应的数组并将其传递到 input 下一个请求的字段,将您的新用户回合作为 user_input 步骤。

输出格式配置: response_format 变化 #

更新后的 API 将所有输出格式控件整合为一个统一的多态 response_format 场。这将输出配置集中在顶层并保持 generation_config 专注于模型行为(如温度、top_p 和思维)。

主要变化 #

  • API 删除 response_mime_type. 现在,您可以指定内部每个格式条目的 MIME 类型 response_format.
  • response_format 现在是一个多态对象(或数组)。 每个条目都有一个 type 判别器(text, audio, image) 和特定于类型的字段。要请求多种输出模式,请传递格式条目数组。
  • image_config 移动自 generation_config 到 response_format. 您现在指定图像输出设置,例如 aspect_ratio 和 image_size 在一个 response_format 条目与 "type": "image".

结构化输出 (JSON) #

新架构删除了 response_mime_type 场。相反,在 a 中指定 MIME 类型和 JSON 架构 response_format 对象与 "type": "text".

之前(遗留)#

python
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Summarize this article.",
    response_mime_type="application/json",
    response_format={
        "type": "object",
        "properties": {
            "summary": {"type": "string"}
        }
    },
)

print(interaction.outputs[-1].text)

之后(新架构)#

python
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Summarize this article.",
    # response_mime_type is removed -- specify mime_type inside response_format
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": {
            "type": "object",
            "properties": {
                "summary": {"type": "string"}
            }
        }
    },
)

# Print response
print(interaction.output_text)

图像配置 #

新架构删除了 image_config 从 generation_config。现在,您可以在中指定图像输出设置 response_format 条目与 "type": "image".

之前(遗留)#

python
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Generate an image of a sunset over the ocean.",
    generation_config={
        "image_config": {
            "aspect_ratio": "1:1",
            "image_size": "1K"
        }
    },
)

之后(新架构)#

python
interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="Generate an image of a sunset over the ocean.",
    # image_config is removed from generation_config -- use response_format
    response_format={
        "type": "image",
        "mime_type": "image/jpeg",
        "aspect_ratio": "1:1",
        "image_size": "1K"
    },
)

音频配置 #

新架构取代 response_modalities: ["audio"] 与一个 response_format 的条目 "type": "audio".

之前(遗留)#

python
interaction = client.interactions.create(
    model="gemini-3.1-flash-tts-preview",
    input="Say cheerfully: Have a wonderful day!",
    response_modalities=["audio"],
    generation_config={
        "speech_config": [
            {"voice": "Kore"}
        ]
    }
)

之后(新架构)#

python
interaction = client.interactions.create(
    model="gemini-3.1-flash-tts-preview",
    input="Say cheerfully: Have a wonderful day!",
    # response_modalities is removed -- use response_format
    response_format={
        "type": "audio"
    },
    generation_config={
        "speech_config": [
            {"voice": "Kore"}
        ]
    }
)

如何迁移到新架构 #

SDK 用户 #

升级到最新的SDK版本(Python≥2.0.0, JavaScript≥2.0.0)。 SDK 自动选择您进入新模式 - 除了更新您读取响应的方式之外,无需更改任何代码(请参阅上面的示例)。请注意,这些 SDK 版本仅支持新架构。较旧的 SDK 版本(Python 1.x.x、JavaScript 1.x.x)将继续工作,直到旧架构被删除 六月 8, 2026.

休息 API 用户 #

添加 Api-Revision: 2026-05-20 标头以立即选择加入新架构。之后 5月 26,新架构成为所有请求的默认架构。您可以暂时选择退出 Api-Revision: 2026-05-07 直到 六月 8,当 API 永久删除旧模式时。

时间轴 #

日期阶段SDK 用户休息 API 用户
5月 7选择加入新的 SDK 版本可用(Python ≥2.0.0, JS ≥2.0.0)。升级以自动获取新架构。添加 Api-Revision: 2026-05-20 选择加入的标头。默认值仍然是旧版。
5月 26默认翻转如果已经升级,则无需执行任何操作。较旧的 SDK(Python 1.x.x、JS 1.x.x)仍然可以工作,但会返回旧响应。新架构现在是默认架构。发送 Api-Revision: 2026-05-07 选择退出的标题。
六月 8日落Python 1.x.x 和 JS 1.x.x SDK 版本将因 Interactions API 调用而中断。删除了 Interactions API 的旧架构。 Api-Revision 标题被忽略。

迁移清单 #

步骤架构 (steps)#

  • 更新代码以读取响应内容 steps 数组而不是 outputs. 查看示例.
  • 验证您的代码是否可以处理这两个问题 user_input 和 model_output 步骤类型。 查看示例.
  • (函数调用)更新代码查找 function_call 步骤在 steps 数组。 查看示例.
  • (服务器端工具)更新代码以处理特定于工具的步骤(例如, google_search_call, google_search_result). 查看示例.
  • (无状态历史)更新历史管理以通过 steps 数组中的 input 下一个请求的字段。 查看详情.
  • (仅限流)更新客户端以侦听新的 SSE 事件类型(interaction.created, step.delta等)。 查看示例.

输出格式配置(response_format)#

  • 更换 response_mime_type 与一个 mime_type 场内 response_format. 查看示例.
  • 包裹你现有的 response_format 内部的 JSON 模式 {"type": "text", "schema": ...} 对象。 查看示例.
  • (图像生成)移动 image_config 从 generation_config 到一个 {"type": "image", ...} 进入 response_format. 查看示例.
  • (语音生成)替换 response_modalities=["audio"] 与一个 {"type": "audio"} 进入 response_format. 查看示例.
  • (多式联运)转换 response_format 请求多种输出模式时从单个对象到数组。

搜索标题、API 名称或正文内容