# Interactions API 不兼容变更迁移指南（2026 年 5 月）

{% callout type="warning" %}
**重大变化**：本指南中描述的更改是对 Interactions API 的重大更改。旧模式将被删除 **六月 8, 2026**。使用 `Api-Revision` 请求标头到 [管理您的迁移](/docs/interactions-breaking-changes-may-2026#how-to-migrate).
{% /callout %}

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

1. [**步骤架构**](/docs/interactions-breaking-changes-may-2026#steps-schema): 一个新的 `steps` 数组替换 `outputs` 数组，提供每个交互回合的结构化时间线。
1. [**输出格式配置**](/docs/interactions-breaking-changes-may-2026#output-format-config): 一种新的多态性 `response_format` 合并所有输出格式控制并删除 `response_mime_type`.

请按照以下步骤操作 [如何迁移到新架构](/docs/interactions-breaking-changes-may-2026#how-to-migrate) 更新您的集成。

## 核心变化： `outputs` 到 `steps` {% #steps-schema %}

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

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

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

### 基本输入/输出（一元）  {% #basic-unary %}

#### 之前（遗留）

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```python
# Request
interaction = client.interactions.create(
    model="gemini-3.8-flash", input="Tell me a joke."
)

# Response access
print(interaction.outputs[-1].text)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```javascript
// Request
const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Tell me a joke.'
});

// Response access
console.log(interaction.outputs[-1].text);
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Tell me a joke."
  }'
```

```none
// Response
{
  "id": "int_123",
  "role": "model",
  {{ '<strong>' }}"outputs": [
    {
      "type": "text",
      "text": "Why did the chicken cross the road?"
    }
  ]{{ '</strong>' }}
}
```
{% /tab %}
{% /tabs %}

#### 之后（新架构）

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```python
# Request
interaction = client.interactions.create(
    model="gemini-3.8-flash", input="Tell me a joke."
)

# Response access (Recommended sugar)
print(interaction.output_text)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```javascript
// Request
const interaction = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Tell me a joke.'
});

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

注：有关 SDK 便利属性的详细信息（包括 `.output_text`, `.output_image`, 和 `.output_audio`），参见 [使用 SDK 便利属性访问输出](/docs/interactions-overview#sdk-sugar)
在概述中。
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
# 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.8-flash",
    "input": "Tell me a joke."
  }'
```

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

// 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?"
        }
      ]
    }
  ]
}
```
{% /tab %}
{% /tabs %}

### 函数调用  {% #function-calling %}

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

#### 之前（遗留）

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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}")
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```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)}`);
    }
}
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```json
// Response
{
  "id": "int_001",
  "role": "model",
  "status": "requires_action",
  {{ '<strong>' }}"outputs": [
    {
      "type": "thought",
      "signature": "abc123..."
    },
    {
      "type": "function_call",
      "id": "fc_1",
      "name": "get_weather",
      "arguments": { "location": "Boston, MA" }
    }
  ]{{ '</strong>' }}
}
```
{% /tab %}
{% /tabs %}

#### 之后（新架构）

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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}")
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```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)}`);
    }
}
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```json
// POST Response
{
  "id": "int_001",
  "status": "requires_action",
  {{ '<strong>' }}"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" }
    }
  ]{{ '</strong>' }}
}
```
{% /tab %}
{% /tabs %}

### 服务器端工具  {% #server-side-tools %}

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

#### 之前（遗留）

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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}")
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```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}`);
    }
}
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Who won the last Super Bowl?",
    "tools": [
      { "type": "google_search" }
    ]
  }'
```

```html
// Response
{
  "id": "int_456",
  {{ '<strong>' }}"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": "...",
        "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"
        }
      ]
    }
  ]{{ '</strong>' }},
  "status": "completed"
}
```
{% /tab %}
{% /tabs %}

#### 之后（新架构）

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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}")
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```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[0].search_suggestions}`);
    }
}
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
# 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.8-flash",
    "input": "Who won the last Super Bowl?",
    "tools": [
      { "type": "google_search" }
    ]
  }'
```

```html
// POST Response
{
  "id": "int_456",
  {{ '<strong>' }}"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": "..."
      },
      "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
            }
          ]
        }
      ]
    }
  ]{{ '</strong>' }},
  "status": "completed"
}
```
{% /tab %}
{% /tabs %}

### 流式输出  {% #streaming %}

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

#### 新的事件类型  {% #event-types %}

- `interaction.created`
- `interaction.completed`
- `step.start`
- `step.delta`
- `step.stop`

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

#### 已弃用的事件类型  {% #deprecated-event-types %}

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

- `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`）。您必须累积这些增量才能获得完整的参数。这与一元调用不同，在一元调用中您会立即收到完整的函数调用对象。

#### 示例  {% #streaming-examples %}

##### 之前（旧版）

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```javascript
// Legacy streaming used content.delta
const stream = await client.interactions.create({
    model: 'gemini-3.8-flash',
    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);
        }
    }
}
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Explain quantum entanglement in simple terms.",
    "stream": true
  }'
```

```none
// 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}}
```
{% /tab %}
{% /tabs %}

##### 之后（新架构）

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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="")
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```javascript
// Consuming stream and handling new event types
const stream = await client.interactions.create({
    model: 'gemini-3.8-flash',
    input: 'Tell me a story.',
    stream: true,
});

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

