Responses API Beta - BLACKBOX AI

This API is in beta stage and may have breaking changes. Use with caution in production environments.

This API currently requires streaming mode (stream: true). All requests must include stream: true, store: false, and instructions (required for gpt-5.3-codex).

Blackbox AI’s Responses API Beta provides OpenAI-compatible access to multiple AI models through a unified interface, designed to be a drop-in replacement for OpenAI’s Responses API. This stateless API offers enhanced capabilities including reasoning, tool calling, and web search integration, with each request being independent and no server-side state persisted.

Base URL


https://enterprise.blackbox.ai/v1/responses

Authentication

All requests require authentication using your Blackbox AI API key:

curl -X POST https://enterprise.blackbox.ai/v1/responses \
  -H "Authorization: Bearer YOUR_BLACKBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.3-codex",
    "instructions": "You are a helpful assistant.",
    "store": false,
    "stream": true,
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "Hello, world!"
          }
        ]
      }
    ]
  }'

Required Parameters

Every request to the Responses API must include the following parameters:

Parameter	Type	Description
`model`	string	Required. Model to use (e.g., `gpt-5.3-codex`)
`instructions`	string	Required for `gpt-5.3-codex`. System instructions for the model
`input`	array	Required. Array of message objects (string or structured content)
`store`	boolean	Required for `gpt-5.3-codex`. Must be set to `false`
`stream`	boolean	Required for `gpt-5.3-codex`. Must be set to `true`

Optional Parameters

Parameter	Type	Description
`tools`	array	List of tools/functions the model can call
`tool_choice`	string/object	Control tool usage: `"auto"`, `"none"`, or specific tool
`parallel_tool_calls`	boolean	Allow multiple tool calls in one response (default: `true`)

Basic Usage

The Responses API accepts message input as an array. Each message can use either a structured format (with type, role, and content array) or a simple format (role and content as a string).

curl -X POST https://enterprise.blackbox.ai/v1/responses \
  -H "Authorization: Bearer YOUR_BLACKBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.3-codex",
    "instructions": "You are a helpful assistant.",
    "store": false,
    "stream": true,
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "What is the meaning of life?"
          }
        ]
      }
    ]
  }'

Streaming Response Format

Since all responses are streamed, the API returns Server-Sent Events (SSE). The final response.completed event contains the full response:

{
  "type": "response.completed",
  "response": {
    "id": "resp_1234567890",
    "created_at": 1234567890,
    "model": "gpt-5.3-codex",
    "object": "response",
    "output": [
      {
        "id": "msg_abc123",
        "type": "message",
        "role": "assistant",
        "status": "completed",
        "content": [
          {
            "type": "output_text",
            "text": "The meaning of life is a philosophical question that has been pondered for centuries...",
            "annotations": []
          }
        ]
      }
    ],
    "status": "completed",
    "usage": {
      "input_tokens": 20,
      "output_tokens": 45,
      "total_tokens": 65,
      "input_tokens_details": { "cached_tokens": 0 },
      "output_tokens_details": { "reasoning_tokens": 0 }
    }
  }
}

Key Streaming Events

Event Type	Description
`response.created`	Response object created, processing started
`response.in_progress`	Response is being generated
`response.output_item.added`	New output message added
`response.content_part.added`	Content part added to message
`response.output_text.delta`	Text chunk streamed (the actual content)
`response.output_text.done`	Full text of the output part completed
`response.content_part.done`	Content part fully completed
`response.output_item.done`	Output message fully completed
`response.completed`	Full response completed with usage stats

Multi-Turn Conversations

Since the API is stateless and previous_response_id is not currently supported, you must include the full conversation history in the input array for multi-turn conversations.

curl -X POST https://enterprise.blackbox.ai/v1/responses \
  -H "Authorization: Bearer YOUR_BLACKBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.3-codex",
    "instructions": "You are a helpful assistant.",
    "store": false,
    "stream": true,
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "What is the capital of France?"
          }
        ]
      },
      {
        "type": "message",
        "role": "assistant",
        "content": [
          {
            "type": "output_text",
            "text": "The capital of France is Paris."
          }
        ]
      },
      {
        "type": "message",
        "role": "user",
        "content": [
          {
            "type": "input_text",
            "text": "What is the population of that city?"
          }
        ]
      }
    ]
  }'

Always include the complete conversation history in the input array. The API does not store previous messages, so context must be maintained client-side.

Tool Calling

The Responses API supports tool/function calling with a different format than the Chat Completions API. Tools are defined at the top level (not nested under function).

The Responses API uses a flat tool structure where name, description, and parameters are at the top level, unlike Chat Completions API which nests them under function.

Tool Definition Format

{
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get the current weather for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          }
        },
        "required": ["location"],
        "additionalProperties": false
      }
    }
  ]
}

Basic Tool Calling Example

curl -X POST https://enterprise.blackbox.ai/v1/responses \
  -H "Authorization: Bearer YOUR_BLACKBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.3-codex",
    "instructions": "You are a helpful assistant. Use tools when appropriate.",
    "store": false,
    "stream": true,
    "input": [
      {
        "role": "user",
        "content": "What is the weather in San Francisco?"
      }
    ],
    "tools": [
      {
        "type": "function",
        "name": "get_weather",
        "description": "Get the current weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          },
          "required": ["location"],
          "additionalProperties": false
        }
      }
    ]
  }'

Tool Call Response Format

When the model decides to call a tool, the response includes a function_call output item:

{
  "type": "response.output_item.done",
  "item": {
    "id": "fc_abc123",
    "type": "function_call",
    "name": "get_weather",
    "arguments": "{\"location\":\"San Francisco, CA\"}",
    "call_id": "call_NyXyRSDn8GtsMWsoW4TFFpi4",
    "status": "completed"
  }
}

