POST https://api.nanorouter.ai/v1/chat/completions
Body
string
default:"gpt-5.6-terra"
One of the ids from
GET /v1/models. An unknown name
is a 404, not a fallback.array
required
Non-empty. Each entry needs a
role of system, developer, user,
assistant, or tool.content must be a string or an array of {"type": "text", "text": "…"}
parts. Image and audio parts are refused.Leading system / developer messages become the model’s instructions;
later ones keep their position in the conversation. An assistant message
may carry tool_calls; a tool message requires tool_call_id.integer
The most output the model may write. Clamped to the model’s ceiling, and
defaults to that ceiling when you leave it out — see Pricing.
Your hold is priced at a fraction of this, not all of it, because almost
no response runs to its limit. Anything above the hold is billed from your
credit when the request settles, so the bill is the same either way — a
smaller hold just means a small balance goes further.
object
{"include_usage": true} appends a final chunk carrying token counts.array
Standard OpenAI function definitions. Calls for your tools come back to you
to run, as they would from OpenAI.You can combine them with the router’s built-ins (
web_search, web_fetch)
— the router answers its own and returns yours. A turn that calls one of yours
ends there, since only you can answer it.string | object
default:"auto"
auto, none, required, or {"type": "function", "function": {"name": "…"}}.boolean
Passed upstream when set.
object
{"type": "text"}, {"type": "json_object"}, or
{"type": "json_schema", "json_schema": {"name": "…", "schema": {…}, "strict": true}}.Any other type is a 400.string
default:"low"
none · minimal · low · medium · high · xhigh.Defaults to low because the upstream’s own default spends seconds thinking
before the first token on trivial prompts — and reasoning is billed as output
tokens.Reasoning summaries stream as delta.reasoning_content.number
Passed upstream when set.
string
Truncated to 128 characters. When absent the router sets a per-request key of
its own, so multi-round tool requests hit the upstream prompt cache.
boolean
default:"false"
Non-standard. Opt in — set The TypeScript SDK has no Or with plain
true to let the model search the web. Off
unless you ask, because a search is billed per call. Requires a configured
provider. See Web search.With the OpenAI Python SDK, non-standard fields go through extra_body:extra_body, so pass them inline and widen the
argument — the fields reach the wire either way:fetch, where they are simply two more keys in the body.boolean
default:"false"
Non-standard. Opt in, same as
web_search. Lets the model fetch a URL and
read the page. Fetched content is re-sent on every later round, so it is
billed as input tokens each time.n must be 1 or absent. n > 1 is a 400.top_p, presence_penalty, frequency_penalty, seed, logprobs, stop,
logit_bias and user are accepted by the parser but not forwarded
upstream. Do not rely on them taking effect.Response
finish_reason is stop, length, tool_calls, or content_filter.
length means the answer was cut short by a budget — usually your max_tokens,
but also the router’s own tool-round budget on a turn that kept searching
instead of answering (see Web search). Either way the text
you got is what there is; raising max_tokens only helps in the first case.
Headers
string
The ledger row for this call. Resolve it at
GET /api/requests/{id} for the
settled cost, the token counts, and the inference-versus-search split.string
What was held up front, in atomic USDC — 6 decimal places, so
2400 is
$0.0024.string
What it actually cost. Non-streaming responses only, and only when the
response finishes inside 45 seconds — on a stream the figure is not known
until the last token, and on a slow buffered request the keepalive has already
committed the headers. Absent in both cases.
Errors
The envelope is OpenAI’s:Full error reference
What each one means and whether to retry.