Text Generation

Generate text responses using the Responses API with BLACKBOX AI models

Use the Responses API to generate text responses from AI models. The input array contains message objects with a role (user or assistant) and content field. The model processes the input and returns a response with the generated text.

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 Request

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: 'openai/gpt-5.3-codex',
    input: [
      {
        type: 'message',
        role: 'user',
        content: 'Why do developers prefer dark mode?',
      },
    ],
  }),
});

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

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': 'openai/gpt-5.3-codex',
        'input': [
            {
                'type': 'message',
                'role': 'user',
                'content': 'Why do developers prefer dark mode?',
            },
        ],
    }
)

result = response.json()
print(result)

curl https://enterprise.blackbox.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BLACKBOX_API_KEY" \
  -d '{
    "model": "openai/gpt-5.3-codex",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": "Why do developers prefer dark mode?"
      }
    ]
  }'

Response Format

The response includes the generated text in the output array, along with token usage information.

{
  "id": "resp_abc123",
  "object": "response",
  "model": "openai/gpt-5.3-codex",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Habit and aesthetics reinforce the preference, but ergonomics and contrast are the primary drivers."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 14,
    "output_tokens": 18
  }
}

Multi-turn Conversations

For conversations with multiple messages, include both user and assistant messages in the input array:

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: 'openai/gpt-5.3-codex',
    input: [
      {
        type: 'message',
        role: 'user',
        content: 'What is React?',
      },
      {
        type: 'message',
        role: 'assistant',
        content: 'React is a JavaScript library for building user interfaces.',
      },
      {
        type: 'message',
        role: 'user',
        content: 'What are the main benefits?',
      },
    ],
  }),
});

const result = await response.json();

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': 'openai/gpt-5.3-codex',
        'input': [
            {
                'type': 'message',
                'role': 'user',
                'content': 'What is React?',
            },
            {
                'type': 'message',
                'role': 'assistant',
                'content': 'React is a JavaScript library for building user interfaces.',
            },
            {
                'type': 'message',
                'role': 'user',
                'content': 'What are the main benefits?',
            },
        ],
    }
)

result = response.json()

Request Parameters

model · string · required

The model identifier to use for generation. Example: openai/gpt-5.3-codex

See the full list of available models in the Models section.

input · array · required

Array of input messages. Each message object must contain:

• type: Always "message"
• role: Either "user", "assistant", or "system"
• content: The message text content

max_output_tokens · integer

Maximum number of tokens to generate. Controls the length of the output.

temperature · number

Controls randomness in generation. Range: 0.0 to 2.0. Lower values produce more focused output; higher values produce more varied output. Default: 1.0

top_p · number

Controls diversity via nucleus sampling. Range: 0.0 to 1.0. Not recommended to use alongside temperature. Default: 1.0

Response Fields

id · string

Unique identifier for this response.

object · string

Always "response" for this endpoint.

model · string

The model used to generate the response.

output · array

Array containing the generated response. Each item has:

• type: "message"
• role: "assistant"
• content: Array with type: "output_text" and text fields

usage · object

Token usage statistics with input_tokens and output_tokens.

Next Steps

Streaming

Receive tokens as they are generated for real-time output

Tool Calling

Give the model access to external functions and APIs