Gemini Interactions API v1-创建查询取消交互-AutoRouter

通过 /v1/interactions 与 Gemini 模型或智能体交互。支持多轮对话、多模态输入、函数调用、后台任务与流式输出。

通过模型或智能体（Agent）创建一次交互。Interactions API 适合需要服务端状态、多轮上下文、工具调用、后台任务和实时流式输出的应用。

本页介绍稳定版 /v1/interactions。仍需使用 Beta 接口时，参阅 Interactions API (v1beta)。

model 与 agent 必须提供其中一个。使用模型时，生成参数放在 generation_config；使用智能体时，参数放在 agent_config。

Base URL

https://api.autorouter.top — Production

Authentication

BearerAuth: http (bearer)

使用 Bearer Token 认证。

格式：Authorization: Bearer sk-xxxxxx

Endpoints

REST URL 已经包含 /v1 版本，调用时无需再传 api_version 参数。

POST `/v1/interactions`

创建交互

创建一个新的模型或智能体交互。

Request Body

Content-Type: application/json

Example:

{
  "model": "gemini-flash-latest",
  "input": "你好，请介绍一下你自己"
}

请求字段说明：

Name	Type	Required	Description
`model`	string	条件	用于生成交互的模型。未提供 `agent` 时必填
`agent`	string	条件	用于生成交互的智能体。未提供 `model` 时必填。当前智能体暂不可用
`input`	string \| Content \| Content[] \| Step[]	Yes	字符串、单个内容块、内容块数组，或完整的 Step 数组
`system_instruction`	string	No	本次交互的系统指令
`tools`	object[]	No	模型可调用的工具声明，见「工具」
`response_format`	object \| object[]	No	文本、图像、音频或视频输出格式，见「ResponseFormat」
`stream`	boolean	No	是否以 Server-Sent Events 流式返回。仅作为输入
`store`	boolean	No	是否保存请求与响应，以便之后按 ID 查询。仅作为输入
`background`	boolean	No	是否在后台运行。仅作为输入。暂不可用
`generation_config`	object	No	模型配置。仅在设置 `model` 时适用
`generation_config.max_output_tokens`	integer	No	响应最多包含的 token 数
`generation_config.seed`	integer	No	解码随机种子，用于结果复现
`generation_config.stop_sequences`	string[]	No	遇到这些字符序列时停止输出
`generation_config.thinking_level`	string	No	思考级别：`minimal` / `low` / `medium` / `high`
`generation_config.thinking_summaries`	string	No	思考摘要：`auto` / `none`
`generation_config.tool_choice`	string \| object	No	工具选择，见「ToolChoiceConfig」
`agent_config`	object	No	智能体配置。仅在设置 `agent` 时适用
`agent_config.type`	string	Yes	使用 `agent_config` 时固定为 `dynamic`
`environment`	string \| object	No	智能体运行环境。该字段见于官方 v1 智能体 REST 示例，但未列入创建请求字段表
`previous_interaction_id`	string	No	上一次交互的 ID，用于延续上下文
`safety_settings`	object[]	No	本次交互的安全设置
`safety_settings[].method`	string	No	`probability`（默认）或 `severity`
`safety_settings[].threshold`	string	Yes	安全设置存在时必填，见下方取值
`safety_settings[].type`	string	Yes	有害内容类别，见下方取值

modelstring（条件必选）

用于生成交互的模型名称。未提供 agent 时必填。

具体模型 ID 以 AutoRouter 平台模型广场及 API Key 可见模型为准。

官方示例也使用 gemini-flash-latest 等滚动别名。别名是否开放同样以平台实际配置为准。

agentstring（条件必选）

用于生成交互的智能体名称。未提供 model 时必填。

当前智能体暂不可用。

safety_settingsobject[]（可选）

本次交互的安全过滤。每一项指定要拦截的类别和阈值。

Responses

200: 创建成功，返回 Interaction 资源；流式请求返回 InteractionSseEvent

Content-Type: application/json

400: 请求参数错误

401: 鉴权失败

403: API Key 无权访问模型或智能体

429: 请求频率限制

请求示例

curl -X POST "https://api.autorouter.top/v1/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-flash-latest",
  "input": "你好，请介绍一下你自己"
}'

响应示例

