Reasoning

Enable reasoning models to think before they respond using the Responses API

Reasoning models are LLMs trained with reinforcement learning to think before they answer, producing a long internal chain of thought before responding. They excel at complex problem solving, coding, scientific reasoning, and multi-step planning for agentic workflows.

The Responses API is best supported on the Enterprise plan. Use https://enterprise.blackbox.ai as the base URL for full model availability and production reliability. The API is also available on standard plans at https://api.blackbox.ai, where it is currently experimental.

Basic Reasoning Request

Pass a reasoning object with an effort field to control how much the model thinks before responding:

TypeScript

const response = await fetch('https://enterprise.blackbox.ai/v1/responses', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.BLACKBOX_API_KEY}`,
  },
  body: JSON.stringify({
    model: 'blackboxai/openai/gpt-5.3-codex',
    reasoning: {
      effort: 'medium',
    },
    input: [
      {
        role: 'user',
        content:
          'Write a bash script that takes a matrix represented as a string with format [1,2],[3,4],[5,6] and prints the transpose in the same format.',
      },
    ],
  }),
});

const data = await response.json();
const msg = data.output.find((item: any) => item.type === 'message');
const text = msg?.content?.find((part: any) => part.type === 'output_text')?.text;
console.log(text);

import os
import requests

response = requests.post(
    'https://enterprise.blackbox.ai/v1/responses',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f"Bearer {os.environ['BLACKBOX_API_KEY']}",
    },
    json={
        'model': 'blackboxai/openai/gpt-5.3-codex',
        'reasoning': {
            'effort': 'medium',
        },
        'input': [
            {
                'role': 'user',
                'content': 'Write a bash script that takes a matrix represented as a string with format [1,2],[3,4],[5,6] and prints the transpose in the same format.',
            }
        ],
    },
)
print(response.json())

curl https://enterprise.blackbox.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BLACKBOX_API_KEY" \
  -d '{
    "model": "blackboxai/openai/gpt-5.3-codex",
    "reasoning": {
      "effort": "medium"
    },
    "input": [
      {
        "role": "user",
        "content": "Write a bash script that takes a matrix represented as a string with format [1,2],[3,4],[5,6] and prints the transpose in the same format."
      }
    ]
  }'

Reasoning Response

When reasoning is enabled, the output array includes a reasoning item with the model’s internal thinking, followed by a message item with the visible response:

{
  "id": "resp_QpQxYjZSgteaeH8SXShotw4n...",
  "object": "response",
  "model": "blackboxai/openai/gpt-5.3-codex",
  "status": "completed",
  "output": [
    {
      "id": "rs_1772502265541_jj0h02gs7k",
      "type": "reasoning",
      "summary": [],
      "content": [
        {
          "type": "reasoning_text",
          "text": "Calculating arithmetic\n\nI need to resolve a simple arithmetic problem: what's 15 times 27? The answer is 405."
        }
      ],
      "encrypted_content": "gAAAAABppjz3bJfZv5_WjuJI..."
    },
    {
      "id": "msg_abc456",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "15 × 27 = **405**.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 75,
    "output_tokens": 1186,
    "output_tokens_details": {
      "reasoning_tokens": 1024
    },
    "total_tokens": 1261
  }
}

The encrypted_content field contains an opaque token that can be passed back in multi-turn conversations so the model can reference its previous reasoning. Use include: ["reasoning.encrypted_content"] to receive it.

Reasoning with Tool Calling

When reasoning is combined with tool calling, the model thinks first (producing a reasoning item), then calls the tool (producing a function_call item):

Python

import os
import requests

response = requests.post(
    'https://enterprise.blackbox.ai/v1/responses',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f"Bearer {os.environ['BLACKBOX_API_KEY']}",
    },
    json={
        'model': 'blackboxai/openai/gpt-5.3-codex',
        'reasoning': {'effort': 'medium'},
        'include': ['reasoning.encrypted_content'],
        'input': [
            {'role': 'user', 'content': "What's the weather in Paris?"}
        ],
        'tools': [{
            'type': 'function',
            'name': 'get_weather',
            'description': 'Get the current weather in a location',
            'parameters': {
                'type': 'object',
                'properties': {
                    'city': {'type': 'string', 'description': 'City name'}
                },
                'required': ['city']
            }
        }]
    },
)
data = response.json()

for item in data['output']:
    if item['type'] == 'reasoning':
        print(f"[Reasoning] {item.get('content', [{}])[0].get('text', '')[:100]}...")
    elif item['type'] == 'function_call':
        print(f"[Tool] {item['name']}({item['arguments']})")

const response = await fetch('https://enterprise.blackbox.ai/v1/responses', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.BLACKBOX_API_KEY}`,
  },
  body: JSON.stringify({
    model: 'blackboxai/openai/gpt-5.3-codex',
    reasoning: { effort: 'medium' },
    include: ['reasoning.encrypted_content'],
    input: [
      { role: 'user', content: "What's the weather in Paris?" }
    ],
    tools: [{
      type: 'function',
      name: 'get_weather',
      description: 'Get the current weather in a location',
      parameters: {
        type: 'object',
        properties: { city: { type: 'string' } },
        required: ['city']
      }
    }]
  })
});

