申请流程
Чтобы использовать 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 составляет 12.50 и $20/миллион токенов; фактические цены платформы рассчитываются с учетом скидок на пакеты. Непотоковые ответы также могут содержатьcost, зафиксированный Ace Data Cloud.
系统提示词
Claude Messages API поддерживает установку системной подсказки через полеsystem, используемое для определения поведения, роли и контекста модели.
Python 示例
system, можно точно контролировать роль и поведение Claude.
流式响应
Этот интерфейс также поддерживает потоковые ответы, установив параметрstream в true, вы можете получить эффект поэтапного возврата, что очень удобно для реализации поэтапного отображения на веб-странице.
Python 示例
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:
{"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: Ошибка сервиса, временно недоступен или превышено время обработки.
Пример ответа об ошибке
error.code.

