跳到主要内容

Google Interactions API 概览

Google Interactions API 将一次模型或 Agent 执行表示为一个 Interaction 资源。与只关注单次文本补全的接口相比，它统一承载输入、多模态内容、工具调用、执行状态、步骤、用量和可选的执行记录保存，适合需要完整执行过程的 Google 原生集成。

什么时候使用​

场景建议
普通跨厂商文本对话继续使用 /v1/chat/completions
GPT-5.x 的推理、工具或结构化输出使用 /v1/responses
Gemini 原生文本、图片或 PDF 能力使用 /v1beta/models/{model}:{method}
Google 模型或 Agent 的多模态、工具、流式或后台执行使用 /v1beta/interactions

Interaction 是什么​

一次 POST /v1beta/interactions 请求会创建一个 Interaction：

  • model 或 agent 指定执行主体，二者必须且只能提供一个。
  • input 可传文本或多模态内容；system_instruction 用于指定系统行为。
  • steps 记录模型输出或工具使用等执行步骤；status 表示当前执行状态。
  • usage 返回输入、输出、思考和工具调用等用量统计。
  • 设置 store: true 后，平台保存该 Interaction 的请求和响应记录。

最小请求​

curl __DOCS_API_ORIGIN__/v1beta/interactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "YOUR_SUPPORTED_MODEL",
    "input": "请用三句话说明 Interaction 的作用"
  }'

YOUR_SUPPORTED_MODEL 应替换为当前 Key 已开通的模型。实际权限可通过查询当前 Key 可调用模型确认。

执行方式​

需求配置行为
流式返回stream: true以 Server-Sent Events 返回 InteractionSseEvent
后台长任务background: true让耗时较长的 Interaction 在后台执行
保存执行记录store: true保存该 Interaction 的请求和响应记录
延续上下文previous_interaction_id基于之前的 Interaction 继续执行

相关页面​