Документация Anthropic Messages API: конечные точки, запросы, Vision и бэкенды агентов

Anthropic Messages API — это основной HTTP-интерфейс для отправки запросов к Claude. Основной endpoint: POST /v1/messages: вы указываете модель, список типизированных блоков содержимого сообщения и лимит токенов, а затем получаете ответ ассистента, содержащий один или несколько блоков вывода.

Это руководство превращает документацию Anthropic API в чек-лист для внедрения. Оно охватывает контракт запроса, многоповоротное состояние, потоковую передачу, Vision, Files API, использование инструментов и выбор, с которым сталкивается бэкенд агента, когда ему нужно поддерживать как нативные для Anthropic, так и совместимые с OpenAI провайдеры моделей.

Конечная точка Messages API и обязательные заголовки

Нативный Messages API от Anthropic использует следующий endpoint:

POST https://api.anthropic.com/v1/messages

Прямые HTTP-запросы обычно включают следующие заголовки:

Заголовок	Назначение
x-api-key	Аутентификация учётной записи Anthropic
anthropic-version	Выбор версии API в соответствии с документацией
content-type: application/json	Объявление JSON-тела запроса

Заголовок версии API не является версией модели. Он управляет поведением HTTP API, в то время как поле model выбирает модель Claude, используемую для инференса. Храните оба значения в конфигурации, а не разбрасывайте их по коду приложения.

Структура запроса и ответа

Базовый запрос содержит три поля:

{
  "model": "YOUR_CLAUDE_MODEL_ID",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Explain idempotency keys in two paragraphs."
    }
  ]
}

Ответ представляет собой сообщение ассистента, а не просто строку. Его свойство content — это массив типизированных блоков, поэтому в production-коде следует проверять type каждого блока перед чтением его полей.

{
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "An idempotency key..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 126
  }
}

Блочная структура становится важной, когда вы добавляете изображения или инструменты. Один ответ ассистента может содержать текст и запрос на использование инструмента, а один запрос пользователя — текст вместе с блоками изображений или документов.

Минимальный curl-запрос

Храните учётные данные в переменной окружения и используйте идентификатор модели, который в настоящее время доступен для вашей учётной записи Anthropic:

export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="your-claude-model-id"

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "content-type: application/json" \
  --data '{
    "model": "'"$ANTHROPIC_MODEL"'",
    "max_tokens": 512,
    "messages": [
      {
        "role": "user",
        "content": "Return three practical ways to reduce API latency."
      }
    ]
  }'

Не жёстко кодируйте имя модели, скопированное из старого туториала. Доступность моделей и их псевдонимы могут меняться, поэтому в конфигурации развёртывания следует использовать идентификатор модели, проверенный в текущей документации провайдера или консоли.

Использование Python с Anthropic SDK

Официальный Python SDK обрабатывает заголовки аутентификации и преобразует ответ в типизированные объекты:

import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