const data = await response.json();
for (const item of data.output) {
  if (item.type === 'reasoning') console.log('[Reasoning]', item.content?.[0]?.text?.slice(0, 100));
  if (item.type === 'function_call') console.log(`[Tool] ${item.name}(${item.arguments})`);
}

curl https://enterprise.blackbox.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BLACKBOX_API_KEY" \
  -d '{
    "model": "blackboxai/openai/gpt-5.3-codex",
    "reasoning": {"effort": "medium"},
    "include": ["reasoning.encrypted_content"],
    "input": [
      {"role": "user", "content": "What is the weather in Paris?"}
    ],
    "tools": [{
      "type": "function",
      "name": "get_weather",
      "description": "Get the current weather in a location",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }]
  }'

Response — Reasoning + Tool Call

{
  "id": "resp_WKnCTWadviYHbIbazz8YU1C1...",
  "object": "response",
  "model": "blackboxai/openai/gpt-5.3-codex",
  "status": "completed",
  "output": [
    {
      "id": "rs_1772502274510_1t9dmjqoee5j",
      "type": "reasoning",
      "summary": [],
      "content": [
        {
          "type": "reasoning_text",
          "text": "I need to use the weather tool to get the weather for Paris."
        }
      ],
      "encrypted_content": "gAAAAABppj0BM4w_s3F9t4kb..."
    },
    {
      "id": "fc_1772502274510_g7twdw0wz7v",
      "type": "function_call",
      "name": "get_weather",
      "arguments": "{\"city\":\"Paris\"}",
      "call_id": "call_7imH3aTWGafLCivAHxauCCrV",
      "status": "completed"
    }
  ],
  "usage": {
    "input_tokens": 591,
    "output_tokens": 120,
    "output_tokens_details": { "reasoning_tokens": 64 },
    "total_tokens": 711
  }
}

Multi-Turn with Reasoning

After executing the tool, pass back the reasoning item, function call, and tool result in the input array. The model uses its previous reasoning context to generate the final answer:

Python

import os
import requests
import json

url = 'https://enterprise.blackbox.ai/v1/responses'
headers = {
    'Content-Type': 'application/json',
    'Authorization': f"Bearer {os.environ['BLACKBOX_API_KEY']}",
}

tools = [{
    'type': 'function',
    'name': 'calculator',
    'description': 'Perform a calculation',
    'parameters': {
        'type': 'object',
        'properties': {'expression': {'type': 'string'}},
        'required': ['expression']
    }
}]

# Turn 1: Model reasons and calls the tool
r1 = requests.post(url, headers=headers, json={
    'model': 'blackboxai/openai/gpt-5.3-codex',
    'reasoning': {'effort': 'medium'},
    'include': ['reasoning.encrypted_content'],
    'input': [{'role': 'user', 'content': 'What is 15 + 27? Use the calculator.'}],
    'tools': tools
}).json()

