Справочник по Claude API

Сообщения

Создание сообщения

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

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

Пример запроса

curl https://api.rockapi.ru/anthropic/v1/messages \
     --header "x-api-key: $ROCKAPI_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-3-5-sonnet-20240620",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, world"}
    ]
}'

Пример ответа

{
  "content": [
    {
      "text": "Hi! My name is Claude.",
      "type": "text"
    }
  ],
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "model": "claude-3-5-sonnet-20240620",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 10,
    "output_tokens": 25
  }
}

Параметры

model (string, обязательно)

Модель, которая завершит ваш запрос.

messages (object[], обязательно)

Входные сообщения.

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

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

Если последнее сообщение имеет роль assistant, ответ продолжит контент этого сообщения. Это можно использовать для ограничения части ответа модели.

Пример с одним сообщением пользователя:

[{"role": "user", "content": "Hello, Claude"}]

Пример с несколькими диалогами:

[
  {"role": "user", "content": "Hello there."},
  {"role": "assistant", "content": "Hi, I'm Claude. How can I help you?"},
  {"role": "user", "content": "Can you explain LLMs in plain English?"}
]

Пример с частично заполненным ответом от Claude:

[
  {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
  {"role": "assistant", "content": "The best answer is ("}
]

Каждое содержимое входного сообщения может быть либо строкой, либо массивом блоков контента, где каждый блок имеет определенный тип. Использование строки для содержимого является сокращением для массива из одного блока контента типа text. Следующие входные сообщения эквивалентны:

{"role": "user", "content": "Hello, Claude"}

{"role": "user", "content": [{"type": "text", "text": "Hello, Claude"}]}

Начиная с моделей Claude 3, вы также можете отправлять блоки контента изображения:

{"role": "user", "content": [
  {
    "type": "image",
    "source": {
      "type": "base64",
      "media_type": "image/jpeg",
      "data": "/9j/4AAQSkZJRg..."
    }
  },
  {"type": "text", "text": "What is in this image?"}
]}

В настоящее время мы поддерживаем тип источника base64 для изображений и типы медиа image/jpeg, image/png, image/gif и image/webp.

Обратите внимание, что если вы хотите включить системный запрос, вы можете использовать параметр верхнего уровня system — нет роли "system" для входных сообщений в API Сообщений.

messages.role (enum<string>, обязательно)

Доступные варианты: user, assistant

messages.content (string, обязательно)

max_tokens (integer, обязательно)

Максимальное количество токенов для генерации до остановки.

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

Разные модели имеют разные максимальные значения для этого параметра. См. models для подробностей.

metadata (object)

Объект, описывающий метаданные о запросе.

metadata.user_id (string | null)

Внешний идентификатор для пользователя, связанного с запросом.

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

stop_sequences (string[])

Пользовательские текстовые последовательности, которые заставят модель остановиться.

Наши модели обычно останавливаются, когда они естественно завершают свой ход, что приведет к значению stop_reason ответа "end_turn".

Если вы хотите, чтобы модель остановилась при встрече с пользовательскими строками текста, вы можете использовать параметр stop_sequences. Если модель встретит одну из пользовательских последовательностей, значение stop_reason ответа будет "stop_sequence", и значение stop_sequence ответа будет содержать совпадающую последовательность остановки.

stream (boolean)

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

См. streaming для подробностей.

system (string)

Системный запрос.

Системный запрос — это способ предоставления контекста и инструкций Claude, например, указание конкретной цели или роли. См. наш руководство по системным запросам.

temperature (number)

Количество случайности, вводимой в ответ.

По умолчанию 1.0. Диапазон от 0.0 до 1.0. Используйте temperature ближе к 0.0 для аналитических / вопросов с множественным выбором и ближе к 1.0 для творческих и генеративных задач.

Обратите внимание, что даже при температуре 0.0 результаты не будут полностью детерминированы.

tool_choice (object)

Как модель должна использовать предоставленные инструменты. Модель может использовать конкретный инструмент, любой доступный инструмент или решать самостоятельно.

tool_choice.type (enum<string>, обязательно)

Доступные варианты: auto/any/tool

tool_choice.name (string, обязательно)

Название инструмента для использования.

tools (object[])

Определения инструментов, которые модель может использовать.

Если вы включите tools в запросе API, модель может вернуть блоки контента tool_use, которые представляют использование этих инструментов моделью. Затем вы можете запустить эти инструменты с использованием ввода инструмента, сгенерированного моделью, и затем опционально вернуть результаты обратно модели с использованием блоков контента tool_result.

Каждое определение инструмента включает:

name: Название инструмента.
description: Необязательное, но настоятельно рекомендуемое описание инструмента.
input_schema: JSON schema для формы ввода инструмента, которую модель будет создавать в блоках вывода tool_use.

Например, если вы определили tools как:

[
  {
    "name": "get_stock_price",
    "description": "Получить текущую цену акции для заданного тикера.",
    "input_schema": {
      "type": "object",
      "properties": {
        "ticker": {
          "type": "string",
          "description": "Биржевой тикер, например AAPL для Apple Inc."
        }
      },
      "required": ["ticker"]
    }
  }
]

И затем спросите модель "Какая цена на S&P 500 сегодня?", модель может сгенерировать блоки контента tool_use в ответе, как это:

[
  {
    "type": "tool_use",
    "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
    "name": "get_stock_price",
    "input": { "ticker": "^GSPC" }
  }
]

Вы затем можете запустить свой инструмент

get_stock_price с {"ticker": "^GSPC"} в качестве ввода и вернуть следующее обратно модели в последующем сообщении пользователя:

[
  {
    "type": "tool_result",
    "tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
    "content": "259.75 USD"
  }
]

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

См. наш руководство для более подробной информации.

tools.description (string)

Описание того, что делает этот инструмент.

Описания инструментов должны быть как можно более подробными. Чем больше информации имеет модель о том, что это за инструмент и как его использовать, тем лучше она будет работать. Вы можете использовать описания на естественном языке, чтобы усилить важные аспекты входного JSON-схемы инструмента.

tools.name (string, обязательно)

tools.input_schema (object, обязательно)

JSON-схема для ввода этого инструмента.

Это определяет форму ввода, которую ваш инструмент принимает и которую модель будет создавать.

tools.input_schema.type (enum<string>, обязательно)

Доступные варианты: object

tools.input_schema.properties (object | null)

Ответ

id (string, обязательно)

Уникальный идентификатор объекта.

Формат и длина идентификаторов могут меняться со временем.

type (enum<string>, по умолчанию: message, обязательно)

Тип объекта.

Для Сообщений это всегда "message".

Доступные варианты: message

role (enum<string>, по умолчанию: assistant, обязательно)

Роль в разговоре сгенерированного сообщения.

Это всегда будет "assistant".

Доступные варианты: assistant

content (object[], обязательно)

Контент, сгенерированный моделью.

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

Пример:

[{"type": "text", "text": "Hi, I'm Claude."}]

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

Например, если входные сообщения были:

[
  {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
  {"role": "assistant", "content": "The best answer is ("}
]

Тогда ответ content может быть:

[{"type": "text", "text": "B)"}]

content.type (enum<string>, по умолчанию: text, обязательно)

Доступные варианты: text

content.text (string, обязательно)

model (string, обязательно)

Модель, обработавшая запрос.

stop_reason (enum<string> | null, обязательно)

Причина остановки.

Это может быть одно из следующих значений:

"end_turn": модель достигла естественной точки остановки
"max_tokens": мы превысили запрашиваемые max_tokens или максимальные значения модели
"stop_sequence": была сгенерирована одна из ваших пользовательских последовательностей остановки
"tool_use": модель использовала один или несколько инструментов

В режиме без потоковой передачи это значение всегда не-null. В режиме потоковой передачи оно null в событии message_start и не-null в остальных случаях.

Доступные варианты: end_turn, max_tokens, stop_sequence, tool_use

stop_sequence (string | null, обязательно)

Какая пользовательская последовательность остановки была сгенерирована, если таковая имелась.

Это значение будет непустой строкой, если была сгенерирована одна из ваших пользовательских последовательностей остановки.

usage (object, обязательно)

Использование для биллинга и ограничения по скорости.

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

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

Например, output_tokens будет ненулевым, даже для пустого строкового ответа от Claude.

usage.input_tokens (integer, обязательно)

Количество входных токенов, которые были использованы.

usage.output_tokens (integer, обязательно)

Количество выходных токенов, которые были использованы.

Потоковая передача сообщений

При создании Сообщения вы можете установить "stream": true, чтобы инкрементально потоково отправлять ответ с использованием событий, отправляемых сервером (SSE).

Потоковая передача с использованием SDK

Наши Python и Typescript SDK предлагают несколько способов потоковой передачи. Python SDK поддерживает как синхронные, так и асинхронные потоки. См. документацию в каждом SDK для подробностей.

import anthropic

client = anthropic.Anthropic(
    api_key="$ROCKAPI_API_KEY",
    base_url="https://api.rockapi.ru/anthropic"
)

with client.messages.stream(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
    model="claude-3-5-sonnet-20240620",
) as stream:
  for text in stream.text_stream:
      print(text, end="", flush=True)

Типы событий

Каждое событие, отправляемое сервером, включает именованный тип события и ассоциированные JSON данные. Каждое событие будет использовать имя события SSE (например, event: message_stop), и включать соответствующий тип события в его данных.

Каждый поток использует следующий порядок событий:

message_start: содержит объект Message с пустым content.
Серия блоков контента, каждый из которых имеет события content_block_start, одно или более событий content_block_delta и событие content_block_stop. Каждый блок контента будет иметь index, который соответствует его индексу в окончательном массиве content сообщения.
Одно или несколько событий message_delta, указывающих изменения верхнего уровня в окончательном объекте Message.
Окончательное событие message_stop.

Пинг-события

Потоки событий могут также включать любое количество событий ping.

Ошибки событий

Мы можем время от времени отправлять ошибки в потоке событий. Например, в периоды высокой нагрузки, вы можете получить overloaded_error, что обычно соответствует HTTP 529 в контексте без потоковой передачи:

event: error
data: {"type": "error", "error": {"type": "overloaded_error", "message": "Overloaded"}}

Другие события

В соответствии с нашей политикой версионирования, мы можем добавлять новые типы событий, и ваш код должен обрабатывать неизвестные типы событий корректно.

Типы дельт

Каждое событие content_block_delta содержит delta типа, который обновляет блок content по заданному index.

Текстовая дельта

Текстовый блок контента delta

выглядит следующим образом:

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "ello frien"}}

