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 "https://api.modelrover.ai/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.
Streaming text
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.2-flash",
"input": "A marble rolling through a glass maze",
"response_format": {
"type": "video",
"resolution": "720p",
"aspect_ratio": "16:9",
"duration": "10s"
},
"generation_config": {
"video_config": { "task": "text_to_video" }
},
"callback_url": "https://example.com/hooks/video?token=unguessable"
}Allowed video tasks are:
| Task | task value | Input requirement |
|---|---|---|
| Text to video | text_to_video | Text only; no image or video. Duration 3–15s. |
| Image to video | image_to_video | One image and text. Duration 3–15s. |
| First and last frame | first_last_frame | Two images (first + last frame) and text. Duration capped at 10s. |
| Reference to video | reference_to_video | 1–6 reference images, optionally with text. Duration 3–15s. |
| Video edit | edit | One video and text describing the change. Duration 3–15s. |
| Video extend | extend | One video and text describing the continuation. Duration 3–10s. |
If task is omitted, the gateway infers it from the input. Defaults are 720p, 16:9, and 10 seconds. gemini-omni-1.2-flash accepts 360p, 720p, 1080p, or 4k, 16:9 or 9:16, and durations from "3s" to "15s" (first-last-frame and extend cap at "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.
gemini-omni-1.1-flashautomatically routes togemini-omni-1.2-flashfrom 2026-12-03 at the lower 1.2 rate, with no code changes required.
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.
Gemini 4 Carbon (google/gemini-4-carbon) and Gemini 4 Argon (google/gemini-4-argon) on Interactions support only stateless synchronous and streaming text calls (store: false, background: false). On same-protocol routes, when generation_config.max_output_tokens exceeds the single-hop cap and the response stops with status: "requires_continuation", resend the original input and generation_config with the returned continuation_token (previous_interaction_id is rejected because storage is disabled).
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.
Help us improve this page
Found something unclear, outdated, or incorrect?
Last updated on