POST /v1/chat/completions

The OpenAI-compatible surface. Point any OpenAI SDK (or OpenAI-compatible client) at https://api.routerplus.com/v1 with your marketplace key and it works — including against Claude models. Every chat model in the catalog is callable from this endpoint no matter which provider serves it; image models answer on POST /v1/images/generations only; the gateway translates requests, streams, and errors between dialects. The Anthropic-native twin of this endpoint is POST /v1/messages.

POST https://api.routerplus.com/v1/chat/completions

Authentication

A missing or invalid key returns 401 with error_type: "auth". Optionally send HTTP-Referer and X-Title to identify your app (content-free attribution).

Request

JSON body, capped at 10 MB (413 request_too_large above that).

A top-level api_key, base_url, connection_id or similar credential or destination field is a 400: keys and endpoints are configured in the console, never sent in a request.

Everything else

The table above is the portable set — it survives translation to any provider. What happens to parameters outside it depends on who serves the request: when the serving provider speaks the OpenAI dialect, the OpenAI chat parameters (response_format, reasoning_effort, seed, user, logprobs, top_logprobs, frequency_penalty, presence_penalty, logit_bias, metadata, store, prediction) reach it as you sent them; when translation to the Anthropic dialect is needed, response_format, reasoning_effort, prediction, audio and modalities are a typed 400 (they change what the model produces), and other unknown parameters are dropped — never silently mutated into something else. Any top-level key outside those sets is dropped and recorded on every route. Every drop is named in the x-tm-dropped-params header; "provider": {"require_parameters": true} turns a drop into a 400 instead. The full tables are on Wire compatibility.

Unsupported content is different from unsupported parameters: it is never dropped, because dropped content would still be billed upstream. A part the model does not take — an image to a model that takes text only, say — is a typed 400 naming the exact field (e.g. messages[0].content[1]), on every route, before anything is billed or sent. On routes that need translation to the Anthropic dialect, images (JPEG, PNG, GIF and WebP) and PDF files are translated; audio parts, video parts, files given by id, other file types and unknown content-part types are a typed 400 naming the field. When the serving provider speaks the OpenAI dialect and the model takes the part, content passes through as sent.

Why n > 1 is rejected

The gateway's normalizer emits exactly one choice. Accepting n: 3 and billing you for a garbled single-choice response would be dishonest, so the request is refused up front:

{
  "error": {
    "code": "invalid_request",
    "message": "n>1 is not supported in v1; request a single choice",
    "type": "invalid_request_error",
    "metadata": { "error_type": "invalid_request" }
  },
  "request_id": "..."
}

Non-streamed response

A standard chat.completion object. On translated responses the id is chatcmpl-<request-id>; when an OpenAI-dialect provider serves the request, the body passes through with the provider's own id. For the /v1/generation?id= audit, use the x-request-id response header — it carries the bare request id on every route.

On a closed dedicated endpoint the body keeps a fixed set of fields on every route: model is the endpoint id, the id is chatcmpl- and the request id without dashes, and provider fields such as system_fingerprint and native_finish_reason are dropped.

{
  "id": "chatcmpl-1c9a7b2e-...",
  "object": "chat.completion",
  "created": 1757000000,
  "model": "claude-sonnet-4-5",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello!" },
      "finish_reason": "stop",
      "native_finish_reason": "end_turn"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 5,
    "total_tokens": 17,
    "prompt_tokens_details": { "cached_tokens": 0, "cache_write_tokens": 0 },
    "cost": 0.000111
  }
}

Usage fields (the billing contract — see Wire compatibility):

finish_reason is one of stop, length, tool_calls, content_filter. On responses translated from an Anthropic-dialect provider, choices[0].native_finish_reason preserves the provider-raw stop reason (e.g. end_turn, stop_sequence) — a documented extension. A model's thinking, when the provider returns it, is in message.reasoning_content.

Streamed response

With stream: true, SSE frames in chat.completion.chunk shape, in a fixed order:

