API v1Updated 2026-09-16

Chat Completions

Drop-in OpenAI-compatible POST /v1/chat/completions endpoint with streaming, function calling, and pass-through parameters.

POST /v1/chat/completions is a drop-in replacement for the OpenAI Chat Completions protocol. Point any OpenAI-compatible client at the gateway base URL and your existing code keeps working — the only change is the model identifier.

Endpoint#

POST/v1/chat/completions

Auth: api-key

Create a chat completion. Responses follow the OpenAI chat.completion object shape, and streaming follows the OpenAI chunk protocol normalized by zrouter (terminator data: [DONE]).

Parameters

modelstringbodyrequired

The model identifier. Use the `<public-name>` value from the Model Catalog — see [Model Catalog](/en/docs/api-reference/models).

messagesarraybodyrequired

The conversation as an ordered array of `{ role, content }` objects. At least one message is required.

streambooleanbodyoptionaldefault: false

Set `true` to receive a Server-Sent Events stream instead of a single JSON response. See [Streaming & SSE](/en/docs/api-reference/streaming).

max_tokensintegerbodyoptional

The maximum number of tokens to generate. Forwarded to the upstream unchanged when provided.

temperaturenumberbodyoptional

Sampling temperature. Forwarded to the upstream unchanged when provided.

top_pnumberbodyoptional

Nucleus sampling. Forwarded to the upstream unchanged when provided.

Request Example

curl -X POST "https://api.zrouter.dev/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<public-name>",
    "messages": [{"role": "user", "content": "Say hello!"}]
  }'

Responses

200Successful completion.

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1720000000,
  "model": "<public-name>",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello!" },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 9, "completion_tokens": 3, "total_tokens": 12 }
}

400`invalid_request` — malformed or invalid body.

401`invalid_api_key` — missing key, wrong key, or two headers with different values.

402`insufficient_balance` — Token Plan and PAYG balance cannot cover the request.

404`model_not_found` — the model identifier does not exist or is hidden.

429`technical_limit` — passthrough of an upstream 429, not a zrouter rate limit.

502`upstream_error` — the upstream provider failed to process the request.

503`overloaded` or `circuit_open` — capacity shed or an open circuit breaker.

Parameters you do not see listed above (for example tool/function-calling fields or response_format) are passed through to the upstream as-is. zrouter does not rewrite the request body beyond the parameters it needs to route, meter, and bill.

Streaming#

Set "stream": true to stream tokens incrementally. The gateway normalizes the upstream stream to the classic OpenAI chunk protocol and terminates it with data: [DONE]. Raw event examples for all three protocols live in Streaming & SSE.