POST https://api.nanorouter.ai/v1/chat/completions

Generates a completion. Requires an API key; a Privy session will not work here.
The request body is capped at 2 MB.

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.
boolean
default:"false"
Server-Sent Events, terminated by data: [DONE]. See Streaming.
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.
Non-standard. Opt in — set 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:
The TypeScript SDK has no extra_body, so pass them inline and widen the argument — the fields reach the wire either way:
Or with plain 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.
All three are exposed via CORS, so browser JavaScript can read them.

Errors

The envelope is OpenAI’s:

Full error reference

What each one means and whether to retry.