Chat Completions format

Generates a model reply from the conversation history, with streaming and non-streaming responses, image input and tool calls. It is compatible with the OpenAI Chat Completions API: the official OpenAI SDKs and most OpenAI-compatible applications work once you set the Base URL to https://api.lyrouter.com/v1. The same model may be served by a channel that speaks the OpenAI-compatible protocol or the Anthropic protocol; the gateway converts requests and responses automatically, and this page also explains which parameters change during conversion.

Authentication

Send your API key in a request header:

Authorization: Bearer <API Key>

Bearer is case-sensitive. You can use x-api-key: <API Key> instead; when both are present, only Authorization is read. Create API keys on the workspace's API Keys page. Your API key is used only to authenticate with LYRouter and is never forwarded to the upstream provider. See Base URLs and authentication.

Headers

Request body

Other parameters not listed in the table are forwarded unchanged to OpenAI-compatible channels; whether they take effect depends on the model.

Structure of messages

Each message has a role and content:

content can be written in two ways. Write plain text directly as a string; to include images, use an array of content blocks:

{
  "role": "user",
  "content": [
    { "type": "text", "text": "What is in this image?" },
    { "type": "image_url", "image_url": { "url": "https://example.com/cat.jpg" } }
  ]
}

• image_url.url can be a publicly accessible https:// URL or Base64 data in the form data:image/png;base64,<data>.
• The model must support image input; text-only models return 400 This model accepts text input only. Use the "Input modalities" filter in the model marketplace to find suitable models; see Multimodal capabilities.
• Anthropic-protocol channels convert only text blocks and image blocks; other content blocks such as input_audio and file work only on OpenAI-compatible channels.

Reasoning parameters

The three reasoning parameters follow different providers' conventions. The gateway keeps or removes them according to the provider that actually serves the request, and does not convert one into another (requests to Anthropic-protocol channels are converted to thinking, as the table shows):

• The provider that served the request is shown in "Provider" in the request log details. When the same model has several sources, verify for each source whether the reasoning parameters take effect.
• When thinking is on for an Anthropic-protocol channel, the upstream requires max_tokens to be greater than budget_tokens. The gateway does not adjust these parameters; if the requirement is not met, the upstream returns 400.
• When a tool call is forced (tool_choice is "required" or a specified function) and the request has no enable_thinking / thinking_budget, Alibaba Cloud Model Studio channels automatically get enable_thinking: false, because these upstreams do not accept forced tool calls in thinking mode.
• The OpenAI Python SDK does not define enable_thinking or thinking_budget; pass them in extra_body, for example extra_body={"enable_thinking": False}. In the Node.js SDK, put them directly in the request parameters.

Request examples

curl https://api.lyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [
      {"role": "system", "content": "You are a concise assistant."},
      {"role": "user", "content": "Introduce LYRouter in one sentence."}
    ],
    "temperature": 0.7,
    "max_tokens": 512
  }'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LYROUTER_API_KEY"],
    base_url="https://api.lyrouter.com/v1",
)
completion = client.chat.completions.create(
    model="MODEL_ID",
    messages=[
        {"role": "system", "content": "You are a concise assistant."},
        {"role": "user", "content": "Introduce LYRouter in one sentence."},
    ],
    temperature=0.7,
    max_tokens=512,
)
print(completion.choices[0].message.content)
print(completion.usage)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LYROUTER_API_KEY,
  baseURL: "https://api.lyrouter.com/v1",
});
const completion = await client.chat.completions.create({
  model: "MODEL_ID",
  messages: [
    { role: "system", content: "You are a concise assistant." },
    { role: "user", content: "Introduce LYRouter in one sentence." },
  ],
  temperature: 0.7,
  max_tokens: 512,
});
console.log(completion.choices[0].message.content);
console.log(completion.usage);

Response

A non-streaming request returns a chat.completion object; an error returns an error object. The 200 example below is a typical response from an OpenAI-compatible channel; the 400 is a request without model in a workspace that has no default model; the 429 means the API key has used up its daily token quota (see 429: rate limits and quotas).

{
  "id": "chatcmpl-9f1c2a7e4b",
  "object": "chat.completion",
  "created": 1791950400,
  "model": "MODEL_ID",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "LYRouter is a trusted model service and token governance platform that lets you call many model providers with a single API key."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1250,
    "completion_tokens": 32,
    "total_tokens": 1282,
    "prompt_tokens_details": { "cached_tokens": 1024 },
    "completion_tokens_details": { "reasoning_tokens": 0 }
  }
}

{
  "error": {
    "message": "you must provide a model parameter",
    "type": "invalid_request_error",
    "code": "missing_model"
  }
}

{
  "error": {
    "message": "rate limit exceeded on apikey total_tokens/day",
    "type": "rate_limit_error",
    "subject": "apikey",
    "metric": "total_tokens",
    "window": "day",
    "limit": 1000000,
    "used": 1000523,
    "reset_at": "2026-10-14T16:01:00Z"
  }
}

usage and the four token types in logs

The fields in usage depend on the upstream that served the request. They map to the four types under "Token usage" in the request logs as follows:

When an Anthropic-protocol channel serves the request, usage in the response looks like this, and prompt_tokens does not include cache hits or cache writes:

"usage": {
  "prompt_tokens": 226,
  "completion_tokens": 32,
  "total_tokens": 258,
  "cache_read_input_tokens": 1024,
  "cache_creation_input_tokens": 0
}