message = client.messages.create(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=512,
    messages=[
        {
            "role": "user",
            "content": "Write a Python function that validates a UUID string.",
        }
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Итерация по блокам содержимого безопаснее, чем предположение, что message.content[0] всегда является текстом. Агентские приложения могут получать блоки tool_use, а мультимодальные функции могут добавлять в диалог другие типы блоков.

Многоповоротные диалоги и системные промпты

Messages API не сохраняет состояние. Ваше приложение отправляет соответствующую историю диалога заново с каждым запросом:

{
  "model": "YOUR_CLAUDE_MODEL_ID",
  "max_tokens": 512,
  "system": "You are a concise API documentation assistant.",
  "messages": [
    {"role": "user", "content": "What does HTTP 429 mean?"},
    {"role": "assistant", "content": "It indicates rate limiting."},
    {"role": "user", "content": "How should my client retry?"}
  ]
}

Anthropic размещает системную инструкцию в поле system верхнего уровня, а не в сообщении с role: "system". Это одно из важных отличий, которые необходимо учитывать при преобразовании запросов из схем, совместимых с OpenAI.

Для длительных сессий не отправляйте неограниченную стенограмму. Сохраняйте последние повороты, сохраняйте решения и результаты инструментов, которые всё ещё влияют на задачу, и обобщайте старый контекст, прежде чем промпт приблизится к лимиту контекста выбранной модели.

Потоковая передача ответов

Установите stream: true, когда интерфейс должен отображать вывод по частям:

import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

with client.messages.stream(
    model=os.environ["ANTHROPIC_MODEL"],
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Explain database connection pooling."}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Потоковая передача улучшает воспринимаемую задержку, но добавляет работу по управлению состоянием. Ваше приложение должно обрабатывать преждевременное закрытие соединения, частичный текст, порядок событий и итоговые метаданные использования. Для агентов, использующих инструменты, буферизируйте полный блок ввода инструмента перед его парсингом или выполнением.

Запросы Claude Vision API

Claude Vision API использует тот же endpoint Messages. Добавьте блок изображения перед соответствующим текстовым вопросом. Изображения могут быть предоставлены в виде поддерживаемых данных base64 или через разрешённый тип источника, описанный в текущей документации по vision.

import base64
import os

from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

with open("architecture.png", "rb") as image_file:
    image_data = base64.b64encode(image_file.read()).decode("utf-8")

message = client.messages.create(
    model=os.environ["ANTHROPIC_VISION_MODEL"],
    max_tokens=700,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data,
                    },
                },
                {
                    "type": "text",
                    "text": "Identify two reliability risks in this architecture diagram.",
                },
            ],
        }
    ],
)

Изменяйте размер изображений перед отправкой. Большие изображения увеличивают время передачи и расход токенов, не обязательно улучшая ответ. Также проверяйте MIME-тип; объявление данных JPEG как PNG — частая причина отклонённых запросов.

Использование Anthropic Files API

Anthropic Files API полезен, когда файл нужно загрузить один раз и затем ссылаться на него в последующих вызовах Messages API, вместо того чтобы кодировать и передавать его повторно. Точная доступность, поддерживаемые типы файлов и поля запроса могут различаться в зависимости от статуса функции, поэтому перед использованием в production проверяйте текущую документацию Files API.

Типичная интеграция состоит из двух этапов:

1. Загрузите файл и сохраните возвращённый идентификатор файла вместе с записью документа вашего приложения.
2. Ссылайтесь на этот идентификатор в поддерживаемом блоке содержимого при создании сообщения.

Относитесь к идентификаторам файлов как к ресурсам, специфичным для провайдера. Записывайте, какой провайдер и учётная запись создали каждый ID, применяйте собственные средства контроля доступа и определяйте политику удаления. Идентификатор файла не должен приниматься напрямую от недоверенного пользователя без проверки авторизации.

Для небольших изображений, используемых время от времени, подходит base64. Для документов, используемых во многих запросах, ресурс файла провайдера может сократить количество повторных загрузок. Если ваше приложение должно работать с несколькими провайдерами, храните исходный объект в собственном хранилище и создавайте идентификаторы файлов, специфичные для провайдера, как кэш.

Использование инструментов для бэкендов агентов

Инструменты позволяют Claude запрашивать определённую вами функцию. Ваш бэкенд описывает каждый инструмент с именем, целью и контрактом ввода в виде JSON Schema. Затем модель может вернуть блок tool_use вместо того, чтобы имитировать выполнение операции.

{
  "name": "get_order_status",
  "description": "Look up the current status of a customer order.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order identifier shown to the customer."
      }
    },
    "required": ["order_id"]
  }
}

Безопасный цикл выполнения:

1. Отправьте модели сообщения и определения инструментов.
2. Обнаружьте блок содержимого tool_use.
3. Проверьте его ввод на соответствие схеме и вашим правилам авторизации.
4. Выполните инструмент в контролируемой среде.
5. Верните соответствующий блок tool_result в следующем повороте пользователя.
6. Продолжайте, пока модель не выдаст обычный ответ или не будет достигнут лимит цикла.

