Claude Messages API заявка та використання

Anthropic Claude — це дуже потужна AI система діалогу, яка може генерувати плавні та природні відповіді всього за кілька секунд, якщо ввести підказку. Claude Messages API — це офіційний рідний формат API Anthropic, який, на відміну від формату OpenAI (Chat Completion), використовує власну структуру запитів і відповідей Anthropic, що дозволяє краще використовувати унікальні можливості Claude, такі як мультимодальний вхід, виклики інструментів, глибоке мислення (Extended Thinking) та інші розширені функції. Цей документ в основному описує процес використання Claude Messages API, за допомогою якого ми можемо використовувати рідний інтерфейс, що відповідає офіційним стандартам Anthropic, для виклику діалогових функцій Claude.

Процес заявки

Щоб використовувати Claude Messages API, спочатку можна перейти на сторінку Claude Messages API та натиснути кнопку «Acquire», щоб отримати необхідні для запиту облікові дані:

Якщо ви ще не увійшли в систему або не зареєстровані, вас автоматично перенаправлять на сторінку входу, запрошуючи вас зареєструватися та увійти. Після входу або реєстрації ви автоматично повернетеся на цю сторінку. При першій заявці буде надано безкоштовний ліміт, що дозволяє безкоштовно використовувати цей API.

Основне використання

Шлях запиту для Claude Messages API — /v1/messages, що відповідає офіційному API Anthropic. Ми повинні надати принаймні три обов’язкові параметри:

model: вибір моделі Claude, наприклад, claude-opus-4-20250514, claude-sonnet-4-20250514 тощо.
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: контроль за тим, як модель використовує надані інструменти.

cURL приклад

curl -X POST 'https://api.acedata.cloud/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "Hello, Claude"
      }
    ]
  }'

Python приклад

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Після виклику, результат буде таким:

{
  "id": "msg_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hi! My name is Claude. How can I help you today?"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 12,
    "output_tokens": 15
  }
}

Опис полів результату:

id: унікальний ідентифікатор цього повідомлення.
type: завжди message.
role: завжди assistant.
content: масив вмісту відповіді, кожен елемент містить type (наприклад, text) та відповідний вміст.
model: назва моделі, що обробляє запит.
stop_reason: причина зупинки, можливі значення включають end_turn (нормальне завершення), max_tokens (досягнуто максимальну довжину), stop_sequence (зустріч з послідовністю зупинки), tool_use (виклик інструменту).
stop_sequence: якщо зупинка сталася через користувацьку послідовність зупинки, відображається текст відповідної зупиненої послідовності.
usage: статистика використання токенів, що містить input_tokens (кількість вхідних токенів) та output_tokens (кількість вихідних токенів).

Системні підказки

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

Python приклад

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "system": "Ти професійний помічник з перекладу на китайську, будь ласка, переклади англійський текст, введений користувачем, на китайську.",
    "messages": [
        {"role": "user", "content": "The quick brown fox jumps over the lazy dog."}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

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

Потокова відповідь

Цей інтерфейс також підтримує потокову відповідь, встановивши параметр stream в true, можна отримати поступове повернення, що дуже підходить для реалізації по словах на веб-сторінці.

Python приклад

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "stream": True,
    "messages": [
        {"role": "user", "content": "Hello, Claude"}
    ]
}

response = requests.post(url, json=payload, headers=headers, stream=True)
for line in response.iter_lines():
    if line:
        print(line.decode("utf-8"))

Потокова відповідь повертається у форматі Server-Sent Events (SSE), кожен рядок має префікси event: та data:. Типи потокових подій включають:

message_start: початок повідомлення, що містить основну інформацію про повідомлення та назву моделі.
content_block_start: початок блоку вмісту.
content_block_delta: інкрементне оновлення блоку вмісту, що містить новостворені текстові фрагменти.
content_block_stop: кінець блоку вмісту.
message_delta: інкрементне оновлення на рівні повідомлення, що містить stop_reason та остаточну інформацію про usage.
message_stop: кінець повідомлення.

Вихідний ефект виглядає наступним чином:

event: message_start
data: {"type":"message_start","message":{"id":"msg_01XFDUDYJgAACzvnptvVoYEL","type":"message","role":"assistant","content":[],"model":"claude-sonnet-4-20250514","stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":12,"output_tokens":0}}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Привіт"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"! Мене звати"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":" Клод. Чим я можу вам допомогти сьогодні?"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":15}}

event: message_stop
data: {"type":"message_stop"}

Можна побачити, що в потоці відповіді подія content_block_delta містить поступово згенерований текст, шляхом з’єднання всіх text_delta можна отримати повну відповідь.

Приклад JavaScript

const options = {
  method: "POST",
  headers: {
    accept: "application/json",
    authorization: "Bearer {token}",
    "content-type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-4-20250514",
    max_tokens: 1024,
    stream: true,
    messages: [{ role: "user", content: "Привіт, Клод" }],
  }),
};

