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

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

通过模型或智能体（Agent）创建一次交互。可以传入纯文本，也可以传入图像、音频、视频和文档；支持多轮历史、工具调用和后台任务。

新项目建议使用稳定版 Interactions API (v1)。本页保留用于兼容 /v1beta/interactions。

当前为 Beta 接口，路径在 /v1beta/ 下。model 与 agent 必须提供其中一个：使用模型时，生成参数放在 generation_config；使用智能体时，参数放在 agent_config。

创建接口会直接返回 Interaction。需要事后按 ID 取回时，创建时将 store 设为 true。长时间任务将 background 设为 true，再用查询接口看状态；仍在运行的后台交互可以取消。

Base URL

https://api.autorouter.top — Production

Authentication

BearerAuth: http (bearer) 使用 Bearer Token 认证。格式: Authorization: Bearer sk-xxxxxx

Endpoints

POST `/v1beta/interactions`

创建交互

创建一个新的交互。通过 model 指定模型，或通过 agent 指定智能体。

Request Body

Content-Type: application/json

Example:

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

请求字段说明：

Name	Type	Required	Description
`model`	string	条件	用于生成交互的模型名称。未提供 `agent` 时必填。可选值见下方说明
`agent`	string	条件	用于生成交互的智能体名称。未提供 `model` 时必填。可选值见下方说明
`input`	string \| Content \| Content[] \| Step[]	No	交互输入。可以是字符串、单个内容块、内容块数组，或由 Step 组成的对话历史。各示例均会传入
`system_instruction`	string	No	本次交互的系统指令
`tools`	Tool[]	No	模型可调用的工具声明列表
`response_format`	object \| object[]	No	强制响应为符合所给 JSON Schema 的 JSON 对象
`stream`	boolean	No	是否以流式返回交互。仅作为输入
`store`	boolean	No	是否保存请求与响应，便于之后按 ID 查询。仅作为输入
`background`	boolean	No	是否在后台运行。仅作为输入。后台任务可用取消接口中止
`generation_config`	object	No	模型配置。仅在设置了 `model` 时适用，与 `agent_config` 二选一
`generation_config.max_output_tokens`	integer	No	响应中最多包含的 token 数
`generation_config.seed`	integer	No	解码使用的随机种子，用于结果复现
`generation_config.speech_config`	object \| object[]	No	语音与多说话人配置
`generation_config.speech_config.speakers`	object[]	No	各说话人的配置
`generation_config.speech_config.speakers[].language`	string	No	语音语言
`generation_config.speech_config.speakers[].speaker`	string	No	说话人名称，需与提示词中的名称一致
`generation_config.speech_config.speakers[].voice`	string	No	说话人音色
`generation_config.stop_sequences`	string[]	No	遇到这些字符序列时停止输出
`generation_config.thinking_level`	string	No	思考 token 级别：`minimal` / `low` / `medium` / `high`
`generation_config.thinking_summaries`	string	No	是否在响应中包含思考摘要：`auto` / `none`
`generation_config.tool_choice`	string \| object	No	工具选择：`auto` / `any` / `none` / `validated`
`generation_config.transcription_config`	object	No	语音识别配置。传入即启用转写
`generation_config.transcription_config.custom_vocabulary`	string[]	No	自定义词汇，引导识别偏向特定术语
`generation_config.transcription_config.language_codes`	string[]	No	BCP-47 语言代码。省略或为空时自动检测语言
`generation_config.transcription_config.mode`	string \| object	No	转写模式：`verbatim`（逐字）/ `smart`（智能）
`generation_config.transcription_config.mode.type`	string	Yes	模式为对象时必填。取值 `smart` 或 `verbatim`
`generation_config.transcription_config.mode.diarization_mode`	string	No	仅 `verbatim`。说话人分离，支持值：`speaker`
`generation_config.transcription_config.mode.timestamp_granularities`	string[]	No	仅 `verbatim`。时间戳粒度，支持值：`word`。为空则不生成时间戳
`generation_config.video_config`	object	No	视频生成配置
`generation_config.video_config.task`	string	No	视频生成任务模式。未指定时由模型根据提示词和输入媒体判断
`agent_config`	object	No	智能体配置。仅在设置了 `agent` 时适用，与 `generation_config` 二选一
`environment`	string \| object	No	运行环境。可以是已有环境 ID，也可以是描述远程环境来源的对象
`labels`	object	No	自定义标签。键和值长度均不超过 63 个字符，只能包含小写字母、数字、下划线和短横线。键必须以字母开头
`previous_interaction_id`	string	No	上一次交互的 ID，用于延续上下文
`safety_settings`	object[]	No	本次交互的安全设置
`safety_settings[].method`	string	No	内容拦截方式。未指定时按概率分数拦截
`safety_settings[].threshold`	string	Yes	拦截阈值。安全设置存在时必填
`safety_settings[].type`	string	Yes	要拦截的有害内容类别。安全设置存在时必填
`service_tier`	string	No	服务层级：`flex` / `standard` / `priority` / `deferred`
`webhook_config`	object	No	交互完成时的 Webhook 通知配置
`webhook_config.uris`	string[]	No	设置后，事件发往这些 URI，不再使用已注册的 Webhook
`webhook_config.user_metadata`	object	No	用户元数据，会随每次事件推送返回

