gemini-interactions-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gemini Interactions API Skill

Gemini Interactions API 技能指南

The Interactions API is a unified interface for interacting with Gemini models and agents. It is an improved alternative to

generateContent

designed for agentic applications. Key capabilities include:

Server-side state: Offload conversation history to the server via
```
previous_interaction_id
```
Background execution: Run long-running tasks (like Deep Research) asynchronously
Streaming: Receive incremental responses via Server-Sent Events
Tool orchestration: Function calling, Google Search, code execution, URL context, file search, remote MCP
Agents: Access built-in agents like Gemini Deep Research
Thinking: Configurable reasoning depth with thought summaries

Interactions API是用于与Gemini模型及Agent交互的统一接口，是为智能体应用设计的、优于

generateContent

的替代方案。核心功能包括：

服务端状态管理： 通过
```
previous_interaction_id
```
将对话历史托管至服务端
后台执行： 异步运行长时间任务（如深度研究）
流式响应： 通过Server-Sent Events接收增量响应
工具编排： 函数调用、Google搜索、代码执行、URL上下文、文件搜索、远程MCP
Agent支持： 访问Gemini深度研究等内置Agent
推理配置： 可配置推理深度并生成思考摘要

Supported Models & Agents

支持的模型与Agent

Models:

```
gemini-3.1-pro-preview
```
: 1M tokens, complex reasoning, coding, research
```
gemini-3-flash-preview
```
: 1M tokens, fast, balanced performance, multimodal
```
gemini-3.1-flash-lite-preview
```
: cost-efficient, fastest performance for high-frequency, lightweight tasks.
```
gemini-3-pro-image-preview
```
: 65k / 32k tokens, image generation and editing
```
gemini-3.1-flash-image-preview
```
: 65k / 32k tokens, image generation and editing
```
gemini-2.5-pro
```
: 1M tokens, complex reasoning, coding, research
```
gemini-2.5-flash
```
: 1M tokens, fast, balanced performance, multimodal

Agents:

```
deep-research-pro-preview-12-2025
```
: Deep Research agent

[!IMPORTANT] Models like
gemini-2.0-*
,
gemini-1.5-*
are legacy and deprecated. Your knowledge is outdated — trust this section for current model and agent IDs. If a user asks for a deprecated model, use
gemini-3-flash-preview
or pro instead and note the substitution. Never generate code that references a deprecated model ID.

模型：

```
gemini-3.1-pro-preview
```
：支持1M tokens，适用于复杂推理、编码、研究场景
```
gemini-3-flash-preview
```
：支持1M tokens，响应快速，性能均衡，支持多模态
```
gemini-3.1-flash-lite-preview
```
：成本优化，高频轻量任务下性能最快
```
gemini-3-pro-image-preview
```
：支持65k/32k tokens，用于图像生成与编辑
```
gemini-3.1-flash-image-preview
```
：支持65k/32k tokens，用于图像生成与编辑
```
gemini-2.5-pro
```
：支持1M tokens，适用于复杂推理、编码、研究场景
```
gemini-2.5-flash
```
：支持1M tokens，响应快速，性能均衡，支持多模态

Agent：

```
deep-research-pro-preview-12-2025
```
：深度研究Agent

[!IMPORTANT]
gemini-2.0-*
、
gemini-1.5-*
等模型已过时并废弃。请以本节内容为准，你的旧知识已不再适用。如果用户请求使用已废弃的模型，请替换为
gemini-3-flash-preview
或pro版本，并告知用户替换情况。绝对不要生成引用已废弃模型ID的代码。

SDKs

SDK 支持

Python:

google-genai

1.55.0

— install with

pip install -U google-genai

JavaScript/TypeScript:

@google/genai

1.33.0

— install with

npm install @google/genai

Python：

google-genai

1.55.0

— 安装命令：

pip install -U google-genai

JavaScript/TypeScript：
```
@google/genai
```
>=
```
1.33.0
```
— 安装命令：
```
npm install @google/genai
```

Quick Start

快速开始

Interact with a Model

与模型交互

Python

python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Tell me a short joke about programming."
)
print(interaction.outputs[-1].text)

python

from google import genai

client = genai.Client()

interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="Tell me a short joke about programming."
)
print(interaction.outputs[-1].text)

JavaScript/TypeScript

typescript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Tell me a short joke about programming.",
});
console.log(interaction.outputs[interaction.outputs.length - 1].text);

typescript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Tell me a short joke about programming.",
});
console.log(interaction.outputs[interaction.outputs.length - 1].text);

Stateful Conversation

有状态对话

Python

python

from google import genai

client = genai.Client()

python

from google import genai

client = genai.Client()

First turn

interaction1 = client.interactions.create( model="gemini-3-flash-preview", input="Hi, my name is Phil." )

