# Обзор API (/docs/api/overview)

> Все эндпоинты Hubris API на одной странице — текст, эмбеддинги, реранкеры, картинки, звук, видео, каталог и аккаунт. Базовый URL, заголовки и общие соглашения.

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

## Базовый URL

```
https://api.hubris.pw/v1
```

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

## Заголовки

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

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

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

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

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

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

### Картинки

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

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

### Звук

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

### Видео

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

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

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

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

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

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

Ключ [только для чтения](/docs/dashboard/workspaces#ключ-только-для-чтения) подходит для каталога, расхода и метрик: ничего не тратит, и его не страшно положить в конфиг. Запросы к моделям с ним отвечают `403 key_read_only`.

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

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

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

### Интеграции

| Метод и путь                                                                                                                                 | Что делает                                             |
| -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| [`POST`, `GET /v1/integrations/bitrix24/connectors`](/docs/integrations/bitrix24), [`DELETE …/connectors/{id}`](/docs/integrations/bitrix24) | Коннекторы Битрикс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` или [каталог](/models).

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

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

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

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

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

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

## Повторы запросов

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

Исключение — `POST /v1/videos`: с заголовком `Idempotency-Key` повтор вернёт уже созданную задачу, не создавая вторую. Все `GET`-запросы идемпотентны.

## Потоковая передача

При `stream: true` ответ `POST /v1/chat/completions` и `POST /v1/responses` приходит через Server-Sent Events, формат — на странице [Потоковая передача](/docs/api/streaming). `POST /v1/messages` отдаёт поток в формате Anthropic.

## Ошибки

Ошибки приходят в формате OpenAI `{ "error": { "message", "type", "code" } }`, у `POST /v1/messages` — в формате Anthropic. Все коды и что делать в каждом случае — на странице [Ошибки](/docs/concepts/errors).