# POST /chat/completions

Создание chat completion, с потоком или без. Тело запроса, ответ и коды ответов.

`POST /api/v1/chat/completions` (нужен API-ключ)

Создает chat completion в формате OpenAI. Полный список полей тела и что делает каждое — в разделе [Параметры](/docs/ru/parameters). Машиночитаемый контракт: [openapi.yaml](/docs/openapi.yaml).

## Тело запроса

| Поле                                  | Тип       |                                                                         |
| ------------------------------------- | --------- | ----------------------------------------------------------------------- |
| `model`                               | string    | ID модели. Обязательно, если не указан `models`.                        |
| `models`                              | string\[] | Резервные модели, которые пробуются после `model`.                      |
| `messages`                            | object\[] | Обязательно. Диалог.                                                    |
| `stream`                              | boolean   | Server-sent events вместо одного JSON.                                  |
| `max_tokens`, `max_completion_tokens` | integer   | Лимит ответа, от 1 до 65536; 4096, если не указан.                      |
| `tools`, `tool_choice`                |           | Вызов инструментов.                                                     |
| `response_format`                     | object    | Режим JSON или JSON Schema.                                             |
| `reasoning`                           | object    | Уровень и бюджет рассуждений.                                           |
| `provider`                            | object    | `only`, `ignore`, `order`, `allow_fallbacks`, `zdr`, `data_collection`. |
| любое другое поле                     |           | Передается провайдеру.                                                  |

## Ответ

Без `stream`: объект `chat.completion`.

| Поле                             | Тип     |                                                                                                                                                          |
| -------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                             | string  | ID генерации, `gen-<uuid>`.                                                                                                                              |
| `object`                         | string  | `chat.completion`                                                                                                                                        |
| `created`                        | integer | Время в формате Unix.                                                                                                                                    |
| `model`                          | string  | Модель, которая ответила.                                                                                                                                |
| `provider`                       | string  | Провайдер, на котором работает модель (глобальный регион), или `Russia`.                                                                                 |
| `choices[].message`              | object  | `role`, `content`, `tool_calls`, `reasoning`.                                                                                                            |
| `choices[].finish_reason`        | string  | `stop`, `length`, `tool_calls`, `content_filter` или `error`.                                                                                            |
| `choices[].native_finish_reason` | string  | Собственное значение провайдера.                                                                                                                         |
| `usage`                          | object  | `prompt_tokens`, `completion_tokens`, `total_tokens`, `cost` (PnP), `prompt_tokens_details.cached_tokens`, `completion_tokens_details.reasoning_tokens`. |

С `"stream": true`: `text/event-stream` из событий `chat.completion.chunk`, комментарии keep-alive, финальный chunk с `usage`, затем `data: [DONE]`. Подробнее — в разделе [Потоковая передача](/docs/ru/streaming).

## Заголовки

| Заголовок         |                                                               |
| ----------------- | ------------------------------------------------------------- |
| `X-Request-Id`    | В каждом ответе.                                              |
| `X-Generation-Id` | В потоковых ответах; в ответе без потока ID находится в `id`. |

## Коды ответов

`200`, `400`, `401`, `402`, `403`, `409`, `413`, `422`, `429`, `502`, `503`, `504`: см. [Ошибки](/docs/ru/errors#коды-ответов).

## Пример

```bash
curl https://router.nodul.ru/api/v1/chat/completions \
  -H "Authorization: Bearer $NODUL_ROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "google/gemma-3-4b-it", "messages": [{"role": "user", "content": "Hello"}], "max_tokens": 100}'
```

Попробуйте запросы со своим ключом в песочнице на странице **API** вашего пространства в кабинете.