POST /chat/completions

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

POST/api/v1/chat/completionsAPI key

Creates a chat completion in the OpenAI format. The full list of body fields with what each does: Parameters. The machine-readable contract: 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.

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.

Example

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.