const response = await fetch("https://api.acedata.cloud/v1/messages", options);
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

Багатокрокова розмова

Якщо ви хочете підключити функцію багатокрокової розмови, потрібно чергувати повідомлення ролей user та assistant в масиві messages, передавши попередню історію розмови.

Приклад Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {"role": "user", "content": "Привіт, мене звати Аліса."},
        {"role": "assistant", "content": "Привіт, Алісо! Радий вас бачити. Чим я можу вам допомогти сьогодні?"},
        {"role": "user", "content": "Як мене звати?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Результат буде таким:

{
  "id": "msg_01Y1wfQmd89g968TVbFu57Yc",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Ваше ім'я Аліса, як ви тільки що сказали!"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 40,
    "output_tokens": 14
  }
}

Передаючи повну історію розмови в messages, Клод може враховувати контекст для точних відповідей.

Модель глибокого мислення

Клод підтримує функцію Розширеного Мислення, яка дозволяє моделі спочатку проводити внутрішнє міркування перед відповіддю, підвищуючи точність обробки складних питань. Для використання цієї функції потрібно передати параметр thinking.

Приклад Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 16000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {"role": "user", "content": "Яке значення синуса 30 градусів? Покажіть своє міркування."}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Результат буде таким:

{
  "id": "msg_018J4YaRoGHtbsTVb4Vvz7oH",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "thinking",
      "thinking": "Користувач запитує про синус 30 градусів. Це базове питання тригонометрії.\n\nУ трикутнику 30-60-90 сторони мають співвідношення 1:√3:2.\n\nДля кута 30°:\n- Протилежна сторона дорівнює 1\n- Гіпотенуза дорівнює 2\n- Отже, sin(30°) = протилежна/гіпотенуза = 1/2 = 0.5"
    },
    {
      "type": "text",
      "text": "Синус 30 градусів дорівнює **1/2** або **0.5**.\n\nЦе одне з основних тригонометричних значень. У трикутнику 30-60-90 сторони мають співвідношення 1:√3:2, де сторона, що протистоїть куту 30°, має довжину 1, а гіпотенуза має довжину 2, що дає нам sin(30°) = 1/2."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 28,
    "output_tokens": 239
  }
}

Можна побачити, що масив content містить два блоки контенту:

type: "thinking": внутрішній процес мислення моделі, що демонструє етапи міркування.
type: "text": остаточний результат відповіді.

Зверніть увагу на такі моменти:

Використовуючи thinking, max_tokens має бути більшим за budget_tokens, оскільки budget_tokens - це бюджет токенів, виділений для процесу мислення.
Чим більший budget_tokens, тим більше простору для глибшого міркування має модель, що підходить для обробки складних питань.

Візуальна модель

Клод підтримує мультимодальний ввід, може одночасно обробляти текст та зображення. У Messages API, передавши content у форматі масиву та включивши блоки зображення, можна використовувати візуальні можливості.

Використання Base64 кодування зображення

import base64
import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

