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

# Chat Completions

> POST /v1/chat/completions — a fully OpenAI-compatible chat endpoint

Create a model response based on the conversation context (the messages array).
Every model with chat capability (OpenAI / Claude / Gemini / DeepSeek / Qwen, etc.) can be called through this endpoint.

## Request

### Authentication

```
Authorization: Bearer sk-XXXXXXXXXXXXXXXX
```

### Main parameters

| Field                   | Type             | Required | Description                                                                               |
| ----------------------- | ---------------- | :------: | ----------------------------------------------------------------------------------------- |
| `model`                 | string           |     ✅    | Model ID, e.g. `gpt-5.5`                                                                  |
| `messages`              | array            |     ✅    | Conversation history, each item `{ role, content }`                                       |
| `temperature`           | number           |          | 0-2, default 1. Lower is more deterministic                                               |
| `top_p`                 | number           |          | 0-1, nucleus sampling; use this or temperature, not both                                  |
| `n`                     | integer          |          | How many candidates to generate (default 1)                                               |
| `stream`                | boolean          |          | true enables SSE streaming                                                                |
| `stream_options`        | object           |          | `{ include_usage: true }` appends usage at the end of the stream                          |
| `max_tokens`            | integer          |          | Maximum output tokens (legacy field, replaced by `max_completion_tokens` for some models) |
| `max_completion_tokens` | integer          |          | New field, for o3 / GPT-5                                                                 |
| `stop`                  | string \| array  |          | Stop sequences                                                                            |
| `presence_penalty`      | number           |          | -2 to 2                                                                                   |
| `frequency_penalty`     | number           |          | -2 to 2                                                                                   |
| `logit_bias`            | map              |          | Token bias                                                                                |
| `seed`                  | integer          |          | Reproducibility seed                                                                      |
| `response_format`       | object           |          | `{ type: "json_object" }` or a JSON Schema                                                |
| `tools`                 | array            |          | List of function-calling tools                                                            |
| `tool_choice`           | string \| object |          | `auto` / `required` / `{ type:"function", function:{name:"..."}}`                         |
| `parallel_tool_calls`   | boolean          |          | Whether to allow parallel tool calls                                                      |
| `reasoning_effort`      | string           |          | Reasoning effort for o3 / GPT-5: `low` / `medium` / `high`                                |
| `modalities`            | array            |          | Multimodal output, e.g. `["text","audio"]`                                                |
| `audio`                 | object           |          | Audio output options                                                                      |
| `user`                  | string           |          | End-user identifier (for auditing)                                                        |

### messages structure

```json theme={null}
[
  {"role": "system",    "content": "You are a helpful assistant"},
  {"role": "user",      "content": "Tell a joke"},
  {"role": "assistant", "content": "Why do programmers like the dark? Because there are no bugs."},
  {"role": "user",      "content": [
    {"type": "text", "text": "Describe this image"},
    {"type": "image_url", "image_url": {"url": "https://..."}}
  ]}
]
```

Supported roles: `system` / `user` / `assistant` / `tool` (function return).

## Response

```json theme={null}
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1715750400,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "answer content..."
      },
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 27,
    "completion_tokens": 19,
    "total_tokens": 46,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 }
  },
  "system_fingerprint": "fp_..."
}
```

`finish_reason` possible values: `stop` / `length` / `tool_calls` / `content_filter`.

## Streaming response

With `stream: true`, the server pushes chunks in SSE format:

```
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"delta":{"content":"He"},"index":0}]}

data: {"id":"chatcmpl-...","choices":[{"delta":{"content":"llo"},"index":0}]}

data: {"id":"chatcmpl-...","choices":[{"delta":{},"index":0,"finish_reason":"stop"}]}

data: [DONE]
```

With `stream_options.include_usage: true`, an extra chunk with usage is sent at the end:

```
data: {"id":"chatcmpl-...","choices":[],"usage":{"prompt_tokens":...,"completion_tokens":...}}
```

## Function calling

```json theme={null}
{
  "model": "gpt-5.5",
  "messages": [{"role": "user", "content": "Weather in Shanghai"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get weather",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}
```

In the response:

```json theme={null}
{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc",
        "type": "function",
        "function": {"name": "get_weather", "arguments": "{\"city\":\"Shanghai\"}"}
      }]
    },
    "finish_reason": "tool_calls"
  }]
}
```

After executing the tool, append the result to messages:

```json theme={null}
{"role": "tool", "tool_call_id": "call_abc", "content": "Shanghai is 26°C and clear today"}
```

Call chat completions again to let the model continue answering based on the tool result.

## Reasoning models

For the o3 / GPT-5 series, use `reasoning_effort`:

```json theme={null}
{
  "model": "o3-mini-high",
  "messages": [{"role": "user", "content": "Prove that √2 is irrational"}],
  "reasoning_effort": "high",
  "max_completion_tokens": 4096
}
```

You can also use a suffixed model ID (`o3-mini-low` / `-medium` / `-high`) for the equivalent effect.

## Errors

See [Error codes](/en/api-reference/errors) for common errors.