Использование 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
  }
}



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

В 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
  }
}



Дальнейшие шаги