modelstring（条件必选）

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

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

agentstring（条件必选）

用于生成交互的智能体名称。未提供 model 时必填。也可以传入已创建的自定义智能体 ID。

Deep Research 一类长时间任务建议同时设置 "background": true，再通过查询接口获取进度。

inputstring | object | array（可选）

本次交互的输入，模型和智能体通用。

字符串：直接作为用户文本
单个 Content，或 Content[]：文本、图像、音频、视频、文档
Step 数组：多轮历史，元素为 user_input / model_output 等步骤

示例值：你好，请介绍一下你自己

toolsobject[]（可选）

模型在本次交互中可以调用的 Tool。用 type 区分类型。

generation_configobject（可选）

模型侧生成参数。仅在请求里设置了 model 时生效。

backgroundboolean（可选）

是否在后台运行本次交互。适合 Deep Research 等耗时任务。

后台任务创建后先返回进行中的 Interaction，再用查询接口轮询 status，直到变为 completed、failed、cancelled 或 incomplete。仍在运行时，可调用取消接口。

storeboolean（可选）

是否保存本次请求与响应，以便之后用查询接口按 id 取回。

streamboolean（可选）

是否以流式方式返回本次交互。查询接口也可以用查询参数 stream=true 以 Server-Sent Events 续传。事件字段见文末「InteractionSseEvent」。

environmentstring | object（可选）

智能体的运行环境。

"remote"：新建一个远程环境。响应里的 environment_id 可在后续请求中原样传回，以复用同一环境
已有环境 ID 字符串：继续使用该环境，通常同时传入 previous_interaction_id
对象：描述远程环境，并可挂载代码仓库或内联文件

{
  "environment": {
    "type": "remote",
    "sources": [
      {
        "type": "repository",
        "source": "https://github.com/octocat/Spoon-Knife",
        "target": "/workspace/repo"
      },
      {
        "type": "inline",
        "content": "只关注 Python 文件。",
        "target": "/workspace/notes.txt"
      }
    ]
  }
}

previous_interaction_idstring（可选）

上一次交互的 ID。与已有 environment 一起使用时，智能体可以接着上次的文件和上下文继续工作。

safety_settingsobject[]（可选）

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

service_tierstring（可选）

交互的服务层级：flex、standard、priority、deferred。

Responses

200: 创建成功，返回 Interaction

Content-Type: application/json

400: 请求参数错误

Content-Type: application/json

401: 鉴权失败

429: 请求频率限制

请求示例

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "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/v1beta/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/v1beta/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/v1beta/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/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "agent": "deep-research-pro-preview-12-2025",
  "input": "Find a cure to cancer",
  "background": true
}'

响应示例

{
  "agent": "deep-research-pro-preview-12-2025",
  "created": "2025-11-26T12:22:47Z",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "object": "interaction",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Here is a comprehensive research report on the current state of cancer research..."
        }
      ]
    }
  ],
  "updated": "2025-11-26T12:22:47Z",
  "usage": {
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 20
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 20,
    "total_output_tokens": 1000,
    "total_thought_tokens": 500,
    "total_tokens": 1520,
    "total_tool_use_tokens": 0
  }
}

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "agent": "antigravity-preview-05-2026",
  "input": "Read Hacker News, summarize the top 5 stories, and save results as a markdown file.",
  "environment": "remote"
}'

