Google Gemini Interactions API

本文档说明客户端如何通过当前系统调用 Google Gemini Interactions API。

这是 Gemini 的原生统一接口（文本、多模态、工具、Agent），入参和成功出参与 官方 Interactions API 对齐。系统按原始 JSON / SSE 透传，不转成 Chat Completions，也不走 generateContent。

客户端使用当前系统签发的 API 令牌，不要使用 Google Gemini API Key，也不要使用 Vertex 服务账号。

BASE_URL=https://open-api.fancyai.com
API_KEY=sk-your-system-token

开发环境：

BASE_URL=https://platform-dev-api.xxd.fans

官方 SDK 只需改 base_url 和 key。完整字段、step 类型、工具声明等以官方文档为准；本文只写本系统已接入的路径、鉴权和与直连 Google 的差异。

各模型的可试调页面在 Gabrielle 侧边栏对应模型下（OpenAI 兼容 chat、原生 generateContent、以及 Interactions）。

1. 接口概览

功能	方法	路径	当前是否支持
创建交互	POST	/v1beta/interactions	支持
创建交互（稳定版路径）	POST	/v1/interactions	支持
查询交互	GET	/v1beta/interactions/{id}	不支持
取消后台任务	POST	/v1beta/interactions/{id}/cancel	不支持
删除交互	DELETE	/v1beta/interactions/{id}	不支持

/v1/interactions 与 /v1beta/interactions 行为相同，只是转发时保留客户端选的版本号。推荐用 /v1beta/interactions，与官方 SDK 默认一致。

鉴权任选其一：

Authorization: Bearer sk-your-system-token

x-goog-api-key: sk-your-system-token

GET /v1beta/interactions?key=sk-your-system-token

官方 REST / google-genai SDK 常用 x-goog-api-key。不要把 Google 官方 Key 填到这里。

可选请求头（系统会原样转给上游）：

Api-Revision: 2026-05-20
x-goog-api-client: google-genai-sdk/...

Api-Revision 用于选择官方 schema 版本。当前官方推荐 2026-05-20。详见 Interactions 破坏性变更说明。

2. 创建交互

POST /v1beta/interactions
Content-Type: application/json

系统校验：body 必须能解析为 JSON；必须有 model 或 agent；必须有 input。其余字段原样转发。

渠道按 model 选择；没有 model 时用 agent。后台若配置了模型映射，只会改 body 里的 model 再发给上游。

2.1 常用字段

字段	类型	必填	说明
model	string	与 agent 二选一	模型名，例如 gemini-3.8-flash。必须是当前系统已开通的模型
agent	string	与 model 二选一	托管 Agent，例如 deep-research-preview-04-2026。没有 model 时用它选渠道
input	string / 对象 / 数组	是	用户输入。最简单是字符串；也可以是 content / steps 数组
stream	boolean	否	true 时按 SSE 流式返回。也可用查询参数 ?alt=sse
system_instruction	string	否	系统指令
generation_config	object	否	仅 model 模式。如 max_output_tokens、thinking_level、seed
tools	array	否	工具声明
response_format	object / array	否	JSON Schema 约束
previous_interaction_id	string	否	多轮：接上一次 interaction 的 id
store	boolean	否	是否在 Google 侧保存，供官方 GET 查询。本系统当前没有 GET 路由
background	boolean	否	后台执行。本系统当前没有查询 / 取消路由，不要用

thinking_level 允许：minimal、low、medium、high。

input 常见写法：

"input": "用一句话介绍 Interactions API"

"input": [
  {
    "type": "text",
    "text": "这张图里有什么？"
  },
  {
    "type": "image",
    "data": "<base64>",
    "mime_type": "image/jpeg"
  }
]

2.2 流式

任选一种即可：

• body："stream": true
• URL：POST /v1beta/interactions?alt=sse

响应 Content-Type 为 text/event-stream。系统整帧透传，包括 event: 行，不会改成 Chat Completions 的 data: {...} 格式。

常见事件：

event_type	含义
interaction.created	已创建，通常带 id
interaction.status_update	状态变化
step.start / step.delta / step.stop	某一步开始、增量、结束
interaction.completed	整段结束，usage 一般在这里
error	上游错误事件

客户端应一直读到 interaction.completed 或连接关闭。

3. 请求示例

3.1 同步文本

curl -X POST "${BASE_URL}/v1beta/interactions" \
  -H "x-goog-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "用一句话介绍 Gemini Interactions API"
  }'

3.2 流式文本

curl -N -X POST "${BASE_URL}/v1beta/interactions" \
  -H "x-goog-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "写一首四行小诗",
    "stream": true
  }'

SSE 片段示例：

event: step.delta
data: {"event_type":"step.delta","index":0,"delta":{"type":"text","text":"Hello"}}

event: interaction.completed
data: {"event_type":"interaction.completed","event_id":"evt_123","interaction":{"id":"v1_...","status":"completed","usage":{...}}}

3.3 Python SDK

把官方 SDK 指向当前系统即可，路径仍是 /v1beta/interactions。

from google import genai

client = genai.Client(
    api_key="sk-your-system-token",
    http_options={"base_url": "https://open-api.fancyai.com"},
)

interaction = client.interactions.create(
    model="gemini-3.8-flash",
    input="用一句话介绍 Gemini Interactions API",
)
print(interaction.id, interaction.status)
print(interaction.outputs)

