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())

Установив системную подсказку system, можно точно контролировать роль и поведение 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, тем больше пространство для более глубоких рассуждений модели, что подходит для обработки сложных вопросов.

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

Клод поддерживает мультимодальный ввод, который может одновременно обрабатывать текст и изображения. В 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

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-запроса для того, что, похоже, является службой завершения чата ИИ. Интерфейс включает параметры для выбора модели, сообщений, режима потока и настроек максимального количества токенов."
    }
  ],
  "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`	Передается через `role: "system"` в `messages`
Структура ответа	Массив `content` (поддерживает несколько типов)	Массив `choices` (содержит `message`)
Потоковый формат	События SSE (несколько типов событий)	Строки SSE `data`
Глубокое мышление	Оригинальный параметр `thinking`	Активируется через специальное имя модели (например, с суффиксом `-thinking`)
Вызов инструментов	Оригинальные `tools` + `input_schema`	Формат `functions`, совместимый с OpenAI
Статистика токенов	`input_tokens` / `output_tokens`	`prompt_tokens` / `completion_tokens`

Если ваша система уже интегрирована с API формата OpenAI, вы можете использовать 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": "Неверный запрос, возможно, из-за отсутствующих или недопустимых параметров."
  }
}

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "не удалось получить данные"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Заключение

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

Начало работы

AI Chat

AI Image

AI Video

AI Audio

Web & Data

CAPTCHA

Identity

Proxy

Продвинутый

Claude Messages API Заявка и использование

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

Основное использование

Пример cURL

Пример на Python

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

Пример на Python

Потоковый ответ

Пример на Python

Пример на JavaScript

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

Пример на Python

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

Пример на Python

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

Использование изображений в формате Base64

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

cURL 示例

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

Пример на Python

Различия с API завершения чата

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

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

Заключение

Начало работы

AI Chat

AI Image

AI Video

AI Audio

Web & Data

CAPTCHA

Identity

Proxy

Продвинутый

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

​Основное использование

​Пример 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 завершения чата

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

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

Заключение