Антропный формат беседы (Сообщения) - chat / anthropic chat

Официальная документация

Антропные сообщения - Антропный стриминг Сообщения

📝 Введение

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

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

Базовый текстовый разговор ✅

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

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

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

Диалог анализа изображения ✅

curl https://88api.ai/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "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-3-5-sonnet-20241022",
  "role": "assistant",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 3050,
    "output_tokens": 892
  }
}

Вызов инструмента ✅

curl https://88api.ai/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "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-3-5-sonnet-20241022",
  "role": "assistant",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "type": "message",
  "usage": {
    "input_tokens": 2156,
    "output_tokens": 468
  }
}

Ответ в потоковом режиме ✅

curl https://88api.ai/v1/messages \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --header "x-api-key: $API_KEY" \
     --data \
'{
    "model": "claude-3-5-sonnet-20241022",
    "messages": [
        {
            "role": "user",
            "content": "рассказать историю"
        }
    ],
    "stream": true
}'

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

{
  "type": "message_start",
  "message": {
    "id": "msg_013Zva2CMHLNnXjNJKqJ2EF",
    "model": "claude-3-5-sonnet-20241022",
    "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 — ваш ключ API. Вы можете получить ключи API через консоль, и каждый ключ ограничен одним рабочим пространством.

Параметры заголовка запроса

`$API_KEY`

Тип: строка
Требуется: Нет

Укажите используемую бета-версию, поддерживающую список, разделенный запятыми, например $API_KEY, или указав этот заголовок запроса несколько раз.

`$API_KEY`

Тип: строка
Требуется: Да

Укажите версию API, которую следует использовать.

Параметры тела запроса

`$API_KEY`

Тип: целое число
Требуется: Да

Максимальное количество сгенерированных токенов. Разные модели имеют разные ограничения, подробности см. в документации модели. Диапазон $API_KEY.

`$API_KEY`

Тип: массив объектов.
Требуется: Да

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

Каждое сообщение должно содержать поля $API_KEY и 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.role`

Тип: строка или массив объектов.
Требуется: Да

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

Текстовое содержимое (Текст)

{
  "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.
Поле типа всех типов является обязательной строкой перечисления.
Поле содержимого результатов инструмента поддерживает строки или массивы блоков контента, содержащие текст/изображения.

`cache_control`

Тип: строка
Требуется: Да

Имя используемой модели, как подробно описано в документации модели. Диапазон символов cache_control.

`cache_control`

Тип: Объект
Требуется: Нет

Объект, описывающий метаданные запроса. Содержит следующие необязательные поля:

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

`cache_control`

Тип: массив строк.
Требуется: Нет

Пользовательская текстовая последовательность для остановки генерации.

`cache_control`

Тип: Логический
Требуется: Нет

Следует ли использовать события, отправленные сервером (SSE), для постепенного возврата содержимого ответа.

`cache_control`

Тип: строка
Требуется: Нет

Системная подсказка, предоставляющая контекст и инструкции для Клода. Это способ предоставления контекста и конкретной цели или роли модели. Обратите внимание, что это отличается от роли в сообщениях: в API сообщений нет «системной» роли.

`cache_control`

Тип: Номер
Требуется: Нет -По умолчанию: 1.0

Управляет случайностью генерации, 0,0–1,0. Диапазон cache_control< x < 1`. Рекомендуется использовать значения, близкие к 0,0, для задач аналитического/множественного выбора и значения, близкие к 1,0, для творческих и генеративных задач.

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

🆕 `cache_control`

Тип: Объект
Требуется: Нет

Настройте расширенные мыслительные способности Клода. Если эта функция включена, ответ будет содержать блок контента, показывающий мыслительный процесс Клода перед тем, как дать окончательный ответ. Требуется минимальный бюджет в 1024 токена, который учитывается при расчете лимита max_tokens.

Можно установить один из двух режимов:

1. Включить режим

{
  "type": "enabled",
  "budget_tokens": 2048
}

type: обязательно, значение перечисления: «включено»
type: обязательный, целое число. Определяет количество токенов, которые Claude может использовать для своего внутреннего процесса рассуждения. Больший бюджет позволяет модели проводить более глубокий анализ сложных проблем и повышать качество ответов. Должно быть ≥1024 и меньше max_tokens. Диапазон x > 1024`.

2. Отключить режим

{
  "type": "disabled"
}

type: обязательно, значение перечисления: «отключено»

`type`

Тип: Объект
Требуется: Нет

Управляет тем, как модель использует предоставленные инструменты. Может быть одного из трех типов:

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. Пользовательский инструмент (Инструмент)

Каждое определение пользовательского инструмента содержит:

tools: необязательно, значение перечисления: «пользовательский».
tools: обязательное имя инструмента, 1–64 символа.
tools: описание инструмента, рекомендуется быть максимально подробным.
tools: требуется определение схемы JSON для ввода инструмента.
tools: управление кешем, необязательно, тип «эфемерный».

Пример:

[
  {
    "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_k`

Тип: Номер
Требуется: Нет
Диапазон: 0 `< x < 1

Используйте отбор проб ядра. Вычислите совокупное распределение каждого последующего токена в порядке убывания вероятности, усекая его при достижении вероятности, указанной top_p. Рекомендуется настраивать только одно из значений температуры или top_p, а не оба одновременно.

📥 Ответ

Успешный ответ

Возвращает объект завершения чата, содержащий следующие поля:

`top_k`

Тип: массив объектов.
Требуется: Да

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

Блок текстового контента (Текст)

{
  "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`

Тип: строка
Требуется: Да

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

`id`

Тип: строка
Требуется: Да

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

`id`

Тип: строка перечисления.
Требуется: Да -Значение по умолчанию: помощник

Роль сеанса, создавшая сообщение, всегда «помощник».

`id`

Тип: строка перечисления или ноль.
Требуется: Да

Причина прекращения генерации, возможные значения:

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

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

`id`

тип: строка или ноль
Требуется: Да

Создана пользовательская последовательность остановок. Если модель встречает одну из последовательностей, указанных в параметре stop_sequences, это поле будет содержать соответствующую последовательность остановки. Если не остановлен из-за последовательности остановки, имеет значение null.

`id`

Тип: строка перечисления.
Требуется: Да -Значение по умолчанию: сообщение
Необязательное значение: сообщение.

Тип объекта, всегда «сообщение» для сообщений.

`id`

Тип: Объект
Требуется: Да

Статистика использования, связанная с выставлением счетов и ограничением тока. Содержит следующие поля:

id: необходимое количество используемых входных токенов, диапазон x >` 0.
id: необходимое количество используемых выходных токенов, диапазон x > 0.
id: количество входных токенов, используемых для создания записей кэша (если применимо), обязательно, диапазон x > 0.
id: количество входных токенов, считанных из кэша (если применимо), обязательно, диапазон x > 0.

Примечание. Поскольку API преобразует и анализирует запросы внутри себя, количество токенов может не совсем соответствовать фактическому видимому содержимому запроса и ответа. Например, output_tokens будет ненулевым даже для ответа в виде пустой строки.

Ошибка ответа

При возникновении проблемы с запросом API вернет объект ответа об ошибке с кодом состояния HTTP в диапазоне 4XX-5XX.

Коды состояния распространенных ошибок

id: ключ API недействителен или не предоставлен.
id: неверные параметры запроса.
id: превышен лимит вызовов API.
500 Internal Server Error: внутренняя ошибка сервера.

Пример ответа об ошибке:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid API key provided",
    "code": "invalid_api_key"
  }
}

Основные типы ошибок:

invalid_request_error: ошибка параметра запроса.
invalid_request_error: ошибка аутентификации.
invalid_request_error: частота запросов превышает предел.
invalid_request_error: внутренняя ошибка сервера.