> For the complete documentation index, see [llms.txt](https://docs.qolaba.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.qolaba.ai/api-platform/openai-compatible-chat.md).

# OpenAI-Compatible Chat

OpenAI-compatible chat completions endpoint. Supports both standard (JSON) and streaming (SSE) responses. Rate-limited per API key.

**Supported endpoints**

| `GET`  | `/v1/chat/models`          | List all available models                              |
| ------ | -------------------------- | ------------------------------------------------------ |
| `GET`  | `/v1/chat/models/{model}`  | Retrieve a specific model                              |
| `POST` | `/api/v1/chat/completions` | Create chat completions (streaming, tools, multimodal) |

## Chat Completions

**POST** `/api/v1/chat/completions`

**Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

**Body**

| Parameter        | Type               | Required | Description                                                                                                                                                                                                               |
| ---------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`          | `string`           | **Yes**  | The model ID to use for completion. Use `GET /api/v1/chat/models` to list available models.                                                                                                                               |
| `messages`       | `array`            | **Yes**  | Ordered list of messages forming the conversation. Each object must have a `role` (`"system"`, `"user"`, or `"assistant"`) and a `content` field (string or structured content array). Must contain at least one message. |
| `stream`         | `boolean`          | No       | If `true`, the response is streamed as Server-Sent Events (SSE). Each event is a `data: {...}` line; the stream ends with `data: [DONE]`. Defaults to `false`.                                                            |
| `temperature`    | `number`           | No       | Sampling temperature between `0` and `2`. Higher values produce more random output; lower values are more deterministic. Defaults to `1`.                                                                                 |
| `max_tokens`     | `integer`          | No       | Maximum number of tokens to generate in the response. Must be a positive integer. If omitted, the model's default limit applies.                                                                                          |
| `tool_choice`    | `string \| object` | No       | Controls which tool (if any) the model calls. Accepts `"none"`, `"auto"`.                                                                                                                                                 |
| `stream_options` | `object`           | No       | Additional options for streaming. Set `{ "include_usage": true }` to receive a final SSE chunk containing token usage data. Automatically enabled when `stream: true`.                                                    |

#### Request

```json
{
  "model": "google/gemini-2.5-flash",
  "messages": [
    {
      "role": "user",
      "content": "What is the capital of France?"
    }
  ],
  "stream": false
}
```

#### Response (non-streaming)

{% tabs %}
{% tab title="200" %}

```json
{
  "id": "chatcmpl-4dd9fded095b4d86bceed1e91042a",
  "object": "chat.completion",
  "created": 1774095579,
  "model": "google/gemini-2.5-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Paris."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "total_credit": 0.25,
    "total_cost": 0.0012441,
    "breakdown": {
      "model": {
        "model": "google/gemini-2.5-flash",
        "credit": 0.25,
        "cost": 0.001244
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Error Responses

| Status | Condition                                     |
| ------ | --------------------------------------------- |
| `400`  | `model` is missing                            |
| `400`  | `messages` is missing, not an array, or empty |
| `400`  | `temperature` is outside `0–2`                |
| `400`  | `top_p` is outside `0–1`                      |
| `400`  | `max_tokens` is not a positive integer        |
| `400`  | `stop` array contains more than 4 sequences   |
| `429`  | Rate limit exceeded                           |
| `504`  | Request timed out (3-minute upstream limit)   |
| `502`  | Upstream provider error or invalid response   |
| `500`  | Internal server error                         |