> 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`  | `/api/v1/chat/models`      | List all available models                              |
| ------ | -------------------------- | ------------------------------------------------------ |
| `POST` | `/api/v1/chat/completions` | Create chat completions (streaming, tools, multimodal) |

{% hint style="info" %}
Gemini 2.5 Flash and Gemini 2.5 Pro retire on December 1, 2026. See [Models](https://docs.qolaba.ai/api-platform/openai-compatible-chat/models.md) for the replacement models and the full deprecation schedule.
{% endhint %}

## 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. See [Models](https://docs.qolaba.ai/api-platform/openai-compatible-chat/models.md) for the available models, or call `GET /api/v1/chat/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-4-hydrogen",
  "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-4-hydrogen",
  "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-4-hydrogen",
        "credit": 0.25,
        "cost": 0.001244
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}

#### Error Responses

| Status | Condition                                                                                                                                                 |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `model` is missing                                                                                                                                        |
| `400`  | `model` is not a supported Gemini model — code `model_not_supported` (see [Models](https://docs.qolaba.ai/api-platform/openai-compatible-chat/models.md)) |
| `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                                                                                                                                     |
