---
title: "Create a Google Gemini Interaction"
method: POST
path: "/v1beta/interactions"
tags: ["Gemini"]
---

# Create a Google Gemini Interaction

`POST /v1beta/interactions`

## Request

- Base URL: `https://api.sandbase.ai`
- URL: `https://api.sandbase.ai/v1beta/interactions`
- Auth: one of:
  - API key in header `x-goog-api-key`
  - HTTP bearer
  - API key in query parameter `key`

Proxies the Google Interactions protocol while routing the logical model through SandBase. Successful requests
always return HTTP 200. Check status: an in_progress response is pollable and is not a completed result.
Set stream=true for SSE, or background=true for a durable background submission; they cannot both be true.

## Request body

- GeminiInteractionRequest: Google Interactions request. Except for fields used for routing and lifecycle control, fields are forwarded to the selected upstream. Agent interactions are not supported. background and stream cannot both be true.
  - `model` string, required: Logical SandBase model name. The response echoes this name instead of an upstream model identifier.
  - `input` unknown, required
  - `stream` boolean: Requests an SSE event stream when the selected model supports it.
  - `background` boolean: Requests durable background execution and an immediately pollable in_progress Interaction.
  - `previous_interaction_id` string: Previous Interaction ID. SandBase keeps the request on the same upstream provider when the mapping is still available.
  - `store` boolean: Forwarded upstream. Stored upstream state may be required for previous_interaction_id.
  - `system_instruction` string
  - `tools` object[]
  - `generation_config` object
  - `response_format` union
    - object
    - unknown[]
      - unknown
  - `response_modalities` string[]

## Response `200`

Current or terminal Interaction, or an Interaction event stream

- GeminiInteraction
  - `id` string, required: Upstream Interaction ID used by GET and previous_interaction_id.
  - `object` 'interaction', required
  - `model` string, required: Logical SandBase model name supplied by the client.
  - `role` string
  - `status` 'in_progress' | 'requires_action' | 'completed' | 'failed' | 'cancelled' | 'incomplete', required
  - `created` string
  - `updated` string
  - `steps` object[]: Polymorphic Google Interaction steps. Unknown step and content types are preserved.
  - `usage` GeminiInteractionUsage
    - `total_input_tokens` integer
    - `total_output_tokens` integer
    - `total_cached_tokens` integer
    - `total_thought_tokens` integer
    - `total_tool_use_tokens` integer
    - `total_tokens` integer
    - `input_tokens_by_modality` GeminiInteractionModalityUsage[]
      - `modality` string, required
      - `tokens` integer, required
    - `output_tokens_by_modality` GeminiInteractionModalityUsage[]
      - `modality` string, required
      - `tokens` integer, required

## Other responses

- `400`: Invalid JSON, missing model, unsupported Agent interaction, incompatible background and stream settings, stale conversation affinity, or upstream request rejection
- `401`: Missing, invalid, revoked, or expired API key
- `402`: Organization balance and credit are exhausted
- `403`: API Key spending limit reached, organization disabled, or upstream permission rejected
- `404`: Logical model or usable provider was not found
- `422`: Upstream rejected otherwise valid Interaction fields
- `429`: Provider rate limit exceeded after failover attempts
- `500`: Prediction lifecycle or internal persistence failed
- `502`: Upstream response exceeded the gateway size limit
- `503`: Routing, upstream connection, or durable background handoff failed
- `504`: Upstream request timed out after failover attempts

---

[API](https://skmtc.dev/sandbase/apis/sandbase-api.md) · [All operations](https://skmtc.dev/sandbase/apis/sandbase-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sandbase/apis/sandbase-api/revisions/d40df2467ba2?raw)