{% tab filename="sample.sh" label="REST" %}
```bash
{{ '**' }}# 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.8-flash",
    "input": "Tell me a story.",
    "stream": true
  }'
```

```none
// Response (SSE Lines)
// event: interaction.created
// data: {"interaction": {"id": "int_xyz", "status": "in_progress", "object": "interaction", "model": "gemini-3.8-flash"}, "event_type": "interaction.created"}
//
// event: interaction.status_update
// data: {"interaction_id": "int_xyz", "status": "in_progress", "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: {"index": 1, "event_type": "step.stop"}
//
// event: interaction.completed
// data: {"interaction": {"id": "int_xyz", "status": "completed", "usage": {"total_input_tokens": 10, "total_output_tokens": 5, "total_tokens": 15}}, "event_type": "interaction.completed"} // NEW: Dedicated completion event
```
{% /tab %}
{% /tabs %}

### 无状态会话历史记录  {% #stateless-history %}

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

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

## 输出格式配置： `response_format` 变化  {% #output-format-config %}

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

### 主要变化  {% #response-format-changes %}

- **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)  {% #structured-output %}

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

#### 之前（遗留）

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```javascript
const interaction = await 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' }
        }
    },
});

console.log(interaction.outputs[-1].text);
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Summarize this article.",
    "response_mime_type": "application/json",
    "response_format": {
      "type": "object",
      "properties": {
        "summary": { "type": "string" }
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

#### 之后（新架构）

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```javascript
const interaction = await 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
console.log(interaction.output_text);
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
# 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.8-flash",
    "input": "Summarize this article.",
    "response_format": {
      "type": "text",
      "mime_type": "application/json",
      "schema": {
        "type": "object",
        "properties": {
          "summary": { "type": "string" }
        }
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

### 图像配置  {% #image-config %}

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

#### 之前（遗留）

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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"
        }
    },
)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```javascript
const interaction = await 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'
        }
    },
});
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
      }
    }
  }'
```
{% /tab %}
{% /tabs %}

#### 之后（新架构）

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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"
    },
)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```javascript
const interaction = await 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'
    },
});
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
# 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.8-flash",
    "input": "Generate an image of a sunset over the ocean.",
    "response_format": {
      "type": "image",
      "mime_type": "image/jpeg",
      "aspect_ratio": "1:1",
      "image_size": "1K"
    }
  }'
```
{% /tab %}
{% /tabs %}

### 音频配置  {% #audio-config %}

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

#### 之前（遗留）

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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"}
        ]
    }
)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```javascript
const interaction = await 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' }
        ]
    },
});
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.1-flash-tts-preview",
    "input": "Say cheerfully: Have a wonderful day!",
    "response_modalities": ["audio"],
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }'
```
{% /tab %}
{% /tabs %}

#### 之后（新架构）

{% tabs %}
{% tab filename="sample.py" label="Python" %}
```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"}
        ]
    }
)
```
{% /tab %}

{% tab filename="sample.js" label="JavaScript" %}
```javascript
const interaction = await 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' }
        ]
    },
});
```
{% /tab %}

{% tab filename="sample.sh" label="REST" %}
```bash
# 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.1-flash-tts-preview",
    "input": "Say cheerfully: Have a wonderful day!",
    "response_format": {
      "type": "audio"
    },
    "generation_config": {
      "speech_config": [
        { "voice": "Kore" }
      ]
    }
  }'
```

要请求多种输出模式（例如，文本和音频一起），请将格式条目数组传递给 `response_format` 而不是单个对象。
{% /tab %}
{% /tabs %}

## 如何迁移到新架构  {% #how-to-migrate %}

### SDK 用户  {% #sdk-users %}

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

### 休息 API 用户  {% #raw-api-users %}

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

### 时间轴  {% #timeline %}

| 日期        | 阶段   | 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` 标题被忽略。  |

{% callout type="note" %}
**注意事项**：5 月之后发布的新功能 7 将仅出现在 `steps` 回应。旧版用户 `outputs`
架构在迁移之前不会接收新功能。
{% /callout %}

## 迁移清单  {% #migration-checklist %}

### 步骤架构 (`steps`)

- 更新代码以读取响应内容 `steps` 数组而不是 `outputs`. [查看示例](/docs/interactions-breaking-changes-may-2026#basic-unary).
- 验证您的代码是否可以处理这两个问题 `user_input` 和 `model_output` 步骤类型。 [查看示例](/docs/interactions-breaking-changes-may-2026#basic-unary).
- （函数调用）更新代码查找 `function_call` 步骤在 `steps` 数组。 [查看示例](/docs/interactions-breaking-changes-may-2026#function-calling).
- （服务器端工具）更新代码以处理特定于工具的步骤（例如， `google_search_call`, `google_search_result`). [查看示例](/docs/interactions-breaking-changes-may-2026#server-side-tools).
- （无状态历史）更新历史管理以通过 `steps` 数组中的 `input` 下一个请求的字段。 [查看详情](/docs/interactions-breaking-changes-may-2026#stateless-history).
- （仅限流）更新客户端以侦听新的 SSE 事件类型（`interaction.created`, `step.delta`等）。 [查看示例](/docs/interactions-breaking-changes-may-2026#streaming).

### 输出格式配置（`response_format`)

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