> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Soju06/codex-lb/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Completions

> Create a chat completion using OpenAI-compatible format

## Overview

The `/v1/chat/completions` endpoint provides full OpenAI Chat Completions API compatibility. It accepts chat-formatted messages and maps them internally to the Responses API format while preserving streaming behavior and tool calling capabilities.

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`
</ParamField>

## Request Body

<ParamField body="model" type="string" required>
  ID of the model to use. Must be a valid model slug from the `/v1/models` endpoint.

  Example: `"gpt-4.1"`, `"gpt-5.2"`
</ParamField>

<ParamField body="messages" type="array" required>
  Array of message objects representing the conversation history. Must contain at least one message.

  Each message object has:

  * `role` (string, required): One of `"system"`, `"developer"`, `"user"`, `"assistant"`, or `"tool"`
  * `content` (string | array): Message content. For `system`/`developer` roles, must be text-only.
  * `tool_calls` (array, optional): For assistant messages, array of tool call objects
  * `tool_call_id` (string, required for tool role): ID of the tool call this message responds to
</ParamField>

<ParamField body="tools" type="array">
  Array of tool definitions available to the model.

  Each tool object:

  * `type` (string): `"function"` or `"web_search"`
  * `function` (object): For function tools, contains `name`, `description`, and `parameters`

  Supported tool types:

  * `function`: Custom function calls
  * `web_search` or `web_search_preview`: Web search capability

  Unsupported types (will return error):

  * `file_search`, `code_interpreter`, `computer_use`, `computer_use_preview`, `image_generation`
</ParamField>

<ParamField body="tool_choice" type="string | object">
  Controls which tool the model should use.

  Options:

  * `"none"`: Model will not call tools
  * `"auto"`: Model decides whether to call tools
  * `"required"`: Model must call at least one tool
  * Object with `{"type": "function", "function": {"name": "tool_name"}}`: Force specific tool
</ParamField>

<ParamField body="parallel_tool_calls" type="boolean">
  Whether to enable parallel tool calling. When true, the model can call multiple tools simultaneously.
</ParamField>

<ParamField body="stream" type="boolean" default={false}>
  Whether to stream the response as server-sent events.

  * `true`: Returns `text/event-stream` with `chat.completion.chunk` objects
  * `false`: Returns a single `chat.completion` object
</ParamField>

<ParamField body="stream_options" type="object">
  Options for streaming responses.

  Properties:

  * `include_usage` (boolean): Include token usage in final chunk
  * `include_obfuscation` (boolean): Include obfuscation data in stream
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature between 0 and 2. Higher values make output more random.
</ParamField>

<ParamField body="top_p" type="number">
  Nucleus sampling parameter. Alternative to temperature.
</ParamField>

<ParamField body="max_tokens" type="integer">
  Maximum number of tokens to generate. Alias for `max_completion_tokens`.
</ParamField>

<ParamField body="max_completion_tokens" type="integer">
  Maximum number of tokens in the completion.
</ParamField>

<ParamField body="response_format" type="object">
  Format for the model's output.

  Options:

  * `{"type": "text"}`: Plain text (default)
  * `{"type": "json_object"}`: Valid JSON object
  * `{"type": "json_schema", "json_schema": {...}}`: JSON matching provided schema

  For `json_schema` type:

  * `json_schema.name` (string): Schema name, 1-64 chars, alphanumeric/underscore/hyphen
  * `json_schema.schema` (object): JSON Schema definition
  * `json_schema.strict` (boolean): Enable strict schema adherence
</ParamField>

<ParamField body="stop" type="string | array">
  Stop sequence(s). Generation stops when these tokens are encountered.
</ParamField>

<ParamField body="presence_penalty" type="number">
  Penalty for token presence. Range: -2.0 to 2.0.
</ParamField>

<ParamField body="frequency_penalty" type="number">
  Penalty for token frequency. Range: -2.0 to 2.0.
</ParamField>

<ParamField body="logprobs" type="boolean">
  Whether to return log probabilities of output tokens.
</ParamField>

<ParamField body="top_logprobs" type="integer">
  Number of most likely tokens to return at each position (requires `logprobs: true`).
</ParamField>

<ParamField body="seed" type="integer">
  Random seed for deterministic sampling.
</ParamField>

<ParamField body="n" type="integer" default={1}>
  Number of completions to generate. Must be 1 (only value supported).
</ParamField>

## Response (Non-Streaming)

When `stream` is `false` or omitted, returns a `chat.completion` object:

<ResponseField name="id" type="string">
  Unique identifier for the completion.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"chat.completion"`.
</ResponseField>

<ResponseField name="created" type="integer">
  Unix timestamp of creation.
</ResponseField>

<ResponseField name="model" type="string">
  Model used for completion.
</ResponseField>

