Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Gemini Interactions API Format

Create Interaction

post

Creates a Gemini interaction and returns the completed result.

Behavior

  • Synchronous: the HTTP call waits until the interaction finishes (including video generation, which can take minutes).

  • Optional stream: true returns Server-Sent Events while the interaction runs, then ends when complete.

  • FastRouter rewrites catalogue model ids to bare Google ids, maps previous_interaction_id for sticky continuity, injects usage.cost / usage.chat_id, and returns a client-facing fr_… id.

  • Alias path: /api/v1/interactions.

Modalities

  • Text / tools as usual.

  • Video generation & conversational editing via models such as google/gemini-omni-flash-preview (see response_modalities, response_format, and generation_config.video_config).

  • Video tokens appear in usage.output_tokens_by_modality and are billed at the catalogue video rate.

Router-only fields (stripped before upstream): provider, request_tags.

Authorizations
AuthorizationstringRequired

FastRouter API Key. Get yours at https://fastrouter.ai

Format: Authorization: Bearer YOUR_API_KEY

Body

Create Interaction request. Provide model (required) plus input. The model must exist in the FastRouter catalogue. Native Google Interactions fields are forwarded to Google AI Studio after FastRouter rewrites model / previous_interaction_id and strips router-only fields (provider, request_tags). Supports multimodal input (text, image, audio, video) and video models such as google/gemini-omni-flash-preview when listed in the catalogue.

modelstringRequired

Model to use. Must be a FastRouter catalogue id (e.g. google/gemini-3.5-flash) or bare Google id that resolves in the catalogue. Unknown models return 400.

Example: google/gemini-3.5-flash
inputone ofRequired

Interaction input: plain string, Content, or an array of Content / Step / Turn objects (e.g. user_input with nested content). For video models, string prompts generate video; arrays can include text plus image/video (base64 data + mime_type, or uri) for image-to-video, video-to-video / reference, or edit flows.

Example: Tell me a short joke.
stringOptional

Simple text input

or
or
objectOptional

Single Content object

previous_interaction_idstringOptional

Continue a prior interaction. Pass the fr_… id returned by FastRouter (preferred) or an upstream id. Used for sticky routing / BYOK pin and rewritten to the provider-native id upstream.

Example: fr_ID123
system_instructionstringOptional

System instruction for this interaction (interaction-scoped; re-send each turn).

toolsobject[]Optional

Tool declarations the model may call (e.g. google_search, function calling).

response_formatone ofOptional

Output format constraints. For video generation use type=video with optional aspect_ratio and delivery. Use delivery=inline so video is returned as base64 in the response (accessible via FastRouter without a Google API key).

or
objectOptional

Other Google response_format variants (text / image / audio / JSON schema).

or
object[]Optional

Array of response format objects when supported.

streambooleanOptional

When true, FastRouter streams Server-Sent Events while the interaction runs. The request still completes in this same call (not a separate async job).

Default: false
storebooleanOptional

Whether Google should store the interaction for later GET / previous_interaction_id. Defaults to true.

Default: true
safety_settingsobject[]Optional

Safety settings for the interaction.

service_tierstring · enumOptional

Service tier for the interaction. Forwarded upstream (unlike provider / request_tags).

Possible values:
environmentone ofOptional

Environment configuration or existing environment id.

stringOptional
or
objectOptional
request_tagsstring[]Optional

Optional FastRouter tags for logging/analytics. Stripped before forwarding upstream.

Example: ["production","feature-chat"]
Responses
200

Completed interaction. When stream=true, body is an SSE stream that ends with the completed interaction. id is FastRouter fr_…; usage includes cost.

Completed interaction resource. FastRouter rewrites id to a client-facing fr_… value and echoes previous_interaction_id when continuing a conversation.

idstringOptional

Client-facing interaction id (fr_…). Pass this as previous_interaction_id to continue.

Example: fr_ID123
objectstringOptionalExample: interaction
statusstringOptional

Interaction status. Successful creates return completed.

Example: completed
modelstringOptional

Upstream model id used for the interaction.

Example: gemini-3.5-flash
createdstring · date-timeOptional

Creation timestamp.