JSON-дельта ввода

Дельты для блоков контента tool_use соответствуют обновлениям для поля input блока. Для поддержки максимальной гранулярности дельты являются частичными строками JSON, тогда как окончательный tool_use.input всегда является объектом.

Вы можете аккумулировать строковые дельты и парсить JSON, как только вы получите событие content_block_stop, используя библиотеку типа Pydantic для частичного парсинга JSON или используя наши SDK, которые предоставляют помощников для доступа к инкрементальным значениям.

Дельта блока контента tool_use выглядит следующим образом:

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"location\": \"San Fra"}}

Примечание: наши текущие модели поддерживают только

выдачу одного полного ключа и значения свойства из input за раз. Таким образом, при использовании инструментов могут возникать задержки между событиями потоковой передачи, пока модель работает. Как только ключ и значение из input аккумулированы, мы выдаем их как несколько событий content_block_delta с частичными json, чтобы формат мог автоматически поддерживать более тонкую гранулярность в будущих моделях.

Ответ потока HTTP

Мы настоятельно рекомендуем использовать наши клиентские SDK при использовании режима потоковой передачи. Однако, если вы создаете прямую интеграцию API, вам придется обрабатывать эти события самостоятельно.

Ответ потока состоит из:

Событие message_start
Потенциально несколько блоков контента, каждый из которых содержит: a. Событие content_block_start b. Потенциально несколько событий content_block_delta c. Событие content_block_stop
Событие message_delta
Событие message_stop

