# Qwen3.8 Max — /chat/completions

Qwen3.8 Max (Alibaba Cloud) — API для чата с флагманом поколения Qwen 3.8, самой сильной моделью Qwen в рассуждениях, программировании и агентных задачах. Модель всегда размышляет перед ответом; вызов инструментов, вывод в формате JSON и ввод изображений. Работает с OpenAI SDK.

**Эндпоинт:** `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": "qwen3.8-max", "messages": [{"role": "user", "content": "Объясни одним предложением, что такое фотосинтез"}]}'
```

Ответ (HTTP 200)

```
{
  "id": "chatcmpl-7f3c9a1e2b4d6f8a",
  "object": "chat.completion",
  "created": 1791281400,
  "model": "qwen3.8-max",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Фотосинтез — это процесс, в котором растения с помощью солнечного света превращают углекислый газ и воду в сахар и выделяют кислород.",
        "reasoning_content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 18,
    "completion_tokens": 186,
    "total_tokens": 204,
    "prompt_tokens_details": {"cached_tokens": 0},
    "completion_tokens_details": {"reasoning_tokens": 144}
  }
}
```

`message.content` — это ответ, `message.reasoning_content` — размышления. В `usage` — токены, по которым оплачивается этот запрос: токены размышлений входят в `completion_tokens` и оплачиваются по цене выхода.

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

```
curl -N https://kovapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3.8-max", "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="qwen3.8-max",
    messages=[{"role": "user", "content": "Объясни одним предложением, что такое фотосинтез"}],
)
print(resp.choices[0].message.content)

# 2. Потоковый вывод
stream = client.chat.completions.create(
    model="qwen3.8-max",
    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)
```

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

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

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

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

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

| Параметр | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| model | string | Да | ID модели: `qwen3.8-max`. |
| messages | array | Да | Диалог: у каждого сообщения есть `role` (`system`, `user`, `assistant` или `tool`) и `content`. `content` — строка или массив частей `text` и `image_url` (ввод изображений, см. ниже). Чтобы продолжить диалог, передавайте всю историю сообщений по порядку. |
| stream | boolean | Нет | `true` — ответ приходит потоком SSE, а `usage` — в последнем фрагменте. По умолчанию `false`. |
| max_tokens | integer | Нет | Принимается, но может не ограничить вывод: на размышления он не действует, а оплата идёт по фактическому `usage`. Если нужен короткий ответ, попросите об этом в промпте. |
| temperature / top_p | number | Нет | Параметры сэмплирования; передаются модели без изменений (`temperature` — от 0 до 2). Модели с размышлениями могут их не учитывать. |
| reasoning_effort | string | Нет | Не действует: эта модель всегда размышляет и сама решает, сколько. |
| tools / tool_choice | array / string | Нет | Вызов функций в стандартном формате OpenAI. Когда модель вызывает функцию, она возвращает `finish_reason: "tool_calls"` и `tool_calls`; подробнее — ниже. |
| response_format | object | Нет | `{"type": "json_object"}` заставляет модель возвращать только валидный JSON; в промпте тоже напишите, что нужен JSON и с какими полями. |
| web_search | boolean | Нет | `true` — сначала выполняется веб-поиск, и его результаты передаются модели как справочные материалы; подробнее — ниже. |

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

## Цена

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

| Тип | USD за 1 млн токенов | Кредитов за 1 млн токенов |
| --- | --- | --- |
| Вход | $1.40 | 280 |
| Выход (включая размышления) | $4.20 | 840 |
| Попадание в кэш | $0.175 | 35 |

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

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

Эта модель всегда размышляет перед ответом; размышления возвращаются в `message.reasoning_content` (при потоковом выводе — в `delta.reasoning_content`). Отключить их нельзя, а `reasoning_effort` и `thinking` не действуют.

Токены размышлений входят в `usage.completion_tokens` и оплачиваются по цене выхода (некоторые модели ещё и указывают их отдельно в `completion_tokens_details.reasoning_tokens`).

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

Параметры не нужны: повторяющийся длинный префикс (тот же системный промпт, предыдущие ходы диалога) поставщик модели может закэшировать автоматически, и закэшированная часть оплачивается по более низкой цене кэша. Кэшировать ли и сколько, решает поставщик; чтобы чаще попадать в кэш, ставьте неизменные части в самое начало сообщений.

Число токенов из кэша возвращается в `usage.prompt_tokens_details.cached_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": "qwen3.8-max", "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": "qwen3.8-max", "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": "qwen3.8-max", "web_search": true, "messages": [{"role": "user", "content": "Какие главные технологические новости сегодня"}]}'
```

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

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

- Начав передачу, поток больше не повторяется автоматически: если он оборвётся на середине, оплачивается то, что успело сгенерироваться до обрыва (см. [Оплата и возвраты](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]`). Считайте такой поток оборванным.