Chat completions

Request fields, message roles and response shape.

POST /v1/chat/completions

Requires an inference key, account access and sufficient balance and key budget. uRouter validates the request, reserves a maximum cost and settles the actual charge. Accounts without access receive 503; invalid keys receive 401.

Minimal body

Requires an account with paid inference access.

{
  "model": "MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "Explain what an API is in one sentence."
    }
  ],
  "max_tokens": 256
}

Fields

Use the exact model ID. These are schema bounds, not a guarantee that every model accepts every value. Unknown fields are rejected.

Fields
Field	Type / bounds	Purpose
`model`	string, 1–150 characters	Required public model ID.
`messages`	array, 1–500 items	Required conversation history.
`max_tokens` / `max_completion_tokens`	integer, 1–131072	Output ceiling. Use one; model-specific limits can be lower.
`temperature`	number, 0–2	Sampling temperature.
`top_p`	number, 0–1	Nucleus sampling.
`stop`	string or up to 8 strings	Each string up to 200 characters.
`stream`	boolean	Request event-stream output.
`stream_options.include_usage`	boolean	Request usage in the stream.
`tools`, `tool_choice`	function definitions / selection	See Parameters & tools.
`response_format`	text, json_object or json_schema	See Parameters & tools.
`reasoning_effort`, `reasoning`	model-dependent	See Parameters & tools.

Messages

Each message has role and content. Content is a string, null, or 1–100 text/image parts. Text strings are limited to 1,000,000 characters in the schema; token context limits still apply.

Messages
Role	Use
`system`, `developer`	Instructions. Model-specific handling must be checked.
`user`	User input, optionally with image parts.
`assistant`	Prior output, including `tool_calls` when needed.
`tool`	Tool result with the matching `tool_call_id`.

Completion shape

The response uses choices[].message and finish_reason, with optional token usage. Tool calls may have null text content. A uRouter accounting extension records request_id, nullable cost_usd, and accounting (pending or settled).

Request accounting