1. 01
   A role-priming delta ({"role":"assistant","content":""}) as soon as the upstream proves alive.
2. 02
   Content deltas: delta.content, delta.reasoning_content (thinking models), and delta.tool_calls fragments addressed by index (id and function.name arrive on each call's first fragment).
3. 03
   A finish chunk with finish_reason set, plus native_finish_reason on translated streams.
4. 04
   A usage chunk (empty choices) — always sent, no stream_options needed:

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","created":1757000000,"model":"claude-haiku-4-5","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":5,"total_tokens":17,"prompt_tokens_details":{"cached_tokens":0,"cache_write_tokens":0},"completion_tokens_details":{"reasoning_tokens":0},"cost":0.000037}}

data: [DONE]

5. 05
   data: [DONE].

When an OpenAI-dialect provider serves the request, its stream is relayed record for record, with usage.cost added to its usage chunk; the shapes above are what a translated stream looks like. On a closed dedicated endpoint each chunk keeps only the fixed set of fields, and a provider's own SSE comment lines are dropped. Full detail on Streaming.

During post-start silences of 15 s or more (slow reasoning models), the gateway emits an SSE comment (: processing) so proxies don't kill an idle-but-healthy stream — spec-ignorable, and your SDK already ignores it.

Errors

Every error uses the OpenAI envelope with a stable error.metadata.error_type (auth, rate_limit, insufficient_quota, model_unavailable, invalid_request, context_overflow, content_policy, upstream_error, gateway_error, ...). A provider's raw error body is never relayed. When a provider rejected the request, the class says so, the message carries the provider's own words (up to 1,000 characters, with keys, account ids and host names removed), and the x-tm-upstream-status header carries its status. A prompt too long for the model is OpenAI's standard 400: error.code is context_length_exceeded, with OpenAI's wording ("This model's maximum context length is M tokens. However, your messages resulted in N tokens. …"), so coding agents compact and retry. Full table with remediations: Errors.

Out-of-credits is the OpenAI-standard 429 insufficient_quota (your SDK already recognizes it), covering an empty balance or a monthly spend cap — cap breaches include the exact UTC reset time in the message and the x-tm-cap-reset header. First trial keys shown after verified sign-in have a 20 RPM limit, and until an organization buys credit its keys together run at 20 RPM; 429 rate_limit carries retry-after.

Response headers

Examples

curl -N https://api.routerplus.com/v1/chat/completions \
  -H "Authorization: Bearer $TM_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","stream":true,"max_tokens":100,"messages":[{"role":"user","content":"Say hello."}]}'

import os
from openai import OpenAI

client = OpenAI(base_url="https://api.routerplus.com/v1", api_key=os.environ["TM_API_KEY"])

resp = client.chat.completions.create(
    model="claude-sonnet-4-5",  # a Claude model over the OpenAI wire — the gateway translates
    max_tokens=200,
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(resp.choices[0].message.content)
print(resp.usage)  # prompt/completion tokens, cache splits, cost (USD)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.routerplus.com/v1",
  apiKey: process.env.TM_API_KEY,
});

const stream = await client.chat.completions.create({
  model: "gpt-4o-mini",
  stream: true,
  messages: [{ role: "user", content: "Count to five." }],
});

for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
  if (chunk.usage) console.log("\n", chunk.usage); // final chunk: tokens, cache splits, cost
}

Model discovery

GET https://api.routerplus.com/v1/models (authenticated) returns the catalog in the OpenAI list shape — one row per model id — and your organization's dedicated endpoints. The public directory with prices and context lengths is https://app.routerplus.com/api/models.json. A model id that is not listed returns 404 model_unavailable naming the id you asked for; if every deployment serving a listed model is cooling down after failures, you get a 503 gateway_error with retry-after: 5 and x-tm-limit-kind: health instead of a fake 404 — retry, don't fix.

See also: POST /v1/messages · Errors · Wire compatibility & billing contract · Quickstart