Chat completions

The OpenAI-compatible chat endpoint. Point any OpenAI SDK or client at https://demo-api.routerplus.com/v1 with your RouterPlus key, and call any chat model in the catalog, Claude models included. The gateway translates requests, streams and errors between provider dialects.

Image models answer on POST /v1/images/generations only. The Anthropic-native endpoint is POST /v1/messages.

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

Examples

curl -N https://dev2-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://demo-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://demo-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
}

The Python and TypeScript examples use the official openai SDK with only the base URL changed.

Authentication

A missing or invalid key returns 401 with error_type: "auth". To identify your app, send HTTP-Referer and X-Title. They carry no content.

Request

The body is JSON, at most 10 MB (413 request_too_large above that).

A top-level api_key, base_url, connection_id or other credential or destination field is a 400. You set keys and endpoints in the console, never in a request.

Everything else

The table above is the portable set: it works on any provider. Other parameters depend on the dialect of the provider that serves the request:

• Any other top-level key is dropped and recorded on every route.
• The x-tm-dropped-params header names every drop.
• "provider": {"require_parameters": true} turns a drop into a 400.
• The full tables are on Wire compatibility.

Content parts

The gateway never drops content, because the provider would still bill for it. A part the model does not take is a typed 400 that names the field (for example messages[0].content[1]), on every route, before anything is billed or sent. An image to a text-only model is one such case.

• On an OpenAI-dialect provider, a part that the model takes passes through as sent.
• On a route translated to the Anthropic dialect (Claude), the gateway translates an image_url part (a JPEG, PNG, GIF or WebP data URL, or an http(s) URL) and a file part with a PDF data URL.
• On those routes, audio parts, video parts, files given by id, other file types and unknown part types are a typed 400 that names the field.

Why n > 1 is rejected

The gateway returns one choice. It refuses n above 1 before dispatch, so you never pay for fewer choices than you asked for:

{
  "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 a translated response, id is chatcmpl-<request-id>.
• On an OpenAI-dialect provider, the body passes through with the provider's own id, keeping OpenAI's fields and the extensions below only. Fields a provider adds of its own (its cost, its token accounting, its host's name) are dropped. The message passes as the model wrote it (what an answer keeps).
• model names the model you asked for, also when the provider knows it under another 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, 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 a response translated from an Anthropic-dialect provider, choices[0].native_finish_reason keeps the provider's raw stop reason (for example end_turn, stop_sequence). When the provider returns the model's thinking, it is in message.reasoning_content.

Streamed response

With stream: true, the gateway sends SSE frames in chat.completion.chunk shape, in this order:

1. 01
   A role delta ({"role":"assistant","content":""}) as soon as the provider answers.
2. 02
   Content deltas: delta.content, delta.reasoning_content (thinking models), and delta.tool_calls fragments addressed by index. The 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 with empty choices. It is always sent, without stream_options:

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].

• These are the shapes of a translated stream.
• On an OpenAI-dialect provider, the gateway relays the stream record for record and adds usage.cost to its usage chunk. Each chunk keeps OpenAI's fields only and names the model you asked for.
• On a closed dedicated endpoint, each chunk keeps only the fixed set of fields, and the provider's own SSE comment lines are dropped.
• When a started stream is silent for 15 s or more (slow reasoning models), the gateway sends an SSE comment (: processing) so that proxies keep the stream open. SDKs ignore it.
• See Streaming for the full detail.

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, ...). Errors has the full table with fixes.

• The gateway never relays a provider's raw error body. When a provider rejected the request, the class says so. The message has the provider's own words (up to 1,000 characters, without keys, account ids and host names), and the x-tm-upstream-status header has 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.
• Out of credits is the OpenAI-standard 429 insufficient_quota, which your SDK recognizes. It covers an empty balance or a monthly spend cap. On a cap breach, the message and the x-tm-cap-reset header give the UTC reset time.
• First trial keys, shown after verified sign-in, have a 20 RPM limit. Until an organization buys credit, all its keys together run at 20 RPM. The 429 rate_limit carries retry-after.

Response headers

Model discovery

GET https://demo-api.routerplus.com/v1/models (authenticated) returns the catalog in the OpenAI list shape, one row per model id, plus your organization's dedicated endpoints. The public directory with prices and context lengths is https://demo.routerplus.com/api/models.json.

• A model id that is not listed returns 404 model_unavailable with the id you asked for.
• If every deployment of a listed model is cooling down after failures, you get a 503 gateway_error with retry-after: 5 and x-tm-limit-kind: health. Retry the same request.

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