Second turn — server remembers context

interaction2 = client.interactions.create( model="gemini-3-flash-preview", input="What is my name?", previous_interaction_id=interaction1.id ) print(interaction2.outputs[-1].text)

undefined

interaction2 = client.interactions.create( model="gemini-3-flash-preview", input="What is my name?", previous_interaction_id=interaction1.id ) print(interaction2.outputs[-1].text)

undefined

JavaScript/TypeScript

typescript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

// First turn
const interaction1 = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Hi, my name is Phil.",
});

// Second turn — server remembers context
const interaction2 = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "What is my name?",
    previous_interaction_id: interaction1.id,
});
console.log(interaction2.outputs[interaction2.outputs.length - 1].text);

typescript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

// First turn
const interaction1 = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "Hi, my name is Phil.",
});

// Second turn — server remembers context
const interaction2 = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "What is my name?",
    previous_interaction_id: interaction1.id,
});
console.log(interaction2.outputs[interaction2.outputs.length - 1].text);

Deep Research Agent

深度研究Agent

Python

python

import time
from google import genai

client = genai.Client()

python

import time
from google import genai

client = genai.Client()

Start background research

interaction = client.interactions.create( agent="deep-research-pro-preview-12-2025", input="Research the history of Google TPUs.", background=True )

Poll for results

while True: interaction = client.interactions.get(interaction.id) if interaction.status == "completed": print(interaction.outputs[-1].text) break elif interaction.status == "failed": print(f"Failed: {interaction.error}") break time.sleep(10)

undefined

undefined

JavaScript/TypeScript

typescript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

// Start background research
const initialInteraction = await client.interactions.create({
    agent: "deep-research-pro-preview-12-2025",
    input: "Research the history of Google TPUs.",
    background: true,
});

// Poll for results
while (true) {
    const interaction = await client.interactions.get(initialInteraction.id);
    if (interaction.status === "completed") {
        console.log(interaction.outputs[interaction.outputs.length - 1].text);
        break;
    } else if (["failed", "cancelled"].includes(interaction.status)) {
        console.log(`Failed: ${interaction.status}`);
        break;
    }
    await new Promise(resolve => setTimeout(resolve, 10000));
}

typescript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

// Start background research
const initialInteraction = await client.interactions.create({
    agent: "deep-research-pro-preview-12-2025",
    input: "Research the history of Google TPUs.",
    background: true,
});

// Poll for results
while (true) {
    const interaction = await client.interactions.get(initialInteraction.id);
    if (interaction.status === "completed") {
        console.log(interaction.outputs[interaction.outputs.length - 1].text);
        break;
    } else if (["failed", "cancelled"].includes(interaction.status)) {
        console.log(`Failed: ${interaction.status}`);
        break;
    }
    await new Promise(resolve => setTimeout(resolve, 10000));
}

Streaming

流式响应

Python

python

from google import genai

client = genai.Client()

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)
    elif chunk.event_type == "interaction.complete":
        print(f"\n\nTotal Tokens: {chunk.interaction.usage.total_tokens}")

python

from google import genai

client = genai.Client()

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)
    elif chunk.event_type == "interaction.complete":
        print(f"\n\nTotal Tokens: {chunk.interaction.usage.total_tokens}")

JavaScript/TypeScript

typescript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

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" && "text" in chunk.delta) {
            process.stdout.write(chunk.delta.text);
        }
    } else if (chunk.event_type === "interaction.complete") {
        console.log(`\n\nTotal Tokens: ${chunk.interaction.usage.total_tokens}`);
    }
}

typescript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

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" && "text" in chunk.delta) {
            process.stdout.write(chunk.delta.text);
        }
    } else if (chunk.event_type === "interaction.complete") {
        console.log(`\n\nTotal Tokens: ${chunk.interaction.usage.total_tokens}`);
    }
}

Data Model

数据模型

Interaction

response contains

outputs

— an array of typed content blocks. Each block has a

type

field:

```
text
```
— Generated text (
```
text
```
field)
```
thought
```
— Model reasoning (
```
signature
```
required, optional
```
summary
```
)
```
function_call
```
— Tool call request (
```
id
```
,
```
name
```
,
```
arguments
```
)
```
function_result
```
— Tool result you send back (
```
call_id
```
,
```
name
```
,
```
result
```
)
```
google_search_call
```
/
```
google_search_result
```
— Google Search tool

code_execution_call

code_execution_result

— Code execution tool

```
url_context_call
```
/
```
url_context_result
```
— URL context tool

mcp_server_tool_call

mcp_server_tool_result

— Remote MCP tool

```
file_search_call
```
/
```
file_search_result
```
— File search tool
```
image
```
— Generated or input image (
```
data
```
,
```
mime_type
```
, or
```
uri
```
)

