Anthropic Messages API: заголовки и запросы
Формат запроса и ответа Anthropic Messages для Anthropic SDK и Claude Code.
Обзор метода
POST https:// принимает тело в формате Anthropic Messages и отвечает в том же формате. Клиентам Anthropic укажите базовый адрес https:// без /: SDK добавляют путь сами.
В аудите 14 октября 2026 успешные запросы в формате Anthropic Messages зафиксированы для claude-opus-4.8. Если у маршрута модели такого протокола нет, запрос получает ответ 503 model_unavailable. Для остальных моделей используйте Chat Completions, если поддержка Messages не подтверждена.
Шлюз читает три поля тела: model, stream и max_tokens. Остальное уходит модели без изменений, поэтому поддержка конкретного параметра зависит от модели.
Аутентификация
Передайте ключ в заголовке x-api-key: RELAY_API_KEY или Authorization: Bearer RELAY_API_KEY. Без ключа, а также с неверным, просроченным или отозванным ключом приходит ответ 401 с кодом invalid_api_key. Если заголовков два, шлюз читает только Authorization.
Заголовок anthropic-version шлюз не требует и не проверяет.
Параметры тела
| Поле | Тип | Назначение |
|---|---|---|
model | string, обязательно | Идентификатор модели из каталога или заведённый для неё алиас. Неизвестная модель даёт ответ 404 с кодом model_not_found. |
messages | array | Сообщения диалога в формате Anthropic. Структуру шлюз не проверяет: по размеру текста и числу картинок он оценивает стоимость запроса, а роли и обязательные поля проверяет модель. |
max_tokens | integer | Ограничение длины ответа, целое число от 1 до 16 777 216, иначе ответ 400. Шлюз принимает запрос и без поля, но модель может его потребовать. Верхняя оценка стоимости, от которой считается резерв до ответа, строится по этому значению. |
stream | boolean | true включает потоковый ответ с именованными событиями. Расход токенов приходит в самих событиях. |
| остальные поля | любой | Например system, tools, thinking и cache_control. Передаются модели без изменений. |
Пример запроса
Один и тот же запрос на трёх языках. Адрес API уже подставлен, путь / указан целиком.
cURL
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
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
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 уже подставлен.
Ответ
{
"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 не возвращается.
{
"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"
}