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

# API Kvantora: руководство

> Ключ, публичный ID модели, первый запрос, ответы, медиа, расходы и безопасные повторы.

API Kvantora принимает запросы к моделям из серверного приложения. Он использует общий баланс Kvantora, права вашего ключа и публичный ID модели из каталога.

## Адрес API и ключ

Базовый адрес API: `https://api.kvantora.ai`. Сохраните его без пути `/v1` в `KVANTORA_BASE_URL`. Путь текстового запроса: `POST /v1/chat/completions`.

Выпустите ключ в разделе «API-ключи» кабинета. Полный секрет показывается один раз. Храните его в переменной окружения на сервере и передавайте в заголовке `Authorization: Bearer <ключ>`. Используйте HTTPS.

Для первого запроса нужны `models:read` и `text` либо `inference`. Чтение баланса и расходов требует `balance:read` и `usage:read`. Организация и проект определяются ключом; поле в теле запроса не переключает их. [Все права ключа](/authentication).

## Как выбрать модель

Скопируйте `public_api_id` из каталога в поле `model`. В `GET /v1/models` поле `id` содержит тот же ID. Сервер разрешает опубликованные aliases в модель; не вычисляйте ID из названия карточки.

```bash theme={null}
curl "$KVANTORA_BASE_URL/v1/models?operation=chat&page=1&page_size=20" \
  -H "Authorization: Bearer $KVANTORA_API_KEY"
```

`data` содержит модели, а `pagination` описывает страницы. Проверьте нужную запись в `availability.operations`: `enabled` разрешает запуск, `api_path` задаёт путь операции. [Поля каталога и цены](/models).

Перед запросом проверьте `availability.operations`: нужная операция должна быть включена, а её `api_path` — соответствовать формату запроса. Ключу нужны права на эту операцию и достаточный бюджет.

## Первый запрос на Node.js

Нужен Node.js 22 или новее. Задайте `KVANTORA_BASE_URL`, `KVANTORA_API_KEY` и `KVANTORA_MODEL_ID`. Создайте `REQUEST_ID` один раз на логический запрос; для нового запроса в Bash можно выполнить:

```bash theme={null}
export REQUEST_ID="$(node -e 'console.log(crypto.randomUUID())')"
```

Сохраните код ниже в `request.mjs` и выполните `node request.mjs`. Код отправляет один запрос, без автоматического повтора. При сетевой ошибке сохраните прежний `REQUEST_ID` и всё тело.

```javascript theme={null}
const { KVANTORA_BASE_URL, KVANTORA_API_KEY,
  KVANTORA_MODEL_ID, REQUEST_ID } = process.env;
if (![KVANTORA_BASE_URL, KVANTORA_API_KEY,
  KVANTORA_MODEL_ID, REQUEST_ID].every(Boolean)) {
  throw new Error('Задайте адрес API, ключ, ID модели и REQUEST_ID');
}
const response = await fetch(
  KVANTORA_BASE_URL.replace(/[/]$/, '') + '/v1/chat/completions', {
    method: 'POST',
    redirect: 'error',
    headers: {
      Authorization: 'Bearer ' + KVANTORA_API_KEY,
      'Content-Type': 'application/json',
      'Idempotency-Key': REQUEST_ID,
    },
    body: JSON.stringify({
      model: KVANTORA_MODEL_ID,
      messages: [{ role: 'user', content: 'Привет' }],
      max_tokens: 256,
    }),
  });
const result = await response.json();
console.log('HTTP', response.status);
console.log('X-Request-Id:', response.headers.get('x-request-id'));
console.log(JSON.stringify(result, null, 2));
if (!response.ok) process.exitCode = 1;
```

Успешный ответ содержит `object: chat.completion`, текст в `choices[0].message.content` и постоянный ID выбранной модели в `model`. Расход токенов и сумму списания смотрите в `usage`, состояние расчёта в `billing.status`.

HTTP 202 означает незавершённую обработку. Это не окончательный текст модели. Для поддержки сохраните `X-Request-Id` из заголовка ответа и `id` принятого запроса.

## Поддерживаемые операции

