# Claude Sonnet 5.5 — /chat/completions

Claude Sonnet 5.5 (Anthropic) — API для чата с преемником Claude Sonnet 5, сочетающим скорость и интеллект: повседневное программирование, агенты и большая нагрузка в продакшене. Контекстное окно на 1 000 000 токенов, до 128 000 выходных токенов за запрос, ввод изображений, вызов инструментов и кэширование промптов; структурированный вывод и ввод PDF доступны в нативном API Anthropic.

**Эндпоинт:** `POST https://kovapi.com/v1/chat/completions`

## Быстрый старт

Два шага: отправить запрос, а затем получить ответ в потоковом режиме. Замените YOUR_API_KEY своим ключом, и команды ниже заработают как есть. Эндпоинт совместим с OpenAI Chat Completions, поэтому в готовом коде для OpenAI достаточно поменять `base_url` и `model`.

**Шаг 1 · Отправка запроса**

```
curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-5-5", "messages": [{"role": "user", "content": "Объясни одним предложением, что такое фотосинтез"}]}'
```

Ответ (HTTP 200)

```
{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "claude-sonnet-5-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Фотосинтез — это процесс, в котором растения с помощью солнечного света превращают углекислый газ и воду в сахар и выделяют кислород."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 42,
    "total_tokens": 60
  }
}
```

`message.content` — это ответ, а в `usage` — токены, по которым оплачивается этот запрос; как оплачивается кэширование промптов, описано ниже в разделе «Кэширование промптов».

**Шаг 2 · Потоковый вывод (рекомендуется)**

```
curl -N https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-5-5", "stream": true, "messages": [{"role": "user", "content": "Объясни одним предложением, что такое фотосинтез"}]}'
```

Поток — это стандартный SSE: каждый фрагмент несёт текст в `choices[0].delta.content`, последний фрагмент содержит `usage`, а завершается поток строкой `data: [DONE]`. Для длинных ответов и моделей с размышлениями используйте потоковый вывод: непотоковый запрос обрывается примерно через 10 минут.

**Python (OpenAI SDK)**

```
from openai import OpenAI

client = OpenAI(base_url="https://kovapi.com/v1", api_key="YOUR_API_KEY")

# 1. Один запрос — один ответ
resp = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[{"role": "user", "content": "Объясни одним предложением, что такое фотосинтез"}],
)
print(resp.choices[0].message.content)

# 2. Потоковый вывод
stream = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[{"role": "user", "content": "Объясни одним предложением, что такое фотосинтез"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
```

**Или используйте Anthropic SDK (нативный API)**

```
import anthropic

client = anthropic.Anthropic(base_url="https://kovapi.com/anthropic", api_key="YOUR_API_KEY")
msg = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Объясни одним предложением, что такое фотосинтез"}],
)
print(next(b.text for b in msg.content if b.type == "text"))
```

В Anthropic SDK укажите `base_url` до `/anthropic` включительно — `/v1/messages` SDK добавит сам; ключ тот же.

## Аутентификация
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Основные характеристики

| Контекстное окно | 1 000 000 токенов |
| --- | --- |
| Максимум выходных токенов за запрос | 128 000 токенов |
| Входные данные | Текст, изображения |
| Размышления | Размышления не управляются параметрами; интенсивность и сводки размышлений не гарантируются |
| Вызов инструментов | Поддерживается (формат OpenAI `tools`) |
| Веб-поиск | Поддерживается (`web_search: true`; сам поиск бесплатный) |
| Эндпоинты | /v1/chat/completions · /anthropic/v1/messages |
| Потоковый вывод | Поддерживается (`stream: true`, SSE) |
| Оплата | За токены: у входа, выхода (включая размышления) и попаданий в кэш — свои цены; неудачные запросы бесплатны |

## Параметры запроса

JSON-тело запроса `POST /v1/chat/completions` — такое же, как в OpenAI Chat Completions. Основные параметры и то, как каждый из них работает у этой модели:

| Параметр | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| model | string | Да | ID модели: `claude-sonnet-5-5`. |
| messages | array | Да | Диалог: у каждого сообщения есть `role` (`system`, `user`, `assistant` или `tool`) и `content`. `content` — строка или массив частей `text` и `image_url` (ввод изображений, см. ниже). Чтобы продолжить диалог, передавайте всю историю сообщений по порядку. |
| stream | boolean | Нет | `true` — ответ приходит потоком SSE, а `usage` — в последнем фрагменте. По умолчанию `false`. |
| max_tokens | integer | Нет | Лимит вывода, включая токены размышлений. Если задать его слишком маленьким, модель может израсходовать его целиком ещё до ответа: тогда шлюз вернёт 400 `max_tokens_too_small` и ничего не спишет (рекомендуется 512 и больше). У некоторых моделей слишком маленькое значение автоматически повышается до минимума, при котором хватает места на полный ответ; оплата и тогда идёт только по фактическому расходу. |
| temperature / top_p | number | Нет | Это поколение Claude больше не поддерживает параметры сэмплирования: шлюз удаляет `temperature`, `top_p` и `top_k` (без ошибки), и модель использует сэмплирование по умолчанию. |
| reasoning_effort | string | Нет | Действие не гарантируется: размышления этой модели параметрами не управляются. |
| tools / tool_choice | array / string | Нет | Вызов функций в стандартном формате OpenAI. Принудительный вызов инструментов эта модель не поддерживает: `tool_choice` со значением `required` или с указанной функцией заменяется на `auto`. |
| web_search | boolean | Нет | `true` — сначала выполняется веб-поиск, и его результаты передаются модели как справочные материалы; подробнее — ниже. |

