跳到主要内容
API 参考/Google/Interactions API

创建 Google Interaction

POST/v1beta/interactions

通过 Google Interactions API 调用平台已支持的模型或 Agent，支持多模态输入、工具调用、流式和后台执行。

认证​

通过 Bearer Token 认证。即使 Google 官方示例使用 Google Cloud 凭据，调用 ClawdRouter 代理地址时也统一使用平台 API Key。

Authorizationstring必填

API Key，格式为 Bearer YOUR_API_KEY。

默认值：-
Content-Typestring必填

请求体格式。

默认值：application/json
Request-Idstring可选

客户侧生成的唯一请求标识，用于追踪和排查。

默认值：-

请求​

model 与 agent 必须且只能提供一个。请通过当前 Key 可调用模型确认模型权限；Agent 权限请以控制台配置为准。

modelstring可选

执行 Interaction 的模型；与 agent 二选一，需使用当前 Key 已开通的模型。

默认值：-
agentstring可选

执行 Interaction 的 Agent；与 model 二选一，需使用当前 Key 已开通的 Agent。

默认值：-
inputstring | object | array必填

输入内容。可传纯文本、Content 对象/数组或 Step 数组，以承载文本、图片、音频、文档和视频。

默认值：-
input[].typestring可选

多模态内容类型，例如 text、image、audio、document 或 video。

默认值：-
input[].textstring可选

文本内容。

默认值：-
input[].mime_typestring可选

二进制内容的 MIME 类型，例如 image/png。

默认值：-
input[].datastring可选

Base64 编码的二进制内容。

默认值：-
system_instructionstring可选

系统指令。

默认值：-
toolsarray可选

模型在 Interaction 中可调用的工具声明，例如 Function、CodeExecution、UrlContext 或 ComputerUse。

默认值：-
response_formatobject | array可选

约束响应为符合 JSON Schema 的对象；设置时必须同时设置 response_mime_type。

默认值：-
response_mime_typestring可选

响应 MIME 类型；使用 response_format 时为必填。

默认值：-
response_modalitiesarray可选

期望响应模态：text、image、audio、video 或 document。

默认值：-
streamboolean可选

是否以 SSE 流返回 InteractionSseEvent。

默认值：false
storeboolean可选

是否保存请求和响应记录。

默认值：false
backgroundboolean可选

是否在后台执行 Interaction。

默认值：false
previous_interaction_idstring可选

前一个 Interaction 的 ID，用于续接上下文。

默认值：-
generation_configobject可选

模型生成配置；仅 model 模式适用，与 agent_config 二选一。

默认值：-
generation_config.temperaturenumber可选

采样随机性。

默认值：-
generation_config.top_pnumber可选

核采样参数。

默认值：-
generation_config.max_output_tokensinteger可选

最大输出 Token 数。

默认值：-
generation_config.thinking_levelstring可选

思考级别：minimal、low、medium 或 high。

默认值：-
agent_configobject可选

Agent 配置；仅 agent 模式适用，与 generation_config 二选一。

默认值：-

多模态输入​

input 可以是字符串，也可以是内容对象数组。以下示例传入文本和 Base64 图片：

{
  "model": "YOUR_SUPPORTED_MODEL",
  "input": [
    { "type": "text", "text": "描述这张图片" },
    { "type": "image", "mime_type": "image/png", "data": "BASE64_ENCODED_IMAGE" }
  ]
}

流式、后台与续接​

  • 设置 stream: true 时，响应为 InteractionSseEvent 的 Server-Sent Events 流。
  • 设置 background: true 可让长任务在后台执行。
  • 设置 store: true 后，平台保存该 Interaction 的请求和响应记录。
  • 设置 previous_interaction_id 可续接已完成或已存储 Interaction 的上下文。

响应​

idstring必填

Interaction 的唯一 ID。

默认值：-
objectstring必填

对象类型。

默认值：interaction
statusstring必填

执行状态，例如 in_progress、completed、failed 或 cancelled。

默认值：-
rolestring可选

响应角色，通常为 model。

默认值：-
modelstring可选

实际执行的模型；Agent 调用可能返回 agent。

默认值：-
agentstring可选

实际执行的 Agent。

默认值：-
stepsarray可选

Interaction 的执行步骤。

默认值：-
steps[].typestring可选

步骤类型，例如 model_output 或 tool_use。

默认值：-
steps[].contentarray可选

步骤内容，可包含 text、image、audio、document 或 video。

默认值：-
usageobject可选

用量统计，包括输入、输出、思考和工具调用 Token。

默认值：-
createdstring可选

创建时间，RFC 3339 格式。

默认值：-
updatedstring可选

最后更新时间，RFC 3339 格式。

默认值：-

错误​

状态码说明
400model/agent 组合、输入内容、结构化输出或生成参数不合法
401API Key 缺失或无效
403当前账户无权调用该模型、Agent 或读取该 Interaction
404Interaction、项目或路径不存在
429请求超过速率限制
500 / 503平台或上游服务异常

相关指南​