Completions

The /v1/completions endpoint provides raw text completion for base models, instruction-tuned foundation models, and legacy completion workloads across all major provider clouds. While modern conversational workloads predominantly use Chat Completions, the Completions API remains essential for code synthesis, text infilling, unstructured generation, and deterministic prompt completion.

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

Architectural Role & Lifecycle

When a prompt is dispatched to /v1/completions, nRouter runs the request through its unified preflight engine:

1. Phase 1: In-Memory Validation: Verifies the virtual key hash (sk-nrouter-...), tenant organization membership, and model access policies.
2. Phase 2: Rate Limits & Token Ceilings: Evaluates requests-per-minute (RPM) and tokens-per-minute (TPM) sliding windows.
3. Phase 3: Content Moderation & Prompt Injection Scoring: Evaluates the input prompt against safety classifiers. If content violates policy, the request is halted with HTTP 400 (x-nr-guardrails: blocked).
4. Phase 4: Credit Reservation: Calculates the upper-bound token cost (input_tokens + max_tokens) and places an atomic hold on organization credits. Blocked requests never incur holds or spend.
5. Execution & Streaming Settlement: Dispatches the prompt to the selected provider or serves the response from the tenant cache (x-nr-response-cache: hit). Streaming requests commit exact spend upon receiving the final chunk.

Request Parameters

The request body must be a JSON object:

Request & Response Headers

Inbound Request Headers

Outbound Response Headers

SDK Code Examples

import { nRouter } from "@nrouter_ai/sdk";

const client = new nRouter({
  apiKey: process.env.NROUTER_API_KEY,
});

const completion = await client.completions.create({
  model: "gpt-5.4-mini",
  prompt: "Write a high-performance Rust function to calculate SHA-256 hashes.",
  max_tokens: 512,
  temperature: 0.2,
});

console.log(completion.choices[0].text);
console.log(`Tokens: ${completion.usage.total_tokens}`);
console.log(`Cost: \$${client.lastResponse?.cost}`);

Error Handling & Status Codes

{
  "error": {
    "type": "gateway_error",
    "message": "The requested max_tokens exceeds model maximum context ceiling.",
    "code": "max_output_tokens_too_large"
  }
}

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  }}