响应示例

{
  "agent": "antigravity-preview-05-2026",
  "created": "2025-11-26T12:22:47Z",
  "environment_id": "env_abc123",
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "object": "interaction",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "I've summarized the top 5 Hacker News stories and saved the results to /workspace/summary.md."
        }
      ]
    }
  ],
  "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": 500,
    "total_thought_tokens": 200,
    "total_tokens": 750,
    "total_tool_use_tokens": 0
  }
}

# Step 1: Create an interaction with a fresh remote environment.
RESPONSE=$(curl -s -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "agent": "antigravity-preview-05-2026",
  "input": "Write a hello world script at /workspace/hello.py.",
  "environment": "remote"
}')

INTERACTION_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
ENV_ID=$(echo "$RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['environment_id'])")

# Step 2: Reuse the same environment in a follow-up interaction.
curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d "{
  \"agent\": \"antigravity-preview-05-2026\",
  \"input\": \"Modify the script to accept a name argument and greet the user.\",
  \"environment\": \"$ENV_ID\",
  \"previous_interaction_id\": \"$INTERACTION_ID\"
}"

响应示例

{
  "agent": "antigravity-preview-05-2026",
  "created": "2025-11-26T12:23:00Z",
  "environment_id": "env_abc123",
  "id": "v1_Chd2ZTJhYmNkZWZnaGlqa2xtbm9wcXJzdHV2d3h5ejAxMjM0NTY3ODkwMTIzNDU2Nzg",
  "object": "interaction",
  "status": "completed",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "I've updated /workspace/hello.py to accept a name argument and greet the user."
        }
      ]
    }
  ],
  "updated": "2025-11-26T12:23:00Z",
  "usage": {
    "input_tokens_by_modality": [
      {
        "modality": "text",
        "tokens": 80
      }
    ],
    "total_cached_tokens": 0,
    "total_input_tokens": 80,
    "total_output_tokens": 200,
    "total_thought_tokens": 100,
    "total_tokens": 380,
    "total_tool_use_tokens": 0
  }
}

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "agent": "antigravity-preview-05-2026",
  "input": "List all files under /workspace and summarize what you find.",
  "environment": {
    "type": "remote",
    "sources": [
      {
        "type": "repository",
        "source": "https://github.com/octocat/Spoon-Knife",
        "target": "/workspace/repo"
      },
      {
        "type": "inline",
        "content": "Focus on Python files only.",
        "target": "/workspace/notes.txt"
      }
    ]
  }
}'

# Step 1: Create a custom agent.
curl -X POST "https://api.autorouter.top/v1beta/agents" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "id": "code-reviewer",
  "base_agent": "antigravity-preview-05-2026",
  "system_instruction": "You are a senior code reviewer. Check every file for bugs, style issues, and security vulnerabilities.",
  "base_environment": {
    "type": "remote",
    "sources": [{
      "type": "repository",
      "source": "https://github.com/octocat/Spoon-Knife",
      "target": "/workspace/repo"
    }]
  }
}'

# Step 2: Use the custom agent.
curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "agent": "code-reviewer",
  "input": "Review the latest changes in /workspace/repo/src and file a summary.",
  "environment": "remote"
}'

Interaction

