Hubris API — один адрес и один ключ для всех моделей каталога. Запросы к текстовым моделям, эмбеддингам, картинкам и звуку идут в формате OpenAI, поэтому работают официальные SDK OpenAI и любые совместимые библиотеки. Для Claude Code и SDK Anthropic есть отдельный эндпоинт в формате Anthropic. У реранкеров, моделей решений и видео свой формат, он описан на их страницах.

Базовый URL

https://api.hubris2.ru/v1

Все пути ниже — от этого адреса, например https://api.hubris2.ru/v1/chat/completions. В SDK OpenAI и Anthropic достаточно поменять базовый URL и ключ.

Заголовки

Заголовок	Значение
`Authorization`	`Bearer sk-gw-...` — ваш API-ключ, обязательно. Как получить — в Аутентификации.
`Content-Type`	`application/json` для `POST`. Исключение — распознавание речи: файл можно отправить как `multipart/form-data`.

Все эндпоинты

Текст и диалоги

Метод и путь	Что делает
`POST /v1/chat/completions`	Ответ модели на переписку: обычный или потоком, с инструментами, картинками и файлами на входе. Основной эндпоинт, формат OpenAI.
`POST /v1/responses`	То же в формате OpenAI Responses API (бета): для рассуждающих моделей, агентов и Codex CLI.
`POST /v1/messages`	Формат Anthropic Messages API: для Claude Code и SDK Anthropic.

Поиск по смыслу

Метод и путь	Что делает
`POST /v1/embeddings`	Превращает текст в вектор чисел: для семантического поиска, RAG и кластеризации. Формат OpenAI.
`POST /v1/rerank`	Сортирует найденные документы по близости к запросу: лучшие первыми, у каждого оценка. Ставится после поиска.
`POST /v1/decisions`	Модели решений: вместо текста отвечают «да/нет», выбором из списка или оценкой по шкале, с вероятностями.

Картинки

Метод и путь	Что делает
`POST /v1/images/generations`	Генерация изображений по описанию, формат OpenAI Images API.

Модели, которые рисуют прямо в ответе чата и пишут текст (Gemini Image, GPT-5 Image), вызываются через POST /v1/chat/completions. Какой адрес нужен модели, сказано на её карточке в каталоге.

Звук

Метод и путь	Что делает
`POST /v1/audio/transcriptions`	Распознавание речи: аудиофайл на входе, текст на выходе. Формат OpenAI.
`POST /v1/audio/speech`	Озвучка: текст на входе, аудиофайл на выходе. Формат OpenAI.

Видео

Метод и путь	Что делает
`POST /v1/videos`	Запускает генерацию видео. Работа идёт в фоне, сразу приходит номер задачи.
`GET /v1/videos/{id}`	Статус задачи.
`GET /v1/videos/{id}/content`	Скачивание готового ролика (mp4).
`GET /v1/videos/models`	Видеомодели с их длительностями, разрешениями и ценами.
`POST /v1/video/transcriptions`	Расшифровка или пересказ ролика YouTube по ссылке.

Каталог моделей

Метод и путь	Что делает
`GET /v1/models`	Модели с ценами в рублях. Без параметров — модели, которые отвечают текстом. Другие виды — фильтром `?output_modalities=`: `embeddings`, `rerank`, `decisions`, `image`, `video`, `speech`, `transcription`, весь каталог — `all`.

Расход и состояние ключа

Работают обычным ключом sk-gw-….

Метод и путь	Что делает
`GET /v1/key`	Сведения о ключе, которым сделан запрос: лимит, сколько потрачено и осталось, баланс аккаунта (у ключа без денег кабинета — `null`).
`GET /v1/usage`	Расход этого ключа за период: рубли, токены, число запросов.
`GET /v1/metrics`	Баланс, расход, запросы и время ответа в формате Prometheus — для Grafana и алертов. Ключ без денег кабинета видит только свои ряды, без баланса.

Ключ только для чтения подходит для каталога, расхода и метрик: ничего не тратит, и его не страшно положить в конфиг. Запросы к моделям с ним отвечают 403 key_read_only.

Управление аккаунтом

Нужен management-ключ sk-gw-mgmt-…: он создаётся только в кабинете на /management-keys и не умеет вызывать модели. Подробно — Management API.

Метод и путь	Что делает
`GET /v1/credits`	Баланс аккаунта.
`GET /v1/transactions`	История пополнений и списаний.
`GET /v1/keys`, `POST /v1/keys`	Список ключей аккаунта, создание ключа.
`GET`, `PATCH`, `DELETE /v1/keys/{id}`	Один ключ: просмотр, изменение лимита и прав, отзыв.

Интеграции

Метод и путь	Что делает
`POST`, `GET /v1/integrations/bitrix24/connectors`, `DELETE …/connectors/{id}`	Коннекторы Битрикс24: модель Hubris в чатах Битрикс24.

Какой эндпоинт выбрать

Чат-бот, ассистент, обработка текста — POST /v1/chat/completions.
Claude Code, Cline и другие агенты под Anthropic — POST /v1/messages; Codex CLI — POST /v1/responses.
Поиск по базе знаний: POST /v1/embeddings находит кандидатов, POST /v1/rerank выбирает из них лучшие, POST /v1/chat/completions отвечает по ним.
Классификация и маршрутизация обращений без генерации текста — POST /v1/decisions.
Какая модель для чего и сколько стоит — GET /v1/models или каталог.

Спецификация OpenAPI

Машиночитаемая спецификация OpenAPI 3.1: https://hubris2.ru/openapi.json. Её можно отдать генератору клиента или AI-агенту. В ней описаны все эндпоинты этой страницы.

Версионирование

Префикс /v1 — стабильный. Несовместимые изменения пойдут под /v2/..., не ломая существующие интеграции.

Об отключении устаревшего эндпоинта или поля предупреждаем не меньше чем за 90 дней: заголовками Deprecation и Sunset, записью в журнале изменений и письмом. Подробно — Версии API и вывод из эксплуатации.

Метка бета у /v1/responses относится только к составу блоков ответа (output[]): туда со временем добавляются новые типы по мере того, как их вводят провайдеры моделей. Авторизация, тарификация и потоковая передача стабильны и подходят для продакшена.

Обзор API