Completions

Create raw text completions using legacy prompt models with streaming support, token usage tracking, automated failover, and multi-tenant budget controls.

The /v1/completions endpoint provides raw text completion for base models, instruction-tuned models, and legacy completion workloads across provider clouds at exact list price with zero percent (0%) markup. Modern conversational applications typically use Chat Completions, while Completions remains available for code synthesis, text infilling, and deterministic single-prompt tasks.

Preflight evaluates rate limits (RPM/TPM), guardrails, and credit reservations before dispatch (x-nr-guardrails: blocked returns HTTP 400 with $0 spent and $0 held). Emits latency, cost, routing, and cache headers (x-nr-response-cache).

POST https://api.nrouter.ai/v1/completions

Request Parameters

Parameter	Type	Required	Default	Description
`model`	`string`	Yes	—	Model ID (e.g. `gpt-5.4-mini`, `gpt-3.5-turbo-instruct`).
`prompt`	`string` or `string[]`	Yes	—	Prompt text or array of prompt strings.
`max_tokens`	`integer`	No	`16`	Maximum number of tokens to generate.
`temperature`	`number`	No	`1.0`	Sampling temperature between `0.0` and `2.0`.
`top_p`	`number`	No	`1.0`	Nucleus sampling cutoff threshold.
`n`	`integer`	No	`1`	Number of completions to generate per prompt.
`stream`	`boolean`	No	`false`	Stream tokens via Server-Sent Events (SSE).
`logprobs`	`integer`	No	`null`	Return log probabilities for up to 5 most likely tokens.
`echo`	`boolean`	No	`false`	Echo prompt alongside completion.
`stop`	`string` or `string[]`	No	`null`	Up to 4 stop sequences.
`presence_penalty`	`number`	No	`0`	Presence penalty between `-2.0` and `2.0`.
`frequency_penalty`	`number`	No	`0`	Frequency penalty between `-2.0` and `2.0`.
`nrouter_cache`	`boolean`	No	`true`	When `false`, bypasses response cache.
`nrouter_prompt_template_id`	`string`	No	—	Tenant-scoped managed prompt template UUID.
`nrouter_prompt_variables`	`object`	No	—	Key-value variables interpolated into template.

Examples

import { nRouter } from "@nrouter_ai/sdk";
const client = new nRouter({ apiKey: process.env.NROUTER_API_KEY });
const res = await client.completions.create({
  model: "gpt-5.4-mini",
  prompt: "Write a Rust hash function.",
  max_tokens: 128,
});
console.log(res.choices[0].text, client.lastResponse?.cost);

Headers & Errors

Required request headers: Authorization: Bearer sk-nrouter-... and Content-Type: application/json. Optional: x-nr-tags, x-nr-compress. Telemetry: x-nr-request-id, x-nr-latency-ms, x-nr-request-cost, x-nr-cost-status, x-nr-model, x-nr-routing, x-nr-attempts, x-nr-guardrails, x-nr-response-cache. See Chat Completions.

HTTP Status	Error Code	Reason
400 Bad Request	`invalid_request`	Malformed JSON or invalid token bounds.
400 Bad Request	`guardrail_blocked`	Preflight inspection detected prompt injection or policy violation.
401 Unauthorized	`invalid_api_key`	Virtual key missing, expired, or invalid.
402 Payment Required	`insufficient_credits`	Tenant credit balance insufficient for reservation hold.
404 Not Found	`model_not_found`	Model identifier not found or unauthorized for tenant.
429 Too Many Requests	`rate_limit_exceeded`	RPM/TPM ceiling crossed; check `x-nr-limit-source`.
500 / 503 Provider Error	`service_unavailable`	Upstream outage. Moves to fallback only if configured (`nrouter_fallbacks`).

Authorization

NRouterApiKey

AuthorizationBearer <token>

Your nRouter virtual key (sk-nrouter-…). Sent as Authorization: Bearer sk-nrouter-….

In: header

Header Parameters

x-nr-compress?string

Request prompt compression: on to compress eligible prompts, off to skip

Value in

"on"
"off"

x-nr-tags?string

Custom spend and attribution tags (comma-separated key=value pairs)

x-nr-mcp-server?string

Target MCP server ID when routing MCP tool calls or prompts through the gateway

x-nr-client-language?string

Caller SDK runtime language identification (e.g. typescript, python, rust, go)

x-nr-session-id?string

Caller session identifier allowed at edge for grouping related client turns

x-nr-trace?string

Inbound trace detail level override for request lifecycle spans

Value in

"off"
"stages"
"verbose"

x-nr-trace-stages?string

Inbound stage-level trace emission override

Value in

"off"
"stages"
"verbose"

x-nr-trace-id?string

Accepted so a client sending it is not refused; the value is not recorded and not propagated. Every response carries the gateway's own trace ID in this header, never the one sent.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

model*string

Model id (see GET /v1/models).

prompt*string

max_tokens?integer

Range1 <= value

Default16

temperature?number

Range0 <= value <= 2

Default1

nrouter_cache?boolean

Use nRouter's tenant-isolated response cache for buffered text requests. Set false to force provider egress; streams are never cached.

Defaulttrue

nrouter_prompt_template_id?string

Tenant-scoped managed prompt template. The gateway selects its production-pinned version, or the active version when no pin exists.

Formatuuid

nrouter_prompt_variables?

Scalar variables rendered into the managed prompt. Authenticated system variables override conflicting caller values.

nrouter_fallbacks?array<string>

Optional list of up to 4 model names tried in order after the model named in the request, only on an upstream 429, 503 or Anthropic 529, or a connection failure. Replaces the fallback list the organization saved for that model for this call. On nrouter/auto it replaces the fallbacks nrouter/auto would choose (its chosen model is tried first, then these), and an empty list means no fallback; an empty list on any other model is refused.

Items0 <= items <= 4

nrouter_optimize?string

nrouter/auto only: the selection strategy for this one request, overriding the organization's Router Settings strategy. "quality" serves the best model for the task; "cost" serves the lowest list rate among the models fit for the task. Any other value, or the field on another model, is refused with 400 invalid_request.

Value in

"quality"
"cost"

nrouter_guardrails?array<string>

Optional list of guardrail policy IDs or names to enforce for this request.

nrouter_web_search?boolean

Enable gateway-augmented web search grounding.

nrouter_tags?

Custom key-value metadata tags recorded in SpendLogs and trace metadata for cost attribution.

Response Body

`application/json`

curl -X POST "https://example.com/v1/completions" \  -H "Content-Type: application/json" \  -d '{    "model": "gpt-5.4-mini",    "prompt": "Write a haiku about cloud infrastructure.",    "max_tokens": 64  }'

{  "id": "cmpl-abc123",  "object": "text_completion",  "model": "gpt-4o-mini",  "choices": [    {      "text": " there!",      "index": 0,      "finish_reason": "stop"    }  ],  "usage": {    "prompt_tokens": 2,    "completion_tokens": 2,    "total_tokens": 4  }}

Request Parameters

Examples

Headers & Errors

Authorization

Header Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

402application/json

404application/json

405application/json

413application/json

415application/json

429application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`