Никогда не выполняйте аргументы инструментов как доверенные shell, SQL или пути к файлам. Для агентов, пишущих код, запускайте сгенерированные команды внутри изолированной среды, такой как Novita Agent Sandbox, с явными ограничениями по времени, сети, файловой системе и ресурсам.

Нативные запросы Anthropic vs совместимые с OpenAI

Нативные для Anthropic и совместимые с OpenAI API решают одну и ту же общую проблему, но их форматы обмена не идентичны.

Аспект	Anthropic Messages API	OpenAI-совместимый чат API
Обычный endpoint	/v1/messages	/v1/chat/completions
Системная инструкция	Поле system верхнего уровня	Обычно сообщение system или developer
Представление вывода	Типизированные блоки содержимого	Обычно choices[].message
Запрос инструмента	Блок tool_use	Обычно tool_calls
Результат инструмента	Блок содержимого tool_result	Обычно сообщение с ролью tool

OpenAI-совместимый endpoint полезен, когда ваше приложение уже использует OpenAI SDK или ему нужно переключаться между моделями с открытым исходным кодом с минимальными изменениями транспорта. Novita AI предоставляет OpenAI-совместимый LLM API, поэтому та же структура клиента может нацеливаться на несколько доступных моделей, изменяя базовый URL и конфигурацию модели.

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NOVITA_API_KEY"],
    base_url="https://api.novita.ai/v3/openai",
)

response = client.chat.completions.create(
    model=os.environ["NOVITA_MODEL"],
    messages=[
        {
            "role": "user",
            "content": "Review this retry strategy for failure modes.",
        }
    ],
)

print(response.choices[0].message.content)

Это не является прямой заменой каждой функции Anthropic. Если ваше приложение зависит от специфичных для Anthropic блоков содержимого, семантики инструментов, цитирований или бета-функций, используйте собственный адаптер для Anthropic. Используйте общий OpenAI-совместимый путь для рабочих нагрузок, которые соответствуют его общей модели запросов.

Создание провайдер-нейтрального бэкенда агента

Провайдер-нейтральный бэкенд должен нормализовать концепции приложения, не делая вид, что все провайдеры идентичны. Практичный дизайн включает четыре слоя:

1. Модель диалога: храните роли, текст, изображения, вызовы инструментов и результаты инструментов во внутренней схеме.
2. Адаптер провайдера: преобразуйте внутреннюю схему в полезные нагрузки Anthropic Messages или OpenAI-совместимые.
3. Реестр возможностей: отслеживайте, поддерживает ли выбранная модель vision, инструменты, структурированный вывод или другие требуемые функции.
4. Слой выполнения: запускайте инструменты и код отдельно от провайдера инференса.

Такое разделение позволяет команде использовать Claude там, где важно нативное поведение Anthropic, одновременно направляя совместимые рабочие нагрузки на модель с открытым исходным кодом через Novita AI. Путь с открытым исходным кодом может быть полезен для контроля затрат, экспериментов с моделями, требований к расположению данных или для избежания зависимости от одного провайдера. Тестируйте качество вывода и надёжность инструментов на своих собственных задачах, а не предполагайте, что две модели взаимозаменяемы, потому что обе принимают чат-сообщения.

Для агентских рабочих нагрузок слой выполнения заслуживает равного внимания. Смена модели не защищает вашу инфраструктуру от небезопасных команд. Используйте изолированную песочницу, применяйте белые списки инструментов, ограничивайте количество итераций и записывайте каждое решение модели и результат инструмента, удаляя секреты.

Распространённые ошибки и отладка

400 Bad Request

Проверьте структуру JSON, типы блоков содержимого, обязательные поля и то, поддерживает ли выбранная модель запрошенную функцию. Записывайте ID запроса провайдера и структурированное тело ошибки, но скрывайте учётные данные и данные файлов в base64.

401 Authentication Error

Убедитесь, что API-ключ присутствует в среде выполнения и принадлежит предполагаемому провайдеру. Anthropic использует x-api-key для прямых HTTP-запросов; OpenAI-совместимый клиент обычно отправляет токен-носитель автоматически.