<ResponseField name="choices" type="array">
  Array of completion choices (always contains one choice).

  Each choice object:

  * `index` (integer): Choice index (always 0)
  * `message` (object): The assistant's message
    * `role` (string): Always `"assistant"`
    * `content` (string | null): Text content of the message
    * `refusal` (string | null): Refusal message if model declined
    * `tool_calls` (array | null): Tool calls made by the model
  * `finish_reason` (string): Why generation stopped
    * `"stop"`: Natural completion
    * `"length"`: Max tokens reached
    * `"tool_calls"`: Model called tools
    * `"content_filter"`: Content filtered
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage information.

  Properties:

  * `prompt_tokens` (integer): Tokens in the prompt
  * `completion_tokens` (integer): Tokens in the completion
  * `total_tokens` (integer): Total tokens used
  * `prompt_tokens_details` (object | null):
    * `cached_tokens` (integer): Cached prompt tokens
  * `completion_tokens_details` (object | null):
    * `reasoning_tokens` (integer): Tokens used for reasoning
</ResponseField>

## Response (Streaming)

When `stream` is `true`, returns `text/event-stream` with `chat.completion.chunk` objects:

<ResponseField name="id" type="string">
  Unique identifier for the chunk stream.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"chat.completion.chunk"`.
</ResponseField>

<ResponseField name="created" type="integer">
  Unix timestamp of creation.
</ResponseField>

<ResponseField name="model" type="string">
  Model being used.
</ResponseField>

<ResponseField name="choices" type="array">
  Array of delta choices.

  Each choice contains:

  * `index` (integer): Always 0
  * `delta` (object): Incremental content
    * `role` (string | null): Role (only in first chunk)
    * `content` (string | null): Content delta
    * `refusal` (string | null): Refusal delta
    * `tool_calls` (array | null): Tool call deltas
  * `finish_reason` (string | null): Reason when complete
</ResponseField>

<ResponseField name="usage" type="object | null">
  Token usage (only in final chunk when `stream_options.include_usage` is true).
</ResponseField>

## Examples

### Basic Chat Completion

```bash theme={null}
curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'
```

### Streaming Response

```bash theme={null}
curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "Write a haiku about coding"}
    ],
    "stream": true
  }'
```

### Streaming with Usage

```bash theme={null}
curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.2",
    "messages": [
      {"role": "user", "content": "Explain quantum computing"}
    ],
    "stream": true,
    "stream_options": {
      "include_usage": true
    }
  }'
```

### Tool Calling

```bash theme={null}
curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "What is the weather in San Francisco?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "Get current weather for a location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "City name"
              }
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'
```

### Web Search Tool

```bash theme={null}
curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "What are the latest news about AI?"}
    ],
    "tools": [
      {"type": "web_search"}
    ]
  }'
```

### JSON Schema Response Format

```bash theme={null}
curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "user", "content": "Generate a person profile"}
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "person_profile",
        "schema": {
          "type": "object",
          "properties": {
            "name": {"type": "string"},
            "age": {"type": "number"},
            "city": {"type": "string"}
          },
          "required": ["name", "age"]
        },
        "strict": true
      }
    }
  }'
```

### Multi-turn Conversation

```bash theme={null}
curl https://api.example.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "messages": [
      {"role": "system", "content": "You are a helpful math tutor."},
      {"role": "user", "content": "What is 25 * 4?"}
    ]
  }'
```

## Content Type Restrictions

### System and Developer Messages

* Must contain **text-only** content
* Cannot include images, files, or other media types
* Violations return `400` with `invalid_request_error`

### User Messages

Supported content types:

* **Text**: String or `{"type": "text", "text": "..."}`
* **Images**: `{"type": "image_url", "image_url": {"url": "..."}}`
  * Data URLs and HTTP(S) URLs supported
  * Images over 8MB are automatically dropped
* **Files**: `{"type": "file", "file": {...}}`
  * `file_id` is **not supported** and will return error

Unsupported:

* **Audio input**: `input_audio` type returns `400` error

### Assistant Messages

* Can include `content` (text) and/or `tool_calls`
* Tool calls must have valid `id` and `function` with `name`

### Tool Messages

* Must include `tool_call_id` matching a previous assistant tool call
* Content becomes the tool output

## Error Handling

All errors return OpenAI-compatible error envelopes:

```json theme={null}
{
  "error": {
    "message": "Error description",
    "type": "invalid_request_error",
    "code": "error_code",
    "param": "field_name"
  }
}
```

Common error codes:

* `invalid_request_error`: Invalid request parameters
* `model_not_allowed`: API key lacks access to requested model
* `no_accounts`: No upstream accounts available
* `upstream_error`: Upstream service error

For streaming requests, errors are emitted as error chunks followed by `data: [DONE]`.

## Model Restrictions

If your API key has `allowed_models` configured, only those models can be used. Requests for other models return:

```json theme={null}
{
  "error": {
    "message": "This API key does not have access to model 'gpt-5.2'",
    "type": "invalid_request_error",
    "code": "model_not_allowed"
  }
}
```

Check available models at `/v1/models`.