Base URLs and authentication

All calls go to the gateway address https://api.lyrouter.com and authenticate with the same LYRouter API key. Set the OpenAI SDK's Base URL to https://api.lyrouter.com/v1 and the Anthropic SDK's to the root address https://api.lyrouter.com; put the key in the Authorization: Bearer <API Key> or x-api-key request header. In the request body, set model to a system model ID, @vmodel/<name> or lyrouter/auto; when it is omitted, the workspace's Default Model is used.

Addresses

• SDKs take only the Base URL: the OpenAI SDK appends paths such as /chat/completions, /responses and /models after /v1, and the Anthropic SDK appends /v1/messages to the root address. With cURL or your own HTTP requests, write the full URL, for example https://api.lyrouter.com/v1/chat/completions.
• Do not repeat /v1: when the Anthropic SDK's Base URL is https://api.lyrouter.com/v1, the actual request goes to /v1/v1/messages and returns 404. An OpenAI SDK Base URL that goes as far as /v1/chat/completions also produces a wrong path.
• Version prefixes: besides /v1, the gateway also accepts the same paths without a version prefix (such as /chat/completions) or with another version prefix (such as /v4/chat/completions, used by some Zhipu clients), and handles them as the same endpoint. Use /v1 for all new applications.
• The console address is not the gateway address: the console page you open in a browser (/ai_gateway/...) cannot be used as a Base URL. For a self-hosted deployment, replace https://api.lyrouter.com on this page with your gateway address.

Authentication

Create an API key on the API Keys page of the current workspace; see Workspaces and API keys. The gateway identifies the workspace by the API key and swaps in a platform or BYOK provider credential when it calls the upstream; your API key is never forwarded upstream. Neither a provider's API key nor a console login session can be used to call the gateway.

• Only one is read: when a request carries both headers, the gateway reads only Authorization. When Authorization is malformed, it returns 401 right away and does not fall back to x-api-key.
• Headers only: do not put the key in URL query parameters or in the request body.
• When changes apply: creating, disabling or editing a key reaches the gateway within a few seconds.

Limits on the API key itself

You can set the following limits when you create or edit a key. Once one is triggered, the gateway rejects the request before calling the upstream:

Keys are also subject to the workspace's guardrail policies (model policies, quotas, client access control); see Guardrails and semantic auditing. How to handle each error is covered in 401 / 403: authentication and access and 429: rate limits and quotas.

OpenAI SDK

Chat Completions, Responses, Models, Embeddings and the other OpenAI-compatible endpoints share one client whose Base URL ends at /v1:

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": "user", "content": "Introduce yourself in one sentence"}]
  }'

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": "user", "content": "Introduce yourself in one sentence"}],
)
print(completion.choices[0].message.content)

# Call Responses with the same client
response = client.responses.create(model="MODEL_ID", input="Introduce yourself in one sentence")
print(response.output_text)

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: "user", content: "Introduce yourself in one sentence" }],
});
console.log(completion.choices[0].message.content);

// Call Responses with the same client
const response = await client.responses.create({ model: "MODEL_ID", input: "Introduce yourself in one sentence" });
console.log(response.output_text);

Replace MODEL_ID with a model ID copied from the model marketplace; setting the LYROUTER_API_KEY environment variable is covered in Your first model call. Responses requires the model, and the channel that serves it, to support the Responses endpoint; see Responses. client.responses in the Python example requires openai Python SDK 1.66 or later; older versions raise AttributeError: 'OpenAI' object has no attribute 'responses'.

Anthropic SDK

The Anthropic SDK's Base URL is the root address, without /v1. /v1/messages does not require a model from Anthropic; you can call any chat model through it:

curl https://api.lyrouter.com/v1/messages \
  -H "x-api-key: $LYROUTER_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Introduce yourself in one sentence"}]
  }'

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["LYROUTER_API_KEY"],
    base_url="https://api.lyrouter.com",
)

message = client.messages.create(
    model="MODEL_ID",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Introduce yourself in one sentence"}],
)
print(message.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.LYROUTER_API_KEY,
  baseURL: "https://api.lyrouter.com",
});

const message = await client.messages.create({
  model: "MODEL_ID",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Introduce yourself in one sentence" }],
});
console.log(message.content[0].text);

Details of requests, responses and streaming events are in Anthropic Messages.

Switching existing code with environment variables only

Both SDKs read environment variables. When your existing code does not pass the address and key explicitly, setting the variables below is enough to route it through the gateway:

The model names in your code also have to change to LYRouter model IDs. Configuration for coding tools such as Claude Code and Codex is in Tools and compatibility.

The model field

• Model IDs are case-sensitive and must match the id shown in the model marketplace or returned by GET /v1/models character for character; the naming rules are in Model identifiers and discovery.
• When model is omitted and the workspace has no Default Model, the request returns 400 you must provide a model parameter (error.code missing_model); when model is not a string, it returns 400 invalid type for 'model': expected a string (invalid_model).
• Virtual models and lyrouter/auto used on image, video or audio endpoints return 403 Model is not available in the model plaza; use a specific model ID on those endpoints.

All endpoints

Every endpoint uses the same Base URL and the same authentication:

Every endpoint, grouped by capability, is listed in API documentation, and the gateway's own request and response headers in Gateway headers and extensions.

Address and authentication errors

On OpenAI-compatible endpoints the error body is {"error": {"message": "...", "type": "...", "code": "..."}}, and code appears only on some errors. Errors on /v1/messages are converted to the Anthropic format {"type": "error", "error": {"type": "authentication_error", "message": "..."}}, with message unchanged and no code.

Responses do not include a request ID. When you report a problem, record the call time, endpoint, model, API key name and the error message; if you can find the request in Log analysis, also include the Request ID at the top of the log detail. 401 requests cannot be attributed to a key and do not appear in the logs. All error codes are listed in Errors and request identifiers.

FAQ

My OpenAI SDK Base URL is missing /v1. Why do calls still work?

Answer: The gateway also accepts paths without a version prefix, so https://api.lyrouter.com/chat/completions is equivalent to /v1/chat/completions. Other tools and SDKs may not build paths the same way, so always use https://api.lyrouter.com/v1.

Can one API key be used by both OpenAI and Anthropic clients?

Answer: Yes. A key belongs to a workspace and is independent of the protocol; when both clients call the same model ID, cost, quotas and logs are all recorded under this key. The API Path column in the logs tells you which endpoint a request came through.

Can I tell from the response which provider a request was routed to?

Answer: The response carries no provider information, and its model field is the value returned by the upstream. Open the request in Log analysis: Model (actual) and Provider show the model and channel that finally served it; see Inspecting request routing.