Gemini Deep Research 现已推出预览版，支持协作规划、可视化、MCP 等功能。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Interactions API：重大更改迁移指南（2026 年 5 月）

v1beta Interactions API 引入了破坏性更改，对 API 形状进行了重构，以支持未来的能力，例如中途引导和异步工具调用。本页介绍了具体变化，并提供了更改前后的代码示例，以帮助您进行迁移。更改分为两类：

步骤架构：新的 steps 数组取代了 outputs 数组，提供了每个互动轮次的结构化时间轴。
输出格式配置：新的多态 response_format整合了所有输出格式控件，并移除了 response_mime_type。

请按照如何迁移到新架构中的步骤更新集成。

核心更改：`outputs` 变为 `steps`

新架构将 outputs 数组替换为 steps 数组。

旧版：响应返回一个扁平的 outputs 数组，其中仅包含模型生成的内容。
新架构：响应返回一个 steps 数组，其中包含回显的用户输入和模型输出，提供了互动轮次的完整时间轴。

一元（非流式）响应会将您的输入回显为 steps 数组中的第一步。流式响应会跳过输入步骤，仅发出生成的内容增量。

基本输入/输出（一元）

之前（旧版）

Python

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

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

JavaScript

// Request
const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Tell me a joke.'
});

// Response access
console.log(interaction.outputs[0].text);

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Tell me a joke."
}

// Response
{
  "id": "int_123",
  "role": "model",
  "outputs": [
    {
      "type": "text",
      "text": "Why did the chicken cross the road?"
    }
  ]
}

之后（新架构）

Python

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

# Response access
print(interaction.steps[-1].content[0].text)  # CHANGED: steps instead of outputs

JavaScript

// Request
const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Tell me a joke.'
});

// Response access
console.log(interaction.steps.at(-1).content[0].text);

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Tell me a joke."
}

// Response
{
  "id": "int_123",
  "steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Tell me a joke."
        }
      ]
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "Why did the chicken cross the road?"
        }
      ]
    }
  ]
}

函数调用

请求结构保持不变，但响应会将扁平的 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}")

JavaScript

// Accessing function call in legacy schema
for (const output of interaction.outputs) {
    if (output.type === 'function_call') {
        console.log(`Calling {output.name} with {JSON.stringify(output.arguments)}`);
    }
}

REST

// Response
{
  "id": "int_001",
  "role": "model",
  "status": "requires_action",
  "outputs": [
    {
      "type": "thought",
      "signature": "abc123..."
    },
    {
      "type": "function_call",
      "id": "fc_1",
      "name": "get_weather",
      "arguments": { "location": "Boston, MA" }
    }
  ]
}

之后（新架构）

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}")

JavaScript

// Accessing function call in new steps schema
for (const step of interaction.steps) {
    if (step.type === 'function_call') {
        console.log(`Calling {step.name} with {JSON.stringify(step.arguments)}`);
    }
}

REST

// Response
{
  "id": "int_001",
  "status": "requires_action",
  "steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [
        { "type": "text", "text": "What's the weather in Boston?" }
      ]
    },
    {
      "type": "thought",
      "status": "done",
      "signature": "abc123..."
    },
    {
      "type": "function_call",
      "status": "waiting",
      "id": "fc_1",
      "name": "get_weather",
      "arguments": { "location": "Boston, MA" }
    }
  ]
}

服务器端工具

服务器端工具（例如 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}")

JavaScript

// Accessing search results in legacy schema
for (const output of interaction.outputs) {
    if (output.type === 'google_search_call') {
        console.log(`Searched for: {output.arguments.queries}`);
    } else if (output.type === 'google_search_result') {
        console.log(`Found results: {output.result.renderedContent}`);
    }
}

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Who won the last Super Bowl?",
  "tools": [
    { "type": "google_search" }
  ]
}

// Response
{
  "id": "int_456",
  "outputs": [
    {
      "type": "google_search_call",
      "id": "gs_1",
      "arguments": { "queries": ["last Super Bowl winner"] }
    },
    {
      "type": "google_search_result",
      "call_id": "gs_1",
      "result": {
        "rendered_content": "<div>...</div>",
        "url": "https://www.nfl.com/super-bowl"
      }
    },
    {
      "type": "text",
      "text": "The Kansas City Chiefs won the last Super Bowl.",
      "annotations": [
        {
          "start_index": 4,
          "end_index": 22,
          "source": "https://www.nfl.com/super-bowl"
        }
      ]
    }
  ],
  "status": "completed"
}

之后（新架构）

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.search_suggestions}")

JavaScript

