Использование Messages API
Практические шаблоны и примеры для эффективного использования Messages API
Anthropic предлагает два способа создания решений с Claude, каждый из которых подходит для разных сценариев использования:
| Messages API | Claude Managed Agents | |
|---|---|---|
| Что это | Прямой доступ к отправке подсказок модели | Готовая настраиваемая агентная обвязка, работающая в управляемой инфраструктуре |
| Лучше всего подходит для | Пользовательских агентных циклов и детального контроля | Длительных задач и асинхронной работы |
В этом руководстве рассматриваются распространённые шаблоны работы с Messages API, включая базовые запросы, многоходовые диалоги, техники предварительного заполнения (prefill) и возможности компьютерного зрения (vision). Полные спецификации API см. в справочнике по Messages APIДоступен предпросмотр со ссылками на справочник API — нажимайте Tab, пока фокус не перейдет на карточку; чтобы вернуться, нажмите Escape.. Если вам нужна управляемая среда для агентов, см. обзор Claude Managed Agents.
Базовый запрос и ответ
message = anthropic.Anthropic().messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": "Hello, Claude"}],
)
print(message){
"id": "msg_01XFDUDYJgAACzvnptvVoYEL",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Hello!"
}
],
"model": "claude-opus-5-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 12,
"output_tokens": 6
}
}Ответы с отказом (stop_reason: "refusal") также содержат объект stop_details, указывающий категорию политики, которая вызвала отказ, — для всех моделей. Справочные сведения о поле и пример кода обработки см. в разделе Как выглядит отказ.
Несколько ходов диалога
Messages API не сохраняет состояние (stateless), поэтому вы всегда отправляете в API полную историю диалога. Этот шаблон можно использовать для постепенного построения диалога. Предыдущие ходы диалога не обязательно должны действительно исходить от Claude. Вы можете использовать синтетические сообщения assistant.
С помощью веток сообщений, находящихся в бета-версии, API может хранить диалог, так что каждый последующий запрос отправляет только новые сообщения. Срок действия ветки истекает через 5 минут после последнего запроса, и она удаляется не позднее чем через 1 час после последнего использования.
message = anthropic.Anthropic().messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{"role": "user", "content": "Hello, Claude"},
{"role": "assistant", "content": "Hello!"},
{"role": "user", "content": "Can you describe LLMs to me?"},
],
)
print(message){
"id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "Sure, I'd be happy to provide..."
}
],
"model": "claude-opus-5-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 30,
"output_tokens": 309
}
}Системная роль в сообщениях
Чтобы добавить новую системную инструкцию посреди диалога, включите сообщение с "role": "system" сразу после хода пользователя. Такое сообщение не может быть первым элементом в messages. Это работает в Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Sonnet 5.5 и Claude Haiku 5.5. См. полные правила размещения.
Системное сообщение посреди диалога имеет те же полномочия, что и поле верхнего уровня system, но поскольку оно добавляется в конец истории сообщений, оно не делает недействительным кэшированный префикс, предшествующий ему. Используйте поле верхнего уровня system для инструкций, которые должны применяться с самого первого хода, а системное сообщение посреди диалога — для инструкций, которые становятся актуальными лишь позднее.
Полное руководство, включая сведения о том, как сочетать эту возможность с кэшированием подсказок, см. в разделе Системные сообщения и изменения инструментов в середине разговора.
Предварительное заполнение ответа Claude
Вы можете предварительно заполнить часть ответа Claude в последней позиции списка входных сообщений. Используйте эту технику, чтобы задать форму ответа Claude. В следующем примере используется "max_tokens": 1, чтобы получить от Claude единственный ответ на вопрос с несколькими вариантами.
message = anthropic.Anthropic().messages.create(
model="claude-sonnet-4-5",
max_tokens=1,
messages=[
{
"role": "user",
"content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae",
},
{"role": "assistant", "content": "The answer is ("},
],
)
print(message){
"id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "C"
}
],
"model": "claude-sonnet-4-5",
"stop_reason": "max_tokens",
"stop_sequence": null,
"usage": {
"input_tokens": 42,
"output_tokens": 1
}
}Компьютерное зрение
Claude может читать в запросах как текст, так и изображения. Вы можете передавать изображения с помощью типов источника base64, url или file. Тип источника file ссылается на изображение, загруженное через Files API. Поддерживаемые типы медиа: image/jpeg, image/png, image/gif и image/webp. Подробнее см. в руководстве Компьютерное зрение.
import base64
import httpx2
# Вариант 1: изображение в кодировке base64
image_url = "https://platform.claude.com/docs/images/vision-example.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx2.get(image_url).content).decode("utf-8")
message = anthropic.Anthropic().messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": image_media_type,
"data": image_data,
},
},
{"type": "text", "text": "What is in the above image?"},
],
}
],
)
print(message)
# Вариант 2: изображение по ссылке URL
message_from_url = anthropic.Anthropic().messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "url",
"url": "https://platform.claude.com/docs/images/vision-example.jpg",
},
},
{"type": "text", "text": "What is in the above image?"},
],
}
],
)
print(message_from_url){
"id": "msg_011CdKmWtV3oFx1C5yUbf5CY",
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "This image is a beautiful minimalist/flat-design illustration of a sunset landscape. Here's what it contains:\n\n**Sky & Sun:**\n- A warm gradient sky transitioning from golden-yellow at the top to deep orange toward the horizon\n- A large pale yellow sun positioned in the upper-right area\n\n**Birds:**\n- Three small silhouetted birds flying in the upper-left portion of the sky, depicted as simple \"M\" or \"v\" shapes\n\n**Mountains:**\n- Multiple layered mountain peaks in purple and maroon tones\n- The mountains overlap to create depth, with varying shades of dusty purple and deep burgundy\n\n**Water:**\n- A dark purple body of water at the bottom of the image\n- A reflection of the sun shown as horizontal cream/peach colored lines in the center-bottom area\n\nThe overall style is clean, geometric, and uses a warm sunset color palette (oranges, yellows, purples, and maroons), giving it a peaceful, serene aesthetic typical of modern vector/flat design artwork."
}
],
"model": "claude-opus-5-5",
"stop_reason": "end_turn",
"stop_sequence": null,
"usage": {
"input_tokens": 1030,
"output_tokens": 350
}
}Следующие шаги
Обрабатывайте каждое значение stop_reason и решайте, что делать, когда ответ завершается.
Предоставьте Claude инструменты для вызова внешних сервисов и API из Messages API.
Управляйте средами настольного компьютера с помощью Messages API.
Позвольте Claude переходить по веб-страницам, читать их и взаимодействовать с ними в запущенном вами браузере.
Получайте от Claude гарантированный JSON-вывод, проверенный по схеме.
Задайте рекомендательный бюджет токенов на весь агентный цикл с помощью output_config.task_budget.
Доступность
Claude API
- Модели
- Все модели
Amazon Bedrock
- Модели
- Все модели
Amazon Bedrock (bedrock-runtime)
- Модели
- Все модели
Claude Platform on AWS
- Модели
- Все модели
Claude Models on Google Cloud (Anthropic managed)
- Модели
- Все модели
Claude Models on Google Cloud (Google managed)
- Модели
- Все модели
Microsoft Foundry
- Модели
- Все модели
Обработка данных
Обзор обработки данныхПрименимые конечные точки
/v1/messages
Кроме Охватываемые модели
Стандартные вызовы API для генерации ответов Claude.
Эта страница была полезной?