Начало

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. Организация и проект определяются ключом; поле в теле запроса не переключает их. Все права ключа.

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

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

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 задаёт путь операции. Поля каталога и цены.

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

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

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

export REQUEST_ID="$(node -e 'console.log(crypto.randomUUID())')"

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

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: текст, изображения на входе (ссылка kvantora-file:<id> на ваш файл), вызовы функций и JSON-объект. SSE доступен при включённом текстовом стриминге.
  • POST /v1/responses: текст без серверной истории; stream=false, store=false.
  • POST /v1/messages: текстовые сообщения, обязательный max_tokens, без потока.
  • POST /v1/embeddings: векторы для строк; точные параметры в руководстве по векторизации.

Совместимость с OpenAI и Anthropic ограничена перечисленными параметрами. Hosted tools, json_schema и произвольные дополнительные поля в chat сейчас не принимаются. Изображения chat принимает только ссылкой kvantora-file:<id> на ваш загруженный файл (внешние URL и data-URL отклоняются), Responses и Messages изображения не принимают: как отправить картинку. Функции, которые вернула модель, выполняет ваше приложение. Kvantora не запускает их код.

Матрица совместимости перечисляет ограничения и проверенные версии SDK. Отдельные примеры: chat, Messages, Responses, SSE.

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

Медиа используют асинхронные задания 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; транскрипция: /v1/audio/transcriptions; редактирование изображения: /v1/images/edits. Для двух последних нужен собственный проверенный file_id. Доступность зависит от модели: проверяйте enabled у нужной операции в availability.operations. Транскрипция включена у части моделей каталога (см. аудио); редактирование изображений сейчас не включено ни у одной.

Загрузка проходит проверку размера, SHA-256, типа и антивируса. Приватная ссылка на результат ограничена сроком действия. Подробности: файлы, задания, изображения, видео, аудио.

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

Баланс, цены и расходы показывайте в рублях с двумя знаками: 1 000,00 ₽, 999,99 ₽. Для ненулевой стоимости меньше копейки используйте менее 0,01 ₽, а не «Бесплатно». Точный расчёт и числовой контракт действующего API сохраняются; округление применяется только к отображению. Форматирование рублей, оценка текста и медиа.

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

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

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

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

Создайте 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. Не повторяйте неопределённый платный вызов другой моделью. Полная памятка по ошибкам.

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

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

Автоматизации · MCP · Матрица совместимости.

Esc
↑↓ выбратьEnter открытьEsc закрыть