# Anthropic Messages API

> Call Claude models through the native Anthropic Messages format with the Anthropic SDKs. Headers, base URL, prompt caching, thinking and beta features.

Source: https://oneaiapikey.com/docs/anthropic-messages

`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.

POST `https://api.oneaiapikey.com/v1/messages` (Anthropic format)

Base URL `https://api.oneaiapikey.com`

## Which models

The Messages format is for Claude models. For every other model, use [chat completions](https://oneaiapikey.com/docs/chat-completions), which Claude models accept as well.

| Model id | Input / 1M | Output / 1M |
| --- | --- | --- |
| [claude-opus-5-5](https://oneaiapikey.com/models/claude-opus-5-5) | $4.40 | $22 |
| [claude-sonnet-5](https://oneaiapikey.com/models/claude-sonnet-5) | $2.20 | $11 |
| [claude-haiku-4-5](https://oneaiapikey.com/models/claude-haiku-4-5) | $1.10 | $5.50 |
| [claude-sonnet-5-5](https://oneaiapikey.com/models/claude-sonnet-5-5) | $2.20 | $11 |

## Send a request

curl:

```bash
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;"}
    ]
  }'
```

Python:

```python
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)
```

Node:

```js
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:

Environment:

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

> **No /v1 in the Anthropic base URL:** Anthropic SDKs and Claude Code append `/v1/messages` themselves. If you set the base URL to `https://api.oneaiapikey.com/v1`, requests go to `/v1/v1/messages` and fail with 404. The one exception is the Vercel AI SDK’s `createAnthropic`, which expects `/v1` (see [SDKs](https://oneaiapikey.com/docs/sdks)).

## Headers

| Header | Required | Notes |
| --- | --- | --- |
| `x-api-key` | Yes (or the next one) | Your key. The Anthropic SDKs send this. |
| `Authorization: Bearer <key>` | Alternative | Accepted too, so one HTTP client can serve both formats. |
| `anthropic-version` | Recommended | `2023-06-01`. If you leave it out, the gateway sends that value. |
| `anthropic-beta` | Optional | Forwarded to Anthropic as it is, for beta features. |
| `Content-Type` | Yes | `application/json`. |

## 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`.

200 OK:

```json
{
  "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](https://oneaiapikey.com/docs/prompt-caching) at work.

## Features that work here

- **Prompt caching.** Mark a stable prefix with `"cache_control": {"type": "ephemeral"}`. See [Prompt caching](https://oneaiapikey.com/docs/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](https://oneaiapikey.com/docs/reasoning).
- **Structured output.** Anthropic’s `output_config.format` with a JSON Schema is forwarded. See [Structured output](https://oneaiapikey.com/docs/structured-output#claude-models).
- **Tools.** Anthropic tool definitions and `tool_use` / `tool_result` blocks. See [Tool calling](https://oneaiapikey.com/docs/tool-calling).
- **Images and PDFs.** `image` and `document` blocks, base64 or URL. See [Vision and files](https://oneaiapikey.com/docs/vision).
- **Streaming.** Anthropic’s server-sent events. See [Streaming](https://oneaiapikey.com/docs/streaming#anthropic-format).

Extended thinking:

```python
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](https://oneaiapikey.com/docs/guides/claude-code): point Claude Code at the gateway.
- [Authentication](https://oneaiapikey.com/docs/authentication): keys, headers and per-key limits.
- [Errors](https://oneaiapikey.com/docs/errors#anthropic-format): the error body on this endpoint.