# Chat completions

Запрос и ответ POST /api/v1/chat/completions, сообщения и роли, причины завершения.

У роутера один эндпоинт генерации — `POST /api/v1/chat/completions` в формате OpenAI Chat Completions. Форматы `prompt` и `input` не поддерживаются: передавайте `messages`.

## Запрос

```json
{
  "model": "google/gemma-3-4b-it",
  "messages": [
    { "role": "system", "content": "You answer in one sentence." },
    { "role": "user", "content": "What is a router?" }
  ],
  "max_tokens": 200,
  "temperature": 0.7
}
```

- `model` — ID модели из [каталога](/models). Вместо одной модели можно передать список резервных моделей в `models`, см. [Модели и маршрутизация](/docs/ru/models-and-routing).
- `messages` — непустой массив; у каждого сообщения должна быть `role`.
- Все остальные поля описаны в разделе [Параметры](/docs/ru/parameters).

## Сообщения и роли

| Роль        | Назначение                                                                                                                 |
| ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| `system`    | Инструкции для модели. Некоторые модели также принимают `developer`.                                                       |
| `user`      | Сообщение пользователя: текст или массив частей с изображениями и файлами, см. [Изображения и файлы](/docs/ru/multimodal). |
| `assistant` | Предыдущие ответы модели, включая ее `tool_calls`.                                                                         |
| `tool`      | Результат вызова инструмента с `tool_call_id`, на который он отвечает. См. [Вызов инструментов](/docs/ru/tool-calling).    |

API не хранит состояние: передавайте весь диалог в каждом запросе. Все, что вы отправляете, оплачивается как входные токены.

## Ответ

```json
{
  "id": "gen-5d0c3b6e-…",
  "object": "chat.completion",
  "created": 1793178000,
  "model": "google/gemma-3-4b-it",
  "provider": "Google",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "native_finish_reason": "STOP",
      "message": { "role": "assistant", "content": "A router forwards each request to a model that can serve it." }
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 14,
    "total_tokens": 38,
    "cost": 0.0000146,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 }
  }
}
```

| Поле         | Значение                                                                                           |
| ------------ | -------------------------------------------------------------------------------------------------- |
| `id`         | ID генерации. По нему запрос можно найти через `GET /api/v1/generation?id=…` или в логах кабинета. |
| `model`      | Модель, которая ответила. Со списком `models` это может быть резервная модель.                     |
| `provider`   | Где размещена модель: провайдер в регионе Глобальный, `Russia` в регионе Россия.                   |
| `usage.cost` | Стоимость запроса в PnP.                                                                           |

## Причины завершения

`finish_reason` нормализован; `native_finish_reason` сохраняет исходное значение провайдера (только в ответах без потока).

| Значение         | Что значит                                                                                   |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `stop`           | Модель закончила ответ или встретила стоп-последовательность.                                |
| `length`         | Ответ достиг `max_tokens` (4096, если вы не задали значение) или лимита модели.              |
| `tool_calls`     | Модель хочет вызвать инструменты.                                                            |
| `content_filter` | Провайдер отфильтровал ответ.                                                                |
| `error`          | Генерация прервалась на середине; см. [Потоковый ответ](/docs/ru/streaming#ошибки-в-потоке). |

## Потоковый ответ

Добавьте `"stream": true`, чтобы получать ответ по мере генерации в виде server-sent events. См. [Потоковый ответ](/docs/ru/streaming).