Текстовая серия
Claude Messages API
- Полная совместимость с нативным протоколом Anthropic Claude Messages (
POST /v1/messages) - Поддержка многошаговых диалогов, потокового SSE, вызова инструментов и extended thinking
- Поддержка мультимодального контента, включая текст и изображения
- Ответ передаётся как у апстрима, без внешней обёртки
{code, data}
POST
Авторизация
Поддерживаются два способа аутентификации — выберите один:string
Заголовок аутентификации в стиле AnthropicОткройте страницу управления API-ключами, чтобы получить ваш API-ключ
string
Bearer Token (альтернатива
x-api-key)string
Версия API (необязательно; без заголовка ответ всё равно будет корректным)Рекомендуется передавать для упрощения последующей миграции на официальный endpoint Anthropic:Пример:
2025-10-01Body
string
по умолчанию:"claude-sonnet-4-6"
обязательно
Model name
claude-opus-4-8- Claude Opus 4.8 flagship modelclaude-opus-4-7- Claude Opus 4.7 flagship modelclaude-opus-4-6- Claude Opus 4.6 flagship modelclaude-sonnet-4-6- Claude Sonnet 4.6 balanced versionclaude-opus-4-5-20251101- Claude Opus 4.5 model
array
обязательно
Список сообщенийМассив сообщений, на основе которых модель сгенерирует следующий ответ. Каждое сообщение содержит поля Многошаговый диалог:Предзаполненный ответ assistant:
role и content.💡 Быстрое заполнение (область «Try it»):- Нажмите «+ Add an item», чтобы добавить сообщение
- В поле
roleвведите:user(сообщение пользователя) илиassistant(ответ AI, для многошагового диалога) - В поле
contentвведите текст вашего сообщения
integer
обязательно
Максимальное количество генерируемых токенов (обязательно, как у Anthropic)Максимальное количество токенов до остановки. Модель может остановиться до достижения этого лимита.У разных моделей разные максимальные значения. Минимум: 1
object
Конфигурация Extended thinkingПри включении в
content ответа может появиться блок thinking. Рекомендуется использовать стандартное имя модели + этот параметр, а не платформенные алиасы -thinking — так проще мигрировать на официальный endpoint без правок кода.Если в многошаговом диалоге нужно вернуть thinking-блоки, передавайте signature как есть, иначе апстрим отклонит запрос.string | array
Системная подсказкаСистемные подсказки задают роль Claude, его характер, цели и инструкции.Строковый формат:Структурированный формат:
number
Параметр температуры, диапазон 0–1Управляет случайностью вывода:
- Низкие значения (например, 0.2): более детерминированный, консервативный
- Высокие значения (например, 0.8): более случайный, креативный
number
Параметр ядровой выборки (nucleus sampling), диапазон 0–1Использует ядровую выборку. Рекомендуется использовать либо
temperature, либо top_p, но не оба сразу.По умолчанию: 1.0integer
Выборка Top-KВыборка только из верхних K вариантов, отсекает «длинный хвост» маловероятных ответов.Рекомендуется только для продвинутых сценариев.
boolean
Включение стримингаПри значении
true использует Server-Sent Events (SSE) для потоковой передачи ответов.По умолчанию: falsearray
Стоп-последовательностиПользовательские текстовые последовательности, при которых модель прекращает генерацию.Максимум 4 последовательности.Пример:
["\n\nHuman:", "\n\nAssistant:"]object
МетаданныеОбъект метаданных для запроса.Включает:
user_id: идентификатор пользователя
array
Определения инструментовСписок инструментов, которые модель может использовать для выполнения задач.Пример функционального инструмента:Поддерживаемые типы инструментов:
- Пользовательские функциональные инструменты
- Инструмент работы с компьютером (computer_20241022)
- Инструмент текстового редактора (text_editor_20241022)
- Инструмент Bash (bash_20241022)
object
Стратегия выбора инструментаУправляет тем, как модель использует инструменты:
{"type": "auto"}: автоматическое решение (по умолчанию){"type": "any"}: обязательно использовать какой-либо инструмент{"type": "tool", "name": "tool_name"}: использовать конкретный инструмент
Response
string
Уникальный идентификатор сообщенияПример:
"msg_013Zva2CMHLNnXjNJJKqJ2EF"string
Тип объектаВсегда
"message"string
РольВсегда
"assistant"array
Массив блоков содержимогоВ Блок tool_use:Блок thinking (появляется, если в теле запроса есть параметр
content тип блока определяется полем type. В одном ответе может быть несколько блоков (например, при включённом thinking — thinking + text).Блок text:caller — новое поле апстрима; в официальной документации ещё не описано. При разборе можно игнорировать.thinking):string
Модель, обработавшая запросПример:
"claude-sonnet-4-6"string
Причина остановкиВозможные значения:
end_turn: естественное завершениеmax_tokens: достигнут лимит токеновstop_sequence: встретилась стоп-последовательностьtool_use: вызван инструмент
string | null
Сработавшая стоп-последовательностьЕсли остановка из‑за стоп-последовательности — её содержимое; иначе
nullobject | null
Более новое поле Anthropic; для обычных запросов —
nullobject
Статистика использования токенов (полная структура при нестриминговом ответе)
Примеры использования
Базовый диалог
Многошаговый диалог
Использование системных подсказок
Потоковый ответ
Использование инструментов
Понимание изображений
Изображение в формате Base64
Лучшие практики
1. Промпт-инжиниринг
Чёткое определение роли:2. Обработка ошибок
3. Оптимизация токенов
4. Предзаполнение ответов
Обработка потоковых ответов
Стриминг в Python
Стриминг в JavaScript
Отличия платформы и замечания по интеграции
Ответ без обёртки
При успехеPOST /v1/messages напрямую возвращает объект Anthropic message без внешней обёртки {code, data}. Это обеспечивает 1:1 совместимость с официальным SDK, Claude Code, Cline и др.
Формат ошибок (единственное существенное отличие от официального API)
"type": "error"; error.type всегда apimart_error, а не семантические типы вроде invalid_request_error.
Рекомендация по интеграции: не ветвите ретраи по error.type; используйте HTTP-статус + error.code:
При обращении в поддержку укажите request id в конце
error.message и заголовок ответа x-oneapi-request-id.
Потоковый SSE
Добавьте"stream": true в запрос. Последовательность событий как у официального API:
message_start → content_block_start → ping → content_block_delta (многократно) → content_block_stop → message_delta → message_stop
⚠️ Структура usage различается для stream и non-stream: в message_delta.usage обычно только 4 token-поля, без cache_creation, service_tier, inference_geo. Парсите раздельно или сделайте все поля опциональными.
Не реализованные эндпоинты
POST /v1/messages/count_tokens не реализован и возвращает 404. Вызов client.messages.count_tokens() официального SDK завершится ошибкой. Для оценки токенов считайте локально или читайте usage.input_tokens в ответе.
Неизвестные поля нужно игнорировать
API прозрачно проксирует апстрим; Anthropic может в любой момент добавить поля (напримерstop_details, inference_geo, caller, output_tokens_details). Не включайте строгую schema:
- Go: не используйте
DisallowUnknownFields() - Pydantic: не ставьте
extra="forbid" - TypeScript / Zod: используйте
.passthrough(), а не.strict()
Рекомендации по именам моделей
Одноимённые модели с суффиксом-thinking — платформенные алиасы. Рекомендуется стандартное имя без суффикса + параметр thinking в теле запроса — так проще перейти на официальный endpoint.
Остальные поля тела запроса совпадают с официальными: model, messages, max_tokens (обязательно), system, temperature, top_p, top_k, stop_sequences, stream, tools, tool_choice, thinking, metadata. Семантика — по Anthropic Messages API.
Важные замечания
-
Безопасность API-ключей:
- Храните API-ключи в переменных окружения
- Никогда не зашивайте ключи в исходный код
- Регулярно ротируйте ключи
-
Ограничение частоты запросов:
- Учитывайте лимиты API
- Реализуйте механизмы повтора (по HTTP-статусу)
- Используйте экспоненциальную задержку (exponential backoff)
-
Управление токенами:
- Отслеживайте расход токенов (читайте
usage) - Оптимизируйте длину промптов
- Используйте подходящие значения
max_tokens - При thinking
output_tokensуже включает thinking — не биллите дважды
- Отслеживайте расход токенов (читайте
-
Выбор модели:
- Opus: сложные задачи, требующие глубокого мышления
- Sonnet: сбалансированная производительность и стоимость
- Haiku: быстрый отклик, простые задачи
-
Разбор контента:
- Обходите
contentи берите блоки сtype == "text"; не жёстко пишитеcontent[0].text - Если модель возвращает JSON, обёрнутый в Markdown code fence, — это вывод модели, а не обёртка API (см. FAQ ниже)
- Обходите
-
Фильтрация контента:
- Валидируйте пользовательский ввод
- Фильтруйте конфиденциальную информацию
- Реализуйте модерацию контента
FAQ
В ответе content поле text — это ```json ... ``` code fence. Как убрать?
Это не проблема структуры API. В поле text лежит сырой вывод модели: если модель решила, что вам нужен JSON, она обернула его в Markdown code fence. API не переписывает и не должна переписывать вывод модели.
Чтобы получить чистые структурированные данные, есть три правильных подхода (от наиболее к наименее предпочтительному):
- Принудительный structured output через tools — самый надёжный способ: поле
inputуже готовый объект:
- Prefill сообщения assistant, чтобы модель продолжила с
{:
- В system prompt явно потребовать: «выводи только JSON, без Markdown code fence».