К содержимому

Anthropic Messages API: заголовки и запросы

Формат запроса и ответа Anthropic Messages для Anthropic SDK и Claude Code.

Обзор метода

POST https://relay-llm.ru/v1/messages принимает тело в формате Anthropic Messages и отвечает в том же формате. Клиентам Anthropic укажите базовый адрес https://relay-llm.ru без /v1: SDK добавляют путь сами.

В аудите 14 октября 2026 успешные запросы в формате Anthropic Messages зафиксированы для claude-opus-4.8. Если у маршрута модели такого протокола нет, запрос получает ответ 503 model_unavailable. Для остальных моделей используйте Chat Completions, если поддержка Messages не подтверждена.

Формат Chat Completions

Шлюз читает три поля тела: model, stream и max_tokens. Остальное уходит модели без изменений, поэтому поддержка конкретного параметра зависит от модели.

Аутентификация

Передайте ключ в заголовке x-api-key: RELAY_API_KEY или Authorization: Bearer RELAY_API_KEY. Без ключа, а также с неверным, просроченным или отозванным ключом приходит ответ 401 с кодом invalid_api_key. Если заголовков два, шлюз читает только Authorization.

Заголовок anthropic-version шлюз не требует и не проверяет.

Параметры тела

ПолеТипНазначение
modelstring, обязательноИдентификатор модели из каталога или заведённый для неё алиас. Неизвестная модель даёт ответ 404 с кодом model_not_found.
messagesarrayСообщения диалога в формате Anthropic. Структуру шлюз не проверяет: по размеру текста и числу картинок он оценивает стоимость запроса, а роли и обязательные поля проверяет модель.
max_tokensintegerОграничение длины ответа, целое число от 1 до 16 777 216, иначе ответ 400. Шлюз принимает запрос и без поля, но модель может его потребовать. Верхняя оценка стоимости, от которой считается резерв до ответа, строится по этому значению.
streambooleantrue включает потоковый ответ с именованными событиями. Расход токенов приходит в самих событиях.
остальные полялюбойНапример system, tools, thinking и cache_control. Передаются модели без изменений.

Пример запроса

Один и тот же запрос на трёх языках. Адрес API уже подставлен, путь /v1/messages указан целиком.

cURL

bash
curl https://relay-llm.ru/v1/messages \
  -H "x-api-key: $RELAY_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Say hello in one sentence."
      }
    ]
  }'

Python

python
import os
from anthropic import Anthropic

client = Anthropic(base_url="https://relay-llm.ru", api_key=os.environ["RELAY_API_KEY"])

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

JavaScript

ts
const response = await fetch('https://relay-llm.ru/v1/messages', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.RELAY_API_KEY,
    'anthropic-version': '2023-06-01',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'MODEL_ID',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Say hello in one sentence.' }],
  }),
})
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`)
const data = await response.json()
console.log(data.content[0].text)

Вместо MODEL_ID подставьте идентификатор модели из каталога. Примеры читают ключ из переменной окружения RELAY_API_KEY, адрес API уже подставлен.

Ответ

json
{
  "id": "msg_01Ab3cD",
  "type": "message",
  "role": "assistant",
  "model": "MODEL_ID",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help you today?"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 9,
    "output_tokens": 7
  }
}

Текст ответа лежит в content[0].text, расход токенов в usage: input_tokens, output_tokens и, если модель использует кэш, cache_creation_input_tokens и cache_read_input_tokens. Поле model содержит идентификатор из вашего запроса.

Заголовок x-request-id хранит идентификатор запроса: он же указан в строке журнала запросов в кабинете и в теле ошибки.

Как считается кэш

Потоковый ответ

Как считается резерв и списание

Ошибки

Ошибка приходит с HTTP-кодом и телом в формате Anthropic: type: "error", объект error с типом и сообщением и request_id. Значение request_id совпадает с заголовком x-request-id. Поле error.code не возвращается.

json
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key See https://relay-llm.ru/docs/errors#invalid_api_key"
  },
  "request_id": "01990f3c-7a52-7c1e-9b0a-3d5e8f2a4c61"
}

Все коды ошибок

Готовы? Три шага, чтобы начатьВойдите в консоль · пополните баланс · создайте API Key