Name	Type	Description
`id`	string	交互的唯一标识。仅输出
`object`	string	固定为 `interaction`
`status`	string	交互状态，见下方说明
`created`	string	创建时间，ISO 8601，例如 `2025-11-26T12:25:15Z`
`updated`	string	最近更新时间，ISO 8601
`model`	string	本次使用的模型。走智能体时可能不返回
`agent`	string	本次使用的智能体。走模型时可能不返回
`steps`	object[]	构成该交互的步骤
`environment_id`	string	环境 ID。请求中设置了环境时返回，可在后续请求的 `environment` 中复用
`usage`	object	token 用量
`usage.total_input_tokens`	integer	输入 token 数
`usage.total_output_tokens`	integer	输出 token 数
`usage.total_cached_tokens`	integer	输入中命中缓存的 token 数
`usage.total_thought_tokens`	integer	思考 token 数
`usage.total_tool_use_tokens`	integer	工具使用相关 token 数
`usage.total_tokens`	integer	本次交互计入的总 token 数
`usage.input_tokens_by_modality`	object[]	按模态统计的输入 token。同类还有 `output_tokens_by_modality`、`cached_tokens_by_modality`、`tool_use_tokens_by_modality`
`usage.*_by_modality[].modality`	string	模态：`text` / `image` / `audio` / `video` / `document`
`usage.*_by_modality[].tokens`	integer	该模态的 token 数
`usage.grounding_tool_count`	object[]	grounding 工具调用次数
`usage.grounding_tool_count[].type`	string	`google_search`（网页与图片搜索）/ `google_maps`（地图）/ `retrieval`（客户数据检索）
`usage.grounding_tool_count[].count`	integer	该类型的调用次数
`errors`	object[]	诊断故障或平台错误。成功时通常不返回
`errors[].code`	string	标识错误类型的 URI
`errors[].message`	string	可读的错误信息
`input`	string \| Content \| Content[] \| Step[]	交互输入。查询时需 `include_input=true` 才会带回
`system_instruction`	string	系统指令
`tools`	Tool[]	本次声明的工具
`previous_interaction_id`	string	关联的上一次交互 ID
`labels`	object	创建时写入的自定义标签
`service_tier`	string	服务层级：`flex` / `standard` / `priority` / `deferred`

statusstring

交互状态：

in_progress：进行中
requires_action：需要你继续提供输入，例如执行函数后把结果再发回去
completed：已完成
failed：失败
cancelled：已取消
incomplete：已结束但结果不完整，例如达到 max_output_tokens
queued：已排队，等待处理

后台任务建议隔几秒查询一次，直到 status 变为 completed、failed、cancelled 或 incomplete。

stepsobject[]

构成该交互的步骤。示例中出现的类型如下，完整 Step 定义以 Gemini 官方文档为准。

`type`	说明	主要字段
`user_input`	用户输入	`content`：Content[]
`model_output`	模型输出	`content`：Content[]
`function_call`	模型发起的函数调用	`id`、`name`、`arguments`

usageobject

本次交互的 token 用量，可作为用量核对依据。

total_input_tokensinteger

提示词与上下文消耗的 token 数。

total_output_tokensinteger

生成内容消耗的 token 数。

total_thought_tokensinteger

思考过程消耗的 token 数。

total_tool_use_tokensinteger

工具使用相关的 token 数。

total_tokensinteger

本次交互的总 token 数，包含输入、输出以及其他内部 token。

input_tokens_by_modalityobject[]

按模态拆分的用量。每一项包含 modality（text、image、audio、video、document）和 tokens。输出、缓存、工具使用也有对应的 *_by_modality 数组。

POST `/v1beta/interactions/{interactionsId}/cancel`

取消交互

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

Path Parameters

Name	Type	Required	Description
`interactionsId`	string	Yes	要取消的交互 ID

Responses

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

Content-Type: application/json

请求示例

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

响应示例

{
  "agent": "deep-research-pro-preview-12-2025",
  "created": "2026-06-22T04:55:47Z",
  "id": "v1_ChdVc0E0YXJTYk1zYlV6N0lQcXRXVG1BYxIXVXNBNGFyU2JNc2JVejdJUHF0V1RtQWM",
  "object": "interaction",
  "status": "cancelled",
  "steps": [
    {
      "type": "user_input",
      "content": [
        {
          "type": "text",
          "text": "Research the history of the Google TPUs with a focus on 2025 specs."
        }
      ]
    }
  ],
  "updated": "2026-06-22T04:55:47Z"
}

GET `/v1beta/interactions/{interactionsId}`

查询交互

根据创建时返回的 id 获取交互详情。适合轮询后台任务，或取回已保存的结果。

Headers

Name	Type	Required	Description
`Authorization`	string	Yes	请求身份认证。格式：`Bearer sk-xxxxxx`

Path Parameters

Name	Type	Required	Description
`interactionsId`	string	Yes	要查询的交互 ID

Query Parameters

Name	Type	Required	Description
`include_input`	boolean	No	为 `true` 时，响应中包含原始输入
`stream`	boolean	No	为 `true` 时，以 Server-Sent Events 流式返回交互事件。事件字段见文末「InteractionSseEvent」
`last_event_id`	string	No	从该事件 ID 之后继续流式返回。仅在 `stream` 为 `true` 时使用