// Accessing search results in new steps schema
for (const step of interaction.steps) {
    if (step.type === 'google_search_call') {
        console.log(`Searched for: {step.arguments.queries}`);
    } else if (step.type === 'google_search_result') {
        console.log(`Found results: {step.result.searchSuggestions}`);
    }
}

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Who won the last Super Bowl?",
  "tools": [
    { "type": "google_search" }
  ]
}

// Response
{
  "id": "int_456",
  "steps": [
    {
      "type": "user_input",
      "status": "done",
      "content": [
        { "type": "text", "text": "Who won the last Super Bowl?" }
      ]
    },
    {
      "type": "google_search_call",
      "status": "done",
      "id": "gs_1",
      "arguments": { "queries": ["last Super Bowl winner"] },
      "signature": "abc123..."
    },
    {
      "type": "google_search_result",
      "status": "done",
      "call_id": "gs_1",
      "result": {
        "search_suggestions": "<div>...</div>"
      },
      "signature": "abc123..."
    },
    {
      "type": "model_output",
      "status": "done",
      "content": [
        {
          "type": "text",
          "text": "The Kansas City Chiefs won the last Super Bowl.",
          "annotations": [
            {
              "type": "url_citation",
              "url": "https://www.nfl.com/super-bowl",
              "title": "NFL.com",
              "start_index": 4,
              "end_index": 22
            }
          ]
        }
      ]
    }
  ],
  "status": "completed"
}

流式

流式公开了新的事件类型：

新事件类型

interaction.created
interaction.status_update - 现在涵盖所有生命周期状态，包括完成和错误（请参阅下面的状态）
step.start
step.delta
step.stop

`interaction.status_update` 状态

in_progress
active
completed
interrupted
requires_action
error

已废弃的事件类型

以下旧版事件类型已替换为上面列出的新事件：

interaction.start → interaction.created
content.start → step.start
content.delta → step.delta
content.stop → step.stop
interaction.complete → interaction.status_update，且 status: "completed"
error → interaction.status_update，且 status: "error"
interaction.status_update → interaction.status_update（未更改，但现在涵盖了其他状态）

流式函数调用：当您将流式与函数调用结合使用时， step.start 事件会传递函数名称，而 step.delta 事件会以部分 JSON 字符串的形式流式传输参数（使用 arguments_delta）。您必须累积这些增量才能获得完整参数。这与一元调用不同，后者会一次性接收完整的函数调用对象。

示例

之前（旧版）

Python

# Legacy streaming used content.delta
stream = client.interactions.create(
    model="gemini-3-flash-preview",
    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)

JavaScript

// Legacy streaming used content.delta
const stream = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Explain quantum entanglement in simple terms.',
    stream: true,
});

for await (const chunk of stream) {
    if (chunk.event_type === 'content.delta') {
        if (chunk.delta.type === 'text') {
            process.stdout.write(chunk.delta.text);
        }
    }
}

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Explain quantum entanglement in simple terms.",
  "stream": true
}

// Response (SSE Lines)
// event: interaction.start
// data: {"id": "int_123", "status": "in_progress"}
//
// event: content.start
// data: {"index": 0, "type": "text"}
//
// event: content.delta
// data: {"delta": {"type": "text", "text": "Quantum entanglement is..."}}
//
// event: content.stop
// data: {"index": 0}
//
// event: interaction.complete
// data: {"id": "int_123", "status": "done", "usage": {"total_tokens": 42}}

之后（新架构）

Python

# Consuming stream and handling new event types
for event in client.interactions.create(
    model="gemini-3-flash-preview",
    input="Tell me a story.",
    stream=True,
):
    if event.type == "step.delta":  # CHANGED: step.delta instead of content.delta
        if event.delta.type == "text":
            print(event.delta.text, end="")

JavaScript

// Consuming stream and handling new event types
const stream = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Tell me a story.',
    stream: true,
});

for await (const event of stream) {
    if (event.type === 'step.delta') {  // CHANGED: step.delta instead of content.delta
        if (event.delta.type === 'text') {
            process.stdout.write(event.delta.text);
        }
    }
}

