Create Chat Completion

Send a chat completion request. Find your API Key.

Headers

Authorizationstringrequired

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

modelstringrequired

The model ID to use. See the LLM Pricing page

messagesarrayrequired

Array of message objects containing the conversation history.

Message Object

rolestringrequired

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

contentstring | array

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

namestring

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

tool_call_idstring

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

modelsarray

Alternate list of models for routing overrides.

providerobject

Preferences for provider routing.

streamboolean

Enable streaming of results via Server-Sent Events.

max_tokensinteger

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

temperaturenumber

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

seedinteger

Seed for deterministic outputs.

top_pnumber

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

top_kinteger

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

frequency_penaltynumber

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

presence_penaltynumber

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

repetition_penaltynumber

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

logit_biasobject

Mapping of token IDs to bias values.

top_logprobsinteger

Number of top log probabilities to return.

min_pnumber

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

top_anumber

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

stoparray

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

toolsarray

Tool definitions following OpenAI's tool calling format.

Tool Object

typestring

Type of tool, typically function.

functionobject

Function definition.

Function Definition

namestring

Name of the function.

descriptionstring

Description of what the function does.

parametersobject

JSON Schema object defining the function parameters.

tool_choicestring | 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_formatobject

Enforce structured output format.

userstring

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

Response

idstring

Unique identifier for the chat completion.

createdinteger

Unix timestamp when the completion was created.

modelstring

The model used for the completion.

objectstring

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

system_fingerprintstring | null

System fingerprint for the model configuration.

choicesarray

Array of completion choices.

Choice Object

finish_reasonstring

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

indexinteger

Index of the choice in the list.

messageobject

The generated message.

Message Object

contentstring | null

The generated content.

rolestring

Role of the message author, typically assistant.

reasoningstring | null

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

reasoning_detailsarray | null

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

Reasoning Detail Object

typestring

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

idstring | null

Unique identifier for the reasoning detail.

formatstring

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

indexnumber

Sequential index of the reasoning detail.

summarystring

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

textstring

Raw reasoning text (for reasoning.text type).

datastring

Encrypted reasoning data (for reasoning.encrypted type).

signaturestring | null

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

tool_callsarray | null

Tool calls made by the assistant.

Tool Call Object

idstring

Unique identifier for the tool call.

typestring

Type of tool, typically function.

functionobject

The function call details.

Function Object

namestring

Name of the function being called.

argumentsstring

JSON string of arguments for the function.

annotationsarray | null

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

Annotation Object

typestring

Type of annotation. Currently supports url_citation.

url_citationobject

Citation information for web sources.

URL Citation Object

urlstring

The URL of the cited source.

titlestring

The title of the web page or article.

contentstring

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

start_indexinteger

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

end_indexinteger

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

function_callobject | null

Deprecated function call field (use tool_calls instead).

provider_specific_fieldsobject

Provider-specific response fields.

Provider Specific Fields

native_finish_reasonstring

Raw finish reason from the underlying provider.

usageobject

Token usage information.

Usage Object

completion_tokensinteger

Number of tokens in the completion.

prompt_tokensinteger

Number of tokens in the prompt.

total_tokensinteger

Total number of tokens used (prompt + completion).

completion_tokens_detailsobject

Detailed breakdown of completion tokens.

Completion Tokens Details

accepted_prediction_tokensinteger | null

Number of accepted prediction tokens.

audio_tokensinteger | null

Number of audio tokens in the completion.

reasoning_tokensinteger

Number of reasoning/thinking tokens used.

rejected_prediction_tokensinteger | null

Number of rejected prediction tokens.

prompt_tokens_detailsobject

Detailed breakdown of prompt tokens.

Prompt Tokens Details

audio_tokensinteger

Number of audio tokens in the prompt.

cached_tokensinteger

Number of cached tokens used from previous requests.

providerstring

The provider that served the request.

Request Example

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

{
  "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"
}