Могут быть разбросаны ping события по всему ответу. См. Типы событий для более подробной информации о формате.

Основной потоковый запрос

curl https://api.rockapi.ru/anthropic/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $ROCKAPI_API_KEY" \
     --data '{
  "model": "claude-3-5-sonnet-20240620",
  "messages": [{"role": "user", "content": "Hello"}],
  "max_tokens": 256,
  "stream": true
}'

Ответ

event: message_start
data: {"type": "message_start", "message": {"id": "msg_1nZdL29xx5MUA1yADyHTEsnR8uuvGzszyY", "type": "message", "role": "assistant", "content": [], "model": "claude-3-5-sonnet-20240620", "stop_reason": null, "stop_sequence": null, "usage": {"input_tokens": 25, "output_tokens": 1}}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

event: ping
data: {"type": "ping"}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "Hello"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "!"}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}, "usage": {"output_tokens": 15}}

event: message_stop
data: {"type": "message_stop"}

Потоковый запрос с использованием инструментов

В этом запросе мы просим Claude использовать инструмент, чтобы сообщить нам погоду.

curl https://api.rockapi.ru/anthropic/v1/messages \
    -H "content-type: application/json" \
    -H "x-api-key: $ROCKAPI_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -d '{
      "model": "claude-3-5-sonnet-20240620",
      "max_tokens": 1024,
      "tools": [
        {
          "name": "get_weather",
          "description": "Узнать текущую погоду в заданном месте",
          "input_schema": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "Город и штат, например, Сан-Франциско, Калифорния"
              }
            },
            "required": ["location"]
          }
        }
      ],
      "tool_choice": {"type": "any"},
      "messages": [
        {
          "role": "user",
          "content": "What is the weather like in San Francisco?"
        }
      ],
      "stream": true
    }'

