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

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

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

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

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

В Claude Opus 4.7 и более поздних моделях ответы с отказом (stop_reason: "refusal") также включают объект stop_details, указывающий категорию политики, которая вызвала отказ. См. раздел Обработка причин остановки для справки по полям и примера кода обработки.

Несколько ходов диалога

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

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

Системная роль в сообщениях

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

Системное сообщение в середине диалога имеет тот же приоритет, что и поле верхнего уровня 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 httpx

# Вариант 1: изображение в кодировке Base64
image_url = "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
image_media_type = "image/jpeg"
image_data = base64.standard_b64encode(httpx.get(image_url).content).decode("utf-8")

message = anthropic.Anthropic().messages.create(
    model="claude-opus-4-8",
    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-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg",
                    },
                },
                {"type": "text", "text": "What is in the above image?"},
            ],
        }
    ],
)
print(message_from_url)

{
  "id": "msg_01EcyWo6m4hyW8KHs2y2pei5",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "This image shows an ant, specifically a close-up view of an ant. The ant is shown in detail, with its distinct head, antennae, and legs clearly visible. The image is focused on capturing the intricate details and features of the ant, likely taken with a macro lens to get an extreme close-up perspective."
    }
  ],
  "model": "claude-opus-4-8",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1551,
    "output_tokens": 71
  }
}

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

См. руководство по использованию инструментов для примеров того, как использовать инструменты с Messages API. См. руководство по управлению компьютером для примеров того, как управлять средами настольных компьютеров с помощью Messages API. Для гарантированного вывода в формате JSON см. раздел Структурированные выходные данные. Для рекомендательного бюджета токенов на протяжении всего агентного цикла установите output_config.task_budget; см. раздел Бюджеты задач.