{
  "created": "2025-11-26T12:25:15Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3.6-flash",
  "object": "interaction",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Hello! I'm functioning perfectly and ready to assist you.\n\nHow are you doing today?"
        }
      ]
    }
  ],
  "updated": "2025-11-26T12:25:15Z",
  "usage": {
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 7
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 7,
    "total_output_tokens": 20,
    "total_thought_tokens": 22,
    "total_tokens": 49,
    "total_tool_use_tokens": 0
  }
}

场景示例

curl -X POST "https://api.autorouter.top/v1/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-flash-latest",
  "input": [
    {"type":"user_input","content":[{"type":"text","text":"Hello!"}]},
    {"type":"model_output","content":[{"type":"text","text":"Hi there! How can I help you today?"}]},
    {"type":"user_input","content":[{"type":"text","text":"What is the capital of France?"}]}
  ]
}'

响应示例

{
  "created": "2025-11-26T12:22:47Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3.6-flash",
  "object": "interaction",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "The capital of France is Paris."
        }
      ]
    }
  ],
  "updated": "2025-11-26T12:22:47Z",
  "usage": {
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 50
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 50,
    "total_output_tokens": 10,
    "total_thought_tokens": 0,
    "total_tokens": 60,
    "total_tool_use_tokens": 0
  }
}

curl -X POST "https://api.autorouter.top/v1/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-flash-latest",
  "input": [
    {"type":"text","text":"What is in this picture?"},
    {"type":"image","data":"BASE64_ENCODED_IMAGE","mime_type":"image/png"}
  ]
}'

响应示例

{
  "created": "2025-11-26T12:22:47Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3.6-flash",
  "object": "interaction",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "A white humanoid robot with glowing blue eyes stands holding a red skateboard."
        }
      ]
    }
  ],
  "updated": "2025-11-26T12:22:47Z",
  "usage": {
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 10
      },
      {
        "modality": "image",
        "tokens": 258
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 268,
    "total_output_tokens": 20,
    "total_thought_tokens": 0,
    "total_tokens": 288,
    "total_tool_use_tokens": 0
  }
}

curl -X POST "https://api.autorouter.top/v1/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-flash-latest",
  "tools": [{
    "type": "function",
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "The city and state, e.g. San Francisco, CA"
        }
      },
      "required": ["location"]
    }
  }],
  "input": "What is the weather like in Boston, MA?"
}'

响应示例

{
  "created": "2025-11-26T12:22:47Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "model": "gemini-3.6-flash",
  "object": "interaction",
  "status": "requires_action",
  "steps": [
    {
      "name": "get_weather",
      "type": "function_call",
      "arguments": {
        "location": "Boston, MA"
      },
      "id": "gth23981"
    }
  ],
  "updated": "2025-11-26T12:22:47Z",
  "usage": {
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 100
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 100,
    "total_output_tokens": 25,
    "total_thought_tokens": 0,
    "total_tokens": 125,
    "total_tool_use_tokens": 50
  }
}

长时间研究任务建议同时开启后台运行和存储。

curl -X POST "https://api.autorouter.top/v1/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "agent": "deep-research-pro-preview-12-2025",
  "input": "总结 2025 年癌症研究的主要进展",
  "background": true,
  "store": true
}'

curl -X POST "https://api.autorouter.top/v1/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "agent": "antigravity-preview-05-2026",
  "input": "阅读 Hacker News，汇总前五条新闻并保存为 Markdown 文件。",
  "environment": "remote"
}'

第一次响应会返回 environment_id。下一次请求把它与 previous_interaction_id 一起传回。

curl -X POST "https://api.autorouter.top/v1/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "agent": "antigravity-preview-05-2026",
  "input": "修改脚本，让它接受姓名参数。",
  "environment": "env_abc123",
  "previous_interaction_id": "v1_INTERACTION_ID"
}'

environment 对象可以为远程环境挂载仓库或内联文件。

curl -X POST "https://api.autorouter.top/v1/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "agent": "antigravity-preview-05-2026",
  "input": "检查仓库里的 Python 代码。",
  "environment": {
    "type": "remote",
    "sources": [{
      "type": "repository",
      "source": "https://github.com/octocat/Spoon-Knife",
      "target": "/workspace/repo"
    }]
  }
}'

先通过 /v1/agents 创建自定义智能体，再把其 ID 传给 agent。

curl -X POST "https://api.autorouter.top/v1/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "agent": "code-reviewer",
  "input": "审查 /workspace/repo/src 的最新改动。",
  "environment": "remote"
}'

Interaction

Interaction 资源表示一次模型或智能体交互。创建、查询和取消接口都会返回该资源；字段方向用于区分请求输入和响应输出。

