Skip to main content
Anthropic Claude — это очень мощная система AI-диалогов, которая может генерировать плавные и естественные ответы всего за несколько секунд, просто вводя подсказки. Claude Messages API — это официальный родной формат API от Anthropic, который отличается от совместимого формата OpenAI (Chat Completion) и использует собственную структуру запросов и ответов Anthropic, что позволяет лучше использовать уникальные возможности Claude, такие как многомодальный ввод контента, вызов инструментов, глубокое мышление (Extended Thinking) и другие продвинутые функции. Этот документ в основном описывает процесс использования Claude Messages API, с помощью которого мы можем использовать родной интерфейс, согласованный с официальным интерфейсом Anthropic, для вызова диалоговых функций Claude.

申请流程

Чтобы использовать Claude Messages API, сначала перейдите в Ace Data Cloud 控制台, чтобы получить ваш API Token и сохранить его на всякий случай. Если вы еще не вошли в систему или не зарегистрированы, вы будете автоматически перенаправлены на страницу входа, где вас пригласят зарегистрироваться и войти в систему, после чего вы будете автоматически возвращены на текущую страницу. Один API Token позволяет вызывать все услуги платформы, не нужно запрашивать отдельный токен для каждой услуги. При первом запросе предоставляется бесплатный лимит, чтобы вы могли попробовать; если лимит исчерпан, вы можете пополнить общий баланс в консоли.
📘 Полная документация:Claude Messages API →

基本使用

Запрос к Claude Messages API осуществляется по пути /v1/messages, что соответствует официальному API Anthropic. Мы должны предоставить как минимум три обязательных параметра:
  • model:выбор используемой модели Claude. Последний флагман — claude-fable-5-1 (1 миллион токенов контекста, максимальный вывод 128K токенов); оригинальный claude-fable-5 по-прежнему совместим.
  • messages:массив входящих сообщений, каждое сообщение содержит role (роль) и content (содержимое), где role поддерживает user и assistant.
  • max_tokens:максимальное количество токенов на вывод, используемое для ограничения длины одного ответа.
Распространенные необязательные параметры:
  • system:системная подсказка, используемая для установки поведения и роли модели.
  • temperature:случайность генерации, от 0 до 1, чем больше значение, тем более разрозненные ответы.
  • stream:использовать ли потоковый ответ, установите true, чтобы получить эффект поэтапного возврата.
  • stop_sequences:пользовательские последовательности остановки, при встрече с которыми модель остановит генерацию.
  • top_p:параметр ядерной выборки, который в сочетании с temperature контролирует случайность генерации.
  • top_k:выборка только из K наиболее вероятных вариантов.
  • tools:определение инструментов, позволяющее модели вызывать внешние функции.
  • tool_choice:контроль того, как модель использует предоставленные инструменты.
  • cache_control:автоматическое создание контрольной точки кэша в последнем кэшируемом блоке запроса; также может быть записано в конкретном блоке содержимого.

cURL 示例

Python 示例

После вызова возвращается следующий результат:
Описание полей возвращаемого результата:
  • id:уникальный идентификатор данного сообщения.
  • type:всегда message.
  • role:всегда assistant.
  • content:массив ответного содержимого, каждый элемент содержит type (например, text) и соответствующее содержимое.
  • model:название модели, обрабатывающей запрос.
  • stop_reason:причина остановки. Стабильные значения включают end_turn, max_tokens, stop_sequence, tool_use, pause_turn (можно вернуть текущее содержимое assistant для продолжения), refusal и model_context_window_exceeded.
  • stop_sequence:если остановка произошла из-за пользовательской последовательности остановки, отображается соответствующий текст последовательности остановки.
  • stop_details:когда stop_reason равно refusal, может содержать категорию отказа и объяснение.
  • usage:статистика использования токенов. input_tokens — это не кэшированный ввод; cache_creation_input_tokens и cache_read_input_tokens — это соответственно запись и чтение кэша; output_tokens — количество выходных токенов. Официальная базовая цена на чтение кэша Fable 5.1 составляет 0.25/миллионтокенов,базовыеценыназаписькэшана5минути1чассоставляютсоответственно0.25/миллион токенов, базовые цены на запись кэша на 5 минут и 1 час составляют соответственно 12.50 и $20/миллион токенов; фактические цены платформы рассчитываются с учетом скидок на пакеты. Непотоковые ответы также могут содержать cost, зафиксированный Ace Data Cloud.

系统提示词

Claude Messages API поддерживает установку системной подсказки через поле system, используемое для определения поведения, роли и контекста модели.

Python 示例

Установив системную подсказку system, можно точно контролировать роль и поведение Claude.

流式响应

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

Python 示例

Потоковый ответ возвращается в формате Server-Sent Events (SSE), каждая строка начинается с префиксов event: и data:. Типы потоковых событий включают:
  • message_start: начало сообщения, содержит основную информацию о сообщении и название модели.
  • content_block_start: начало блока контента.
  • content_block_delta: инкрементальное обновление блока контента, содержит новые сгенерированные текстовые фрагменты.
  • content_block_stop: конец блока контента.
  • message_delta: инкрементальное обновление на уровне сообщения, содержит информацию о stop_reason и окончательном usage.
  • message_stop: конец сообщения.
Вывод выглядит следующим образом:
Как видно, событие content_block_delta в потоковом ответе содержит постепенно сгенерированный текст, который можно получить, объединив все text_delta.

Пример на JavaScript

Многоходовые диалоги

Если вы хотите подключить функцию многоходового диалога, вам нужно чередовать сообщения ролей user и assistant в массиве messages, передавая предыдущую историю диалога.

Пример на Python

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

Модель глубокого мышления

