Skip to main content
POST
Не смешивайте два API: /v1/* — inference API (этот документ, прозрачная передача апстрима, без обёртки); /api/* — management API (баланс/логи и т.п., ответ {success, message, data}). Если где-то указано, что /v1/messages возвращает {code, data}, ориентируйтесь на этот документ.

Авторизация

Поддерживаются два способа аутентификации — выберите один:
string
Заголовок аутентификации в стиле AnthropicОткройте страницу управления API-ключами, чтобы получить ваш API-ключ
string
Bearer Token (альтернатива x-api-key)
string
Версия API (необязательно; без заголовка ответ всё равно будет корректным)Рекомендуется передавать для упрощения последующей миграции на официальный endpoint Anthropic:Пример: 2025-10-01

Body

string
по умолчанию:"claude-sonnet-4-6"
обязательно
Model name
  • claude-opus-4-8 - Claude Opus 4.8 flagship model
  • claude-opus-4-7 - Claude Opus 4.7 flagship model
  • claude-opus-4-6 - Claude Opus 4.6 flagship model
  • claude-sonnet-4-6 - Claude Sonnet 4.6 balanced version
  • claude-opus-4-5-20251101 - Claude Opus 4.5 model
array
обязательно
Список сообщенийМассив сообщений, на основе которых модель сгенерирует следующий ответ. Каждое сообщение содержит поля role и content.💡 Быстрое заполнение (область «Try it»):
  1. Нажмите «+ Add an item», чтобы добавить сообщение
  2. В поле role введите: user (сообщение пользователя) или assistant (ответ AI, для многошагового диалога)
  3. В поле content введите текст вашего сообщения
Одиночное сообщение пользователя:
Многошаговый диалог:
Предзаполненный ответ assistant:
integer
обязательно
Максимальное количество генерируемых токенов (обязательно, как у Anthropic)Максимальное количество токенов до остановки. Модель может остановиться до достижения этого лимита.У разных моделей разные максимальные значения. Минимум: 1
object
Конфигурация Extended thinkingПри включении в content ответа может появиться блок thinking. Рекомендуется использовать стандартное имя модели + этот параметр, а не платформенные алиасы -thinking — так проще мигрировать на официальный endpoint без правок кода.Если в многошаговом диалоге нужно вернуть thinking-блоки, передавайте signature как есть, иначе апстрим отклонит запрос.
string | array
Системная подсказкаСистемные подсказки задают роль Claude, его характер, цели и инструкции.Строковый формат:
Структурированный формат:
number
Параметр температуры, диапазон 0–1Управляет случайностью вывода:
  • Низкие значения (например, 0.2): более детерминированный, консервативный
  • Высокие значения (например, 0.8): более случайный, креативный
По умолчанию: 1.0
number
Параметр ядровой выборки (nucleus sampling), диапазон 0–1Использует ядровую выборку. Рекомендуется использовать либо temperature, либо top_p, но не оба сразу.По умолчанию: 1.0
integer
Выборка Top-KВыборка только из верхних K вариантов, отсекает «длинный хвост» маловероятных ответов.Рекомендуется только для продвинутых сценариев.
boolean
Включение стримингаПри значении true использует Server-Sent Events (SSE) для потоковой передачи ответов.По умолчанию: false
array
Стоп-последовательностиПользовательские текстовые последовательности, при которых модель прекращает генерацию.Максимум 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
Массив блоков содержимогоВ content тип блока определяется полем type. В одном ответе может быть несколько блоков (например, при включённом thinking — thinking + text).Блок text:
Блок tool_use:
caller — новое поле апстрима; в официальной документации ещё не описано. При разборе можно игнорировать.
Блок thinking (появляется, если в теле запроса есть параметр thinking):
При возврате thinking-блоков в многошаговом диалоге передавайте signature как есть, иначе апстрим отклонит запрос.
Не предполагайте, что content[0] — это текст. При включённом thinking content[0] может быть блоком thinking. Обходите и фильтруйте так:
string
Модель, обработавшая запросПример: "claude-sonnet-4-6"
string
Причина остановкиВозможные значения:
  • end_turn: естественное завершение
  • max_tokens: достигнут лимит токенов
  • stop_sequence: встретилась стоп-последовательность
  • tool_use: вызван инструмент
string | null
Сработавшая стоп-последовательностьЕсли остановка из‑за стоп-последовательности — её содержимое; иначе null
object | null
Более новое поле Anthropic; для обычных запросов — null
object
Статистика использования токенов (полная структура при нестриминговом ответе)

Примеры использования

Базовый диалог

Многошаговый диалог

Использование системных подсказок

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

Использование инструментов

Понимание изображений

Изображение в формате Base64

Лучшие практики

1. Промпт-инжиниринг

Чёткое определение роли:
Структурированный вывод:

2. Обработка ошибок

3. Оптимизация токенов

4. Предзаполнение ответов

Обработка потоковых ответов

Стриминг в Python

Стриминг в JavaScript

Отличия платформы и замечания по интеграции

Ответ без обёртки

При успехе POST /v1/messages напрямую возвращает объект Anthropic message без внешней обёртки {code, data}. Это обеспечивает 1:1 совместимость с официальным SDK, Claude Code, Cline и др.

Формат ошибок (единственное существенное отличие от официального API)

По сравнению с Anthropic: на верхнем уровне нет "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_startcontent_block_startpingcontent_block_delta (многократно) → content_block_stopmessage_deltamessage_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.

Важные замечания

  1. Безопасность API-ключей:
    • Храните API-ключи в переменных окружения
    • Никогда не зашивайте ключи в исходный код
    • Регулярно ротируйте ключи
  2. Ограничение частоты запросов:
    • Учитывайте лимиты API
    • Реализуйте механизмы повтора (по HTTP-статусу)
    • Используйте экспоненциальную задержку (exponential backoff)
  3. Управление токенами:
    • Отслеживайте расход токенов (читайте usage)
    • Оптимизируйте длину промптов
    • Используйте подходящие значения max_tokens
    • При thinking output_tokens уже включает thinking — не биллите дважды
  4. Выбор модели:
    • Opus: сложные задачи, требующие глубокого мышления
    • Sonnet: сбалансированная производительность и стоимость
    • Haiku: быстрый отклик, простые задачи
  5. Разбор контента:
    • Обходите content и берите блоки с type == "text"; не жёстко пишите content[0].text
    • Если модель возвращает JSON, обёрнутый в Markdown code fence, — это вывод модели, а не обёртка API (см. FAQ ниже)
  6. Фильтрация контента:
    • Валидируйте пользовательский ввод
    • Фильтруйте конфиденциальную информацию
    • Реализуйте модерацию контента

FAQ

В ответе content поле text — это ```json ... ``` code fence. Как убрать?

Это не проблема структуры API. В поле text лежит сырой вывод модели: если модель решила, что вам нужен JSON, она обернула его в Markdown code fence. API не переписывает и не должна переписывать вывод модели. Чтобы получить чистые структурированные данные, есть три правильных подхода (от наиболее к наименее предпочтительному):
  1. Принудительный structured output через tools — самый надёжный способ: поле input уже готовый объект:
  1. Prefill сообщения assistant, чтобы модель продолжила с {:
  1. В system prompt явно потребовать: «выводи только JSON, без Markdown code fence».
Сдирать code fence регулярными выражениями не рекомендуется — если модель иногда не ставит ограду, разбор падает.