> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blackbox.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Tip>
  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.
</Tip>

## Basic Request

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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);
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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)
  ```

  ```bash cURL theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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?"
        }
      ]
    }'
  ```
</CodeGroup>

## Response Format

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

```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "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:

<CodeGroup>
  ```typescript TypeScript theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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();
  ```

  ```python Python theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
  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()
  ```
</CodeGroup>

## Request Parameters

<ParamField body="model" type="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](/api-reference/models/chat-models) section.
</ParamField>

<ParamField body="input" type="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
</ParamField>

<ParamField body="max_output_tokens" type="integer">
  Maximum number of tokens to generate. Controls the length of the output.
</ParamField>

<ParamField body="temperature" type="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`
</ParamField>

<ParamField body="top_p" type="number">
  Controls diversity via nucleus sampling. Range: `0.0` to `1.0`. Not recommended to use alongside `temperature`. Default: `1.0`
</ParamField>

## Response Fields

<ResponseField name="id" type="string">
  Unique identifier for this response.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"response"` for this endpoint.
</ResponseField>

<ResponseField name="model" type="string">
  The model used to generate the response.
</ResponseField>

<ResponseField name="output" type="array">
  Array containing the generated response. Each item has:

  * `type`: `"message"`
  * `role`: `"assistant"`
  * `content`: Array with `type: "output_text"` and `text` fields
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage statistics with `input_tokens` and `output_tokens`.
</ResponseField>

## Next Steps

<CardGroup cols={2}>
  <Card title="Streaming" icon="water" href="/api-reference/responses/streaming">
    Receive tokens as they are generated for real-time output
  </Card>

  <Card title="Tool Calling" icon="wrench" href="/api-reference/responses/tool-calling">
    Give the model access to external functions and APIs
  </Card>
</CardGroup>