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 数组，其中包含带有类型判别器的结构化步骤。

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

基本输入/输出（一元）

之前（旧版）

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

// POST Response
{
  "id": "int_123",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Why did the chicken cross the road?"
        }
      ]
    }
  ]
}

// GET /v1beta/interactions/int_123 (returns full timeline including input)
{
  "id": "int_123",
  "steps": [
    {
      "type": "user_input",
      "content": [
        { "type": "text", "text": "Tell me a joke." }
      ]
    },
    {
      "type": "model_output",
      "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

// POST Response
{
  "id": "int_001",
  "status": "requires_action",
  "steps": [
    {
      "type": "thought",
      "summary": [{
        "type": "text",
        "text": "I need to check the weather in Boston..."
      }],
      "signature": "abc123..."
    },
    {
      "type": "function_call",
      "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" }
  ]
}

// POST Response
{
  "id": "int_456",
  "steps": [
    {
      "type": "google_search_call",
      "id": "gs_1",
      "arguments": { "queries": ["last Super Bowl winner"] },
      "signature": "abc123..."
    },
    {
      "type": "google_search_result",
      "call_id": "gs_1",
      "result": {
        "search_suggestions": "<div>...</div>"
      },
      "signature": "abc123..."
    },
    {
      "type": "model_output",
      "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.completed
interaction.status_update - 涵盖生命周期状态和错误（请参阅下文中的状态）
step.start
step.delta
step.stop

`interaction.status_update` 个状态

in_progress
active
interrupted
requires_action
error

已弃用的事件类型

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

interaction.start → interaction.created
content.start → step.start
content.delta → step.delta
content.stop → step.stop
interaction.complete → interaction.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.",
   "stream": true
 }

 // Response (SSE Lines)
 // event: interaction.created
 // data: {"interaction": {"id": "int_xyz", "status": "in_progress", "object": "interaction", "model": "gemini-3-flash-preview"}, "event_type": "interaction.created"}
 //
 // event: interaction.status_update
 // data: {"interaction_id": "int_xyz", "status": "active", "event_type": "interaction.status_update"}
 //
 // event: step.start
 // data: {"index": 0, "step": {"type": "thought", "signature": "abc123..."}, "event_type": "step.start"}
 //
 // event: step.stop
 // data: {"index": 0, "event_type": "step.stop"}
 //
 // event: step.start
 // data: {"index": 1, "step": {"content": [{"text": "Once upon", "type": "text"}], "type": "model_output"}, "event_type": "step.start"}
 //
 // event: step.delta
 // data: {"index": 1, "delta": {"text": " a time...", "type": "text"}, "event_type": "step.delta"}
 //
 // event: step.stop
 // data: {"type": "step.stop", "index": 1, "status": "done"}
 //
 // event: interaction.completed
 // data: {"type": "interaction.completed", "interaction": {"id": "int_xyz", "status": "completed", "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}}} // NEW: Dedicated completion event

无状态对话记录

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

旧版：开发者通常会从响应中收集 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。 现在，您可以在包含 "type": "image" 的 response_format 条目中指定图片输出设置，例如 aspect_ratio 和 image_size。

结构化输出 (JSON)

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

之前（旧版）

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。您现在可以在包含 "type": "image" 的 response_format 条目中指定图片输出设置。

之前（旧版）

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 ≥2.0.0，JavaScript ≥2.0.0）。SDK 会自动选择启用新架构，您只需更新读取响应的方式（请参阅上文中的示例），无需进行其他代码更改。请注意，这些 SDK 版本仅支持新架构。旧版 SDK（Python 1.x.x、JavaScript 1.x.x）将继续有效，直到旧版架构于 2026 年 6 月 1 日被移除为止。

REST API 用户

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

时间轴

日期	阶段	SDK 用户	REST API 用户
5 月 7 日	选择启用	新版 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-07` 标头即可选择停用。
6 月 1 日	落日余晖	Python 1.x.x 和 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`)