# Создать chat completion

`POST /v1/chat/completions`

> OpenAI-совместимая генерация текста: `model` + `messages`, авторизация — `Authorization: Bearer <API-ключ>`. Принимаются оба cap-поля (`max_tokens` и `max_completion_tokens`) — шлюз сам нормализует под семейство модели (openai/* получает `max_completion_tokens`, остальные — `max_tokens`; оба поля с разными значениями → 400). Стриминг — `stream: true` (SSE); финальный чанк с `usage` приходит только при `stream_options.include_usage: true`. Списание с баланса — после успешного ответа провайдера по фактическому usage, при ошибке апстрима денег не берём; лимит — 60 запросов в минуту на аккаунт (общий bucket для text/images/video/audio).

Авторизация: заголовок `Authorization: Bearer <API-ключ>` (ключ sk-aiagg-… из личного кабинета). Base URL: `https://api.trackly.one/v1`.

Веб-версия: https://ai.trackly.one/developers/docs/reference/chat-completions · Индекс документации: https://ai.trackly.one/llms.txt

## Тело запроса (ChatCompletionRequest)

Content-Type: `application/json`.

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `frequency_penalty` | `number \| null` | нет | — |
| `logprobs` | `boolean \| null` | нет | — |
| `max_completion_tokens` | `integer \| null` | нет | — |
| `max_tokens` | `integer \| null` | нет | — |
| `messages` | `array<ChatMessage>` | да | — |
| `model` | `string` | да | — |
| `n` | `integer \| null` | нет | — |
| `presence_penalty` | `number \| null` | нет | — |
| `response_format` | `object \| null` | нет | — |
| `seed` | `integer \| null` | нет | — |
| `stop` | `string \| array<string> \| null` | нет | — |
| `stream` | `boolean` | нет | По умолчанию: false |
| `stream_options` | `StreamOptions \| null` | нет | — |
| `temperature` | `number \| null` | нет | — |
| `tool_choice` | `string \| object \| null` | нет | — |
| `tools` | `array<object> \| null` | нет | — |
| `top_p` | `number \| null` | нет | — |
| `user` | `string \| null` | нет | — |

## Схема ChatMessage

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `content` | `string \| array<ContentPart> \| null` | нет | — |
| `name` | `string \| null` | нет | — |
| `role` | `"system" \| "user" \| "assistant" \| "tool" \| "developer"` | да | — |

## Схема ContentPart

Часть multimodal-сообщения — текст, картинка, аудио и т.д.

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `image_url` | `object \| null` | нет | — |
| `text` | `string \| null` | нет | — |
| `type` | `string` | да | — |

## Схема StreamOptions

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `include_usage` | `boolean` | нет | По умолчанию: false |

## Схема ChatCompletionResponse

Ответ от провайдера в non-streaming режиме.

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `choices` | `array<Choice>` | да | — |
| `created` | `integer` | да | — |
| `id` | `string` | да | — |
| `model` | `string` | да | — |
| `object` | `"chat.completion"` | нет | По умолчанию: "chat.completion" |
| `usage` | `Usage` | да | — |

## Схема Choice

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `finish_reason` | `string \| null` | нет | — |
| `index` | `integer` | да | — |
| `message` | `ChatMessage \| null` | нет | — |

## Схема Usage

| Поле | Тип | Обязательное | Описание |
| --- | --- | --- | --- |
| `completion_tokens` | `integer` | да | — |
| `prompt_tokens` | `integer` | да | — |
| `total_tokens` | `integer` | да | — |

## Ответы

| Код | Описание | Схема |
| --- | --- | --- |
| 200 | Успешный ответ | `ChatCompletionResponse` |
| 422 | Ошибка валидации тела запроса или параметров | — |

## Пример запроса

```bash
curl https://api.trackly.one/v1/chat/completions \
  -H "Authorization: Bearer $TRACKLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-mini",
    "messages": [
      { "role": "system", "content": "Отвечай кратко и по-русски" },
      { "role": "user", "content": "Объясни, что такое эмбеддинги, в двух абзацах" }
    ],
    "temperature": 0.7,
    "max_completion_tokens": 512
  }'
```

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-aiagg-...",
    base_url="https://api.trackly.one/v1",
)

resp = client.chat.completions.create(
    model="openai/gpt-5-mini",
    messages=[
        {"role": "system", "content": "Отвечай кратко и по-русски"},
        {"role": "user", "content": "Объясни, что такое эмбеддинги, в двух абзацах"},
    ],
    temperature=0.7,
    max_completion_tokens=512,
)
print(resp.choices[0].message.content)
print(resp.usage)  # prompt/completion/total_tokens
```

```javascript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-aiagg-...",
  baseURL: "https://api.trackly.one/v1",
});

const resp = await client.chat.completions.create({
  model: "openai/gpt-5-mini",
  messages: [
    { role: "system", content: "Отвечай кратко и по-русски" },
    { role: "user", content: "Объясни, что такое эмбеддинги, в двух абзацах" },
  ],
  temperature: 0.7,
  max_completion_tokens: 512,
});
console.log(resp.choices[0].message.content);
console.log(resp.usage);
```

## Пример ответа

```json
{
  "id": "chatcmpl-9f4c2a7b1d",
  "object": "chat.completion",
  "created": 1752395112,
  "model": "openai/gpt-5-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Эмбеддинги — это числовые векторы, в которые модель…"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 31,
    "completion_tokens": 208,
    "total_tokens": 239
  }
}
```