ModelRover

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

FieldTypeRequiredDescription
modelstringYesComplete public model ID.
inputstring, object, or arrayYesNon-empty text or interaction input items.
system_instructionstring or objectNoSystem-level instruction.
toolsarrayNoFunction and protocol-native tool declarations.
streambooleanNoReturn Interactions SSE events when true.
generation_config.max_output_tokensintegerNoMaximum text output tokens.
generation_config.temperaturenumberNoSampling temperature.
generation_config.top_pnumberNoNucleus sampling value.
storebooleanNoMust be omitted or false for text calls.
backgroundbooleanNoMust 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:

Tasktask valueInput requirement
Text to videotext_to_videoText only; no image or video. Duration 3–15s.
Image to videoimage_to_videoOne image and text. Duration 3–15s.
First and last framefirst_last_frameTwo images (first + last frame) and text. Duration capped at 10s.
Reference to videoreference_to_video1–6 reference images, optionally with text. Duration 3–15s.
Video editeditOne video and text describing the change. Duration 3–15s.
Video extendextendOne 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-flash automatically routes to gemini-omni-1.2-flash from 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