# Читання та кодування зображення
with open("image.png", "rb") as f:
    image_data = base64.standard_b64encode(f.read()).decode("utf-8")

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/png",
                        "data": image_data
                    }
                },
                {
                    "type": "text",
                    "text": "Що на цьому зображенні?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Використання URL зображення

```python
import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "url",
                        "url": "https://cdn.acedata.cloud/ueugot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "Що на цьому зображенні?"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

cURL приклад

curl -X POST 'https://api.acedata.cloud/v1/messages' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "image",
            "source": {
              "type": "url",
              "url": "https://cdn.acedata.cloud/ueugot.png"
            }
          },
          {
            "type": "text",
            "text": "Що на цьому зображенні?"
          }
        ]
      }
    ]
  }'

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

{
  "id": "msg_01NCrxpZmV17bhQJJRQEFEb9",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Це зображення показує інтерфейс конфігурації запиту API для того, що, здається, є сервісом завершення чату AI. Інтерфейс включає параметри для вибору моделі, повідомлень, режиму потоку та налаштувань максимальних токенів."
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 1570,
    "output_tokens": 52
  }
}

Використання інструментів (Tool Use)

API повідомлень Claude нативно підтримує функцію виклику інструментів, що дозволяє моделі викликати заздалегідь визначені вами інструменти/функції за потреби.

Приклад Python

import requests

url = "https://api.acedata.cloud/v1/messages"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Отримати поточну погоду в заданому місці",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "Місто та штат, наприклад, Сан-Франциско, Каліфорнія"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "Яка погода в Сан-Франциско?"}
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Коли модель вирішує викликати інструмент, у відповіді content буде містити блок вмісту типу tool_use:

{
  "id": "msg_01Aq9w938a90dw8q",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Дайте мені перевірити погоду в Сан-Франциско для вас."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lgs",
      "name": "get_weather",
      "input": {
        "location": "Сан-Франциско, Каліфорнія"
      }
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 120,
    "output_tokens": 68
  }
}

Зверніть увагу, що stop_reason є tool_use, що вказує на те, що моделі потрібно викликати інструмент. Отримавши цей результат, вам потрібно виконати функцію інструменту та повернути результат у формі tool_result моделі:

payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "tools": [
        {
            "name": "get_weather",
            "description": "Отримати поточну погоду в заданому місці",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "Місто та штат, наприклад, Сан-Франциско, Каліфорнія"
                    }
                },
                "required": ["location"]
            }
        }
    ],
    "messages": [
        {"role": "user", "content": "Яка погода в Сан-Франциско?"},
        {
            "role": "assistant",
            "content": [
                {"type": "text", "text": "Дайте мені перевірити погоду в Сан-Франциско для вас."},
                {"type": "tool_use", "id": "toolu_01A09q90qw90lq917835lgs", "name": "get_weather", "input": {"location": "Сан-Франциско, Каліфорнія"}}
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_01A09q90qw90lq917835lgs",
                    "content": "Сонячно, 22°C"
                }
            ]
        }
    ]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Модель буде генерувати остаточну відповідь природною мовою на основі результатів, повернених інструментом.

Відмінності з API завершення чату

Ace Data Cloud одночасно надає два формати API Claude, основні відмінності між якими наведені нижче:

Особливість	Messages API (`/v1/messages`)	Chat Completion API (`/v1/chat/completions`)
Формат	Нативний формат Anthropic	Формат, сумісний з OpenAI
Системне повідомлення	Окреме поле `system`	Передається через `messages` з `role: "system"`
Структура відповіді	Масив `content` (підтримує кілька типів)	Масив `choices` (містить `message`)
Потоковий формат	Події SSE (різні типи подій)	Рядки SSE `data`
Глибоке мислення	Нативний параметр `thinking`	Викликається за допомогою спеціального імені моделі (наприклад, з суфіксом `-thinking`)
Виклик інструментів	Нативний формат `tools` + `input_schema`	Формат `functions`, сумісний з OpenAI
Статистика токенів	`input_tokens` / `output_tokens`	`prompt_tokens` / `completion_tokens`

Якщо ваша система вже інтегрована з API формату OpenAI, ви можете використовувати Chat Completion API для безшовного переходу. Якщо вам потрібно використовувати всі нативні можливості Claude, рекомендується використовувати Messages API.

Обробка помилок

При виклику API, якщо виникає помилка, API поверне відповідний код помилки та інформацію. Наприклад:

400 token_mismatched: Неправильний запит, можливо, через відсутні або недійсні параметри.
400 api_not_implemented: Неправильний запит, можливо, через відсутні або недійсні параметри.
401 invalid_token: Неавторизовано, недійсний або відсутній токен авторизації.
429 too_many_requests: Занадто багато запитів, ви перевищили ліміт запитів.
500 api_error: Внутрішня помилка сервера, щось пішло не так на сервері.

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

{
  "error": {
    "code": "400",
    "message": "token_mismatched"
  }
}

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "не вдалося отримати"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Висновок

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

Getting Started

AI Chat

AI Image

AI Video

AI Audio

Web & Data

CAPTCHA

Identity

Proxy

Advanced

Claude Messages API заявка та використання

Процес заявки

Основне використання

cURL приклад

Python приклад

Системні підказки

Python приклад

Потокова відповідь

Python приклад

Приклад JavaScript

Багатокрокова розмова

Приклад Python

Модель глибокого мислення

Приклад Python

Візуальна модель

Використання Base64 кодування зображення

Використання URL зображення

cURL приклад

Використання інструментів (Tool Use)

Приклад Python

Відмінності з API завершення чату

Обробка помилок

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

Висновок

Getting Started

AI Chat

AI Image

AI Video

AI Audio

Web & Data

CAPTCHA

Identity

Proxy

Advanced

​Процес заявки

​Основне використання

​cURL приклад

​Python приклад

​Системні підказки

​Python приклад

​Потокова відповідь

​Python приклад

​Приклад JavaScript

​Багатокрокова розмова

​Приклад Python

​Модель глибокого мислення

​Приклад Python

​Візуальна модель

​Використання Base64 кодування зображення

​Використання URL зображення

​cURL приклад

​Використання інструментів (Tool Use)

​Приклад Python

​Відмінності з API завершення чату

​Обробка помилок

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

​Висновок

Процес заявки

Основне використання

cURL приклад

Python приклад

Системні підказки

Python приклад

Потокова відповідь

Python приклад

Приклад JavaScript

Багатокрокова розмова

Приклад Python

Модель глибокого мислення

Приклад Python

Візуальна модель

Використання Base64 кодування зображення

Використання URL зображення

cURL приклад

Використання інструментів (Tool Use)

Приклад Python

Відмінності з API завершення чату

Обробка помилок

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

Висновок