Ответ

event: message_start
data: {"type":"message_start","message":{"id":"msg_014p7gG3wDgGV9EUtLvnow3U","type":"message","role":"assistant","model":"claude-3-haiku-20240307","stop_sequence":null,"usage":{"input_tokens":472,"output_tokens":2},"content":[],"stop_reason":null}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: ping
data: {"type":"ping"}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Okay"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" let"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"'s"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" check"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" the"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" weather"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" for"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" San"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Francisco"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":","}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" CA"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":":"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"toolu_01T1x1fJ34qAmk2tNTrN7Up6","name":"get_weather","input":{}}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"location\":"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" \"San"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" Francisc"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"o,"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":" CA\""}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":", "}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\"unit\": \"fah"}}

event: content_block_delta
data: {"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"renheit\"}"}}

event: content_block_stop
data: {"type":"content_block_stop","index":1}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":89}}

event: message_stop
data: {"type":"message_stop"}

Переход с Text Completions на Messages

При переходе с Text Completions на Messages, учитывайте следующие изменения.

Входы и выходы

Самое большое

изменение между Text Completions и Messages - это способ, которым вы указываете входы модели и получаете выходы от модели.

С Text Completions входы представляют собой сырые строки:

prompt = "\n\nHuman: Hello there\n\nAssistant: Hi, I'm Claude. How can I help?\n\nHuman: Can you explain Glycolysis to me?\n\nAssistant:"

С Messages вы указываете список входных сообщений вместо сырого запроса:

messages = [
  {"role": "user", "content": "Hello there."},
  {"role": "assistant", "content": "Hi, I'm Claude. How can I help?"},
  {"role": "user", "content": "Can you explain Glycolysis to me?"},
]

Каждое входное сообщение имеет role и content.

API Text Completions ожидает чередование \n\nHuman: и \n\nAssistant: ходов, но API Messages ожидает роли user и assistant. Вы можете увидеть документацию, ссылающуюся на либо "human", либо "user" ходы. Это ссылается на ту же роль, и в дальнейшем будет использоваться "user".

С Text Completions, сгенерированный текст модели возвращается в значениях completion ответа:

>>> response = anthropic.completions.create(...)
>>> response.completion
" Hi, I'm Claude"

С Messages ответ - это значение content, которое является списком блоков контента:

>>> response = anthropic.messages.create(...)
>>> response.content
[{"type": "text", "text": "Hi, I'm Claude"}]

Подставляем слова в уста Claude

С Text Completions вы можете предварительно заполнить часть ответа Claude:

prompt = "\n\nHuman: Hello\n\nAssistant: Hello, my name is"

С Messages вы можете добиться того же результата, сделав последнее входное сообщение с ролью assistant:

messages = [
  {"role": "human", "content": "Hello"},
  {"role": "assistant", "content": "Hello, my name is"},
]

При этом, контент ответа продолжится с последнего входного сообщения:

{
  "role": "assistant",
  "content": [{"type": "text", "text": " Claude. How can I assist you today?"}],
  ...
}

Системный запрос

С Text Completions, системный запрос указывается добавлением текста перед первым ходом \n\nHuman::

prompt = "Today is January 1, 2024.\n\nHuman: Hello, Claude\n\nAssistant:"

С Messages вы указываете системный запрос с параметром system:

anthropic.Anthropic().messages.create(
    model="claude-3-opus-20240229",
    max_tokens=1024,
    system="Today is January 1, 2024.", ## <-- системный запрос
    messages=[
        {"role": "user", "content": "Hello, Claude"}
    ]
)