404 Model or Resource Not Found

Проверьте ID модели в текущей документации провайдера или консоли. Для ресурсов Files API также убедитесь, что файл принадлежит той же учётной записи и среде, которые используются в запросе.

429 Rate Limit

Повторите запрос с экспоненциальной задержкой и джиттером, но ограничьте количество попыток. Ставьте в очередь фоновую работу, ограничивайте параллелизм на провайдера и избегайте немедленного повторения каждого неудачного запроса с одинаковым интервалом.

Context or Token Limit Errors

Уменьшите историю диалога, размер изображения, содержимое файла или запрашиваемую длину вывода. Учитывайте весь запрос, включая системные инструкции, схемы инструментов, предыдущие результаты инструментов и мультимодальное содержимое.

Рекомендуемые статьи

• What Are Coding Agents? Architecture, Tools, and Execution Loops
• What Is MCP? A Developer’s Guide to Model Context Protocol
• Open-Source LLM Guide 2026: Models, Tradeoffs, and Deployment

Чек-лист внедрения

• Храните API-ключи, ID моделей, базовые URL и версии API в конфигурации времени выполнения.
• Разбирайте типизированные блоки содержимого вместо предположения, что это одна текстовая строка.
• Сохраняйте достаточно состояния диалога для восстановления каждого запроса без сохранения состояния.
• Проверяйте ввод инструментов и выполняйте их вне процесса модели.
• Добавляйте тайм-ауты, лимиты повторных попыток, ID запросов и наблюдаемость с удалением секретов.
• Управляйте маршрутизацией провайдера на основе возможностей модели, а не только цены или имени.
• Перепроверяйте ID моделей, статус функций, лимиты и цены перед развёртыванием.

Messages API прост на уровне HTTP. Более сложная инженерная работа возникает, когда приложение добавляет потоковую передачу, мультимодальный ввод, инструменты, постоянные файлы или несколько провайдеров моделей. Держите эти аспекты за явными адаптерами, и ваш бэкенд агента сможет развиваться, не привязывая бизнес-логику к одному формату запроса.

FAQ

Что такое endpoint Anthropic Messages API?

Нативный endpoint: POST https://api.anthropic.com/v1/messages. Запросы требуют аутентификации, заголовка версии Anthropic API, ID модели, лимита токенов и массива сообщений.

Совместим ли Anthropic Messages API с OpenAI?

Нет. Концепции пересекаются, но системные промпты, блоки содержимого, объекты ответов и сообщения об использовании инструментов различаются. Используйте адаптер провайдера, если одному приложению нужно поддерживать оба формата.

Использует ли Claude Vision API отдельный endpoint?

Нет. Запросы Vision используют Messages API с блоками изображений и текста. Выбранная модель Claude должна поддерживать ввод изображений.

Когда следует использовать Anthropic Files API?

Используйте его, когда поддерживаемые файлы нужно многократно использовать в запросах, а повторная загрузка base64 была бы расточительной. Храните исходный файл и запись авторизации, так как ID файлов провайдера являются ресурсами, специфичными для учётной записи.

Может ли Claude Code использовать пользовательский бэкенд API?

Интеграция Claude Code зависит от конфигурации аутентификации и провайдера, поддерживаемой текущим релизом Claude Code. Не предполагайте, что OpenAI-совместимый endpoint реализует Messages API от Anthropic. Для собственного агента обычно понятнее использовать провайдер-нейтральный адаптер, чем пытаться сделать разные протоколы идентичными.

Когда следует выбирать модель с открытым исходным кодом через Novita AI?

Рассмотрите этот вариант, когда вам нужно переключение между моделями, совместимыми с OpenAI, эксперименты с открытыми моделями или второй провайдер для совместимых рабочих нагрузок. Оставляйте нативные запросы Anthropic для функций, требующих специфического поведения API Claude, и оценивайте оба пути на своих собственных промптах и инструментах.