Google Gemini Interactions API

This page explains how to call Google Gemini Interactions API through this platform.

Interactions is Gemini's native unified interface (text, multimodal, tools, agents). Request and success response bodies match the official Interactions API. The gateway forwards original JSON / SSE and does not convert to Chat Completions or generateContent.

Use an API token issued by this platform. Do not use a Google Gemini API key or a Vertex service account.

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

Development:

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

Official SDKs only need a new base_url and key. Full field lists, step types, and tool declarations follow the official docs. This page covers paths, auth, and differences from calling Google directly.

Per-model try-it pages live under each Gabrielle Gemini model in the sidebar (OpenAI-compatible chat, native generateContent, and Interactions).

1. Endpoint overview

Feature	Method	Path	Supported
Create interaction	POST	`/v1beta/interactions`	Yes
Create interaction (stable path)	POST	`/v1/interactions`	Yes
Get interaction	GET	`/v1beta/interactions/{id}`	No
Cancel background task	POST	`/v1beta/interactions/{id}/cancel`	No
Delete interaction	DELETE	`/v1beta/interactions/{id}`	No

/v1/interactions and /v1beta/interactions behave the same; the gateway keeps the version the client chose. Prefer /v1beta/interactions to match the official SDK default.

Auth (any one):

Authorization: Bearer sk-your-system-token

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

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

Official REST / google-genai often uses x-goog-api-key. Do not put a Google official key here.

Optional headers (forwarded upstream as-is):

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

Api-Revision selects the official schema version. Google currently recommends 2026-05-20. See Interactions breaking changes.

2. Create an interaction

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

Gateway checks: body must be JSON; model or agent is required; input is required. Other fields are forwarded unchanged.

Channel selection uses model. If model is absent, it uses agent. If the backend has a model mapping, only the model field in the body is rewritten before the upstream call.

2.1 Common fields

Field	Type	Required	Notes
`model`	string	Either `model` or `agent`	Model name, for example `gemini-3.8-flash`. Must be enabled on this system
`agent`	string	Either `model` or `agent`	Hosted agent, for example `deep-research-preview-04-2026`. Used for routing when `model` is absent
`input`	string / object / array	Yes	User input. A string is simplest; it can also be a content / steps array
`stream`	boolean	No	`true` returns SSE. You can also use `?alt=sse`
`system_instruction`	string	No	System instruction
`generation_config`	object	No	Model mode only. Examples: `max_output_tokens`, `thinking_level`, `seed`
`tools`	array	No	Tool declarations
`response_format`	object / array	No	JSON Schema constraint
`previous_interaction_id`	string	No	Multi-turn: previous interaction `id`
`store`	boolean	No	Whether Google stores the interaction for official GET. This system has no GET route
`background`	boolean	No	Background execution. This system has no query / cancel routes. Do not use

thinking_level values: minimal, low, medium, high.

input examples:

"input": "Introduce the Interactions API in one sentence"

"input": [
  {
    "type": "text",
    "text": "What is in this image?"
  },
  {
    "type": "image",
    "data": "<base64>",
    "mime_type": "image/jpeg"
  }
]

2.2 Streaming

Use either:

Body: "stream": true
URL: POST /v1beta/interactions?alt=sse

Response Content-Type is text/event-stream. The gateway forwards frames as-is, including event: lines. It does not rewrite them to Chat Completions data: {...}.

Common events:

`event_type`	Meaning
`interaction.created`	Created, usually includes `id`
`interaction.status_update`	Status change
`step.start` / `step.delta` / `step.stop`	Step start, delta, end
`interaction.completed`	Finished; usage is usually here
`error`	Upstream error event

Clients should read until interaction.completed or the connection closes.

3. Request examples

3.1 Sync text

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": "Introduce the Gemini Interactions API in one sentence"
  }'

3.2 Streaming text

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": "Write a four-line poem",
    "stream": true
  }'

SSE fragment:

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

Point the official SDK at this platform. The path remains /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="Introduce the Gemini Interactions API in one sentence",
)
print(interaction.id, interaction.status)
print(interaction.outputs)