Остальные параметры OpenAI (например, `stop`, `seed`, `user`) передаются модели без изменений; сработают ли они, зависит от модели.

## Цена

Оплата за токены по актуальным ценам ниже (за миллион токенов). Токены, записанные в кэш промптов, оплачиваются по цене записи в кэш, а попадания в кэш — по цене попадания в кэш. Оплачиваются только успешные запросы и только по фактическому расходу. 1 кредит = $0.005.

| Тип | USD за 1 млн токенов | Кредитов за 1 млн токенов |
| --- | --- | --- |
| Вход | $1.50 | 300 |
| Выход (включая размышления) | $7.50 | 1500 |
| Попадание в кэш | $0.15 | 30 |
| Запись в кэш | $1.875 | 375 |

Например, запрос с 2000 входных токенов и 1000 выходных (включая размышления) стоит около $0.0105.

## Размышления

Будет ли эта модель сначала размышлять, параметрами не управляется, и её ответы не обязательно содержат размышления.

`reasoning_effort`, `output_config.effort` в нативном API и настройка `thinking` не гарантированно действуют. Если нужна настраиваемая интенсивность размышлений, выберите Claude Opus 5.5 или модель Claude 5.

Токены размышлений считаются выходными и оплачиваются по цене выхода.

## Кэширование промптов

Длинные промпты могут автоматически записываться в кэш даже без пометки (по цене записи в кэш), и тогда повторяющийся префикс оплачивается по цене попадания в кэш. В нативном API `/anthropic` место кэширования можно задать самостоятельно: `"cache_control": {"type": "ephemeral"}` в системном промпте или в блоке сообщения; Claude Code делает это сам.

Нативный API сообщает число токенов кэша в `usage.cache_creation_input_tokens` (запись) и `usage.cache_read_input_tokens` (попадания), и списание считается по этим числам.

## Ввод изображений

Добавьте в массив `content` часть `image_url`. Рекомендуемый вариант — data URI в base64 (`data:image/png;base64,...`): его всегда удаётся прочитать. Изображение по публичной ссылке сначала нужно скачать, и иногда это не удаётся или не укладывается в таймаут. Изображения пересчитываются во входные токены по правилам разработчика модели.

```
curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-5-5", "messages": [{"role": "user", "content": [{"type": "text", "text": "Что изображено на этой картинке"}, {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBORw0KGgo..."}}]}]}'
```

## Вызов инструментов (function calling)

Опишите свои функции в `tools` с помощью JSON Schema. Когда модель решит вызвать функцию, она вернёт `finish_reason: "tool_calls"`, а в `message.tool_calls` — имя функции и аргументы (строкой JSON).

```
curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-5-5", "messages": [{"role": "user", "content": "Какая сейчас погода в Шанхае"}], "tools": [{"type": "function", "function": {"name": "get_weather", "description": "Current weather of a city", "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}}]}'
```

Выполните функцию, добавьте результат в диалог сообщением с `role: "tool"` и соответствующим `tool_call_id` и отправьте диалог повторно — модель даст итоговый ответ. `tool_choice` принимает `auto`, `none`, `required` или конкретную функцию.

## Веб-поиск

Добавьте в запрос `"web_search": true` (или элемент `{"type": "web_search"}` в `tools`): шлюз сначала ищет в интернете в реальном времени по содержанию диалога, передаёт модели до 5 результатов со ссылками как справочные материалы, а модель отвечает и указывает источники. Сам поиск бесплатный; справочный текст оплачивается как входные токены.

```
curl https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-5-5", "web_search": true, "messages": [{"role": "user", "content": "Какие главные технологические новости сегодня"}]}'
```

## Нативный API Anthropic (/anthropic)

- Адрес — `https://kovapi.com/anthropic/v1/messages`, запросы и ответы используют формат Anthropic Messages: потоковые события, вызовы инструментов (`tool_use` / `tool_result`) и блоки изображений полностью совпадают с Anthropic, поэтому Anthropic SDK и Claude Code работают без изменений.

- Авторизация — через заголовок `x-api-key: YOUR_API_KEY` (подходит и `Authorization: Bearer`); ключ тот же, что и для `/v1`. Заголовки `anthropic-version` и `anthropic-beta` передаются без изменений, а `max_tokens` обязателен.

- Здесь доступны только модели Claude: на любую другую модель вернётся 404 `not_found_error`. Также есть `POST /anthropic/v1/messages/count_tokens` (подсчёт токенов, бесплатно) и `GET /anthropic/v1/models`.

