Interactions API

Build with Gemini models using the unified Interactions API format

The Interactions API (/v1/interactions) is the unified interface for calling Gemini models — single-turn text generation, multimodal understanding, streaming, tool orchestration, and reasoning all share one endpoint and one request shape. Unlike the Chat Completion or Responses endpoints, it accepts the native Interactions format: the request is passed through to the model unchanged, and you receive the native response (or native SSE stream) back.

Basic Request

The simplest request passes a string as input:

const response = await fetch('https://enterprise.blackbox.ai/v1/interactions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.BLACKBOX_API_KEY}`,
  },
  body: JSON.stringify({
    model: 'gemini-3.8-flash',
    input: 'Why do developers prefer dark mode?',
    store: false,
  }),
});

const result = await response.json();
console.log(result);

import os
import requests

response = requests.post(
    'https://enterprise.blackbox.ai/v1/interactions',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f"Bearer {os.environ['BLACKBOX_API_KEY']}",
    },
    json={
        'model': 'gemini-3.8-flash',
        'input': 'Why do developers prefer dark mode?',
        'store': False,
    },
)
print(response.json())

curl https://enterprise.blackbox.ai/v1/interactions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BLACKBOX_API_KEY" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Why do developers prefer dark mode?",
    "store": false
  }'

Response Format

The model returns an interaction object. The visible answer lives in the steps array as a model_output step; token usage is reported under usage.

{
  "id": "eSzEati8NNGE9LsPl_298QI",
  "object": "interaction",
  "model": "gemini-3.8-flash",
  "status": "completed",
  "role": "model",
  "steps": [
    { "type": "thought", "signature": "AY89a1+..." },
    {
      "type": "model_output",
      "content": [
        { "type": "text", "text": "Contrast and eye-strain ergonomics are the main drivers." }
      ]
    }
  ],
  "usage": {
    "total_input_tokens": 6,
    "total_output_tokens": 12,
    "total_thought_tokens": 65,
    "total_tokens": 83
  }
}

Request Parameters

Response Fields

Next Steps