Адрес 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 из названия карточки.
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 можно выполнить:
request.mjs и выполните node request.mjs. Код отправляет один запрос, без автоматического повтора. При сетевой ошибке сохраните прежний REQUEST_ID и всё тело.
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: векторы для строк; точные параметры в руководстве по векторизации.
json_schema и произвольные дополнительные поля в chat сейчас не принимаются. Функции, которые вернула модель, выполняет ваше приложение. Kvantora не запускает их код.
Матрица совместимости перечисляет ограничения и проверенные версии SDK. Отдельные примеры: chat, Messages, Responses, SSE.
Медиа и приватные файлы
Медиа используют асинхронные задания Kvantora с JSON-телом. Ответ на генерацию содержит задание, а не готовый файл. Полная совместимость медиа с SDK OpenAI не заявлена.- Получите оценку через
POST /v1/quotes. Оценка не создаёт резерв. - Передайте значение
estimated_cost_microrubкакmax_cost_microrubи отдельныйIdempotency-Keyв запрос генерации. - Проверяйте
GET /v1/jobs/IDдо завершения. Приunknownсохраните ID и дождитесь уточнения исхода. - После
succeededвозьмитеoutput.file_idи запроситеGET /v1/files/ID/download.
/v1/images/generations; видео: /v1/videos; озвучивание: /v1/audio/speech. Для редактирования изображения и транскрипции нужен собственный проверенный file_id. Эти две операции сейчас недоступны для внешних моделей.
Загрузка проходит проверку размера, SHA-256, типа и антивируса. Приватная ссылка на результат ограничена сроком действия. Подробности: файлы, задания, изображения, видео, аудио.
Стоимость и дневной бюджет
Цены, бюджет и расходы показывайте в рублях с двумя знаками после запятой без округления вверх: 0,99975 ₽ → 0,99 ₽. Поля API сохраняют точность: 1 ₽ = 1 000 000 единиц API. Не подставляйте отображённую сумму обратно в расчёты. Код перевода и показа сумм. Цена модели содержит единицу и количество.unit=token и quantity=1000000 означают цену за миллион токенов. Отсутствующая цена не означает бесплатный запрос. Медиа сейчас принимаются только с опубликованным фиксированным тарифом за запрос.
Перед платной отправкой резервируется верхняя оценка. После подтверждённого результата сумма списывается один раз, остаток возвращается в доступный баланс. Неизвестный исход сохраняет резерв. Дневной бюджет ключа общий для API и MCP; он учитывает списания и открытые резервы.
GET /v1/balance показывает доступный баланс и резерв; GET /v1/usage?days=30 показывает использование. Подробнее: расчёт стоимости и дневные бюджеты.
Ошибки и безопасные повторы
СоздайтеREQUEST_ID один раз на логический запрос. После сетевой ошибки используйте прежний API-ключ, endpoint, Idempotency-Key и то же тело. Новый ID создаёт новый запрос и может привести к повторному списанию.
Ошибка содержит
error.code, error.message и error.request_id. Не повторяйте неопределённый платный вызов другой моделью. Полная памятка по ошибкам.