updatedstring · date-timeOptional

Last update timestamp.

previous_interaction_idstringOptional

Previous interaction id as sent by the client (fr_… when continuing).

Example: fr_PREV123
stepsobject[]Optional

Execution steps (model_output, tool calls/results, etc.).

outputsobject[]Optional

Convenience output payloads when present (may include video content blocks).

post/v1/interactions
POST /v1/interactions HTTP/1.1
Host: api.fastrouter.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 67

{
  "model": "google/gemini-3.5-flash",
  "input": "Tell me a short joke."
}
{
  "id": "fr_ID123",
  "object": "interaction",
  "status": "completed",
  "model": "gemini-3.5-flash",
  "created": "2025-11-26T12:25:15Z",
  "updated": "2025-11-26T12:25:15Z",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Why did the GPU go to therapy? Too many cores issues."
        }
      ]
    }
  ],
  "usage": {
    "total_input_tokens": 7,
    "total_output_tokens": 20,
    "total_thought_tokens": 22,
    "total_tokens": 49,
    "cost": 0.00012,
    "chat_id": "fr_ID123"
  }
}

Get Interaction

get

Retrieves a previously stored interaction by FastRouter fr_… id (or upstream id). Use the returned id with previous_interaction_id on a later create to continue the conversation (e.g. Omni video edits). Alias: /api/v1/interactions/{id}.

Authorizations
AuthorizationstringRequired

FastRouter API Key. Get yours at https://fastrouter.ai

Format: Authorization: Bearer YOUR_API_KEY

Path parameters
idstringRequired

Interaction id returned by create (fr_…) or an upstream id.

Example: fr_ID123
Responses
200

Stored interaction resource. Same shape as a completed create response (FastRouter fr_… id and usage.cost / usage.chat_id when present).

application/json

Completed interaction resource. FastRouter rewrites id to a client-facing fr_… value and echoes previous_interaction_id when continuing a conversation.

idstringOptional

Client-facing interaction id (fr_…). Pass this as previous_interaction_id to continue.

Example: fr_ID123
objectstringOptionalExample: interaction
statusstringOptional

Interaction status. Successful creates return completed.

Example: completed
modelstringOptional

Upstream model id used for the interaction.

Example: gemini-3.5-flash
createdstring · date-timeOptional

Creation timestamp.

updatedstring · date-timeOptional

Last update timestamp.

previous_interaction_idstringOptional

Previous interaction id as sent by the client (fr_… when continuing).

Example: fr_PREV123
stepsobject[]Optional

Execution steps (model_output, tool calls/results, etc.).

outputsobject[]Optional

Convenience output payloads when present (may include video content blocks).

get/v1/interactions/{id}
GET /v1/interactions/{id} HTTP/1.1
Host: api.fastrouter.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "fr_ID123",
  "object": "interaction",
  "status": "completed",
  "model": "gemini-3.5-flash",
  "created": "2025-11-26T12:25:15Z",
  "updated": "2025-11-26T12:25:15Z",
  "steps": [
    {
      "type": "model_output",
      "content": [
        {
          "type": "text",
          "text": "Why did the GPU go to therapy? Too many cores issues."
        }
      ]
    }
  ],
  "usage": {
    "total_input_tokens": 7,
    "total_output_tokens": 20,
    "total_thought_tokens": 22,
    "total_tokens": 49,
    "cost": 0.00012,
    "chat_id": "fr_ID123"
  }
}

Delete Interaction

delete

Deletes a stored interaction by id. Alias: /api/v1/interactions/{id}.

Authorizations
AuthorizationstringRequired

FastRouter API Key. Get yours at https://fastrouter.ai

Format: Authorization: Bearer YOUR_API_KEY

Path parameters
idstringRequired

Interaction id (fr_… or upstream).

Example: fr_ID123
Responses
200

Upstream acknowledged deletion (body may be empty or a small status object).

application/json
delete/v1/interactions/{id}
DELETE /v1/interactions/{id} HTTP/1.1
Host: api.fastrouter.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "fr_ID123",
  "object": "interaction",
  "deleted": true
}
PreviousAnthropic Messages Format
NextGemini Native Format

Last updated