Tool Call Streaming Events

Event Type	Description
`response.output_item.added`	Tool call item added (type: `function_call`)
`response.function_call_arguments.delta`	Streaming tool call arguments
`response.function_call_arguments.done`	Complete tool call arguments
`response.output_item.done`	Tool call completed

Handling Tool Results

After receiving a tool call, execute the tool and send the result back:

curl -X POST https://enterprise.blackbox.ai/v1/responses \
  -H "Authorization: Bearer YOUR_BLACKBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.3-codex",
    "instructions": "You are a helpful assistant.",
    "store": false,
    "stream": true,
    "input": [
      {
        "role": "user",
        "content": "What is the weather in San Francisco?"
      },
      {
        "type": "function_call",
        "name": "get_weather",
        "call_id": "call_NyXyRSDn8GtsMWsoW4TFFpi4",
        "arguments": "{\"location\":\"San Francisco, CA\"}"
      },
      {
        "type": "function_call_output",
        "call_id": "call_NyXyRSDn8GtsMWsoW4TFFpi4",
        "output": "{\"temperature\": 65, \"condition\": \"Partly cloudy\", \"humidity\": 72}"
      }
    ]
  }'

The model will then respond with a natural language answer based on the tool result:

It's currently 65°F in San Francisco with partly cloudy skies and 72% humidity.

Multiple Tools

You can provide multiple tools for the model to choose from:

{
  "tools": [
    {
      "type": "function",
      "name": "get_weather",
      "description": "Get the current weather for a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        },
        "required": ["location"],
        "additionalProperties": false
      }
    },
    {
      "type": "function",
      "name": "search_web",
      "description": "Search the web for information",
      "parameters": {
        "type": "object",
        "properties": {
          "query": { "type": "string" }
        },
        "required": ["query"],
        "additionalProperties": false
      }
    }
  ]
}

Tool Choice

Control tool usage with the tool_choice parameter:

// Let model decide (default)
{ "tool_choice": "auto" }

// Disable tool usage
{ "tool_choice": "none" }

// Force specific tool
{
  "tool_choice": {
    "type": "function",
    "name": "get_weather"
  }
}

Parallel Tool Calls

By default, the model can request multiple tool calls in parallel. Control this with parallel_tool_calls:

{
  "parallel_tool_calls": true  // default
}

Format Comparison: Responses API vs Chat Completions API

The Responses API uses a different tool format than the Chat Completions API. Make sure to use the correct format for each endpoint.

Aspect	Chat Completions API	Responses API
Tool structure	Nested under `function`	Flat (top-level)
`name` location	`tools[].function.name`	`tools[].name`
`description` location	`tools[].function.description`	`tools[].description`
`parameters` location	`tools[].function.parameters`	`tools[].parameters`
Tool call in response	`message.tool_calls[].function`	`output[].name`, `output[].arguments`
Tool result format	`role: "tool"`, `tool_call_id`	`type: "function_call_output"`, `call_id`

Chat Completions API Tool Format

{
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get weather",
      "parameters": { ... }
    }
  }]
}

Responses API Tool Format

{
  "tools": [{
    "type": "function",
    "name": "get_weather",
    "description": "Get weather",
    "parameters": { ... }
  }]
}

Error Handling

Handle common errors gracefully:

try {
  
  const response = await fetch('https://enterprise.blackbox.ai/v1/responses', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_BLACKBOX_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'gpt-5.3-codex',
      instructions: 'You are a helpful assistant.',
      store: false,
      stream: true,
      input: [
        {
          type: 'message',
          role: 'user',
          content: [
            { type: 'input_text', text: 'Hello, world!' },
          ],
        },
      ],
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', error.error.message);
    return;
  }

  // Process streaming response...
} catch (error) {
  console.error('Network Error:', error);
}

The API returns structured error responses:

{
  "error": {
    "code": "400",
    "message": "Missing required parameter: 'instructions'."
  }
}

Common Errors

Error	Cause
`Instructions are required`	Missing `instructions` parameter (required for `gpt-5.3-codex`)
`Input must be a list`	`input` was a string instead of an array
`Store must be set to false`	`store` was not set to `false` (required for `gpt-5.3-codex`)
`Stream must be set to true`	`stream` was not set to `true` (required for `gpt-5.3-codex`)
`Unsupported parameter: previous_response_id`	`previous_response_id` is not currently supported

For comprehensive error handling guidance, see Error Handling.

Endpoints

​Base URL

​Authentication

​Required Parameters

​Optional Parameters

​Basic Usage

​Streaming Response Format

​Key Streaming Events

​Multi-Turn Conversations

​Tool Calling

​Tool Definition Format

​Basic Tool Calling Example

​Tool Call Response Format

​Tool Call Streaming Events

​Handling Tool Results

​Multiple Tools

​Tool Choice

​Parallel Tool Calls

​Format Comparison: Responses API vs Chat Completions API

​Chat Completions API Tool Format

​Responses API Tool Format

​Error Handling

​Common Errors

Base URL

Authentication

Required Parameters

Optional Parameters

Basic Usage

Streaming Response Format

Key Streaming Events

Multi-Turn Conversations

Tool Calling

Tool Definition Format

Basic Tool Calling Example

Tool Call Response Format

Tool Call Streaming Events

Handling Tool Results

Multiple Tools

Tool Choice

Parallel Tool Calls

Format Comparison: Responses API vs Chat Completions API

Chat Completions API Tool Format

Responses API Tool Format

Error Handling

Common Errors