REST

 // Request: POST /v1beta/interactions
 // Accept: text/event-stream
 {
   "model": "gemini-3-flash-preview",
   "input": "Tell me a story."
 }

 // Response (SSE Lines)
 // event: interaction.created
 // data: {"type": "interaction.created", "interaction": {"id": "int_xyz", "status": "created"}} // CHANGED: 'type' instead of 'event_type'
 //
 // event: interaction.status_update
 // data: {"type": "interaction.status_update", "status": "in_progress"} // NEW: Lifecycle status updates in stream (postpone until Sessions launch dependency)
 //
 // event: step.start
 // data: {"type": "step.start", "index": 0, "step": {"type": "thought"}} // NEW: Replaces content.start, 'step' instead of 'content'
 //
 // event: step.delta
 // data: {"type": "step.delta", "index": 0, "delta": {"type": "thought", "text": "User wants an explanation."}} // NEW: Delta type matches step type
 //
 // event: step.stop
 // data: {"type": "step.stop", "index": 0, "status": "done"} // NEW: Includes status
 //
 // event: step.start
 // data: {"type": "step.start", "index": 1, "step": {"type": "model_output"}} // NEW: Step wrapper for output
 //
 // event: step.delta
 // data: {"type": "step.delta", "index": 1, "delta": {"type": "text", "text": "Hello"}}
 //
 // event: step.stop
 // data: {"type": "step.stop", "index": 1, "status": "done"}
 //
 // event: interaction.complete
 // data: {"type": "interaction.complete", "interaction": {"id": "int_xyz", "status": "completed", "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}}} // NEW: End of stream event with interaction details

无状态对话记录

如果您在客户端手动管理对话记录（无状态用例），则必须更新串联先前轮次的方式。

旧版：开发者通常会从响应中收集 outputs 数组，并在下一轮次中将其发送回 input 字段。
新架构：您现在应从响应中收集 steps 数组，并在下一个请求的 input 字段中传递该数组，并将新的用户轮次附加为 user_input 步骤。

输出格式配置：`response_format` 更改

更新后的 API 将所有输出格式控件整合到一个统一的多态 response_format 字段中。这会将输出配置集中在顶层，并使 generation_config 专注于模型行为（例如温度、top_p 和思考）。

主要变化

API 移除了 response_mime_type。您现在可以在 response_format 中为每个格式条目指定 MIME 类型。
response_format 现在是一个多态对象（或数组）。每个条目都有一个 type 鉴别器（text、audio、image）和特定于类型的字段。如需请求多种输出模态，请传递格式条目数组。
image_config 从 generation_config 移到了 response_format。 您现在可以在 response_format 条目中指定图片输出设置，例如 aspect_ratio 和 image_size ，且 "type": "image"。

结构化输出 (JSON)

新架构移除了 response_mime_type 字段。请改为在对象中指定 MIME 类型和 JSON 架构，且 "type": "text"。response_format

之前（旧版）

Python

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

print(interaction.outputs[0].text)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Summarize this article.',
    responseMimeType: 'application/json',
    responseFormat: {
        type: 'object',
        properties: {
            summary: { type: 'string' }
        }
    },
});

console.log(interaction.outputs[0].text);

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Summarize this article.",
  "response_mime_type": "application/json",
  "response_format": {
    "type": "object",
    "properties": {
      "summary": { "type": "string" }
    }
  }
}

之后（新架构）

Python

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    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(interaction.steps[-1].content[0].text)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Summarize this article.',
    // responseMimeType is removed — specify mimeType inside responseFormat
    responseFormat: {
        type: 'text',
        mimeType: 'application/json',
        schema: {
            type: 'object',
            properties: {
                summary: { type: 'string' }
            }
        }
    },
});

console.log(interaction.steps.at(-1).content[0].text);

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Summarize this article.",
  // response_mime_type is removed
  "response_format": {
    "type": "text",                          // NEW: type discriminator
    "mime_type": "application/json",          // MOVED: from response_mime_type
    "schema": {                              // RENAMED: was response_format directly
      "type": "object",
      "properties": {
        "summary": { "type": "string" }
      }
    }
  }
}

图片配置

新架构从 generation_config 中移除了 image_config。您现在可以在条目中指定图片输出设置，且 response_format "type": "image"。

之前（旧版）

Python

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

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Generate an image of a sunset over the ocean.',
    generationConfig: {
        imageConfig: {
            aspectRatio: '1:1',
            imageSize: '1K'
        }
    },
});

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "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-flash-preview",
    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",
        "delivery": "inline",
        "aspect_ratio": "1:1",
        "image_size": "1K"
    },
)

JavaScript

const interaction = await client.interactions.create({
    model: 'gemini-3-flash-preview',
    input: 'Generate an image of a sunset over the ocean.',
    // imageConfig is removed from generationConfig — use responseFormat
    responseFormat: {
        type: 'image',
        mimeType: 'image/jpeg',
        delivery: 'inline',
        aspectRatio: '1:1',
        imageSize: '1K'
    },
});

REST

