Anthropic Messages API

POST /v1/messages is Anthropic’s own API. Use it when your code or tool already speaks Anthropic (the Anthropic SDKs, Claude Code, Claude Agent SDK) or when you want Anthropic-only features such as cache_control breakpoints and thinking blocks.

Which models

The Messages format is for Claude models. For every other model, use chat completions, which Claude models accept as well.

Send a request

curl https://api.oneaiapikey.com/v1/messages \
  -H "x-api-key: $RELAYKIT_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "system": "You are a careful code reviewer.",
    "messages": [
      {"role": "user", "content": "Review this line: if (user = null) return;"}
    ]
  }'

import os
import anthropic

# base_url has no /v1: the SDK adds /v1/messages itself.
client = anthropic.Anthropic(base_url="https://api.oneaiapikey.com", api_key=os.environ["RELAYKIT_API_KEY"])

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    system="You are a careful code reviewer.",
    messages=[{"role": "user", "content": "Review this line: if (user = null) return;"}],
)
print(message.content[0].text)
print(message.usage)

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

// baseURL has no /v1: the SDK adds /v1/messages itself.
const client = new Anthropic({ baseURL: "https://api.oneaiapikey.com", apiKey: process.env.RELAYKIT_API_KEY });

const message = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 1024,
  system: "You are a careful code reviewer.",
  messages: [{ role: "user", content: "Review this line: if (user = null) return;" }],
});
console.log(message.content[0].text);
console.log(message.usage);

The Anthropic SDKs also read the base URL and key from the environment, so existing code needs no changes:

export ANTHROPIC_BASE_URL="https://api.oneaiapikey.com"
export ANTHROPIC_API_KEY="$RELAYKIT_API_KEY"   # the Anthropic SDKs read both variables

Headers

Request and response

The body is Anthropic’s: model, max_tokens (required by Anthropic; the gateway sends 8,192 if you leave it out), messages, and optionally system, temperature, top_p, top_k, stop_sequences, stream, tools, tool_choice, thinking, metadata. Message content can be a string or a list of blocks: text, image, document, tool_use, tool_result.

{
  "id": "msg_…",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [{ "type": "text", "text": "This assigns null instead of comparing …" }],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 28,
    "output_tokens": 64,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0
  }
}

stop_reason is end_turn, max_tokens, stop_sequence or tool_use. usage.cache_read_input_tokens and usage.cache_creation_input_tokens show prompt caching at work.

Features that work here

• Prompt caching. Mark a stable prefix with "cache_control": {"type": "ephemeral"}. See Prompt caching for what is billed.
• Extended thinking. Pass thinking; the reply contains thinking blocks before the text. Thinking tokens are billed as output tokens. See Reasoning models.
• Structured output. Anthropic’s output_config.format with a JSON Schema is forwarded. See Structured output.
• Tools. Anthropic tool definitions and tool_use / tool_result blocks. See Tool calling.
• Images and PDFs. image and document blocks, base64 or URL. See Vision and files.
• Streaming. Anthropic’s server-sent events. See Streaming.

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 8000},
    messages=[{"role": "user", "content": "Is 2^61 - 1 prime? Show your reasoning briefly."}],
)
for block in message.content:
    print(block.type, getattr(block, "thinking", None) or getattr(block, "text", ""))

Not available

• POST /v1/messages/count_tokens is turned off. Use the usage in each response, or count locally.
• The Message Batches and Files APIs are not offered.
• GET /v1/models lists the models your key can use. Sent with x-api-key and anthropic-version (as the Anthropic SDK’s client.models.list() does), it answers in Anthropic’s list format; otherwise in OpenAI’s.

Related

• Claude Code guide: point Claude Code at the gateway.
• Authentication: keys, headers and per-key limits.
• Errors: the error body on this endpoint.