Формат диалога Anthropic (Messages)
Официальная документация
📝 Введение
Учитывая набор структурированных списков входных сообщений, содержащих текст и/или изображение, модель генерирует следующее сообщение в диалоге. API сообщений можно использовать для одного запроса или для многоходовых диалогов без сохранения состояния.
💡 Пример запроса
Базовый текстовый разговор ✅
curl https://api.88api.ai/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: $API_KEY" \
--data \
'{
"model": "claude-sonnet-5-5",
"max_tokens": 1024,
"messages": [
{"role": "user", "content": "Hello, world"}
]
}'Пример ответа:
{
"content": [
{
"text": "Hi! My name is Claude.",
"type": "text"
}
],
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-sonnet-5-5",
"role": "assistant",
"stop_reason": "end_turn",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 2095,
"output_tokens": 503
}
}Диалог анализа изображения ✅
curl https://api.88api.ai/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: $API_KEY" \
--data \
'{
"model": "claude-sonnet-5-5",
"messages": [
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/jpeg",
"data": "/9j/4AAQSkZJRg..."
}
},
{
"type": "text",
"text": "Что на этой картинке?"
}
]
}
]
}'Пример ответа:
{
"content": [
{
"text": "这张图片显示了一只橙色的猫咪正在窗台上晒太阳。猫咪看起来很放松,眯着眼睛享受阳光。窗外可以看到一些绿色的植物。",
"type": "text"
}
],
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-sonnet-5-5",
"role": "assistant",
"stop_reason": "end_turn",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 3050,
"output_tokens": 892
}
}Вызов инструмента ✅
curl https://api.88api.ai/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: $API_KEY" \
--data \
'{
"model": "claude-sonnet-5-5",
"messages": [
{
"role": "user",
"content": "Какая сегодня погода в Пекине??"
}
],
"tools": [
{
"name": "get_weather",
"description": "Получить текущую погоду для указанного места",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "название города,нравиться:Пекин"
}
},
"required": ["location"]
}
}
]
}'Пример ответа:
{
"content": [
{
"type": "tool_use",
"id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"name": "get_weather",
"input": { "location": "Пекин" }
}
],
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-sonnet-5-5",
"role": "assistant",
"stop_reason": "tool_use",
"stop_sequence": null,
"type": "message",
"usage": {
"input_tokens": 2156,
"output_tokens": 468
}
}Ответ в потоковом режиме ✅
curl https://api.88api.ai/v1/messages \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--header "x-api-key: $API_KEY" \
--data \
'{
"model": "claude-sonnet-5-5",
"messages": [
{
"role": "user",
"content": "рассказать историю"
}
],
"stream": true
}'Пример ответа:
{
"type": "message_start",
"message": {
"id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
"model": "claude-sonnet-5-5",
"role": "assistant",
"type": "message"
}
}
{
"type": "content_block_start",
"index": 0,
"content_block": {
"type": "text"
}
}
{
"type": "content_block_delta",
"index": 0,
"delta": {
"text": "Давным-давно"
}
}
{
"type": "content_block_delta",
"index": 0,
"delta": {
"text": "есть один"
}
}
{
"type": "content_block_delta",
"index": 0,
"delta": {
"text": "кролик..."
}
}
{
"type": "content_block_stop",
"index": 0
}
{
"type": "message_delta",
"delta": {
"stop_reason": "end_turn",
"usage": {
"input_tokens": 2045,
"output_tokens": 628
}
}
}
{
"type": "message_stop"
}📮 Запрос
Конечная точка
POST /v1/messagesМетод аутентификации
Включите в заголовок запроса для аутентификации ключа API следующее:
x-api-key: $API_KEYГде $API_KEY — ваш токен 88API, который можно создать на странице токенов в консоли 88API.
Параметры заголовка запроса
anthropic-beta
- Тип: строка
- Обязательно: Нет
Укажите используемую бета-версию, поддерживающую список, разделенный запятыми, например beta1,beta2, или указав этот заголовок запроса несколько раз.
anthropic-version
- Тип: строка
- Обязательно: Да
Укажите версию API, которую следует использовать.
Параметры тела запроса
max_tokens
- Тип: целое число
- Обязательно: Да
Максимальное количество сгенерированных токенов. Разные модели имеют разные ограничения, подробности см. в документации модели. Диапазон x > 1.
messages
- Тип: массив объектов.
- Обязательно: Да
Войдите в список сообщений. Модель обучена чередовать разговоры между пользователем и помощником. При создании нового сообщения вы можете указать предыдущий ход разговора с помощью параметра messages, и модель сгенерирует следующее сообщение в разговоре. Последовательные сообщения пользователя или помощника объединяются в один ход.
Каждое сообщение должно содержать поля role и content. Вы можете указать одно сообщение роли пользователя или включить несколько сообщений пользователя и помощника. Если последнее сообщение использует вспомогательную роль, содержимое ответа будет продолжаться непосредственно из содержимого этого сообщения, что можно использовать для ограничения ответа модели.
Пример сообщения для одного пользователя:
[{ "role": "user", "content": "Hello, Claude" }]Пример нескольких раундов диалога:
[
{ "role": "user", "content": "你好。" },
{ "role": "assistant", "content": "你好!我是 Claude。有什么可以帮你的吗?" },
{ "role": "user", "content": "请用简单的话解释什么是 LLM?" }
]Пример частично заполненного ответа:
[
{
"role": "user",
"content": "Как по-гречески называется солнце?? (A) Sol (B) Helios (C) Sun"
},
{ "role": "assistant", "content": "Правильный ответ (" }
]Содержимое каждого сообщения может быть строкой или массивом блоков содержимого. Использование строки — это сокращение массива блоков контента типа «текст». Следующие два способа записи эквивалентны:
{ "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": "Что на этой картинке?"
}
]
}В настоящее время поддерживаются следующие форматы изображений: base64, image/jpeg, image/png, image/gif и image/webp.
messages.role
- Тип: строка перечисления.
- Обязательно: Да
- Необязательные значения: пользователь, помощник.
Примечание. В API сообщений нет «системной» роли. Если вам нужны системные подсказки, используйте системный параметр верхнего уровня.
messages.content
- Тип: строка или массив объектов.
- Обязательно: Да
Содержимое сообщения может быть одного из следующих типов:
Текстовое содержимое (Текст)
{
"type": "text", // 必需,枚举值: "text"
"text": "Hello, Claude", // 必需,最小长度: 1
"cache_control": {
"type": "ephemeral" // 可选,枚举值: "ephemeral"
}
}Содержимое изображения (Изображение)
{
"type": "image", // 必需,枚举值: "image"
"source": {
// необходимый
"type": "base64", // 必需,枚举值: "base64"
"media_type": "image/jpeg", // 必需,支持: image/jpeg, image/png, image/gif, image/webp
"data": "/9j/4AAQSkZJRg..." // 必需,base64 编码的图片数据
},
"cache_control": {
"type": "ephemeral" // 可选,枚举值: "ephemeral"
}
}Использование инструмента
{
"type": "tool_use", // 必需,枚举值: "tool_use",默认值
"id": "toolu_xyz...", // 必需,工具使用的唯一标识符
"name": "get_weather", // 必需,工具名称,最小长度: 1
"input": {
// 必需,工具的输入参数对象
// 工具输入参数,具体格式由工具的 input_schema 定义
},
"cache_control": {
"type": "ephemeral" // 可选,枚举值: "ephemeral"
}
}Результат инструмента
{
"type": "tool_result", // 必需,枚举值: "tool_result"
"tool_use_id": "toolu_xyz...", // необходимый
"content": "结果内容", // 必需,可以是字符串或内容块数组
"is_error": false, // 可选,布尔值
"cache_control": {
"type": "ephemeral" // 可选,枚举值: "ephemeral"
}
}Когда контент представляет собой массив блоков контента, каждый блок контента может быть текстом или изображением:
{
"type": "tool_result",
"tool_use_id": "toolu_xyz...",
"content": [
{
"type": "text", // 必需,枚举值: "text"
"text": "分析结果", // 必需,最小长度: 1
"cache_control": {
"type": "ephemeral" // 可选,枚举值: "ephemeral"
}
},
{
"type": "image", // 必需,枚举值: "image"
"source": {
// необходимый
"type": "base64", // 必需,枚举值: "base64"
"media_type": "image/jpeg",
"data": "..."
},
"cache_control": {
"type": "ephemeral"
}
}
]
}Документ
{
"type": "document", // 必需,枚举值: "document"
"source": {
// необходимый
// Исходные данные документа
},
"cache_control": {
"type": "ephemeral" // 可选,枚举值: "ephemeral"
}
}Примечание:
- Каждый тип может содержать необязательное поле
cache_controlдля управления поведением кэширования контента. - Минимальная длина текстового контента – 1.
- Поле типа всех типов является обязательной строкой перечисления.
- Поле содержимого результатов инструмента поддерживает строки или массивы блоков контента, содержащие текст/изображения.
model
- Тип: строка
- Обязательно: Да
Имя используемой модели, как подробно описано в документации модели. Диапазон символов 1 - 256.
metadata
- Тип: Объект
- Обязательно: Нет
Объект, описывающий метаданные запроса. Содержит следующие необязательные поля:
user_id: внешний идентификатор пользователя, связанного с запросом. Должен быть uuid, хэш или другой непрозрачный идентификатор. Не включайте никакой идентифицирующей информации, такой как имя, адрес электронной почты или номер телефона. Максимальная длина: 256.
stop_sequences
- Тип: массив строк.
- Обязательно: Нет
Пользовательская текстовая последовательность для остановки генерации.
stream
- Тип: Логический
- Обязательно: Нет
Следует ли использовать события, отправленные сервером (SSE), для постепенного возврата содержимого ответа.
system
- Тип: строка
- Обязательно: Нет
Системная подсказка, предоставляющая контекст и инструкции для Claude. Это способ предоставления контекста и конкретной цели или роли модели. Обратите внимание, что это отличается от роли в сообщениях: в API сообщений нет «системной» роли.
temperature
- Тип: Номер
- Обязательно: Нет
- По умолчанию: 1.0
Управляет случайностью генерации, 0,0–1,0. Диапазон 0 < x < 1`. Рекомендуется использовать значения, близкие к 0,0, для задач аналитического/множественного выбора и значения, близкие к 1,0, для творческих и генеративных задач.
Примечание. Даже если температура установлена на 0,0, результаты не будут полностью точными.
🆕 thinking
- Тип: Объект
- Обязательно: Нет
Настройте расширенные мыслительные способности Claude. Если эта функция включена, ответ будет содержать блок контента, показывающий мыслительный процесс Claude перед тем, как дать окончательный ответ. Требуется минимальный бюджет в 1024 токена, который учитывается при расчете лимита max_tokens.
Можно установить один из двух режимов:
1. Включить режим
{
"type": "enabled",
"budget_tokens": 2048
}type: обязательно, значение перечисления: «включено»budget_tokens: обязательный, целое число. Определяет количество токенов, которые Claude может использовать для своего внутреннего процесса рассуждения. Больший бюджет позволяет модели проводить более глубокий анализ сложных проблем и повышать качество ответов. Должно быть ≥1024 и меньше max_tokens. Диапазонx >1024`.
2. Отключить режим
{
"type": "disabled"
}type: обязательно, значение перечисления: «отключено»
tool_choice
- Тип: Объект
- Обязательно: Нет
Управляет тем, как модель использует предоставленные инструменты. Может быть одного из трех типов:
1. Автоматический режим (автоматический выбор)
{
"type": "auto", // 必需,枚举值: "auto"
"disable_parallel_tool_use": false // 可选,默认 false。如果为 true,模型最多只会使用一个工具
}2. Любой режим (любой инструмент)
{
"type": "any", // 必需,枚举值: "any"
"disable_parallel_tool_use": false // 可选,默认 false。如果为 true,模型将恰好使用一个工具
}3. Режим инструмента (укажите инструмент)
{
"type": "tool", // 必需,枚举值: "tool"
"name": "get_weather", // 必需,指定要使用的工具名称
"disable_parallel_tool_use": false // 可选,默认 false。如果为 true,模型将恰好使用一个工具
}Примечание:
- Автоматический режим: модель может самостоятельно решать, использовать ли инструменты.
- Любой режим: модель должна использовать инструменты, но можно выбрать любой доступный инструмент.
- Режим инструмента: модель должна использовать указанный инструмент.
tools
- Тип: массив объектов.
- Обязательно: Нет
Определяет инструменты, которые может использовать модель. Инструменты могут быть пользовательскими или встроенными типами инструментов:
1. Пользовательский инструмент (Инструмент)
Каждое определение пользовательского инструмента содержит:
type: необязательно, значение перечисления: «пользовательский».name: обязательное имя инструмента, 1–64 символа.description: описание инструмента, рекомендуется быть максимально подробным.input_schema: требуется определение схемы JSON для ввода инструмента.cache_control: управление кешем, необязательно, тип «эфемерный».
Пример:
[
{
"type": "custom",
"name": "get_weather",
"description": "Получить текущую погоду для указанного места",
"input_schema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "название города,нравиться:Пекин"
}
},
"required": ["location"]
}
}
]2. ComputerUseTool
{
"type": "computer_20241022", // необходимый
"name": "computer", // 必需,枚举值: "computer"
"display_width_px": 1024, // 必需,显示宽度(像素)
"display_height_px": 768, // 必需,显示高度(像素)
"display_number": 0, // 可选,X11 显示编号
"cache_control": {
"type": "ephemeral" // Необязательный
}
}3. Инструмент Bash (BashTool)
{
"type": "bash_20241022", // необходимый
"name": "bash", // 必需,枚举值: "bash"
"cache_control": {
"type": "ephemeral" // Необязательный
}
}4. Инструмент текстового редактора (TextEditor)
{
"type": "text_editor_20241022", // необходимый
"name": "str_replace_editor", // 必需,枚举值: "str_replace_editor"
"cache_control": {
"type": "ephemeral" // Необязательный
}
}Когда модель использует инструмент, возвращается блок содержимогоtool_use:
[
{
"type": "tool_use",
"id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"name": "get_weather",
"input": { "location": "Пекин" }
}
]Вы можете запустить инструмент и вернуть результат через блок содержимогоtool_result:
[
{
"type": "tool_result",
"tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"content": "北京当前天气晴朗,温度 25°C"
}
]top_k
- Тип: целое число
- Обязательно: Нет
- Диапазон: х > 0
Выборка из K лучших вариантов токена. Используется для удаления маловероятных ответов «длинного хвоста». Рекомендуется использовать только в сложных случаях, когда обычно требуется только регулировка температуры.
top_p
- Тип: Номер
- Обязательно: Нет
- Диапазон: 0 `< x < 1
Используйте отбор проб ядра. Вычислите совокупное распределение каждого последующего токена в порядке убывания вероятности, усекая его при достижении вероятности, указанной top_p. Рекомендуется настраивать только одно из значений температуры или top_p, а не оба одновременно.
📥 Ответ
Успешный ответ
Возвращает объект завершения чата, содержащий следующие поля:
content
- Тип: массив объектов.
- Обязательно: Да
Содержимое, генерируемое моделью, состоит из нескольких блоков контента. Каждый блок контента имеет тип, определяющий его форму. Блоки контента могут быть одного из следующих типов:
Блок текстового контента (Текст)
{
"type": "text", // 必需,枚举值: "text",默认值
"text": "你好,我是 Claude。" // 必需,最大长度: 5000000,最小长度: 1
}Блок контента «Использование инструмента» (Использование инструмента)
{
"type": "tool_use", // 必需,枚举值: "tool_use",默认值
"id": "toolu_xyz...", // 必需,工具使用的唯一标识符
"name": "get_weather", // 必需,工具名称,最小长度: 1
"input": {
// 必需,工具的输入参数对象
// 工具输入参数,具体格式由工具的 input_schema 定义
}
}Пример:
// Пример текстового контента
[{"type": "text", "text": "你好,我是 Claude。"}]
// Примеры использования инструмента
[{
"type": "tool_use",
"id": "toolu_xyz...",
"name": "get_weather",
"input": { "location": "Пекин" }
}]
// Примеры смешанного контента
[
{"type": "text", "text": "根据天气查询结果:"},
{
"type": "tool_use",
"id": "toolu_xyz...",
"name": "get_weather",
"input": { "location": "Пекин" }
}
]Если последнее запрошенное сообщение было вспомогательной ролью, содержимое ответа продолжается непосредственно из этого сообщения. Например:
// просить
[
{"role": "user", "content": "Как по-гречески называется солнце?? (A) Sol (B) Helios (C) Sun"},
{"role": "assistant", "content": "Правильный ответ ("}
]
// ответ
[{"type": "text", "text": "B)"}]id
- Тип: строка
- Обязательно: Да
Уникальный идентификатор ответа.
model
- Тип: строка
- Обязательно: Да
Имя модели, которую нужно использовать.
role
- Тип: строка перечисления.
- Обязательно: Да
- Значение по умолчанию: assistant
Роль сеанса, создавшая сообщение, всегда assistant.
stop_reason
- Тип: строка перечисления или null.
- Обязательно: Да
Причина прекращения генерации, возможные значения:
"end_turn": модель достигает естественной точки остановки."max_tokens": превышено запрошенное max_tokens или максимальный предел модели."stop_sequence": была создана одна из пользовательских последовательностей остановок."tool_use": модель вызывает один или несколько инструментов.
В непотоковом режиме это значение всегда не равно нулю. В потоковом режиме значение null в событии message_start и ненулевое значение в противном случае.
stop_sequence
- тип: строка или null
- Обязательно: Да
Создана пользовательская последовательность остановок. Если модель встречает одну из последовательностей, указанных в параметре stop_sequences, это поле будет содержать соответствующую последовательность остановки. Если не остановлен из-за последовательности остановки, имеет значение null.
type
- Тип: строка перечисления.
- Обязательно: Да
- Значение по умолчанию: message
- Необязательное значение: сообщение.
Тип объекта, всегда «сообщение» для сообщений.
usage
- Тип: Объект
- Обязательно: Да
Статистика использования, связанная с выставлением счетов и ограничением тока. Содержит следующие поля:
input_tokens: необходимое количество используемых входных токенов, диапазон x >` 0.output_tokens: необходимое количество используемых выходных токенов, диапазон x > 0.cache_creation_input_tokens: количество входных токенов, используемых для создания записей кэша (если применимо), обязательно, диапазон x > 0.cache_read_input_tokens: количество входных токенов, считанных из кэша (если применимо), обязательно, диапазон x > 0.
Примечание. Поскольку API преобразует и анализирует запросы внутри себя, количество токенов может не совсем соответствовать фактическому видимому содержимому запроса и ответа. Например, output_tokens будет ненулевым даже для ответа в виде пустой строки.
Ошибка ответа
При возникновении проблемы с запросом API вернет объект ответа об ошибке с кодом состояния HTTP в диапазоне 4XX-5XX.
Коды состояния распространенных ошибок
401 Unauthorized: ключ API недействителен или не предоставлен.400 Bad Request: неверные параметры запроса.429 Too Many Requests: превышен лимит вызовов API.500 Internal Server Error: внутренняя ошибка сервера.
Пример ответа об ошибке:
{
"error": {
"type": "invalid_request_error",
"message": "Invalid API key provided",
"code": "invalid_api_key"
}
}Основные типы ошибок:
invalid_request_error: ошибка параметра запроса.authentication_error: ошибка аутентификации.rate_limit_error: частота запросов превышает предел.server_error: внутренняя ошибка сервера.