// Request: POST /v1beta/interactions
{
  "model": "gemini-3-flash-preview",
  "input": "Generate an image of a sunset over the ocean.",
  // image_config removed from generation_config
  "response_format": {
    "type": "image",                         // NEW: type discriminator
    "mime_type": "image/jpeg",
    "delivery": "inline",
    "aspect_ratio": "1:1",                   // MOVED: from generation_config.image_config
    "image_size": "1K"                       // MOVED: from generation_config.image_config
  }
}

如需请求多种输出模态（例如，同时请求文本和音频），请将格式条目数组传递给 response_format，而不是传递单个对象。

如何迁移到新架构

SDK 用户

请升级到最新 SDK 版本（Python ≥1.76.0，JavaScript ≥1.53.0）。SDK 会自动让您选择启用新架构，除了更新读取响应的方式（请参阅上面的示例）之外，无需进行任何代码更改。请注意，这些 SDK 版本仅支持新架构。旧版 SDK（Python ≤1.73.1，JavaScript ≤1.50.1）将继续运行，直到旧版架构于 2026 年 6 月 6 日 移除。

REST API 用户

请将 Api-Revision: 2026-05-20 标头添加到您的请求中，以便立即选择启用新架构。5 月 20 日 之后，新架构将成为所有请求的默认架构。您可以使用 Api-Revision: 2026-05-06 暂时选择停用，直到 6 月 6 日，届时 API 将永久移除旧版架构。

时间轴

日期	阶段	SDK 用户	REST API 用户
5 月 6 日	选择启用	新主要 SDK 版本现已推出（Python ≥2.0.0，JS ≥2.0.0）。请升级以自动获取新架构。	添加 `Api-Revision: 2026-05-20` 标头以选择启用。默认架构仍为旧版。
5 月 20 日	默认翻转	如果已升级，则无需执行任何操作。旧版 SDK（Python 1.x.x、JS 1.x.x）仍然有效，但会返回旧版响应。	新架构现在是默认架构。发送 `Api-Revision: 2026-05-06` 标头以选择停用。
6 月 6 日	落日余晖	Python 和 JS 的 1.x.x SDK 版本将无法用于 Interactions API 调用。	移除了 Interactions API 的旧版架构。`Api-Revision` 标头将被忽略。

迁移核对清单

步骤架构 (`steps`)

更新代码，以从 steps 数组而不是 outputs 中读取响应内容。请参阅示例。
验证您的代码是否同时处理 user_input 和 model_output 步骤类型。请参阅示例。
（函数调用）更新代码，以在 steps 数组中查找 function_call 步骤。请参阅示例。
（服务器端工具）更新代码以处理特定于工具的步骤（例如，google_search_call、google_search_result）。请参阅示例。
（无状态记录）更新记录管理，以在下一个请求的 input 字段中传递 steps 数组。请参阅详情。
（仅限流式）更新客户端以监听新的 SSE 事件类型（interaction.created、step.delta 等）。请参阅示例。

输出格式配置 (`response_format`)

将 response_mime_type 替换为 response_format 中的 mime_type 字段。请参阅示例。
将现有的 response_format JSON 架构封装在 {"type": "text", "schema": ...} 对象中。请参阅示例。
（图片生成）将 image_config 从 generation_config 移到 response_format 中的 {"type": "image", ...} 条目。请参阅示例。
（多模态）在请求多种输出模态时，将 response_format 从单个对象转换为数组。

Interactions API：重大更改迁移指南（2026 年 5 月）

核心更改：outputs 变为 steps

基本输入/输出（一元）

之前（旧版）

Python

JavaScript

REST

之后（新架构）

Python

JavaScript

REST

函数调用

之前（旧版）

Python

JavaScript

REST

之后（新架构）

Python

JavaScript

REST

服务器端工具

之前（旧版）

Python

JavaScript

REST

之后（新架构）

Python

JavaScript

REST

流式

新事件类型

interaction.status_update 状态

已废弃的事件类型

示例

之前（旧版）

Python

JavaScript

REST

之后（新架构）

Python

JavaScript

REST

无状态对话记录

输出格式配置：response_format 更改

主要变化

结构化输出 (JSON)

之前（旧版）

Python

JavaScript

REST

之后（新架构）

Python

JavaScript

REST

图片配置

之前（旧版）

Python

JavaScript

REST

之后（新架构）

Python

JavaScript

REST

如何迁移到新架构

SDK 用户

REST API 用户

时间轴

迁移核对清单

步骤架构 (steps)

输出格式配置 (response_format)

核心更改：`outputs` 变为 `steps`

`interaction.status_update` 状态

输出格式配置：`response_format` 更改

步骤架构 (`steps`)

输出格式配置 (`response_format`)