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 (можна повернути вміст поточного асистента без змін для продовження), 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 приклад

Встановивши системну підказку, можна точно контролювати роль і поведінку 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.
  • Відображення впливає лише на повернуту інформацію та затримку потоку, не закриваючи міркування і не зменшуючи облік токенів мислення.
  • Чи активовано за замовчуванням мислення та значення за замовчуванням відображення - це два незалежні питання. 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:
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 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: Помилка сервісу, тимчасово недоступний або перевищено час обробки.

Приклад відповіді з помилкою

Ця структура помилки є контрактом часу виконання Ace Data Cloud, не є аналогом офіційної обгортки помилок Anthropic; будь ласка, обробляйте відповідно до HTTP статусу та error.code.

Висновок

Завдяки цьому документу ви дізналися, як використовувати API Messages Claude у форматі Anthropic для виклику діалогових функцій Claude. API Messages підтримує основні діалоги, системні підказки, потокові відповіді, багатократні діалоги, глибоке мислення, візуальне розуміння, PDF, кешування підказок та виклики інструментів та інші багаті функції. Якщо у вас є будь-які питання, будь ласка, звертайтеся до нашої команди технічної підтримки.