Gemini Interactions

Use Gemini Interactions for stateless text calls, streaming events, and Omni video tasks.

`POST /v1beta/interactions`

The Interactions endpoint serves two execution paths:

Text and multimodal-input models return a synchronous interaction object or SSE events.
Gemini Omni video models create an asynchronous task whose result is read through the task API.

Authenticate with x-goog-api-key: $API_KEY or Authorization: Bearer $API_KEY.

Text request body

Field	Type	Required	Description
`model`	string	Yes	Complete public model ID.
`input`	string, object, or array	Yes	Non-empty text or interaction input items.
`system_instruction`	string or object	No	System-level instruction.
`tools`	array	No	Function and protocol-native tool declarations.
`stream`	boolean	No	Return Interactions SSE events when `true`.
`generation_config.max_output_tokens`	integer	No	Maximum text output tokens.
`generation_config.temperature`	number	No	Sampling temperature.
`generation_config.top_p`	number	No	Nucleus sampling value.
`store`	boolean	No	Must be omitted or `false` for text calls.
`background`	boolean	No	Must be omitted or `false` for text calls.

input can be a string or items such as text, image, user input, function call, function result, and thought steps. Same-protocol routes preserve supported Interactions extensions and signatures.

Synchronous text example

curl "http://127.0.0.1:11113/v1beta/interactions" -H "x-goog-api-key: $API_KEY" -H "Content-Type: application/json" -d '{
  "model": "google/gemini-2.5-flash",
  "input": "Explain model gateways briefly.",
  "store": false
}'

{
  "id": "int_01J...",
  "object": "interaction",
  "model": "google/gemini-2.5-flash",
  "status": "completed",
  "created": "2026-09-12T08:00:00Z",
  "updated": "2026-09-12T08:00:01Z",
  "steps": [
    {
      "type": "model_output",
      "content": [
        { "type": "text", "text": "A model gateway unifies access to multiple AI models." }
      ]
    }
  ],
  "usage": {
    "total_input_tokens": 8,
    "total_output_tokens": 12
  }
}

Text status can be completed, requires_action, or incomplete, depending on tool calls and the finish reason.

Set stream: true to receive named events. A converted stream emits interaction.created, interaction.status_update, step.start, one or more step.delta events, step.stop, interaction.completed, and finally event: done with data: [DONE].

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

event: done
data: [DONE]

Same-protocol routes retain native event extensions. Usage is final in interaction.completed.interaction.usage.

Omni video request

The same endpoint creates a video task when the selected model is a video model or the request contains a video response_format or video_config. Video requests must not set stream: true.

{
  "model": "google/gemini-omni-1.1-flash",
  "input": "A marble rolling through a glass maze",
  "response_format": {
    "type": "video",
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "duration": "8s"
  },
  "generation_config": {
    "video_config": { "task": "text_to_video" }
  },
  "callback_url": "https://example.com/hooks/video?token=unguessable"
}

Allowed video tasks are:

Task	Input requirement
`text_to_video`	Text only; no image or video input.
`image_to_video`	Exactly one image and no video.
`edit`	Exactly one video and no image.

If task is omitted, the gateway infers it from the input. Defaults are 720p, 16:9, and 10 seconds. Gemini Omni 1.1 accepts 360p, 720p, 1080p, or 4k, 16:9 or 9:16, and durations from "3s" to "10s". The create response id is rewritten to a platform task ID; poll it through GET /v1/tasks/{taskId}. See Gemini video for the full media contract.

Stateless and routing restrictions

Text requests reject store: true, background: true, and non-null previous_interaction_id, agent, environment, or webhook_config. Video requests also reject those continuation and agent fields, and support neither extend nor reference_to_video.

On cross-protocol text routes, the gateway maps text and image input, function calls and results, function tools, common generation settings, output and thought steps, stream events, and usage. Other items can be reported in x-dropped-params. Client routing fields and paid service tiers are rejected.