开桥 Native API: Create Interaction ​

Create an interaction: ​

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

Both paths are equivalent — /api/v1beta1/interactions is an alias of /api/v1/interactions.

This endpoint calls the native Google Interactions API v1 protocol — a stateful, multi-modal generation protocol that accepts text / image / video / file inputs and produces text and video outputs. The request body adopts Google's native Interactions structure directly, no SDK required, authenticated with a standard Authorization: Bearer header. Upstream reference: Google Interactions API v1.

The request body is forwarded to the upstream provider largely verbatim. 开桥 only:

• strips its internal routing fields (provider, model_routing_config) before forwarding, and
• rewrites the model field to the provider's model name upstream, then rewrites the echoed model in the response back to the 开桥 model slug.

Any field not listed below is passed through to the provider as-is and validated by the provider per model; unsupported fields return a native error.

Supported models ​

Authentication ​

Authorization string * ​

Request header in the form Bearer $OPENQIAO_API_KEY, using your 开桥 API key for authentication.

Request body ​

model string * ​

The model slug used for the interaction, in the form {provider}/{model}, 例如 google/gemini-omni-flash. 开桥 uses this to resolve and route the request, then rewrites it to the provider's model name before forwarding.

input Content | string * ​

The user inputs for the interaction. May be a plain string (text prompt) or the native multi-modal Content structure carrying text, image, video, or file parts. Supported input modalities: text, image, video, file.

system_instruction string Optional ​

System-level guidance that steers the model's behavior.

tools array Optional ​

Declared tools the model may invoke (例如 grounding / search tools), passed through to the provider.

generation_config object Optional ​

Model generation parameters, passed through to the provider. Common fields include:

• temperature number: output randomness.
• top_p number: nucleus sampling threshold.
• max_output_tokens integer: maximum length of the response.
• thinking_level string: reasoning effort, one of minimal | low | medium | high.
• stop_sequences string[]: sequences that terminate generation.

response_format object Optional ​

JSON-schema enforcement for structured output, passed through to the provider.

stream boolean Optional ​

When true, the response is delivered incrementally as Server-Sent Events (SSE). When omitted or false, a single JSON response is returned. Defaults to false. Note that streaming support is model-dependent — some models (例如 gemini-omni-flash-preview) do not support streaming and will reject stream: true.

Response ​

Non-streaming response ​

A single JSON object (native Google Interactions response, passed through with the model field rewritten to the 开桥 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 ​

Unique interaction identifier.

model string ​

The 开桥 model slug used for the interaction (rewritten from the provider model name).

status string ​

Interaction status, one of in_progress | requires_action | completed | failed | cancelled | incomplete.

steps array ​

The interaction sequence — user input, model output, tool calls, and tool results. Each step has a type and a content array whose parts carry the generated text, video, and other modalities.

usage object ​

Token accounting for the interaction:

• total_input_tokens integer: total prompt tokens.
• input_tokens_by_modality array: per-modality input breakdown, each entry { "modality": string, "tokens": integer }.
• total_cached_tokens integer: cached content tokens.
• total_output_tokens integer: generated response tokens.
• total_thought_tokens integer: reasoning tokens (thinking models).
• total_tokens integer: cumulative total.
• grounding_tool_count array: per-tool grounding invocation counts, each entry { "type": string, "count": integer }.

Streaming response (SSE) ​

When stream: true, the response is a stream of Server-Sent Events describing the interaction lifecycle:

Each event may carry a metadata object with the cumulative total_usage (same fields as the non-streaming usage block).

# Non-streaming: single JSON response
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 }
  }'

# Multi-modal input: text + image via the native content structure
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 }
  }'

# Streaming: set stream: true for incremental 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
  }'

// Non-streaming response
{
  "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
  }
}

// Streaming response (stream: true) — SSE lifecycle events
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}}}