流式：

stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="写一首四行小诗",
    stream=True,
)

for event in stream:
    if getattr(event, "event_type", None) == "step.delta":
        delta = getattr(event, "delta", None)
        if delta is not None and getattr(delta, "type", None) == "text":
            print(delta.text, end="", flush=True)

JavaScript：

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

const client = new GoogleGenAI({
  apiKey: "sk-your-system-token",
  httpOptions: { baseUrl: "https://open-api.fancyai.com" },
});

const interaction = await client.interactions.create({
  model: "gemini-3.8-flash",
  input: "用一句话介绍 Gemini Interactions API",
});
console.log(interaction.id, interaction.status);

3.4 图像模型

协议上可用图像模型，例如 gemini-3.1-flash-image、gemini-3-pro-image。流式出图请优先用官方流式示例里的图像模型（如 gemini-3.1-flash-image）。gemini-3-pro-image 流式经常只出思考、不出成品图。

curl -N -X POST "${BASE_URL}/v1beta/interactions" \
  -H "x-goog-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -H "Api-Revision: 2026-05-20" \
  -d '{
    "model": "gemini-3.1-flash-image",
    "input": "一只坐在窗台上的橘猫，午后阳光，写实照片",
    "stream": true
  }'

可用的具体模型名以控制台开通列表为准，不要假设官方文档里的每一个名字当前系统都已配置。

4. 成功响应

非流式成功时，body 是官方 Interaction 对象，系统不改写。典型字段：

字段	说明
id	本次 interaction ID
object	一般为 "interaction"
status	如 completed、in_progress、requires_action、failed
model / agent	实际上游使用的模型或 Agent
steps	输出步骤。POST 成功响应通常只有输出 steps；完整时间线（含 user_input）要靠官方 GET，本系统暂无
usage	token 用量，snake_case
created / updated	时间

示例：

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIXT1NBeGFhbTZBcEtpMWU4UGdOZW13UTg",
  "object": "interaction",
  "status": "completed",
  "model": "gemini-3.8-flash",
  "created": "2025-11-26T12:22:47Z",
  "updated": "2025-11-26T12:22:47Z",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Interactions API 是 Gemini 的统一原生接口。"
        }
      ]
    }
  ],
  "usage": {
    "total_input_tokens": 12,
    "total_output_tokens": 40,
    "total_thought_tokens": 80,
    "total_cached_tokens": 0,
    "total_tool_use_tokens": 0,
    "total_tokens": 132,
    "input_tokens_by_modality": [
      { "modality": "text", "tokens": 12 }
    ]
  }
}

status 为 requires_action 时，需要按官方协议把工具结果再发一次 POST /interactions（或带 previous_interaction_id 继续）。本系统只负责转发，不代跑工具。

5. 错误

网关或渠道错误时，响应体不一定是官方 Interactions 错误格式，可能被包成现有 Gemini 原生转发同一套 OpenAI 风格：

{
  "error": {
    "message": "...",
    "type": "...",
    "code": "..."
  }
}

HTTP 状态码仍会尽量跟随上游（4xx / 5xx）。客户端不要只按官方 error.code 解析网关失败。

流式过程中，上游也可能推一条 event_type 为 error 的 SSE 帧，这一帧会原样到达客户端。

6. 计费

系统按上游返回的 usage 扣费：

• 非流式：响应体里的 usage
• 流式：interaction.completed（或事件上的 usage）

映射关系：

计费项	上游字段
Prompt	total_input_tokens + total_tool_use_tokens
Completion	total_output_tokens + total_thought_tokens
Reasoning	total_thought_tokens
图 / 音频	*_tokens_by_modality 里 modality 为 image / audio 的 tokens

价格以控制台该模型的倍率 / 计费表达式为准。

7. 与直连 Google 的差异

项目	本系统	直连 Google
创建 POST /interactions	支持，成功 JSON / SSE 原样回写	支持
GET /interactions/{id}	不支持	查状态、拉完整 steps、断线后续流
POST /interactions/{id}/cancel	不支持	取消仍在跑的 background 任务
DELETE /interactions/{id}	不支持	删除服务端记录
background: true	不要用。创建后无法在本系统查询或取消	适合超长 Agent / 深度研究
多轮 previous_interaction_id	可以转发，但必须打到同一把上游 Key。渠道多 Key 负载均衡时可能 404	同一项目 Key 即可
错误体	网关失败可能是 OpenAI 风格	官方错误对象
模型名	必须是本系统已开通且渠道已配置的名字；可能被渠道映射改写	官方模型列表

store、background 是 Google 服务端能力。即使请求里带了 store: true，本系统也没有查询入口。

background 的用途：任务在 Google 侧后台跑，创建接口立刻返回 id，再用 GET 轮询。深度研究、多步 Agent 常超过约 60 秒 HTTP 超时，才需要它。当前请改用同步或 SSE（"stream": true），并给客户端足够长的超时。

8. 建议

• 普通对话、流式出字、流式出图：用 POST + 可选 "stream": true 即可。
• 客户端超时建议大于上游实际耗时；思考模型和图像模型可能明显长于普通文本。
• 不要因为几十秒没有返回就重试同一条请求，可能重复计费。
• 多轮优先自己把需要的 steps 带回下一次 input；不要依赖本系统提供 GET 历史。
• 完整 schema 见官方文档：Interactions API。