* `POST /v1/chat/completions`: текст, вызовы функций и JSON-объект. SSE доступен при включённом текстовом стриминге.
* `POST /v1/responses`: текст без серверной истории; `stream=false`, `store=false`.
* `POST /v1/messages`: текстовые сообщения, обязательный `max_tokens`, без потока.
* `POST /v1/embeddings`: векторы для строк; точные параметры в [руководстве по векторизации](/embeddings).

Совместимость с OpenAI и Anthropic ограничена перечисленными параметрами. Vision, hosted tools, `json_schema` и произвольные дополнительные поля в chat сейчас не принимаются. Функции, которые вернула модель, выполняет ваше приложение. Kvantora не запускает их код.

[Матрица совместимости](/compatibility) перечисляет ограничения и проверенные версии SDK. Отдельные примеры: [chat](/chat), [Messages](/messages), [Responses](/responses), [SSE](/streaming).

## Медиа и приватные файлы

Медиа используют асинхронные задания Kvantora с JSON-телом. Ответ на генерацию содержит задание, а не готовый файл. Полная совместимость медиа с SDK OpenAI не заявлена.

1. Получите оценку через `POST /v1/quotes`. Оценка не создаёт резерв.
2. Передайте значение `estimated_cost_microrub` как `max_cost_microrub` и отдельный `Idempotency-Key` в запрос генерации.
3. Проверяйте `GET /v1/jobs/ID` до завершения. При `unknown` сохраните ID и дождитесь уточнения исхода.
4. После `succeeded` возьмите `output.file_id` и запросите `GET /v1/files/ID/download`.

Генерация изображений: `/v1/images/generations`; видео: `/v1/videos`; озвучивание: `/v1/audio/speech`. Для редактирования изображения и транскрипции нужен собственный проверенный `file_id`. Эти две операции сейчас недоступны для внешних моделей.

Загрузка проходит проверку размера, SHA-256, типа и антивируса. Приватная ссылка на результат ограничена сроком действия. Подробности: [файлы](/files), [задания](/jobs), [изображения](/images), [видео](/video), [аудио](/audio).

## Стоимость и дневной бюджет

Цены, бюджет и расходы показывайте в рублях с двумя знаками после запятой без округления вверх: **0,99975 ₽ → 0,99 ₽**. Поля API сохраняют точность: **1 ₽ = 1 000 000 единиц API**. Не подставляйте отображённую сумму обратно в расчёты. [Код перевода и показа сумм](/billing).

Цена модели содержит единицу и количество. `unit=token` и `quantity=1000000` означают цену за миллион токенов. Отсутствующая цена не означает бесплатный запрос. Медиа сейчас принимаются только с опубликованным фиксированным тарифом за запрос.

Перед платной отправкой резервируется верхняя оценка. После подтверждённого результата сумма списывается один раз, остаток возвращается в доступный баланс. Неизвестный исход сохраняет резерв. Дневной бюджет ключа общий для API и MCP; он учитывает списания и открытые резервы.

`GET /v1/balance` показывает доступный баланс и резерв; `GET /v1/usage?days=30` показывает использование. Подробнее: [расчёт стоимости](/billing) и [дневные бюджеты](/daily-budgets).

## Ошибки и безопасные повторы

Создайте `REQUEST_ID` один раз на логический запрос. После сетевой ошибки используйте прежний API-ключ, endpoint, `Idempotency-Key` и то же тело. Новый ID создаёт новый запрос и может привести к повторному списанию.

| Код                                                       | Что проверить                             |
| --------------------------------------------------------- | ----------------------------------------- |
| validation\_error                                         | Тело и поддерживаемые параметры           |
| unauthorized / insufficient\_scope                        | Ключ и права                              |
| api\_key\_daily\_budget\_exceeded / insufficient\_balance | Доступную сумму, лимит и открытые резервы |
| model\_unavailable                                        | Доступность нужной операции               |
| idempotency\_conflict                                     | Совпадение тела с ранее принятым запросом |

Ошибка содержит `error.code`, `error.message` и `error.request_id`. Не повторяйте неопределённый платный вызов другой моделью. [Полная памятка по ошибкам](/errors).

## API, Studio и автоматизации

API подключает ваше серверное приложение. Нейростудия позволяет работать с моделью в кабинете без кода. Автоматизация связывает обращение к модели с другими шагами. Выбирайте способ по задаче; публичный каталог и баланс общие.

[Автоматизации](/automations) · [MCP](/mcp) · [Матрица совместимости](/compatibility).