# Build input for Turn 2: include all output items + tool result
input_turn2 = [{'role': 'user', 'content': 'What is 15 + 27? Use the calculator.'}]
for item in r1['output']:
    input_turn2.append(item)
    if item['type'] == 'function_call':
        input_turn2.append({
            'type': 'function_call_output',
            'call_id': item['call_id'],
            'output': '42'
        })

# Turn 2: Model uses reasoning context + tool result for final answer
r2 = requests.post(url, headers=headers, json={
    'model': 'blackboxai/openai/gpt-5.3-codex',
    'reasoning': {'effort': 'medium'},
    'input': input_turn2,
    'tools': tools
}).json()

msg = next(item for item in r2.get('output', []) if item.get('type') == 'message')
text = next(part['text'] for part in msg['content'] if part['type'] == 'output_text')
print(text)  # "15 + 27 = 42"

const url = 'https://enterprise.blackbox.ai/v1/responses';
const headers = {
  'Content-Type': 'application/json',
  Authorization: `Bearer ${process.env.BLACKBOX_API_KEY}`,
};

const tools = [{
  type: 'function',
  name: 'calculator',
  description: 'Perform a calculation',
  parameters: {
    type: 'object',
    properties: { expression: { type: 'string' } },
    required: ['expression']
  }
}];

// Turn 1
const r1 = await fetch(url, {
  method: 'POST', headers,
  body: JSON.stringify({
    model: 'blackboxai/openai/gpt-5.3-codex',
    reasoning: { effort: 'medium' },
    include: ['reasoning.encrypted_content'],
    input: [{ role: 'user', content: 'What is 15 + 27? Use the calculator.' }],
    tools
  })
}).then(r => r.json());

// Build Turn 2 input
const input: any[] = [{ role: 'user', content: 'What is 15 + 27? Use the calculator.' }];
for (const item of r1.output) {
  input.push(item);
  if (item.type === 'function_call') {
    input.push({ type: 'function_call_output', call_id: item.call_id, output: '42' });
  }
}

// Turn 2
const r2 = await fetch(url, {
  method: 'POST', headers,
  body: JSON.stringify({
    model: 'blackboxai/openai/gpt-5.3-codex',
    reasoning: { effort: 'medium' },
    input, tools
  })
}).then(r => r.json());

const r2Msg = r2.output.find((item: any) => item.type === 'message');
const r2Text = r2Msg?.content?.find((part: any) => part.type === 'output_text')?.text;
console.log(r2Text); // "15 + 27 = 42"

Turn 2 Response — Final Answer

