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

Anthropic предлагает два способа создания решений с Claude, каждый из которых подходит для разных сценариев использования:

В этом руководстве рассматриваются распространённые паттерны работы с Messages API, включая базовые запросы, многоходовые диалоги, техники предзаполнения и возможности компьютерного зрения. Полные спецификации API см. в справочнике Messages API. Если вместо этого вам нужна управляемая агентная среда, см. обзор Claude Managed Agents.

Базовый запрос и ответ

message = anthropic.Anthropic().messages.create(
    model="claude-opus-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",
  "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.

message = anthropic.Anthropic().messages.create(
    model="claude-opus-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",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 30,
    "output_tokens": 309
  }
}

Роль system в сообщениях

В Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 4.8 и Claude Opus 5 вы можете включать сообщения с "role": "system" после хода пользователя (с учётом правил размещения), чтобы добавить новую системную инструкцию в середине диалога. Сообщение system не может быть первой записью в messages. Для инструкций, которые действуют с самого начала, используйте поле верхнего уровня system.

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

Полное руководство, включая способы сочетания с кэшированием подсказок (prompt caching), см. в разделе Системные сообщения в середине диалога.

Предзаполнение ответа 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",
    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",
    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",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1030,
    "output_tokens": 350
  }
}

Следующие шаги