Reasoning

Let Gemini think before it answers

Gemini models produce an internal chain of thought before responding. This reasoning appears in the response as thought steps and is billed as output tokens. Reasoning improves complex problem solving, coding, and multi-step planning.

Reasoning Request

Reasoning is on by default for Gemini models. Reserve enough output budget for both the internal thinking and the visible answer:

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': 'A bat and ball cost $1.10. The bat costs $1 more than the ball. How much is the ball?',
    },
)
data = response.json()
answer = next(
    c['text']
    for s in data['steps'] if s['type'] == 'model_output'
    for c in s['content'] if c['type'] == 'text'
)
print(answer)
print('thought tokens:', data['usage']['total_thought_tokens'])

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": "A bat and ball cost $1.10. The bat costs $1 more than the ball. How much is the ball?"
  }'

Reasoning Response

The steps array includes a thought step (carrying an opaque signature) before the visible model_output step. The thought content itself is not returned as readable text — only its signature, which links the reasoning to any tool calls in the turn.

{
  "status": "completed",
  "steps": [
    { "type": "thought", "signature": "AY89a1+BGsvw7Qxat83I5k5..." },
    {
      "type": "model_output",
      "content": [{ "type": "text", "text": "The ball costs $0.05." }]
    }
  ],
  "usage": {
    "total_input_tokens": 28,
    "total_output_tokens": 9,
    "total_thought_tokens": 231,
    "total_tokens": 268
  }
}

Token Usage

Reasoning tokens are generated internally and billed as output tokens. They are reported separately as total_thought_tokens:

{
  "usage": {
    "total_input_tokens": 28,
    "total_output_tokens": 9,
    "total_thought_tokens": 231,
    "total_tokens": 268
  }
}

Reasoning with Tool Calling

When you continue a turn after a tool call, pass the model's returned steps back including the thought step. Its signature is required to resume the same reasoning chain — see Tool Calling.

Response Fields

Next Steps