Responses

200: 查询成功，返回 Interaction。字段与创建接口相同

Content-Type: application/json

请求示例

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

响应示例

{
  "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": "我这边很好，谢谢。需要我帮你做什么？"
        }
      ]
    }
  ],
  "updated": "2025-11-26T12:25:15Z"
}

DELETE `/v1beta/interactions/{interactionsId}`

删除交互

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

Path Parameters

Name	Type	Required	Description
`interactionsId`	string	Yes	要删除的交互 ID

Responses

200: 删除成功，响应体为空

请求示例

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

Content

input 以及 Step 的 content 使用内容块，用 type 区分。文本块的 annotations 用来标记引用，出现在模型生成的文本上。

`type`	说明	主要字段
`text`	文本	`text`。可选 `annotations`
`image`	图像	`data`（Base64）或 `uri`，以及 `mime_type`、`resolution`
`audio`	音频	`data` 或 `uri`，以及 `mime_type`、`channels`、`sample_rate`
`video`	视频	`data` 或 `uri`（可为视频链接），以及 `mime_type`、`resolution`、`processing`
`document`	文档	`data` 或 `uri`，以及 `mime_type`

图像 mime_type： image/png、image/jpeg、image/webp、image/heic、image/heif、image/gif、image/bmp、image/tiff

音频 mime_type： audio/wav、audio/mp3、audio/aiff、audio/aac、audio/ogg、audio/flac、audio/mpeg、audio/m4a、audio/l16、audio/opus、audio/alaw、audio/mulaw、audio/webm

视频 mime_type： video/mp4、video/mpeg、video/mpg、video/mov、video/avi、video/x-flv、video/webm、video/wmv、video/3gpp

文档 mime_type： application/pdf、text/csv

图像和视频的 resolution 取值：low、medium、high、ultra_high。

视频 processing 控制模型如何读视频：

agentic：由模型动态浏览画面
static：按固定帧率抽帧并放入上下文。可直接传字符串 "static"，或传对象并指定 start_offset、end_offset（如 "10.5s"、"30s"）和 fps

文本上的 annotations 用 start_index / end_index 标出被引用的片段（start_index 以字节计，end_index 不含该位置）。

`type`	说明	主要字段
`url_citation`	网页引用	`url`、`title`
`file_citation`	文件引用	`file_name`、`document_uri`、`page_number`、`source`、`media_id`、`custom_metadata`
`place_citation`	地点引用	`name`、`place_id`、`url`、`review_snippets`
`speech_metadata`	语音注解	`speaker`、`style`
`word_info`	转写的词级注解	`text`、`start_offset`、`end_offset`、`speaker`

{
  "type": "text",
  "text": "Hello, how are you?"
}

Tool

创建交互时，tools 声明模型可以调用的工具，用 type 区分。同一份声明也会出现在返回的 Interaction 上。是否调用、调用哪一个，由 generation_config.tool_choice 控制：auto、any、none、validated。

模型决定调用自定义函数时，交互状态为 requires_action，steps 里会出现 function_call。执行完函数后，把结果作为下一轮 input 发回。

`type`	说明	主要字段
`function`	自定义函数	`name`、`description`、`parameters`
`code_execution`	执行代码	无其他字段
`url_context`	提取网址内容	无其他字段
`computer_use`	操作计算机	`environment`、`excluded_predefined_functions`、`disabled_safety_policies`、`enable_prompt_injection_detection`
`mcp_server`	调用 MCP 服务器	`name`、`url`、`headers`、`allowed_tools`
`google_search`	搜索 Google	`search_types`
`file_search`	搜索文件库	`file_search_store_names`、`top_k`、`metadata_filter`
`google_maps`	查询 Google 地图	`enable_widget`、`latitude`、`longitude`
`retrieval`	检索文件	`retrieval_types`、`vertex_ai_search_config`

可供模型使用的自定义函数工具。模型决定调用时，交互会返回 function_call 步骤，状态为 requires_action。

示例：函数调用

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "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?"
}'

示例响应（模型请求调用函数，状态为 requires_action）

{
  "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/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "tools": [{
    "type": "code_execution"
  }],
  "input": "Calculate the first 10 Fibonacci numbers"
}'

