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

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

  1. **steps 架构**：新的 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.6-flash", input="Tell me a joke."
)

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

JavaScript

// Request
const interaction = await client.interactions.create({
    model: 'gemini-3.6-flash',
    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.6-flash",
    "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.6-flash", input="Tell me a joke."
)

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

JavaScript

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

// Response access (Recommended sugar)
console.log(interaction.output_text);

[sdk-convenience]: /gemini-api/docs/interactions-overview#sdk-sugar

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.6-flash",
    "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)