Процес подачі заявки
Щоб використовувати 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(можна повернути вміст поточного асистента без змін для продовження),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 приклад
Потокова відповідь
Цей інтерфейс також підтримує потокову відповідь, встановивши параметр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. - Відображення впливає лише на повернуту інформацію та затримку потоку, не закриваючи міркування і не зменшуючи облік токенів мислення.
- Чи активовано за замовчуванням мислення та значення за замовчуванням відображення - це два незалежні питання. Opus 5, Sonnet 5 за замовчуванням активують адаптивне мислення; Opus 4.8, 4.7 та 4.6 потребують явного включення.
budget_tokensвикористовується лише для старих моделей, які все ще підтримують фіксований бюджет мислення. Нові моделі повинні використовуватиthinking.type=adaptiveтаoutput_config.effort; мислення Fable 5.1 завжди активоване і не може бути явно вимкнене.- Під час багатокрокового діалогу та викликів інструментів потрібно повернути повний блок мислення та підпис, отримані від асистента, без змін; не змінюйте або не генеруйте підпис самостійно.
- Деякі маршрути з частковою сумісністю не можуть без втрат обробляти
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 API Messages лише вказує на не кешовані входи, 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.