可供模型用来提取网址上下文的工具。该类型没有其他字段。

示例：网址上下文

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "tools": [{
    "type": "url_context"
  }],
  "input": "Summarize the page at https://example.com"
}'

可供模型用来操作计算机的工具。需搭配支持该能力的模型，例如 gemini-2.5-computer-use-preview-10-2025。

示例：计算机使用

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-2.5-computer-use-preview-10-2025",
  "tools": [{
    "type": "computer_use"
  }],
  "input": "Find a flight to Tokyo"
}'

可供模型调用以执行操作的 MCP 服务器。

示例：MCP 服务器

服务器地址、令牌和工具名请换成你自己的。

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "tools": [{
    "type": "mcp_server",
    "name": "weather",
    "url": "https://api.example.com/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_TOKEN"
    },
    "allowed_tools": {
      "mode": "auto",
      "tools": ["get_forecast"]
    }
  }],
  "input": "What is the forecast for Boston tomorrow?"
}'

可供模型用来搜索 Google 的工具。

示例：Google 搜索

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "tools": [{
    "type": "google_search",
    "search_types": ["web_search"]
  }],
  "input": "What are the latest developments in solid-state batteries?"
}'

可供模型用来搜索文件的工具。

示例：文件搜索

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "tools": [{
    "type": "file_search",
    "file_search_store_names": ["fileSearchStores/m64d1sevsr4y-xfyawui3fxqg"]
  }],
  "input": "Who is the author of the book?"
}'

可供模型用来查询 Google 地图的工具。

示例：Google 地图

坐标为示例值。

curl -X POST "https://api.autorouter.top/v1beta/interactions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
  "model": "gemini-3.6-flash",
  "tools": [{
    "type": "google_maps",
    "enable_widget": true,
    "latitude": 37.7749,
    "longitude": -122.4194
  }],
  "input": "Find a good coffee shop near me"
}'

可供模型用来检索文件的工具。

此类型没有可用的请求示例。

InteractionSseEvent

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

`event_type`	说明	主要字段
`interaction.created`	交互已创建	`interaction`
`interaction.completed`	交互已完成	`interaction`。其中 `steps` 为空，正文用前面的 `step.delta` 拼接
`interaction.status_update`	状态更新	`interaction_id`、`status`
`error`	出错	`error.code`、`error.message`
`step.start`	步骤开始	`index`、`step`
`step.delta`	步骤增量	`index`、`delta`
`step.stop`	步骤结束	`index`

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

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

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

错误处理

HTTP 400 参数错误

场景	处理建议
`model` 和 `agent` 都未传	二者填一个
`model` 与 `agent` 同时配置了互斥参数	模型用 `generation_config`，智能体用 `agent_config`
未知模型名	使用平台模型广场中对该 API Key 开放的模型 ID

HTTP 401 / 403 鉴权错误

401 Unauthorized：API Key 无效或已过期
403 Forbidden：API Key 无权访问此模型（检查 token 的模型白名单）

HTTP 402 余额不足

返回余额不足错误。请前往 AutoRouter 控制台充值。

交互 `failed` / `incomplete`

状态	处理建议
`failed`	查看响应里的 `errors[].message`，调整输入或安全设置后重试
`incomplete`	结果因达到输出上限等原因被截断，可提高 `generation_config.max_output_tokens` 后重试
`requires_action`	按 `steps` 中的 `function_call` 执行函数，再把结果作为下一轮 `input` 发回

交互失败时，诊断信息在 errors 数组中：code 为错误类型标识，message 为可读说明。

Interactions API (v1beta)

modelstring（条件必选）

可选模型

agentstring（条件必选）

可选智能体

inputstring | object | array（可选）

toolsobject[]（可选）

属性

generation_configobject（可选）

属性

backgroundboolean（可选）

storeboolean（可选）

streamboolean（可选）

environmentstring | object（可选）

previous_interaction_idstring（可选）

safety_settingsobject[]（可选）

属性

service_tierstring（可选）

statusstring

stepsobject[]

usageobject

属性

字段

字段

字段

字段

字段

字段

字段

字段

字段

interaction.created

interaction.completed

interaction.status_update

error

step.start

step.delta

step.stop

目录