Google Gemini Interactions

POST/v1beta/interactions

Create a native Google Interaction. Check status even on HTTP 200; an in_progress response must be polled.

Request body

stringmodelrequired

Logical SandBase model name.

string | object | arrayinputrequired

Native Google Interaction input.

Optional<boolean>stream

Return Google Interactions SSE events when supported by the model.

Optional<boolean>background

Submit durably and return an immediately pollable Interaction. Cannot be combined with stream.

Optional<string>previous_interaction_id

Continue from an upstream Interaction while preserving provider affinity.

Optional<boolean>store

Forward the upstream storage preference unchanged.

Optional<string>system_instruction

Native system instruction.

Optional<array>tools

Native Google tool definitions.

Optional<object>generation_config

Native generation configuration.

Optional<object | array>response_format

Requested response format.

Optional<array>response_modalities

Requested output modalities.

curl -X POST https://api.sandbase.ai/v1beta/interactions \
  -H "x-goog-api-key: $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemini-omni-flash-preview",
    "input": "A red ball rolls across a table, 3 seconds.",
    "background": true,
    "response_format": {"type": "video"}
  }'

Response200 OK

{
  "id": "job_75b74acd12534b01baba820b",
  "object": "interaction",
  "model": "google/gemini-omni-flash-preview",
  "status": "in_progress"
}

Authentication

Use x-goog-api-key, Authorization: Bearer …, or the key query parameter, in that priority order. Prefer a header because query-string credentials can be logged.

Supported models

The Interactions endpoint is not a generic route for every model whose catalog name starts with google/. The model must have an Interactions-compatible provider mapping. SandBase currently documents these compatible models:

• Gemini Omni Flash Preview
• Gemini Omni 1.1 Flash Preview

Use the endpoint documented on each model page. For example, Nano Banana Pro and Nano Banana 2 use /v1beta/models/{model}:generateContent, not /v1beta/interactions. An unsupported model fails instead of being routed through a different Google protocol.

Success and polling

Successful submissions return HTTP 200, including background work and synchronous requests whose bounded wait expires. Always inspect status:

• completed, failed, cancelled, and incomplete are terminal.
• in_progress is still running. Poll GET /v1beta/interactions/{id}; the response can also include that path in the Location header.
• requires_action is a protocol status, but SandBase does not currently expose the tool-confirmation endpoint needed to advance it.

The polling ID is the upstream Interaction id returned by POST, not a SandBase prediction ID. The same SandBase API key that created the Interaction must retrieve it.

curl https://api.sandbase.ai/v1beta/interactions/job_75b74acd12534b01baba820b \
  -H "x-goog-api-key: $SANDBASE_API_KEY"

Non-terminal GET responses omit partial output and usage. Terminal responses can include inline image, audio, or video data and may be several megabytes. Download and persist required media promptly: after upstream retention expires, SandBase can return only a lossy terminal fallback with structure and metadata, not the original media bytes.

Streaming

Set stream: true in the request body. The response is text/event-stream; ?alt=sse is not used by this protocol. Event and delta types are open-ended and are forwarded without a fixed allowlist, so clients should tolerate unknown values. Once streaming headers have been written, failures arrive as an error event rather than a different HTTP status.

Streaming is model-dependent. An upstream provider can reject stream: true even though the protocol supports it.

Current limits

SandBase currently exposes only create and get:

• Agent Interactions are rejected; use model.
• background: true and stream: true cannot be combined.
• Interaction list, delete, and cancel are not exposed.
• URI delivery and GET-based stream reconnection are not exposed.
• previous_interaction_id requires a live provider-affinity mapping and upstream support. SandBase fails instead of silently switching providers when affinity is unavailable.

Errors use the Google envelope { "error": { "code", "message", "status" } }. Treat the HTTP status as stable; sanitized upstream text in message can change.