# POST /chat/completions

Create a chat completion, streamed or not. The request body, the response and the status codes.

`POST /api/v1/chat/completions` (requires an API key)

Creates a chat completion in the OpenAI format. The full list of body fields with what each does: [Parameters](/docs/en/parameters). The machine-readable contract: [openapi.yaml](/docs/openapi.yaml).

## Request body

| Field                                 | Type      |                                                                         |
| ------------------------------------- | --------- | ----------------------------------------------------------------------- |
| `model`                               | string    | Model id. Required unless `models` is given.                            |
| `models`                              | string\[] | Fallback models, tried after `model`.                                   |
| `messages`                            | object\[] | Required. The conversation.                                             |
| `stream`                              | boolean   | Server-sent events instead of one JSON.                                 |
| `max_tokens`, `max_completion_tokens` | integer   | Output limit, 1 to 65536; 4096 when absent.                             |
| `tools`, `tool_choice`                |           | Tool calling.                                                           |
| `response_format`                     | object    | JSON mode or JSON Schema.                                               |
| `reasoning`                           | object    | Reasoning effort and budget.                                            |
| `provider`                            | object    | `only`, `ignore`, `order`, `allow_fallbacks`, `zdr`, `data_collection`. |
| any other field                       |           | Passed to the provider.                                                 |

## Response

Without `stream`: a `chat.completion` object.

| Field                            | Type    |                                                                                                                                                          |
| -------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                             | string  | Generation id, `gen-<uuid>`.                                                                                                                             |
| `object`                         | string  | `chat.completion`                                                                                                                                        |
| `created`                        | integer | Unix time.                                                                                                                                               |
| `model`                          | string  | The model that answered.                                                                                                                                 |
| `provider`                       | string  | The hosting provider (Global) or `Russia`.                                                                                                               |
| `choices[].message`              | object  | `role`, `content`, `tool_calls`, `reasoning`.                                                                                                            |
| `choices[].finish_reason`        | string  | `stop`, `length`, `tool_calls`, `content_filter` or `error`.                                                                                             |
| `choices[].native_finish_reason` | string  | The provider's own value.                                                                                                                                |
| `usage`                          | object  | `prompt_tokens`, `completion_tokens`, `total_tokens`, `cost` (PnP), `prompt_tokens_details.cached_tokens`, `completion_tokens_details.reasoning_tokens`. |

With `"stream": true`: `text/event-stream` of `chat.completion.chunk` events, keep-alive comments, a final chunk with `usage`, then `data: [DONE]`. See [Streaming](/docs/en/streaming).

## Headers

| Header            |                                                                    |
| ----------------- | ------------------------------------------------------------------ |
| `X-Request-Id`    | On every response.                                                 |
| `X-Generation-Id` | On streamed responses; a non-streamed response has the id in `id`. |

## Status codes

`200`, `400`, `401`, `402`, `403`, `409`, `413`, `422`, `429`, `502`, `503`, `504`: see [Errors](/docs/en/errors#status-codes).

## Example

```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}'
```

Try requests with your key in the playground on the **API** page of your space in the cabinet.