Anthropic format

Generates a model reply from the conversation history, with streaming, image input and tool calls. It is compatible with the Anthropic Messages API: the system prompt goes in system, the conversation goes in messages made of content blocks, and the response's content is also an array of content blocks. The official Anthropic SDKs and Anthropic-protocol clients such as Claude Code connect by setting the Base URL to the gateway root, https://api.lyrouter.com. The gateway converts between Messages and the upstream protocol, so besides the Claude family, this endpoint can also call the platform's other chat models.

Authentication

Send your API key in a request header, using either of the two forms below:

x-api-key: <API Key>
Authorization: Bearer <API Key>

When both are present, only Authorization is read; Bearer is case-sensitive. The Anthropic SDK's api_key parameter sends x-api-key, and its auth_token parameter sends Authorization: Bearer; Claude Code's ANTHROPIC_AUTH_TOKEN uses the latter. 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.

The Anthropic SDKs and Claude Code append /v1/messages themselves, so do not add /v1 to the Base URL; otherwise the request path becomes /v1/v1/messages and returns 404.

Headers

Request body

Other fields not listed in the table are not forwarded to the upstream.

Content blocks

Blocks of other types (such as document) are not forwarded to the upstream.

Prompt caching

Add "cache_control": {"type": "ephemeral"} to a system block, a text block in a message or a tool definition (for a 1-hour cache, write {"type": "ephemeral", "ttl": "1h"}) to mark where a cacheable prefix ends:

The part written to the cache is recorded as "Explicit cache write", and later hits are recorded as "Input (cache hit)". OpenAI-compatible upstreams have only the caching the upstream performs automatically and do not produce "Explicit cache write". For how to place markers and improve hit rates, see Reducing costs and improving cache reuse.

Request examples

Install the SDK first: pip install anthropic or npm install @anthropic-ai/sdk.

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,
    "system": "You are a concise assistant.",
    "messages": [
      { "role": "user", "content": "Explain what an API gateway is in one sentence." }
    ]
  }'

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["LYROUTER_API_KEY"],
    base_url="https://api.lyrouter.com",
)
message = client.messages.create(
    model="MODEL_ID",
    max_tokens=1024,
    system="You are a concise assistant.",
    messages=[{"role": "user", "content": "Explain what an API gateway is in one sentence."}],
)
print(message.content[0].text)  # content may be empty; see "Response" below
print(message.usage)

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,
  system: "You are a concise assistant.",
  messages: [{ role: "user", content: "Explain what an API gateway is in one sentence." }],
});
console.log(message.content[0].text);
console.log(message.usage);

Replace MODEL_ID with a model ID enabled in your workspace. To use Authorization: Bearer instead, in cURL replace the x-api-key header with -H "Authorization: Bearer $LYROUTER_API_KEY"; in the SDK, replace api_key / apiKey with auth_token / authToken.

Response

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

{
  "id": "msg_01HCDu5LRGeP2o7s2xGmxyZa",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-5-20250929",
  "content": [
    {
      "type": "text",
      "text": "An API gateway is the single entry point between clients and backend services, handling authentication, routing, rate limiting and monitoring."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 294,
    "output_tokens": 46,
    "cache_read_input_tokens": 1536,
    "cache_creation_input_tokens": 212
  }
}

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

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid api key"
  }
}

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "rate limit exceeded on apikey total_tokens/day"
  }
}

• content can be {}: when the upstream outputs only thinking and is cut off by max_tokens while still thinking, the content of a non-streaming response is currently an empty object {} rather than an empty array [] (seen on glm-5.3, kimi-k2.7-code and deepseek-v4). Leave enough room in max_tokens, and when parsing, treat a content that is not an array as empty.
• <think> tags: some models (such as minimax-m3) write their thinking as <think>…</think> inside text blocks, both in non-streaming and streaming responses. The gateway does not strip it; remove it yourself if needed.

usage and the four token types in logs

usage maps one to one to the four items under "Token usage" in the logs, and the four fields do not overlap:

The two cache fields are omitted when they are 0. When the upstream uses the OpenAI-compatible protocol, the gateway subtracts the cache hits from the upstream's prompt_tokens to get input_tokens, matching Anthropic's definition; the total input for the call is input_tokens + cache_read_input_tokens + cache_creation_input_tokens. For billing, see Estimating costs and cache pricing.

Tool calls

Declare the tool in the request:

{
  "model": "MODEL_ID",
  "max_tokens": 1024,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather for a city",
      "input_schema": {
        "type": "object",
        "properties": { "city": { "type": "string" } },
        "required": ["city"]
      }
    }
  ],
  "messages": [{ "role": "user", "content": "What's the weather in Shanghai right now?" }]
}

When the model decides to call the tool, a tool_use block appears in content, and stop_reason is usually tool_use:

{
  "type": "tool_use",
  "id": "toolu_01A09q90qw90lq917835lq9",
  "name": "get_weather",
  "input": { "city": "Shanghai" }
}

To decide whether to run a tool, check whether content contains a tool_use block rather than relying only on stop_reason: currently, when tool_choice is {"type": "tool", "name": "..."}, the response carries a tool_use block but stop_reason is end_turn; with any or auto it is tool_use.

After running the tool, put the assistant turn back into messages unchanged, then return tool_result in a user message, with tool_use_id matching the call's id:

{
  "model": "MODEL_ID",
  "max_tokens": 1024,
  "tools": ["...same as in the first request..."],
  "messages": [
    { "role": "user", "content": "What's the weather in Shanghai right now?" },
    {
      "role": "assistant",
      "content": [
        {
          "type": "tool_use",
          "id": "toolu_01A09q90qw90lq917835lq9",
          "name": "get_weather",
          "input": { "city": "Shanghai" }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
          "content": "{\"temp_c\":22,\"condition\":\"cloudy\"}"
        }
      ]
    }
  ]
}

The tools value in the example is abbreviated; a real request must include the full tool definitions. Keep the following in mind:

• Use only custom tools that have input_schema. Anthropic server tools (such as web_search) are sent as ordinary custom tools and are not executed on the server.
• In a user message that contains tool_result, any text and image blocks next to it are not forwarded. To add notes, put them in the tool_result's content or in the next user message.
• is_error in tool_result is not forwarded; when a tool fails, describe the error in content.

For a comparison with the Chat Completions format, see Tool calls.

Streaming

With "stream": true, the response is text/event-stream, and each event consists of an event: line and a data: line:

event: message_start
data: {"type":"message_start","message":{"id":"msg_01HCDu5LRGeP2o7s2xGmxyZa","type":"message","role":"assistant","model":"claude-sonnet-4-5-20250929","content":[],"usage":{"input_tokens":294,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"An API gateway is"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"input_tokens":294,"output_tokens":46,"cache_read_input_tokens":1536,"cache_creation_input_tokens":212}}

event: message_stop
data: {"type":"message_stop"}

• Event order: message_start → for each content block, content_block_start, content_block_delta, content_block_stop → message_delta → message_stop. message_stop marks a normal end.
• Delta types: text uses text_delta; tool call arguments use input_json_delta (the partial_json pieces form complete JSON only after they are joined); thinking content uses thinking_delta, and an Anthropic upstream's thinking block also has one complete signature_delta before content_block_stop. Thinking content returned by OpenAI-compatible upstreams is likewise output as thinking blocks, but without a signature.
• Usage: the complete usage, including the cache fields, is in message_delta. The usage in message_start has only input_tokens and an output_tokens of 0, and when the upstream is OpenAI-compatible, input_tokens is 0 as well, so rely on message_delta.
• Errors mid-stream: if the upstream breaks off after output has started, the gateway sends an event: error whose data is {"type": "error", "error": {"type": "api_error", "message": "upstream timed out after the response had started"}}, and no message_stop follows. Error events sent by the upstream itself (such as overloaded_error) are passed to the client in the same format. Treat a stream without message_stop as failed; see Timeouts and interrupted streams.

curl -N 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,"stream":true,"messages":[{"role":"user","content":"Write a two-line poem"}]}'

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["LYROUTER_API_KEY"],
    base_url="https://api.lyrouter.com",
)
with client.messages.stream(
    model="MODEL_ID",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Write a two-line poem"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)
    print("\n", stream.get_final_message().usage)

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

const client = new Anthropic({
  apiKey: process.env.LYROUTER_API_KEY,
  baseURL: "https://api.lyrouter.com",
});
const stream = client.messages.stream({
  model: "MODEL_ID",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Write a two-line poem" }],
});
stream.on("text", (text) => process.stdout.write(text));
const final = await stream.finalMessage();
console.log("\n", final.usage);

For a comparison of streaming formats across protocols, see Streaming.

Gateway behavior

Internally, the gateway handles all chat requests in the OpenAI Chat Completions format. A /v1/messages request is first converted to the internal format, then sent in the protocol of the selected channel: for an Anthropic-protocol channel it is converted back into a Messages request, and for an OpenAI-compatible channel it becomes a Chat Completions request; responses and streaming events are converted back into the Messages format. This conversion happens even when the upstream is Anthropic, so requests and responses are not forwarded byte for byte.

• Thinking blocks and switching models: when a conversation switches midway from a model on an OpenAI-compatible upstream to an Anthropic upstream, the thinking blocks in the history have no signatures, so that turn is sent with thinking turned off to keep the upstream from rejecting the request.
• Model name: model is replaced with the selected channel's actual model name, and the model in the response is the name the upstream returns.
• Virtual models: when the request has no system, the gateway fills in the virtual model's system prompt; when system is present, nothing is injected; see Virtual models.
• Key order: in the request JSON sent to the upstream, object keys are reordered (array order is unchanged) so identical prefixes reliably hit the upstream cache.
• Fallback on failure: when the upstream returns an error or the connection fails before output starts, the gateway switches channels as described in Retries and fallback, and if needed moves on to fallback models and the workspace's default model. Once streaming output has started, the gateway no longer switches channels.
• Response headers: the upstream's Retry-After is forwarded to the client. Responses carry anthropic-ratelimit-* headers: when the upstream returned these headers they are forwarded as is; otherwise, when quotas are configured, they are generated from the gateway quota. For x-aigw-quota-*, see Gateway headers and extensions.

Common errors

Errors on /v1/messages are always converted to the Anthropic format. message keeps its original text, error.code is no longer included, and error.type is determined by the status code:

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "Model is not available in the model plaza"
  }
}

The full list is in Errors and request identifiers. To tell apart specific causes under the same status code, rely on message, or check "Status explanation" for the request in the request logs. Gateway responses do not include a request ID; when troubleshooting, copy the Request ID from the top of the log details.