属性

Name	Type	Required	Direction	Description
`agent`	string	条件	输入/输出	本次使用的智能体；未提供 `model` 时，创建请求必须提供该字段
`agent_config`	object	No	输入/输出	智能体配置；仅在设置 `agent` 时适用
`background`	boolean	No	仅输入	是否在后台运行交互
`created`	string	Yes	仅输出	创建时间，ISO 8601
`errors`	object[]	No	仅输出	诊断错误；每项包含 URI 形式的 `code` 和可读的 `message`
`generation_config`	object	No	仅输入	模型配置；仅在设置 `model` 时适用
`id`	string	Yes	仅输出	交互的唯一标识
`input`	string \| Content \| Content[] \| Step[]	创建时 Yes	输入/输出	创建交互时的输入
`max_total_tokens`	string	No	输入/输出	智能体运行可使用的最大总 token 数
`model`	string	条件	输入/输出	本次使用的模型；未提供 `agent` 时，创建请求必须提供该字段
`object`	string	示例字段	仅输出	REST 响应示例中的资源类型，值为 `interaction`；未列入 Interaction 属性表
`previous_interaction_id`	string	No	输入/输出	关联的上一次交互 ID
`response_format`	ResponseFormat \| ResponseFormat[]	No	输入/输出	输出格式配置
`safety_settings`	object[]	No	输入/输出	安全设置
`status`	string	Yes	仅输出	交互状态，见下表
`steps`	Step[]	Yes	仅输出	响应包含步骤时，表示构成该交互的步骤
`store`	boolean	No	仅输入	是否保存请求和响应以供之后查询
`stream`	boolean	No	仅输入	是否以 Server-Sent Events 流式返回
`system_instruction`	string	No	输入/输出	系统指令
`tools`	Tool[]	No	输入/输出	本次声明的工具
`updated`	string	Yes	仅输出	最近更新时间，ISO 8601
`usage`	object	No	仅输出	token 用量，见下表
`environment_id`	string	示例字段	仅输出	官方智能体示例返回的环境 ID，可用于复用环境；未列入 Interaction 属性表

Required 依据 Interaction 资源定义；创建请求自身的必填规则以本页 Request Body 表为准。

status 取值

Value	Description
`in_progress`	交互正在进行
`requires_action`	需要用户执行工具调用并提供结果
`completed`	交互已完成
`failed`	交互失败，可查看 `errors`
`cancelled`	交互已取消
`incomplete`	交互已结束，但结果不完整，例如达到 token 上限

Usage

Name	Type	Description
`cached_tokens_by_modality`	object[]	按模态拆分的缓存 token 用量
`grounding_tool_count`	object[]	Grounding 工具调用统计；每项包含 `type` 和 `count`
`input_tokens_by_modality`	object[]	按模态拆分的输入 token 用量
`output_tokens_by_modality`	object[]	按模态拆分的输出 token 用量
`tool_use_tokens_by_modality`	object[]	按模态拆分的工具使用 token 用量
`total_cached_tokens`	integer	缓存提示词中的 token 数
`total_input_tokens`	integer	输入上下文中的 token 数
`total_output_tokens`	integer	所有生成响应的 token 总数
`total_thought_tokens`	integer	思考模型使用的思考 token 数
`total_tokens`	integer	本次交互的总 token 数
`total_tool_use_tokens`	integer	工具使用提示中的 token 数

按模态统计的数组项包含 modality 和 tokens；modality 可以是 text、image、audio、video 或 document。grounding_tool_count 的数组项包含整数 count，以及值为 google_search 或 google_maps 的 type。

ResponseFormat

response_format 可以是一个对象，也可以是对象数组。用 type 区分输出模态。

`type`	主要字段	说明
`text`	`mime_type`、`schema`	文本或符合 JSON Schema 的 JSON
`image`	`aspect_ratio`、`delivery`、`image_size`、`mime_type`	图像输出
`audio`	`bit_rate`、`delivery`、`mime_type`、`sample_rate`	音频输出
`video`	`aspect_ratio`、`delivery`、`duration`、`resolution`	视频输出

ToolChoiceConfig

generation_config.tool_choice 可以直接使用 auto、any、none、validated，也可以用对象限制可调用的工具。

{
  "allowed_tools": {
    "mode": "any",
    "tools": ["get_weather"]
  }
}

POST `/v1/interactions/{id}/cancel`

取消交互

