> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Claude AI 集成指南 - XHuoAPI

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](https://api.xhuoapi.ai/documents/280928a2-2dce-419c-adb5-1ea835e8183a) и нажмите кнопку «Acquire», чтобы получить необходимые для запроса учетные данные:

![](https://cdn.xhuoapi.ai/nyq0xz.png)

Если вы еще не вошли в систему или не зарегистрированы, вы будете автоматически перенаправлены на страницу входа, где вас пригласят зарегистрироваться и войти в систему. После входа в систему или регистрации вы будете автоматически возвращены на текущую страницу.

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

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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())
```

После вызова возвращается следующий результат:

```json theme={null}
{
  "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

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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

```javascript theme={null}
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.xhuoapi.ai/v1/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

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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())
```

Возвращаемый результат будет следующим:

```json theme={null}
{
  "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

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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())
```

Возвращаемый результат будет следующим:

```json theme={null}
{
  "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

```python theme={null}
import base64
import requests

url = "https://api.xhuoapi.ai/v1/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 theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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.xhuoapi.ai/ueugot.png"
                    }
                },
                {
                    "type": "text",
                    "text": "Что на этом изображении?"
                }
            ]
        }
    ]
}

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

### cURL 示例

```bash theme={null}
curl -X POST 'https://api.xhuoapi.ai/v1/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.xhuoapi.ai/ueugot.png"
            }
          },
          {
            "type": "text",
            "text": "Что на этом изображении?"
          }
        ]
      }
    ]
  }'
```

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

Пример возвращаемого результата:

```json theme={null}
{
  "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

```python theme={null}
import requests

url = "https://api.xhuoapi.ai/v1/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`:

```json theme={null}
{
  "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` модели:

```python theme={null}
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 завершения чата

XHuoAPI одновременно предоставляет два формата 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`: Внутренняя ошибка сервера, что-то пошло не так на сервере.

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

```json theme={null}
{
  "error": {
    "code": "400",
    "message": "Неверный запрос, возможно, из-за отсутствующих или недопустимых параметров."
  }
}
```

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

## Заключение

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