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 步骤。
基本输入/输出(一元) #
之前(遗留)#
# Request
interaction = client.interactions.create(
model="gemini-3.8-flash", input="Tell me a joke."
)
# Response access
print(interaction.outputs[-1].text)
// 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);
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."
}'
// Response
{
"id": "int_123",
"role": "model",
{{ '<strong>' }}"outputs": [
{
"type": "text",
"text": "Why did the chicken cross the road?"
}
]{{ '</strong>' }}
}
之后(新架构)#
# Request
interaction = client.interactions.create(
model="gemini-3.8-flash", input="Tell me a joke."
)
# Response access (Recommended sugar)
print(interaction.output_text)
// 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 便利属性访问输出 在概述中。
# 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."
}'
// 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?"
}
]
}
]
}
函数调用 #
请求结构保持不变,但响应取代了平面 outputs 具有结构化步骤的内容。
之前(遗留)#
# Accessing function call in legacy schema
for output in interaction.outputs:
if output.type == "function_call":
print(f"Calling {output.name} with {output.arguments}")
// 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)}`);
}
}
// 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>' }}
}
之后(新架构)#
# 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}")
// 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)}`);
}
}
// 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>' }}
}
服务器端工具 #
服务器端工具(例如 Google 搜索或代码执行)现在可以在 steps 数组。虽然旧架构将这些操作作为特定内容类型返回 outputs 数组,新模式将它们移动到 steps 数组。以下示例使用 Google 搜索。
之前(遗留)#
# 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}")
// 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}`);
}
}
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" }
]
}'
// 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"
}
之后(新架构)#
# 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}")
// 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}`);
}
}
# 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" }
]
}'
// 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"
}
流式输出 #
流式传输公开了新的事件类型:
新的事件类型 #
interaction.createdinteraction.completedstep.startstep.deltastep.stop
interaction.status_update 是不变的。它承载着新 status (例如 in_progress 或 requires_action)。每个事件都在中命名其类型 event_type JSON 负载的字段,与 SSE 匹配 event: 线。
已弃用的事件类型 #
以下旧事件类型已被上面列出的新事件所取代:
interaction.start→interaction.createdcontent.start→step.startcontent.delta→step.deltacontent.stop→step.stopinteraction.complete→interaction.completed
流函数调用:当您使用函数调用进行流式传输时, step.start 事件传递函数名称,并且 step.delta 事件将参数作为部分 JSON 字符串进行流式传输(使用 arguments_delta)。您必须累积这些增量才能获得完整的参数。这与一元调用不同,在一元调用中您会立即收到完整的函数调用对象。
示例 #
之前(旧版)#
# 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)
// 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);
}
}
}
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
}'
// 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}}
之后(新架构)#
# 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="")
// 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);
}
}
}
{{ '**' }}# 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
}'
// 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
无状态会话历史记录 #
如果您在客户端手动管理对话历史记录(无状态用例),则必须更新先前回合的串连方式。
- 遗产:开发者经常收集
outputs来自响应的数组并将它们发送回input下一个回合的场地。 - 新模式:您现在应该收集
steps来自响应的数组并将其传递到input下一个请求的字段,将您的新用户回合作为user_input步骤。
输出格式配置: response_format 变化 #
更新后的 API 将所有输出格式控件整合为一个统一的多态 response_format 场。这将输出配置集中在顶层并保持 generation_config 专注于模型行为(如温度、top_p 和思维)。
主要变化 #
- 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) #
新架构删除了 response_mime_type 场。相反,在 a 中指定 MIME 类型和 JSON 架构 response_format 对象与 "type": "text".
之前(遗留)#
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)
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);
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" }
}
}
}'
之后(新架构)#
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)
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);
# 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" }
}
}
}
}'
图像配置 #
新架构删除了 image_config 从 generation_config。现在,您可以在中指定图像输出设置 response_format 条目与 "type": "image".
之前(遗留)#
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"
}
},
)
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'
}
},
});
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"
}
}
}'
之后(新架构)#
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"
},
)
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'
},
});
# 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"
}
}'
音频配置 #
新架构取代 response_modalities: ["audio"] 与一个 response_format 的条目 "type": "audio".
之前(遗留)#
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"}
]
}
)
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' }
]
},
});
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" }
]
}
}'
之后(新架构)#
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"}
]
}
)
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' }
]
},
});
# 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 而不是单个对象。
如何迁移到新架构 #
SDK 用户 #
升级到最新的SDK版本(Python≥2.0.0, JavaScript≥2.0.0)。 SDK 自动选择您进入新模式 - 除了更新您读取响应的方式之外,无需更改任何代码(请参阅上面的示例)。请注意,这些 SDK 版本仅支持新架构。较旧的 SDK 版本(Python 1.x.x、JavaScript 1.x.x)将继续工作,直到旧架构被删除 六月 8, 2026.
休息 API 用户 #
添加 Api-Revision: 2026-05-20 标头以立即选择加入新架构。之后 5月 26,新架构成为所有请求的默认架构。您可以暂时选择退出 Api-Revision: 2026-05-07 直到 六月 8,当 API 永久删除旧模式时。
时间轴 #
| 日期 | 阶段 | 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 标题被忽略。 |
迁移清单 #
步骤架构 (steps)#
- 更新代码以读取响应内容
steps数组而不是outputs. 查看示例. - 验证您的代码是否可以处理这两个问题
user_input和model_output步骤类型。 查看示例. - (函数调用)更新代码查找
function_call步骤在steps数组。 查看示例. - (服务器端工具)更新代码以处理特定于工具的步骤(例如,
google_search_call,google_search_result). 查看示例. - (无状态历史)更新历史管理以通过
steps数组中的input下一个请求的字段。 查看详情. - (仅限流)更新客户端以侦听新的 SSE 事件类型(
interaction.created,step.delta等)。 查看示例.
输出格式配置(response_format)#
- 更换
response_mime_type与一个mime_type场内response_format. 查看示例. - 包裹你现有的
response_format内部的 JSON 模式{"type": "text", "schema": ...}对象。 查看示例. - (图像生成)移动
image_config从generation_config到一个{"type": "image", ...}进入response_format. 查看示例. - (语音生成)替换
response_modalities=["audio"]与一个{"type": "audio"}进入response_format. 查看示例. - (多式联运)转换
response_format请求多种输出模式时从单个对象到数组。