Справочник API
Эндпоинты и параметры
Базовый адрес всех эндпоинтов:
https://api.tsarrouter.ru/v1API совместим с OpenAI: подставьте этот адрес в base_url любого OpenAI-клиента.
Ключ передаётся в заголовке Authorization: Bearer sk-tsar-ваш-ключ. Какой ключ
нужен эндпоинту - в колонке «Ключ» таблицы ниже и на странице эндпоинта.
Потоковое распознавание речи работает через WebSocket и описано в руководстве: «Потоковое распознавание».
Эндпоинты
Модели
| Эндпоинт | Что делает | Ключ |
|---|---|---|
GET /v1/models | Список моделей | Вызов моделей |
GET /v1/models/{model_id} | Карточка модели | Вызов моделей |
GET /v1/models/info | Публичный прайс | без ключа |
Текст
| Эндпоинт | Что делает | Ключ |
|---|---|---|
POST /v1/chat/completions | Ответ текстовой модели | Вызов моделей |
POST /v1/embeddings | Векторы текста | Вызов моделей |
POST /v1/rerank | Сортировка документов по запросу | Вызов моделей |
POST /v1/classify | Классификация текста | Вызов моделей |
POST /v1/ai/check | Детектор ИИ-текста | Вызов моделей |
Изображения
| Эндпоинт | Что делает | Ключ |
|---|---|---|
POST /v1/images/generations | Генерация картинки | Вызов моделей |
POST /v1/images/enhance | Улучшение и увеличение фото | Вызов моделей |
Аудио
| Эндпоинт | Что делает | Ключ |
|---|---|---|
POST /v1/audio/speech | Синтез речи | Вызов моделей |
POST /v1/audio/transcriptions | Распознавание речи | Вызов моделей |
POST /v1/audio/sentiment | Тональность речи | Вызов моделей |
Аккаунт
| Эндпоинт | Что делает | Ключ |
|---|---|---|
GET /v1/balance | Баланс аккаунта | Просмотр баланса |
GET /v1/key | Статус ключа | любой |
GET /v1/limits | Сетка лимитов | без ключа |
Ключи и доступ
Тип ключа выбирается при создании и потом не меняется. Нужен другой доступ - создайте ещё один ключ.
| Тип | Для чего | Кредитный лимит | Срок действия |
|---|---|---|---|
| Вызов моделей | запросы к моделям: текст, картинки, речь, эмбеддинги; список моделей и статистика | можно задать | можно задать |
| Просмотр баланса | узнать баланс аккаунта через API | нет | можно задать |
Ключ «Просмотр баланса» не может тратить деньги, поэтому его можно отдать
системе мониторинга или бухгалтерии. Баланс аккаунта через API видит только он.
GET /v1/key отвечает ключу любого типа, а
GET /v1/models/info и
GET /v1/limits работают без ключа.
Ключ не того типа получает 403 с кодом insufficient_scope, в тексте сказано,
какой ключ нужен:
{
"error": {
"message": "Баланс доступен ключу типа «Просмотр баланса» - создайте его в личном кабинете.",
"type": "permission_error",
"param": null,
"code": "insufficient_scope"
}
}Как создать ключ
- Откройте «API-ключи» в личном кабинете и нажмите «Создать ключ».
- Задайте название и выберите тип: «Вызов моделей» или «Просмотр баланса».
- Для ключа «Вызов моделей» при желании задайте кредитный лимит в рублях и период его сброса: ежедневно, еженедельно, ежемесячно или без сброса.
- Выберите срок действия или оставьте «Без срока действия».
Ключ показывается один раз, сразу после создания, - сохраните его. На аккаунте
может быть до 10 ключей. Что умеет ключ, покажет поле scopes в
GET /v1/key: ["models"] у ключа «Вызов моделей» и
["balance:read"] у ключа «Просмотр баланса».
Формат ошибок
Все ошибки приходят в формате OpenAI:
{
"error": {
"message": "Invalid API key",
"type": "authentication_error",
"param": null,
"code": "401"
}
}code обычно повторяет HTTP-код строкой. Исключения: insufficient_scope -
ключ не того типа, invalid_value - запрос не прошёл проверку. Все коды и что с
ними делать - в списке ошибок.
Лимиты
Лимиты считаются на аккаунт целиком, по всем ключам сразу. На странице каждого
эндпоинта указано, какой счётчик он расходует; значения для вашего аккаунта - в
GET /v1/key, сетка по уровням - в
GET /v1/limits, подробнее - на странице
«Лимиты». Ответ 429 несёт заголовок Retry-After: через
сколько секунд повторить запрос.