Streaming:

stream = client.interactions.create(
    model="gemini-3.8-flash",
    input="Write a four-line poem",
    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: "Introduce the Gemini Interactions API in one sentence",
});
console.log(interaction.id, interaction.status);

3.4 Image models

The protocol supports image models such as gemini-3.1-flash-image and gemini-3-pro-image. Prefer flash image models for streaming images. gemini-3-pro-image streams often emit thinking without a finished 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": "An orange cat sitting on a windowsill in afternoon sunlight, photorealistic",
    "stream": true
  }'

Enabled model names are those listed in the console. Do not assume every name in Google's docs is configured here.

4. Success response

On non-stream success, the body is the official Interaction object. The gateway does not rewrite it. Typical fields:

Field	Notes
`id`	Interaction ID
`object`	Usually `"interaction"`
`status`	`completed`, `in_progress`, `requires_action`, `failed`
`model` / `agent`	Upstream model or agent
`steps`	Output steps. POST success usually has output steps only; the full timeline (including `user_input`) needs official GET, which this system does not provide
`usage`	Token usage, snake_case
`created` / `updated`	Timestamps

Example:

{
  "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": "The Interactions API is Gemini's unified native interface."
        }
      ]
    }
  ],
  "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 }
    ]
  }
}

When status is requires_action, send tool results with another POST /interactions (or continue with previous_interaction_id). This system only relays; it does not run tools.

5. Errors

Gateway or channel errors are not always official Interactions error objects. They may use the same OpenAI-style wrapper as other Gemini native relays:

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

HTTP status still follows upstream when possible (4xx / 5xx). Do not parse gateway failures only as official error.code.

During streaming, upstream may also push an SSE frame with event_type error. That frame reaches the client unchanged.

6. Billing

The system bills from upstream usage:

Non-stream: usage in the response body
Stream: interaction.completed (or usage on the event)

Mapping:

Billing item	Upstream field
Prompt	`total_input_tokens + total_tool_use_tokens`
Completion	`total_output_tokens + total_thought_tokens`
Reasoning	`total_thought_tokens`
Image / audio	tokens where `modality` is `image` / `audio` in `*_tokens_by_modality`

Prices follow the model's ratio / billing expression in the console.

7. Differences from calling Google directly

Item	This system	Direct Google
Create `POST /interactions`	Yes; success JSON / SSE is passed through	Yes
`GET /interactions/{id}`	No	Status, full steps, resume after disconnect
`POST /interactions/{id}/cancel`	No	Cancel a running background task
`DELETE /interactions/{id}`	No	Delete the server-side record
`background: true`	Do not use. You cannot query or cancel after create	Long-running agents / deep research
Multi-turn `previous_interaction_id`	Forwarded, but must hit the same upstream key. Multi-key load balancing can 404	Same project key is enough
Error body	Gateway failures may be OpenAI-style	Official error object
Model name	Must be enabled and configured on a channel; mapping may rewrite it	Official model list

store and background are Google server-side features. Even with store: true, this system has no query endpoint.

background is for tasks that run on Google's side: create returns id immediately, then poll GET. Deep research and multi-step agents often exceed ~60s HTTP timeouts. Use sync or SSE ("stream": true) instead, and give the client a long enough timeout.

8. Recommendations

Chat, streaming text, and streaming images: POST plus optional "stream": true.
Client timeouts should exceed upstream runtime; thinking and image models can take much longer than plain text.
Do not retry the same request after tens of seconds with no response; that can double-bill.
For multi-turn, send needed steps back in the next input. Do not rely on GET history from this system.
Full schema: Interactions API.

1. Endpoint overview​

2. Create an interaction​

2.1 Common fields​

2.2 Streaming​

3. Request examples​

3.1 Sync text​

3.2 Streaming text​

3.3 Python SDK​

3.4 Image models​

4. Success response​

5. Errors​

6. Billing​

7. Differences from calling Google directly​

8. Recommendations​