Мышление Клода и резюме мышления — это два разных понятия: модель может проводить внутренние рассуждения, но API не возвращает исходные цепочки мышления. Когда необходимо продемонстрировать процесс рассуждения, API возвращает обработанное резюме. Текущая модель рекомендует использовать адаптивное мышление и контролировать общие усилия рассуждения через output_config.effort:
Блок мышления в ответе выглядит следующим образом:
  • display: "summarized" возвращает читаемое резюме мышления; это не исходная цепочка мышления.
  • display: "omitted" возвращает thinking: "", но все равно сохраняет непрозрачный signature для поддержки последующих диалогов.
  • По умолчанию модели Fable 5.1, Fable 5, Opus 5, Sonnet 5, Opus 4.8 и Opus 4.7 имеют значение omitted; модели Opus 4.6, Sonnet 4.6 и более ранние, поддерживающие мышление, по умолчанию используют summarized.
  • Параметр Display влияет только на возвращаемое содержимое и задержку потока, не отключая рассуждения и не уменьшая учет токенов мышления.
  • Вопрос о том, включено ли мышление по умолчанию, и значение по умолчанию для display — это два независимых вопроса. Opus 5, Sonnet 5 по умолчанию включают адаптивное мышление; Opus 4.8, 4.7 и 4.6 требуют явного включения.
  • budget_tokens используется только для старых моделей, которые все еще поддерживают фиксированный бюджет мышления. Новые модели должны использовать thinking.type=adaptive и output_config.effort; мышление Fable 5.1 всегда включено и не может быть явно отключено.
  • При многоходовых диалогах и вызовах инструментов необходимо возвращать полный блок мышления и подпись, полученные от assistant, без изменений; не изменяйте и не генерируйте подпись самостоятельно.
  • Некоторые совместимые маршруты не могут без потерь обрабатывать redacted_thinking или явно отключать мышление, в этом случае будет возвращена ошибка параметров, а не тихо отброшены или изменены семантика запроса.
В потоковом запросе summarized будет генерировать thinking_delta; omitted не будет генерировать thinking_delta, только сохраняет жизненный цикл блока мышления и signature_delta.

Визуальная модель

Использование изображений по URL

Пример cURL

Поддерживаемые форматы изображений включают: image/jpeg, image/png, image/gif, image/webp.

Документы и PDF

PDF использует блок содержимого document, поддерживающий как Base64, так и URL в качестве стабильных источников. Источник Base64 должен использовать application/pdf:
URL источник записывается как {"type":"url","url":"https://example.com/report.pdf"}. document также поддерживает text/plain и источники content, состоящие из блоков text/image; необязательные поля включают title, context и citations. Источник file_id API файлов является отдельной бета-функцией и не входит в стабильный контракт этого интерфейса.

Кэширование подсказок

Верхний уровень cache_control автоматически разместит точки кэширования в последнем кэшируемом блоке:
При необходимости точного контроля позиции также можно указать тот же cache_control в блоках содержимого text, image, document, tool_use, tool_result или в определениях инструментов. ttl поддерживает 5m (по умолчанию) и 1h; пожалуйста, используйте usage.cache_creation_input_tokens и usage.cache_read_input_tokens для определения записи и попадания в кэш. Пример возвращаемого результата:

Вызов инструментов (Tool Use)

Claude Messages API изначально поддерживает функцию вызова инструментов, позволяя модели вызывать заранее определенные вами инструменты/функции по мере необходимости.

Пример на Python

Когда модель решает вызвать инструмент, в возвращаемом результате content будет содержать блок содержимого типа tool_use:
Обратите внимание, что stop_reason равен tool_use, что указывает на то, что модели необходимо вызвать инструмент. Получив этот результат, вам нужно выполнить функцию инструмента и вернуть результат в виде tool_result модели:
Модель будет генерировать окончательный ответ на естественном языке на основе результатов, возвращаемых инструментом.

Различия с Chat Completion API

Ace Data Cloud одновременно предоставляет два формата API Claude, основные различия между которыми следующие: usage.input_tokens в Messages API обозначает только не кэшированные входные данные, cache_read_input_tokens и cache_creation_input_tokens являются независимыми счетными категориями; все три будут рассчитываться по соответствующим ценам. Если ваша система уже интегрирована с API формата OpenAI, вы можете использовать Chat Completion API для бесшовного переключения. Если вам нужно использовать все нативные возможности Claude, рекомендуется использовать Messages API.

Обработка ошибок

Ошибки публичного интерфейса используют обертку платформы Ace Data Cloud: error.code — это стабильный код ошибки, error.message — описание, trace_id используется для отладки запроса. Общие HTTP статусы включают:
  • 400: Неверные параметры запроса или содержимое протокола.
  • 401: Неверный, отсутствующий или истекший токен авторизации.
  • 403: Доступ запрещен, недостаточно средств или ограничение квоты.
  • 404: API или модель не существует.
  • 413: Слишком большой размер тела запроса.
  • 429: Слишком много запросов.
  • 500 / 503 / 504: Ошибка сервиса, временно недоступен или превышено время обработки.

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

Эта структура ошибки является контрактом времени выполнения Ace Data Cloud и не эквивалентна официальной обертке ошибок Anthropic; обрабатывайте в соответствии с HTTP статусом и error.code.

Заключение

С помощью этого документа вы узнали, как использовать API сообщений Claude в нативном формате Anthropic для вызова диалоговых функций Claude. Messages API поддерживает основные диалоги, системные подсказки, потоковые ответы, многократные диалоги, глубокое мышление, визуальное понимание, PDF, кэширование подсказок и вызовы инструментов и другие богатые функции. Если у вас есть какие-либо вопросы, пожалуйста, не стесняйтесь обращаться в нашу техническую поддержку.