Названия моделей

API Messages требует, чтобы вы указали полную версию модели (например, claude-3-opus-20240229).

Ранее мы поддерживали указание только основного номера версии (например, claude-2), что приводило к автоматическому обновлению до минорных версий. Однако, мы больше не рекомендуем этот шаблон интеграции, и Messages не поддерживает его.

Причина остановки

Text Completions всегда имеют stop_reason либо:

"stop_sequence": Модель либо завершила свой ход естественным образом, либо была сгенерирована одна из ваших пользовательских последовательностей остановки.
"max_tokens": Либо модель сгенерировала запрашиваемое вами количество max_tokens контента, либо достигла своего абсолютного максимума.

Messages имеют stop_reason одного из следующих значений:

"end_turn": Диалоговый ход завершился естественным образом.
"stop_sequence": Была сгенерирована одна из ваших пользовательских последовательностей остановки.
"max_tokens": (без изменений)

Указание максимального количества токенов

Text Completions: параметр max_tokens_to_sample. Нет валидации, но ограниченные значения для каждой модели.
Messages: параметр max_tokens. Если передается значение, превышающее поддерживаемое моделью, возвращается ошибка валидации.

Формат потоковой передачи

При использовании "stream": true в Text Completions, ответ включал любое из completion, ping и error событий, отправляемых сервером. См. Text Completions streaming для подробностей.

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

Примеры сообщений

Примеры запросов и ответов для API Сообщений

См. Справочник по API для полной документации по доступным параметрам.

Основной запрос и ответ

#!/bin/sh
curl https://api.rockapi.ru/anthropic/v1/messages \
     --header "x-api-key: $ROCKAPI_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data '{
    "model": "claude-3-5-sonnet-20240620",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}'

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "model": "claude-3-5-sonnet-20240620",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 6
  }
}

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

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

#!/bin/sh
curl https://api.rockapi.ru/anthropic/v1/messages \
     --header "x-api-key: $ROCKAPI_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data '{
    "model": "claude-3-5-sonnet-20240620",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"},
        {"role": "assistant", "content": "Hello!"},
        {"role": "user", "content": "Can you describe LLMs to me?"}
    ]
}'

{
    "id": "msg_018gCsTGsXkYJVqYPxTgDHBU",
    "type": "message",
    "role": "assistant",
    "content": [
        {
            "type": "text",
            "text": "Sure, I'd be happy to provide..."
        }
    ],
    "stop_reason": "end_turn",
    "stop_sequence": null,
    "usage": {
        "input_tokens": 30,
        "output_tokens": 309
    }
}

Подставляем слова в уста Claude

Вы можете предварительно заполнить часть ответа Claude в последней позиции списка входных сообщений. Это можно использовать для формирования ответа Claude. Пример ниже использует "max_tokens": 1, чтобы получить один ответ с множественным выбором от Claude.

#!/bin/sh
curl https://api.rockapi.ru/anthropic/v1/messages \
     --header "x-api-key: $ROCKAPI_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data '{
    "model": "claude-3-5-sonnet-20240620",
    "max_tokens": 1,
    "messages": [
        {"role": "user", "content": "What is latin for Ant? (A) Apoidea, (B) Rhopalocera, (C) Formicidae"},


        {"role": "assistant", "content": "The answer is ("}
    ]
}'

{
  "id": "msg_01Q8Faay6S7QPTvEUUQARt7h",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "C"
    }
  ],
  "model": "claude-3-5-sonnet-20240620",
  "stop_reason": "max_tokens",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 42,
    "output_tokens": 1
  }
}

Вижн

Claude может читать как текст, так и изображения в запросах. В настоящее время мы поддерживаем тип источника base64 для изображений и типы медиа image/jpeg, image/png, image/gif и image/webp. См. наш вижн гид для более подробной информации.

#!/bin/sh

IMAGE_URL="https://upload.wikimedia.org/wikipedia/commons/a/a7/Camponotus_flavomarginatus_ant.jpg"
IMAGE_MEDIA_TYPE="image/jpeg"
IMAGE_BASE64=$(curl "$IMAGE_URL" | base64)

curl https://api.rockapi.ru/anthropic/v1/messages \
     --header "x-api-key: $ROCKAPI_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data '{
    "model": "claude-3-5-sonnet-20240620",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": [
            {"type": "image", "source": {
                "type": "base64",
                "media_type": "'$IMAGE_MEDIA_TYPE'",
                "data": "'$IMAGE_BASE64'"
            }},
            {"type": "text", "text": "What is in the above image?"}
        ]}
    ]
}'

