开桥原生 API: 创建交互 ​

创建交互： ​

POST https://openqiao.com/api/v1/interactions
POST https://openqiao.com/api/v1beta1/interactions

两个路径等价——/api/v1beta1/interactions 是 /api/v1/interactions 的别名。

该接口调用原生 Google Interactions API v1 协议——一个有状态的多模态生成协议，支持文本 / 图像 / 视频 / 文件输入，产出文本与视频。请求体直接采用 Google 原生的 Interactions 结构，无需 SDK，使用标准 Authorization: Bearer 鉴权。上游参考：Google Interactions API v1。

请求体基本会原样转发给上游供应商。开桥仅会：

• 在转发前剥离其内部路由字段（provider、model_routing_config），并
• 将 model 字段改写为上游供应商的模型名，再把响应中回显的 model 改写回开桥的模型标识（slug）。

下文未列出的字段将原样透传给供应商，并由供应商按模型进行校验；不支持的字段会返回原生错误。

支持的模型 ​

鉴权参数 ​

Authorization string * ​

请求头，格式为 Bearer $OPENQIAO_API_KEY，使用你的开桥 API Key 进行鉴权。

请求体 ​

model string * ​

用于本次交互的模型标识，格式为 {provider}/{model}，例如 google/gemini-omni-flash。开桥据此解析并路由请求，随后在转发前将其改写为供应商的模型名。

input Content | string * ​

交互的用户输入。可以是纯字符串（文本提示词），也可以是承载文本、图像、视频或文件片段的原生多模态 Content 结构。支持的输入模态：文本、图像、视频、文件。

system_instruction string 可选 ​

系统级指令，用于引导模型的行为。

tools array 可选 ​

声明模型可调用的工具（如 grounding / 搜索工具），透传给供应商。

generation_config object 可选 ​

模型生成参数，透传给供应商。常见字段包括：

• temperature number：输出随机性。
• top_p number：核采样阈值。
• max_output_tokens integer：响应最大长度。
• thinking_level string：推理强度，取值 minimal | low | medium | high。
• stop_sequences string[]：终止生成的序列。

response_format object 可选 ​

用于结构化输出的 JSON Schema 约束，透传给供应商。

stream boolean 可选 ​

为 true 时，响应以 Server-Sent Events（SSE）方式增量返回；省略或为 false 时返回单个 JSON。默认为 false。注意流式支持因模型而异——部分模型（如 gemini-omni-flash-preview）不支持流式，传入 stream: true 会被拒绝。

响应 ​

非流式响应 ​

单个 JSON 对象（原生 Google Interactions 响应，原样透传，仅将 model 字段改写为开桥的 slug）。

{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIX",
  "model": "google/gemini-omni-flash",
  "object": "interaction",
  "status": "completed",
  "created": "2026-07-03T12:25:15Z",
  "updated": "2026-07-03T12:25:15Z",
  "steps": [
    {
      "type": "model_output",
      "content": [{ "type": "text", "text": "The capital of France is Paris." }]
    }
  ],
  "usage": {
    "total_input_tokens": 7,
    "input_tokens_by_modality": [{ "modality": "text", "tokens": 7 }],
    "total_cached_tokens": 0,
    "total_output_tokens": 10,
    "total_thought_tokens": 0,
    "total_tokens": 17
  }
}

id string ​

交互的唯一标识。

model string ​

本次交互使用的开桥模型标识（由供应商模型名改写而来）。

status string ​

交互状态，取值 in_progress | requires_action | completed | failed | cancelled | incomplete。

steps array ​

交互序列——用户输入、模型输出、工具调用与工具结果。每个 step 都有 type 与 content 数组，其片段承载生成的 text、video 等模态。

usage object ​

本次交互的 Token 计量：

• total_input_tokens integer：输入 Token 总数。
• input_tokens_by_modality array：按模态划分的输入明细，每项为 { "modality": string, "tokens": integer }。
• total_cached_tokens integer：缓存内容 Token 数。
• total_output_tokens integer：生成的响应 Token 数。
• total_thought_tokens integer：推理 Token 数（思考型模型）。
• total_tokens integer：累计总数。
• grounding_tool_count array：各工具的 grounding 调用次数，每项为 { "type": string, "count": integer }。

流式响应（SSE） ​

当 stream: true 时，响应为描述交互生命周期的一串 Server-Sent Events：

每个事件都可能带有 metadata 对象，其中包含累计的 total_usage（字段与非流式的 usage 块相同）。

# 非流式：返回单个 JSON
curl -X POST "https://openqiao.com/api/v1/interactions" \
  -H "Authorization: Bearer $OPENQIAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-omni-flash",
    "input": "What is the capital of France?",
    "generation_config": { "max_output_tokens": 100 }
  }'

# 多模态输入：通过原生 content 结构传入文本 + 图像
curl -X POST "https://openqiao.com/api/v1/interactions" \
  -H "Authorization: Bearer $OPENQIAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-omni-flash",
    "input": [
      {
        "role": "user",
        "content": [
          { "type": "text", "text": "Describe this scene, then animate it." },
          { "type": "image", "data": "<base64>", "mime_type": "image/png" }
        ]
      }
    ],
    "system_instruction": "You are a helpful creative assistant.",
    "generation_config": { "temperature": 0.8 }
  }'

# 流式：设置 stream: true 以增量接收 Server-Sent Events
curl -N -X POST "https://openqiao.com/api/v1/interactions" \
  -H "Authorization: Bearer $OPENQIAO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-omni-flash",
    "input": "Write a short poem about the sea.",
    "stream": true
  }'

// 非流式响应
{
  "id": "v1_ChdPU0F4YWFtNkFwS2kxZThQZ05lbXdROBIX",
  "model": "google/gemini-omni-flash",
  "object": "interaction",
  "status": "completed",
  "created": "2026-07-03T12:25:15Z",
  "updated": "2026-07-03T12:25:15Z",
  "steps": [
    {
      "type": "model_output",
      "content": [{ "type": "text", "text": "The capital of France is Paris." }]
    }
  ],
  "usage": {
    "total_input_tokens": 7,
    "input_tokens_by_modality": [{ "modality": "text", "tokens": 7 }],
    "total_cached_tokens": 0,
    "total_output_tokens": 10,
    "total_thought_tokens": 0,
    "total_tokens": 17
  }
}

// 流式响应（stream: true）——SSE 生命周期事件
event: interaction.created
data: {"interaction":{"id":"v1_ChdP...","model":"google/gemini-omni-flash","status":"in_progress"},"event_id":"evt_0"}

event: step.start
data: {"index":0,"step":{"type":"model_output"}}

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

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

event: step.stop
data: {"index":0}

event: interaction.completed
data: {"interaction":{"id":"v1_ChdP...","model":"google/gemini-omni-flash","status":"completed","usage":{"total_input_tokens":8,"total_output_tokens":24,"total_tokens":32}}}