Create Chat Completion

Send a chat completion request. Find your API Key.

POST /chat/completions

cURL

# Public api users: use https://api.blackbox.ai/chat/completions
curl -X POST https://enterprise.blackbox.ai/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "blackboxai/openai/gpt-5.5",
    "messages": [
        {
            "role": "user",
            "content": "What is the capital of France?"
        }
    ],
    "temperature": 0.7,
    "max_tokens": 256,
    "stream": false
}'

const API_KEY = "YOUR_API_KEY";
// Public api users: use "https://api.blackbox.ai/chat/completions"
const API_URL = "https://enterprise.blackbox.ai/chat/completions";

const data = {
    "model": "blackboxai/openai/gpt-5.5",
    "messages": [
        {
            "role": "user",
            "content": "What is the capital of France?"
        }
    ],
    "temperature": 0.7,
    "max_tokens": 256,
    "stream": false
};

const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
});

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

import requests

API_KEY = "YOUR_API_KEY"
# Public api users: use "https://api.blackbox.ai/chat/completions"
API_URL = "https://enterprise.blackbox.ai/chat/completions"

headers = {
  "Authorization": f"Bearer {API_KEY}",
  "Content-Type": "application/json"
}

data = {
    "model": "blackboxai/openai/gpt-5.5",
    "messages": [
        {
            "role": "user",
            "content": "What is the capital of France?"
        }
    ],
    "temperature": 0.7,
    "max_tokens": 256,
    "stream": False
}

response = requests.post(API_URL, headers=headers, json=data)
print(response.json())

Response

{
  "id":"gen-...",
  "created":1757140020,
  "model":"blackboxai/openai/gpt-5.5",
  "object":"chat.completion",
  "system_fingerprint":"None",
  "choices":[
    {
      "finish_reason":"stop",
      "index":0,
      "message":{
        "content":"The capital of France is Paris.",
        "role":"assistant",
        "tool_calls":"None",
        "function_call":"None"
      },
      "provider_specific_fields":{
        "native_finish_reason":"stop"
      }
    }
  ],
  "usage":{
    "completion_tokens":7,
    "prompt_tokens":14,
    "total_tokens":21,
    "completion_tokens_details":{
      "accepted_prediction_tokens":"None",
      "audio_tokens":"None",
      "reasoning_tokens":0,
      "rejected_prediction_tokens":"None"
    },
    "prompt_tokens_details":{
      "audio_tokens":0,
      "cached_tokens":0
    }
  },
  "provider":"OpenAI"
}

Headers

Authorization · string · required

API Key of the from Bearer <api_key>, you can get it from here.

On an Enterprise plan? Just use enterprise.blackbox.ai instead of api.blackbox.ai for your endpoint.

Request

model · string · required

The model ID to use. See the Chat Models page

messages · array · required

Array of message objects containing the conversation history.

Show Message Object

role · string · required

The role of the message author. One of system, user, assistant, or tool.

content · string | array

The content of the message. Can be a string or array of content parts for multimodal inputs.

name · string

An optional name for the participant. Provides the model information to differentiate between participants of the same role.

tool_call_id · string

For tool messages, the ID of the tool call this message is responding to.

models · array

Alternate list of models for routing overrides.

provider · object

Preferences for provider routing.

stream · boolean

Enable streaming of results via Server-Sent Events.

max_tokens · integer

Maximum number of tokens to generate (range: [1, context_length)).

temperature · number

Sampling temperature (range: [0, 2]).

seed · integer

Seed for deterministic outputs.

top_p · number

Top-p sampling value (range: (0, 1]).

top_k · integer

Top-k sampling value (range: [1, Infinity)).

frequency_penalty · number

Frequency penalty (range: [-2, 2]).

presence_penalty · number

Presence penalty (range: [-2, 2]).

repetition_penalty · number

Repetition penalty (range: (0, 2]).

logit_bias · object

Mapping of token IDs to bias values.

top_logprobs · integer

Number of top log probabilities to return.

min_p · number

Minimum probability threshold (range: [0, 1]).

top_a · number

Alternate top sampling parameter (range: [0, 1]).

stop · array

Stop sequences - generation will stop if any of these strings are encountered.

tools · array

Tool definitions following OpenAI’s tool calling format.

Show Tool Object

type · string

Type of tool, typically function.

function · object

Function definition.

Show Function Definition

name · string

Name of the function.

description · string

Description of what the function does.

parameters · object

JSON Schema object defining the function parameters.

tool_choice · string | object

Controls which (if any) tool is called by the model.

• none - Model will not call any tool
• auto - Model can pick between generating a message or calling tools
• required - Model must call one or more tools
• Or specify a particular tool via {"type": "function", "function": {"name": "function_name"}}

response_format · object

Enforce structured output format.

user · string

A stable identifier for your end-users. Used to help detect and prevent abuse.

Response

id · string

Unique identifier for the chat completion.

created · integer

Unix timestamp when the completion was created.

model · string

The model used for the completion.

object · string

Object type, always chat.completion or chat.completion.chunk for streaming.

system_fingerprint · string | null

System fingerprint for the model configuration.

choices · array

Array of completion choices.

Show Choice Object

finish_reason · string

Reason the generation stopped. Options: stop, length, content_filter, tool_calls, error.

index · integer

Index of the choice in the list.

message · object

The generated message.