{
  "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-3-5-sonnet-20240620",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1551,
    "output_tokens": 71
  }
}

Использование инструментов и JSON-режим

См. наш руководство для примеров того, как использовать инструменты с API Сообщений.

Справочник по Claude API

Сообщения​

Создание сообщения​

Пример запроса​

Пример ответа​

Параметры​

model (string, обязательно)​

messages (object[], обязательно)​

messages.role (enum<string>, обязательно)​

messages.content (string, обязательно)​

max_tokens (integer, обязательно)​

metadata (object)​

metadata.user_id (string | null)​

stop_sequences (string[])​

stream (boolean)​

system (string)​

temperature (number)​

tool_choice (object)​

tool_choice.type (enum<string>, обязательно)​

tool_choice.name (string, обязательно)​

tools (object[])​

tools.description (string)​

tools.name (string, обязательно)​

tools.input_schema (object, обязательно)​

tools.input_schema.type (enum<string>, обязательно)​

tools.input_schema.properties (object | null)​

Ответ​

id (string, обязательно)​

type (enum<string>, по умолчанию: message, обязательно)​

role (enum<string>, по умолчанию: assistant, обязательно)​

content (object[], обязательно)​

content.type (enum<string>, по умолчанию: text, обязательно)​

content.text (string, обязательно)​

model (string, обязательно)​

stop_reason (enum<string> | null, обязательно)​

stop_sequence (string | null, обязательно)​

usage (object, обязательно)​

usage.input_tokens (integer, обязательно)​

usage.output_tokens (integer, обязательно)​

Потоковая передача сообщений​

Потоковая передача с использованием SDK​

Типы событий​

Пинг-события​

Ошибки событий​

Другие события​

Типы дельт​

Текстовая дельта​

JSON-дельта ввода​

Ответ потока HTTP​

Основной потоковый запрос​

Ответ​

Потоковый запрос с использованием инструментов​

Ответ​

Переход с Text Completions на Messages​

Входы и выходы​

Подставляем слова в уста Claude​

Системный запрос​

Названия моделей​

Причина остановки​

Указание максимального количества токенов​

Формат потоковой передачи​

Примеры сообщений​

Основной запрос и ответ​

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

Подставляем слова в уста Claude​

Вижн​

Использование инструментов и JSON-режим​

Сообщения

Создание сообщения

Пример запроса

Пример ответа

Параметры

model (string, обязательно)

messages (object[], обязательно)

messages.role (enum<string>, обязательно)

messages.content (string, обязательно)

max_tokens (integer, обязательно)

metadata (object)

metadata.user_id (string | null)

stop_sequences (string[])

stream (boolean)

system (string)

temperature (number)

tool_choice (object)

tool_choice.type (enum<string>, обязательно)

tool_choice.name (string, обязательно)

tools (object[])

tools.description (string)

tools.name (string, обязательно)

tools.input_schema (object, обязательно)

tools.input_schema.type (enum<string>, обязательно)

tools.input_schema.properties (object | null)

Ответ

id (string, обязательно)

type (enum<string>, по умолчанию: message, обязательно)

role (enum<string>, по умолчанию: assistant, обязательно)

content (object[], обязательно)

content.type (enum<string>, по умолчанию: text, обязательно)

content.text (string, обязательно)

model (string, обязательно)

stop_reason (enum<string> | null, обязательно)

stop_sequence (string | null, обязательно)

usage (object, обязательно)

usage.input_tokens (integer, обязательно)

usage.output_tokens (integer, обязательно)

Потоковая передача сообщений

Потоковая передача с использованием SDK

Типы событий

Пинг-события

Ошибки событий

Другие события

Типы дельт

Текстовая дельта

JSON-дельта ввода

Ответ потока HTTP

Основной потоковый запрос

Ответ

Потоковый запрос с использованием инструментов

Ответ

Переход с Text Completions на Messages

Входы и выходы

Подставляем слова в уста Claude

Системный запрос

Названия моделей

Причина остановки

Указание максимального количества токенов

Формат потоковой передачи

Примеры сообщений

Основной запрос и ответ

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

Подставляем слова в уста Claude

Вижн

Использование инструментов и JSON-режим