按 ID 取消一个仍在运行的后台交互。仅适用于创建时设置了 background: true、且尚未结束的任务。

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	要取消的 `Interaction.id`

本接口没有请求体。

Responses

200: 取消成功，返回 Interaction 资源，status 为 cancelled

请求示例

curl -X POST "https://api.autorouter.top/v1/interactions/{id}/cancel" \
  -H "Authorization: Bearer sk-xxxxxx"

响应示例

{
  "created": "2025-11-26T12:25:15Z",
  "id": "v1_INTERACTION_ID",
  "model": "gemini-3.6-flash",
  "object": "interaction",
  "status": "cancelled",
  "updated": "2025-11-26T12:25:20Z"
}

GET `/v1/interactions/{id}`

查询交互

按 ID 获取交互详情。适合轮询后台任务、取回已保存结果，或继续读取流式事件。

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	要查询的 `Interaction.id`

Query Parameters

Name	Type	Required	Description
`stream`	boolean	No	为 `true` 时以 Server-Sent Events 返回，默认 `false`
`last_event_id`	string	No	从指定事件之后继续。仅在 `stream=true` 时使用

本接口没有请求体。

Responses

200: 返回 Interaction 资源；stream=true 时返回 InteractionSseEvent

请求示例

curl -X GET "https://api.autorouter.top/v1/interactions/{id}" \
  -H "Authorization: Bearer sk-xxxxxx"

流式读取：

curl -N "https://api.autorouter.top/v1/interactions/{id}?stream=true" \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer sk-xxxxxx"

响应示例

{
  "created": "2025-11-26T12:25:15Z",
  "id": "v1_INTERACTION_ID",
  "model": "gemini-3.6-flash",
  "object": "interaction",
  "status": "completed",
  "steps": [{
    "type": "model_output",
    "content": [{"type":"text","text":"我这边很好，谢谢。需要我帮你做什么？"}]
  }],
  "updated": "2025-11-26T12:25:15Z"
}

DELETE `/v1/interactions/{id}`

删除交互

按 ID 删除一个已保存的交互。

Path Parameters

Name	Type	Required	Description
`id`	string	Yes	要删除的 `Interaction.id`

本接口没有请求体。

Responses

成功: 响应体为空。客户端应以实际返回的成功 HTTP 状态码为准

请求示例

curl -X DELETE "https://api.autorouter.top/v1/interactions/{id}" \
  -H "Authorization: Bearer sk-xxxxxx"

响应示例

成功时响应体为空。客户端只需检查 HTTP 状态码，不要调用 response.json()。

Content

input 以及 Step 的 content 使用内容块，用 type 区分。v1 定义以下四种内容块：

`type`	主要字段	说明
`text`	`text`、`annotations`	文本，模型输出可包含引用标注
`image`	`data`、`uri`、`mime_type`、`resolution`	Base64 或 URI 图像
`audio`	`data`、`uri`、`mime_type`、`sample_rate`、`channels`	Base64 或 URI 音频
`document`	`data`、`uri`、`mime_type`	PDF 或 CSV 文档

内容块必须设置 type。二进制内容可以使用 Base64 data 或 uri。

Text annotations

引用使用 start_index 和 end_index 标出对应文本片段；start_index 按字节计，end_index 不包含该位置。

`type`	字段	说明
`url_citation`	`url`、`title`、`start_index`、`end_index`	网页引用
`file_citation`	`document_uri`、`file_name`、`source`、`custom_metadata`、`page_number`、`media_id`、`start_index`、`end_index`	文件引用
`place_citation`	`name`、`place_id`、`url`、`review_snippets`、`start_index`、`end_index`	Google 地图地点引用

review_snippets 的项目包含 review_id、title 和 url。

Tool

创建交互时，tools 声明模型可以调用的工具。v1 的 Tool 资源定义以下六种类型：

`type`	主要字段	说明
`function`	`name`、`description`、`parameters`	自定义函数
`code_execution`	无	执行 Python 代码
`file_search`	`file_search_store_names`、`metadata_filter`、`top_k`	搜索文件库
`google_maps`	`enable_widget`、`latitude`、`longitude`	查询 Google 地图
`google_search`	`search_types`	Google 网页或图片搜索
`url_context`	无	提取 URL 内容

工具示例

{
  "type": "function",
  "name": "get_weather",
  "description": "查询指定地点的当前天气",
  "parameters": {
    "type": "object",
    "properties": {"location":{"type":"string"}},
    "required": ["location"]
  }
}