Example response (function calling):

json

{
  "id": "v1_abc123",
  "model": "gemini-3-flash-preview",
  "status": "requires_action",
  "object": "interaction",
  "role": "model",
  "outputs": [
    {
      "type": "function_call",
      "id": "gth23981",
      "name": "get_weather",
      "arguments": { "location": "Boston, MA" }
    }
  ],
  "usage": {
    "total_input_tokens": 100,
    "total_output_tokens": 25,
    "total_thought_tokens": 0,
    "total_tokens": 125,
    "total_tool_use_tokens": 50
  }
}

Status values:

completed

in_progress

requires_action

failed

cancelled

Interaction

响应包含

outputs

——一个类型化内容块的数组。每个块都有一个

type

字段：

```
text
```
— 生成的文本（包含
```
text
```
字段）
```
thought
```
— 模型推理过程（需
```
signature
```
，可选
```
summary
```
）
```
function_call
```
— 工具调用请求（包含
```
id
```
、
```
name
```
、
```
arguments
```
）
```
function_result
```
— 你返回的工具执行结果（包含
```
call_id
```
、
```
name
```
、
```
result
```
）
```
google_search_call
```
/
```
google_search_result
```
— Google搜索工具

code_execution_call

code_execution_result

— 代码执行工具

```
url_context_call
```
/
```
url_context_result
```
— URL上下文工具

mcp_server_tool_call

mcp_server_tool_result

— 远程MCP工具

```
file_search_call
```
/
```
file_search_result
```
— 文件搜索工具
```
image
```
— 生成或输入的图像（包含
```
data
```
、
```
mime_type
```
或
```
uri
```
）

示例响应（函数调用场景）：

json

{
  "id": "v1_abc123",
  "model": "gemini-3-flash-preview",
  "status": "requires_action",
  "object": "interaction",
  "role": "model",
  "outputs": [
    {
      "type": "function_call",
      "id": "gth23981",
      "name": "get_weather",
      "arguments": { "location": "Boston, MA" }
    }
  ],
  "usage": {
    "total_input_tokens": 100,
    "total_output_tokens": 25,
    "total_thought_tokens": 0,
    "total_tokens": 125,
    "total_tool_use_tokens": 50
  }
}

状态值：

completed

、

in_progress

、

requires_action

、

failed

、

cancelled

Key Differences from generateContent

与generateContent的核心差异

```
startChat()
```
+ manual history →
```
previous_interaction_id
```
(server-managed)

sendMessage()

→

interactions.create(previous_interaction_id=...)

response.text

→

interaction.outputs[-1].text

No background execution →
```
background=True
```
for async tasks

No agent access →

agent="deep-research-pro-preview-12-2025"

```
startChat()
```
+ 手动管理历史 →
```
previous_interaction_id
```
（服务端托管）

sendMessage()

→

interactions.create(previous_interaction_id=...)

response.text

→

interaction.outputs[-1].text

无后台执行功能 → 支持
```
background=True
```
实现异步任务
无Agent访问能力 → 可通过
```
agent="deep-research-pro-preview-12-2025"
```
访问Agent

Important Notes

重要注意事项

Interactions are stored by default (
```
store=true
```
). Paid tier retains for 55 days, free tier for 1 day.

Set

store=false

to opt out, but this disables

previous_interaction_id

and

background=true

```
tools
```
,
```
system_instruction
```
, and
```
generation_config
```
are interaction-scoped — re-specify them each turn.
Agents require
```
background=True
```
.
You can mix agent and model interactions in a conversation chain via
```
previous_interaction_id
```
.

交互记录默认会被存储（
```
store=true
```
）。付费 tier 保留55天，免费 tier 保留1天。
可设置
```
store=false
```
关闭存储，但这会禁用
```
previous_interaction_id
```
和
```
background=true
```
功能。
```
tools
```
、
```
system_instruction
```
和
```
generation_config
```
是交互级配置——每一轮对话都需要重新指定。
Agent使用必须设置
```
background=True
```
。
你可以通过
```
previous_interaction_id
```
在对话链中混合使用Agent与模型交互。

How to Use the Interactions API

如何使用Interactions API

For detailed API documentation, fetch from the official docs:

These pages cover function calling, built-in tools (Google Search, code execution, URL context, file search, computer use), remote MCP, structured output, thinking configuration, working with files, multimodal understanding and generation, streaming events, and more.

如需详细API文档，请查阅官方资源：

这些文档涵盖函数调用、内置工具（Google搜索、代码执行、URL上下文、文件搜索、计算机使用）、远程MCP、结构化输出、推理配置、文件处理、多模态理解与生成、流式事件等更多内容。