Text Generation

Generate text with single-turn and multi-turn conversations

Use the Interactions API to generate text from Gemini models. For a single turn, pass a string as input. For multi-turn conversations, pass an array of steps that interleaves user prompts and prior model output.

The Interactions API is best supported on the Enterprise plan. Use https://enterprise.blackbox.ai as the base URL.

Single-Turn Request

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: 'Write a haiku about databases.',
    store: false,
  }),
});

const data = await response.json();
const text = data.steps
  .filter((s) => s.type === 'model_output')
  .flatMap((s) => s.content)
  .find((c) => c.type === 'text')?.text;
console.log(text);

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': 'Write a haiku about databases.',
        'store': False,
    },
)
data = response.json()
text = next(
    c['text']
    for s in data['steps'] if s['type'] == 'model_output'
    for c in s['content'] if c['type'] == 'text'
)
print(text)

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": "Write a haiku about databases.",
    "store": false
  }'

Multi-Turn Conversations

The Interactions API is step-based, not message-based. To continue a conversation statelessly, pass an array where each prior user turn is a text step and each prior model turn is a model_output step:

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',
        'store': False,
        'input': [
            {'type': 'text', 'text': 'My name is Alice.'},
            {'type': 'model_output',
             'content': [{'type': 'text', 'text': 'Nice to meet you, Alice.'}]},
            {'type': 'text', 'text': "What's my name? One word."},
        ],
    },
)
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",
    "store": false,
    "input": [
      {"type": "text", "text": "My name is Alice."},
      {"type": "model_output", "content": [{"type": "text", "text": "Nice to meet you, Alice."}]},
      {"type": "text", "text": "What is my name? One word."}
    ]
  }'

Do not send a messages array or role-tagged content objects — those belong to the Chat Completion / Responses formats. The Interactions API uses the step_list format shown above. A turn-list body returns use step_list input format instead of turn_list.

Request Parameters

modelstringrequired

The model identifier. Example: gemini-3.8-flash.

inputstring | arrayrequired

A prompt string, or an array of steps. Supported step types for text include text (user input) and model_output (prior assistant turn).

storebooleandefault: false

Forced to false by the gateway for Zero Data Retention.

Response Fields

stepsarray

Ordered steps. The visible answer is the model_output step whose content contains { "type": "text", "text": "..." }.

statusstring

completed for a finished text turn.

usageobject

total_input_tokens, total_output_tokens, total_thought_tokens, total_tokens.

Next Steps

Streaming

Stream tokens in real time

Reasoning

Let the model think before answering