- Здесь доступны структурированный вывод (`output_config.format`) и ввод PDF; интенсивность и сводки размышлений не гарантируются. Принудительный вызов инструментов (`tool_choice` со значением `any` или с указанным инструментом) заменяется на `auto`, а предзаполнение ответа ассистента (последнее сообщение `assistant`) возвращает 400.

- Ошибки возвращаются в формате Anthropic: `{"type": "error", "error": {"type": ..., "message": ...}}`; если на балансе не хватает средств, возвращается 402 `billing_error`.

- Веб-поиск на этом эндпоинте по умолчанию выключен (чтобы не менять префикс, который Claude Code повторяет в каждом ходе, и не сбивать его кэш); включается заголовком `x-web-search: 1`.

```
curl https://kovapi.com/anthropic/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-5-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Объясни одним предложением, что такое фотосинтез"}]}'
```

[Использование в Claude Code →](https://docs.kovapi.com/ru/integrations/claude-code)

## Надёжность и автоматические повторы

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

- Начав передачу, поток больше не повторяется автоматически: если он оборвётся на середине, оплачивается то, что успело сгенерироваться до обрыва (см. [Оплата и возвраты](https://docs.kovapi.com/ru/guide/billing)).

- Если модель загружена до предела, шлюз возвращает 429 с `Retry-After`: подождите указанное число секунд и повторите. Неудачные запросы не оплачиваются. Статус каждой модели — на [странице статуса](https://kovapi.com/ru/status).

## Ошибки и возвраты

Ошибки возвращаются объектом `error` (`message`, `type`, `code`, `param`); ориентируйтесь на HTTP-статус и `code`, а не на текст `message`. Неудачные запросы не оплачиваются; полный список — в разделе [Коды ошибок](https://docs.kovapi.com/ru/guide/errors).

| HTTP | code | Причина | Что делать |
| --- | --- | --- | --- |
| 400 | invalid_messages / invalid_role / invalid_max_tokens | В запросе к чату поле `messages` отсутствует, пустое или имеет неверный формат, у `role` недопустимое значение либо `max_tokens` — не положительное целое число. Поле указано в `param`. | Исправьте поле, указанное в `param`. |
| 400 | model_not_found | ID модели написан с ошибкой, `model` не передан или модель нельзя использовать на этом эндпоинте (например, чат-модель на эндпоинте изображений). | Берите ID модели из `GET /v1/models` или из [справочника API](https://docs.kovapi.com/ru/api). |
| 400 | max_tokens_too_small | Модель с размышлениями потратила весь `max_tokens` на размышления и не написала ответ (непотоковый чат). | Увеличьте `max_tokens` и повторите. |
| 4xx | invalid_request | Поставщик модели отклонил запрос (например, из-за слишком длинного контекста или неподдерживаемого параметра); статус и `message` передаются в том виде, в каком их прислал поставщик, а в `code` — его значение. | Измените запрос согласно `message`. |
| 401 | invalid_api_key | Ключ не существует, удалён или отключён, либо отключён аккаунт. | Проверьте ключ на странице API Keys в консоли. |
| 402 | insufficient_quota | Баланса не хватает, чтобы зарезервировать стоимость этого запроса. Шлюз сначала резервирует максимально возможную стоимость запроса, поэтому ошибка может возникнуть и при всплеске одновременных вызовов. | Если был всплеск запросов, подождите несколько секунд и повторите; в остальных случаях пополните баланс. |
| 403 | permission_denied | Модели нет в списке разрешённых моделей ключа. | Используйте модель из списка разрешённых или измените список в консоли. |
| 429 | rate_limit_exceeded | Превышен лимит запросов в минуту, заданный для этого ключа (считается за последние 60 секунд). Заголовка `Retry-After` нет. | Подождите несколько секунд и повторите или увеличьте лимит ключа в консоли. |
| 429 | rate_limit_exceeded | Модель загружена до предела, и запрос не был отправлен. Бывает только на эндпоинтах чата: задачи изображений и видео не отклоняются, а встают в очередь. OpenAI-совместимые эндпоинты добавляют `Retry-After`. | Подождите столько секунд, сколько указано в `Retry-After`, и повторите. |
| 502 | upstream_timeout | Поставщик не уложился в таймаут, в том числе слишком долго не отправлял первый токен. | Повторите; для длинных ответов используйте `stream: true`. |
| 502 | upstream_unavailable | Поставщик дал сбой или временно недоступен. | Повторите чуть позже. |
| 502 | upstream_busy | Поставщик модели ограничивает частоту запросов. Его 429 никогда не передаётся вам как 429 — вместо этого вы получаете этот 502. | Повторите чуть позже. |
| 502 | empty_completion | Поставщик модели вернул пустой ответ. Это не оценка вашего контента. | Повторите. |
| 503 | model_maintenance | Модель на обслуживании и не принимает запросы; пока идёт обслуживание, другая модель вместо неё не ответит. | Повторите, когда обслуживание закончится; ход работ — на [странице статуса](https://kovapi.com/ru/status). |

Если поток дал сбой уже после начала передачи, код статуса не меняется: ошибка приходит строкой данных с `error`, или поток просто заканчивается (без `data: [DONE]`). Считайте такой поток оборванным.