Step

Interaction 的 steps 记录输入、模型输出、思考过程以及工具调用和结果。

`type`	主要字段	说明
`user_input`	`content`	用户输入
`model_output`	`content`	模型输出
`thought`	`summary`、`signature`	思考摘要及后端签名
`function_call`	`id`、`name`、`arguments`	自定义函数调用
`function_result`	`call_id`、`name`、`result`、`is_error`	自定义函数结果
`code_execution_call`	`id`、`arguments`、`signature`	代码执行调用
`code_execution_result`	`call_id`、`result`、`is_error`、`signature`	代码执行结果
`file_search_call`	`id`、`signature`	文件搜索调用
`file_search_result`	`call_id`、`signature`	文件搜索结果
`google_maps_call`	`id`、`arguments`、`signature`	Google 地图调用
`google_maps_result`	`call_id`、`result`、`signature`	Google 地图结果
`google_search_call`	`id`、`arguments`、`search_type`、`signature`	Google 搜索调用
`google_search_result`	`call_id`、`result`、`is_error`、`signature`	Google 搜索结果
`url_context_call`	`id`、`arguments`、`signature`	URL 获取调用
`url_context_result`	`call_id`、`result`、`is_error`、`signature`	URL 获取结果

function_result.result 可以是字符串、对象，或由文本和图像内容块组成的数组。工具结果通过 call_id 对应调用步骤的 id。

Step 示例

{
  "type": "model_output",
  "content": [{"type":"text","text":"法国的首都是巴黎。"}]
}

InteractionSseEvent

创建请求设置 stream: true，或查询时使用 stream=true，服务器会以 Server-Sent Events 推送事件，用 event_type 区分。每个事件都可以带 event_id。查询时把上一次的 event_id 作为 last_event_id，即可从该事件之后继续。

`event_type`	说明	主要字段
`interaction.created`	交互已创建	`interaction`
`interaction.completed`	交互已结束，不再接受后续输入	`interaction`
`interaction.status_update`	状态更新	`interaction_id`、`status`、`usage`
`error`	流式处理错误	`error.code`、`error.message`
`step.start`	步骤开始	`index`、`step`
`step.delta`	步骤增量	`index`、`delta`、`metadata`、`total_usage`
`step.stop`	步骤结束	`index`、`step_usage`、`usage`

一次文本回复大致按这个顺序到达：interaction.created，然后 interaction.status_update（in_progress），接着 step.start、若干 step.delta、step.stop，最后是 interaction.completed。一次交互可以包含多个步骤。

点开某一 event_type 可查看该事件的字段。

流式响应示例

{
  "event_id": "evt_123",
  "event_type": "interaction.created",
  "interaction": {
    "created": "2025-12-04T15:01:45Z",
    "id": "v1_INTERACTION_ID",
    "model": "gemini-3-flash-preview",
    "object": "interaction",
    "status": "in_progress",
    "updated": "2025-12-04T15:01:45Z"
  }
}

客户端应记录最后处理成功的 event_id。连接中断后，用查询接口传入 stream=true&last_event_id=...，从下一条事件继续。

错误处理

HTTP 400 参数错误

场景	处理建议
`model` 和 `agent` 都未传	二者必须提供一个
`input` 未传	v1 中 `input` 为必填字段
同时使用不兼容的模型和智能体配置	模型使用 `generation_config`，智能体使用 `agent_config`
未知模型或智能体 ID	使用平台对当前 API Key 开放的 ID
`safety_settings` 使用 v1 不支持的类别或阈值	使用本页列出的 v1 枚举

HTTP 401 / 403 鉴权错误

401 Unauthorized：API Key 无效或已过期
403 Forbidden：API Key 无权访问该模型或智能体

状态	处理建议
`failed`	查看 `errors[].code` 和 `errors[].message`，调整输入后重试
`incomplete`	结果可能达到输出上限，可提高 `generation_config.max_output_tokens` 后重试
`requires_action`	执行 `steps` 中的工具调用，再把对应结果作为下一轮 `input` 发回
`cancelled`	交互已取消，需重新创建才能继续

Interactions API (v1)

modelstring（条件必选）

可选模型

agentstring（条件必选）

可选智能体

safety_settingsobject[]（可选）

属性

text

image

audio

video

text

image

audio

document

function

code_execution

file_search

google_maps

google_search

url_context

interaction.created

interaction.completed

interaction.status_update

error

step.start

step.delta

step.stop

目录