If you estimate costs from usage yourself, first confirm which kind of upstream served the request, then price the four types separately; see Estimating costs and cache pricing. When reconciling, the logs are authoritative.

Streaming

With "stream": true, the response Content-Type is text/event-stream, and each event is one data: <JSON> line followed by a blank line:

data: {"id":"chatcmpl-9f1c2a7e4b","object":"chat.completion.chunk","created":1791950400,"model":"MODEL_ID","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-9f1c2a7e4b","object":"chat.completion.chunk","created":1791950400,"model":"MODEL_ID","choices":[{"index":0,"delta":{"content":"LYRouter is"},"finish_reason":null}]}

data: {"id":"chatcmpl-9f1c2a7e4b","object":"chat.completion.chunk","created":1791950400,"model":"MODEL_ID","choices":[{"index":0,"delta":{"content":" a trusted model service and token governance platform."},"finish_reason":null}]}

data: {"id":"chatcmpl-9f1c2a7e4b","object":"chat.completion.chunk","created":1791950400,"model":"MODEL_ID","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-9f1c2a7e4b","object":"chat.completion.chunk","created":1791950400,"model":"MODEL_ID","choices":[],"usage":{"prompt_tokens":1250,"completion_tokens":32,"total_tokens":1282,"prompt_tokens_details":{"cached_tokens":1024}}}

data: [DONE]

• Answer text arrives piece by piece in choices[0].delta.content; the thinking process is in delta.reasoning_content (delta.reasoning on a few upstreams).
• The gateway always turns on include_usage, so just before the end there is a chunk whose choices is an empty array and which carries usage. Check that the array is not empty before reading choices[0].
• data: [DONE] marks a normal end. If the connection closes before it arrives, or you receive an error event with "code": "stream_interrupted", the output is incomplete; see Timeouts and interrupted streams.
• When an Anthropic-protocol channel serves the request, the gateway generates the chunks by conversion, and the chunk with usage has only three fields: prompt_tokens, completion_tokens and total_tokens. Check cache counts in the logs.

curl -N https://api.lyrouter.com/v1/chat/completions \
  -H "Authorization: Bearer $LYROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"MODEL_ID","stream":true,"messages":[{"role":"user","content":"Write a two-line poem about autumn"}]}'

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["LYROUTER_API_KEY"],
    base_url="https://api.lyrouter.com/v1",
)
stream = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "Write a two-line poem about autumn"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:
        print("\n", chunk.usage)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LYROUTER_API_KEY,
  baseURL: "https://api.lyrouter.com/v1",
});
const stream = await client.chat.completions.create({
  model: "MODEL_ID",
  messages: [{ role: "user", content: "Write a two-line poem about autumn" }],
  stream: true,
});
for await (const chunk of stream) {
  const text = chunk.choices[0]?.delta?.content;
  if (text) process.stdout.write(text);
  if (chunk.usage) console.log("\n", chunk.usage);
}

For a comparison of event formats across the three chat endpoints and key points for client implementations, see Streaming.

Gateway behavior

Compared with calling the upstream directly, calling through LYRouter differs in these ways:

• Channel selection and fallback: the gateway selects a channel for the model according to the workspace's routing strategy, moves to the next channel on failure, and may finally switch to the workspace's Default Model; see Retries and fallback and Channels and routing. Once streaming output has started, the gateway no longer switches channels.
• Protocol conversion: when the channel uses the Anthropic protocol, the gateway converts the request to Anthropic Messages format and converts the response back to Chat Completions format. response_format, seed, n, logprobs, top_logprobs, frequency_penalty, presence_penalty, logit_bias, parallel_tool_calls and reasoning_effort are removed, and metadata keeps only user_id; these removals are not reported in response headers. For a comparison, see Capabilities and compatibility.
• Reasoning parameters: kept, removed or converted according to the table in "Reasoning parameters" above.
• Prompt cache markers: cache_control takes effect only on Anthropic-protocol channels, where markers on text content blocks and tool definitions are kept. With "ttl": "1h", the gateway sets the anthropic-beta request header to the value required for the 1-hour cache (overriding any value the client sent). For OpenAI-compatible channels, all markers are removed and the upstream's implicit caching does the work.
• Extension fields in history messages: before sending to OpenAI-compatible channels, the gateway removes reasoning_content, reasoning_blocks and cache_control from messages.
• Fixed JSON key order: the gateway reorders the keys of every JSON object in the request body sent upstream into a fixed order, including JSON inside tool call argument strings, so that the same content always produces the same bytes and the upstream prefix cache hits more often; see Reducing costs and improving cache reuse.
• Number precision: the gateway parses and re-encodes the request body, and numbers keep at most 14 significant digits. Longer integers (such as 19-digit IDs) become scientific notation; pass them as strings.
• Usage: streaming requests always return usage; the fields in usage vary by upstream, see the mapping table above.

Common errors

Error responses take the form {"error":{"message":"...","type":"...","code":"..."}}; only some errors include code.

• For 401 / 403 authentication issues, see 401 / 403: authentication and access; for 429, see 429: rate limits and quotas.
• 500 / 504 mean the connection to the upstream failed or the wait for the upstream timed out; the response body is an HTML page rather than JSON. See Timeouts and interrupted streams.
• Some 400s generated by the gateway itself are a single line of plain text rather than JSON, for example unsupported content-type: … when Content-Type is not application/json. Their response header is currently still Content-Type: application/json, so check whether the body is JSON before parsing the error.
• Errors returned by the upstream provider are forwarded unchanged; the status code and error text come from the upstream. For the full list, see Errors and request identifiers.