88API88API
Руководство пользователяAI-приложенияAPIПомощь и поддержка
Чат (Chat)

Формат диалога 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"
  }
}

Примечание:

  1. Каждый тип может содержать необязательное поле cache_control для управления поведением кэширования контента.
  2. Минимальная длина текстового контента – 1.
  3. Поле типа всех типов является обязательной строкой перечисления.
  4. Поле содержимого результатов инструмента поддерживает строки или массивы блоков контента, содержащие текст/изображения.

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,模型将恰好使用一个工具
}

Примечание:

  1. Автоматический режим: модель может самостоятельно решать, использовать ли инструменты.
  2. Любой режим: модель должна использовать инструменты, но можно выбрать любой доступный инструмент.
  3. Режим инструмента: модель должна использовать указанный инструмент.

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: внутренняя ошибка сервера.

Содержание

📝 Введение
💡 Пример запроса
Базовый текстовый разговор ✅
Диалог анализа изображения ✅
Вызов инструмента ✅
Ответ в потоковом режиме ✅
📮 Запрос
Конечная точка
Метод аутентификации
Параметры заголовка запроса
anthropic-beta
anthropic-version
Параметры тела запроса
max_tokens
messages
messages.role
messages.content
Текстовое содержимое (Текст)
Содержимое изображения (Изображение)
Использование инструмента
Результат инструмента
Документ
model
metadata
stop_sequences
stream
system
temperature
🆕 thinking
1. Включить режим
2. Отключить режим
tool_choice
1. Автоматический режим (автоматический выбор)
2. Любой режим (любой инструмент)
3. Режим инструмента (укажите инструмент)
tools
1. Пользовательский инструмент (Инструмент)
2. ComputerUseTool
3. Инструмент Bash (BashTool)
4. Инструмент текстового редактора (TextEditor)
top_k
top_p
📥 Ответ
Успешный ответ
content
Блок текстового контента (Текст)
Блок контента «Использование инструмента» (Использование инструмента)
id
model
role
stop_reason
stop_sequence
type
usage
Ошибка ответа
Коды состояния распространенных ошибок