Show Message Object

content · string | null

The generated content.

role · string

Role of the message author, typically assistant.

reasoning · string | null

Raw reasoning text when reasoning tokens are enabled and not excluded. Contains the model’s step-by-step thinking process.

reasoning_details · array | null

Structured reasoning information containing detailed reasoning blocks. Used for preserving reasoning context across multiple API calls.

Show Reasoning Detail Object

type · string

Type of reasoning detail. Options: reasoning.summary, reasoning.encrypted, reasoning.text.

id · string | null

Unique identifier for the reasoning detail.

format · string

Format of the reasoning detail. Options: unknown, openai-responses-v1, xai-responses-v1, anthropic-claude-v1.

index · number

Sequential index of the reasoning detail.

summary · string

High-level summary of reasoning process (for reasoning.summary type).

text · string

Raw reasoning text (for reasoning.text type).

data · string

Encrypted reasoning data (for reasoning.encrypted type).

signature · string | null

Optional signature for verification (for reasoning.text type).

tool_calls · array | null

Tool calls made by the assistant.

Show Tool Call Object

id · string

Unique identifier for the tool call.

type · string

Type of tool, typically function.

function · object

The function call details.

Show Function Object

name · string

Name of the function being called.

arguments · string

JSON string of arguments for the function.

annotations · array | null

Annotations containing source citations and references. Available when using models with web search capabilities like blackbox-search.

Show Annotation Object

type · string

Type of annotation. Currently supports url_citation.

url_citation · object

Citation information for web sources.

Show URL Citation Object

url · string

The URL of the cited source.

title · string

The title of the web page or article.

content · string

Excerpt or summary of the content from the source (if available).

start_index · integer

The character index where the citation begins in the message content.

end_index · integer

The character index where the citation ends in the message content.

function_call · object | null

Deprecated function call field (use tool_calls instead).

provider_specific_fields · object

Provider-specific response fields.

Show Provider Specific Fields

native_finish_reason · string

Raw finish reason from the underlying provider.

usage · object

Token usage information.

Show Usage Object

completion_tokens · integer

Number of tokens in the completion.

prompt_tokens · integer

Number of tokens in the prompt.

total_tokens · integer

Total number of tokens used (prompt + completion).

completion_tokens_details · object

Detailed breakdown of completion tokens.

Show Completion Tokens Details

accepted_prediction_tokens · integer | null

Number of accepted prediction tokens.

audio_tokens · integer | null

Number of audio tokens in the completion.

reasoning_tokens · integer

Number of reasoning/thinking tokens used.

rejected_prediction_tokens · integer | null

Number of rejected prediction tokens.

prompt_tokens_details · object

Detailed breakdown of prompt tokens.

Show Prompt Tokens Details

audio_tokens · integer

Number of audio tokens in the prompt.

cached_tokens · integer

Number of cached tokens used from previous requests.

provider · string

The provider that served the request.

cURL

# Public api users: use https://api.blackbox.ai/chat/completions
curl -X POST https://enterprise.blackbox.ai/chat/completions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "blackboxai/openai/gpt-5.5",
    "messages": [
        {
            "role": "user",
            "content": "What is the capital of France?"
        }
    ],
    "temperature": 0.7,
    "max_tokens": 256,
    "stream": false
}'

const API_KEY = "YOUR_API_KEY";
// Public api users: use "https://api.blackbox.ai/chat/completions"
const API_URL = "https://enterprise.blackbox.ai/chat/completions";

const data = {
    "model": "blackboxai/openai/gpt-5.5",
    "messages": [
        {
            "role": "user",
            "content": "What is the capital of France?"
        }
    ],
    "temperature": 0.7,
    "max_tokens": 256,
    "stream": false
};

const response = await fetch(API_URL, {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
});

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

import requests

API_KEY = "YOUR_API_KEY"
# Public api users: use "https://api.blackbox.ai/chat/completions"
API_URL = "https://enterprise.blackbox.ai/chat/completions"

headers = {
  "Authorization": f"Bearer {API_KEY}",
  "Content-Type": "application/json"
}

data = {
    "model": "blackboxai/openai/gpt-5.5",
    "messages": [
        {
            "role": "user",
            "content": "What is the capital of France?"
        }
    ],
    "temperature": 0.7,
    "max_tokens": 256,
    "stream": False
}

response = requests.post(API_URL, headers=headers, json=data)
print(response.json())

Response

{
  "id":"gen-...",
  "created":1757140020,
  "model":"blackboxai/openai/gpt-5.5",
  "object":"chat.completion",
  "system_fingerprint":"None",
  "choices":[
    {
      "finish_reason":"stop",
      "index":0,
      "message":{
        "content":"The capital of France is Paris.",
        "role":"assistant",
        "tool_calls":"None",
        "function_call":"None"
      },
      "provider_specific_fields":{
        "native_finish_reason":"stop"
      }
    }
  ],
  "usage":{
    "completion_tokens":7,
    "prompt_tokens":14,
    "total_tokens":21,
    "completion_tokens_details":{
      "accepted_prediction_tokens":"None",
      "audio_tokens":"None",
      "reasoning_tokens":0,
      "rejected_prediction_tokens":"None"
    },
    "prompt_tokens_details":{
      "audio_tokens":0,
      "cached_tokens":0
    }
  },
  "provider":"OpenAI"
}