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[-1].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[-1].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "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

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "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.in_progress
interaction.requires_action
interaction.error
step.start
step.delta
step.stop

已废弃的事件类型

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

interaction.start → interaction.created
content.start → step.start
content.delta → step.delta
content.stop → step.stop
interaction.complete → interaction.completed
error → interaction.error
interaction.status_update → 替换为 interaction.in_progress、interaction.requires_action 等。

流式函数调用：当您将流式与函数调用搭配使用时， 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

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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

 # Opt-in needed before May 26th
 curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
   -H "Content-Type: application/json" \
   -H "Accept: text/event-stream" \
   -H "Api-Revision: 2026-05-20" \
   -d '{
     "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.in_progress
 // data: {"interaction_id": "int_xyz", "event_type": "interaction.in_progress"}
 //
 // 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。 您现在可以在 response_format 条目中指定图片输出设置，例如 aspect_ratio 和 image_size ，并使用 "type": "image"。

结构化输出 (JSON)

新架构移除了 response_mime_type 字段。请改为在对象中使用 "type": "text"指定 MIME 类型和 JSON 架构。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[-1].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[-1].text);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Summarize this article.",
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "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

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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

# Opt-in needed before May 26th
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3-flash-preview",
    "input": "Generate an image of a sunset over the ocean.",
    "response_format": {
      "type": "image",
      "mime_type": "image/jpeg",
      "delivery": "inline",
      "aspect_ratio": "1:1",
      "image_size": "1K"
    }
  }'

如需请求多种输出模态（例如，同时请求文本和音频），请将格式条目数组传递给 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 月 8 日 移除。

REST API 用户

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

时间轴

日期	阶段	SDK 用户	REST 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` 标头以选择停用。
6 月 8 日	落日余晖	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

流式

新事件类型

已废弃的事件类型

示例

之前（旧版）

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`

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

步骤架构 (`steps`)

输出格式配置 (`response_format`)