{
  "id": "resp_AaQmI9orpLppdWHhpAkPGu5o...",
  "object": "response",
  "model": "blackboxai/openai/gpt-5.3-codex",
  "status": "completed",
  "output": [
    {
      "id": "msg_1772502284627_3tpxqy1rums",
      "type": "message",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "15 + 27 = **42**.",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 85,
    "output_tokens": 13,
    "output_tokens_details": { "reasoning_tokens": 0 },
    "total_tokens": 98
  }
}

---

Effort Levels

The reasoning.effort parameter guides how many reasoning tokens the model generates before responding. The default is medium.

Value	Description
"low"	Favors speed and economical token usage
"medium"	Balanced between speed and reasoning accuracy (default)
"high"	Favors more complete reasoning for complex tasks
"xhigh"	Maximum reasoning depth — allocates the largest portion of tokens for thinking

Reasoning Summaries

The reasoning.summary field is part of the OpenAI Responses API spec and is accepted by the API. Support varies by model — when supported, setting it causes the output array to include a reasoning item before the message item containing a human-readable summary of the model’s internal thinking.

Value	Description
"auto"	Uses the most detailed summarizer available (recommended)
"detailed"	Full step-by-step reasoning summary
"concise"	A shorter, high-level summary of the reasoning process

reasoning.summary is not currently supported by blackboxai/openai/gpt-5.3-codex. When unsupported, the field is accepted but ignored — the response returns only the message output item.

When a model supports reasoning.summary, the output array contains a reasoning item before the message:

[
  {
    "id": "rs_abc123",
    "type": "reasoning",
    "summary": [
      {
        "type": "summary_text",
        "text": "**Answering a simple question**\n\nThe capital of France is Paris — a well-known fact. I'll keep the answer brief and direct."
      }
    ]
  },
  {
    "id": "msg_abc456",
    "type": "message",
    "status": "completed",
    "role": "assistant",
    "content": [
      {
        "type": "output_text",
        "text": "The capital of France is Paris.",
        "annotations": []
      }
    ]
  }
]

Token Usage

Reasoning tokens are generated internally and are not visible in the response, but they are billed as output tokens and appear in usage.output_tokens_details:

{
  "usage": {
    "input_tokens": 75,
    "output_tokens": 1186,
    "output_tokens_details": {
      "reasoning_tokens": 1024
    },
    "total_tokens": 1261
  }
}

Reasoning tokens occupy space in the model’s context window and are billed as output tokens even though they are not returned in the response.

Handling Incomplete Responses

If the model runs out of token budget while reasoning, it may return status: incomplete — or in some cases return status: completed with an empty output_text when all tokens were consumed by internal reasoning. Reserve enough tokens for both reasoning and the visible output to avoid this.

TypeScript

const response = await fetch('https://enterprise.blackbox.ai/v1/responses', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${process.env.BLACKBOX_API_KEY}`,
  },
  body: JSON.stringify({
    model: 'blackboxai/openai/gpt-5.3-codex',
    reasoning: { effort: 'medium' },
    max_output_tokens: 300,
    input: [
      {
        role: 'user',
        content: 'Write a bash script that transposes a matrix.',
      },
    ],
  }),
});

const data = await response.json();
if (data.status === 'incomplete' && data.incomplete_details?.reason === 'max_output_tokens') {
  console.log('Ran out of tokens');
  const msg = data.output?.find((item: any) => item.type === 'message');
  const text = msg?.content?.find((part: any) => part.type === 'output_text')?.text;
  if (text) {
    console.log('Partial output:', text);
  } else {
    console.log('Ran out of tokens during reasoning — no visible output produced');
  }
}

import os
import requests

response = requests.post(
    'https://enterprise.blackbox.ai/v1/responses',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f"Bearer {os.environ['BLACKBOX_API_KEY']}",
    },
    json={
        'model': 'blackboxai/openai/gpt-5.3-codex',
        'reasoning': {'effort': 'medium'},
        'max_output_tokens': 300,
        'input': [
            {
                'role': 'user',
                'content': 'Write a bash script that transposes a matrix.',
            }
        ],
    },
)

data = response.json()
if data.get('status') == 'incomplete' and data.get('incomplete_details', {}).get('reason') == 'max_output_tokens':
    print('Ran out of tokens')
    msg = next((item for item in data.get('output', []) if item.get('type') == 'message'), None)
    text = next((part['text'] for part in (msg or {}).get('content', []) if part.get('type') == 'output_text'), None)
    if text:
        print('Partial output:', text)
    else:
        print('Ran out of tokens during reasoning — no visible output produced')

Request Parameters

reasoning · object

Configures reasoning behavior for the model.

Show reasoning fields

effort · string

Controls how many reasoning tokens the model uses. One of "low", "medium" (default), "high", or "xhigh".

summary · string

When set, returns a human-readable reasoning summary alongside the response. One of "auto", "detailed", or "concise". Not included unless explicitly set.

max_output_tokens · integer

Maximum number of tokens to generate in the response, including reasoning tokens. Increase this when using higher effort levels to avoid incomplete responses.

Next Steps

Text Generation

Learn the basics of the Responses API

Tool Calling

Combine reasoning with tool calls for complex agentic workflows

Best Practices

Preserve reasoning signatures across turns and avoid common errors