260 KiB
API Reference (Русский)
🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW
🌐 Языки: 🇺🇸 English | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇧🇦 Bosanski | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇩🇪 Deutsch | 🇬🇷 Ελληνικά | 🇪🇸 Español | 🇪🇪 Eesti | 🇮🇷 فارسی | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇪 Gaeilge | 🇮🇳 ગુજરાતી | 🇳🇬 Hausa | 🇮🇱 עברית | 🇮🇳 हिन्दी | 🇭🇷 Hrvatski | 🇭🇺 Magyar | 🇦🇲 Հայերեն | 🇮🇩 Bahasa Indonesia | 🇳🇬 Igbo | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇬🇪 ქართული | 🇰🇭 ខ្មែរ | 🇮🇳 ಕನ್ನಡ | 🇰🇷 한국어 | 🇱🇹 Lietuvių | 🇱🇻 Latviešu | 🇮🇳 മലയാളം | 🇮🇳 मराठी | 🇲🇾 Bahasa Melayu | 🇲🇹 Malti | 🇲🇲 မြန်မာ | 🇳🇵 नेपाली | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇮🇳 ଓଡ଼ିଆ | 🇮🇳 ਪੰਜਾਬੀ | 🇵🇭 Filipino | 🇵🇱 Polski | 🇵🇹 Português (Portugal) | 🇧🇷 Português (Brasil) | 🇷🇴 Română | 🇷🇺 Русский | 🇱🇰 සිංහල | 🇸🇰 Slovenčina | 🇸🇮 Slovenščina | 🇷🇸 Српски | 🇸🇪 Svenska | 🇰🇪 Kiswahili | 🇮🇳 தமிழ் | 🇮🇳 తెలుగు | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇵🇰 اردو | 🇺🇿 Oʻzbekcha | 🇻🇳 Tiếng Việt | 🇳🇬 Yorùbá | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)
Основной справочник по API OmniRoute. В нём описывается общедоступный интерфейс /v1 и наиболее часто используемые конечные точки управления; машиночитаемый docs/openapi.yaml и дерево маршрутов в src/app/api/ являются исчерпывающими источниками.
Сведения о специализированном протоколе, совместимом с OpenAI, и матрице возможностей провайдеров см. в
OPENAI_COMPATIBILITY.md.
Каждое развёртывание предоставляет собственную копию спецификации по адресу /openapi.yaml, сгенерированную из docs/openapi.yaml во время сборки. Она содержит версию сборки и относительный URL сервера (./), поэтому запросы остаются на хосте, с которого был получен документ. Инструмент, импортирующий загруженный файл, не располагает информацией об этом хосте, поэтому базовый URL необходимо задать вручную.
Содержание
- Завершение чата
- Эксклюзивные управляемые аренды сеансов
- Векторные представления
- Генерация изображений
- Распознавание документов
- Список моделей
- Манифест плагина поставщика
- Конечные точки совместимости
- API файлов
- API пакетной обработки
- API поиска
- Потоковая передача через WebSocket
- Квоты и отчёты о проблемах
- Семантический кэш
- Совместимость управления CLIProxyAPI
- Панель мониторинга и управление
- Управление комбинациями
- Вебхуки
- Зарегистрированные ключи (автоматическое управление)
- Протокол агентов
- Прокси управления
- Отказоустойчивость (расширенная)
- Навыки
- Память
- Сервер MCP
- Сервер A2A
- Облако, оценки и Assess
- Обработка запросов
- Аутентификация
Завершение чата
POST /v1/chat/completions
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "cc/claude-opus-4-6",
"messages": [
{"role": "user", "content": "Write a function to..."}
],
"stream": true
}
Пользовательские заголовки
| Header | Направление | Описание |
|---|---|---|
X-OmniRoute-No-Cache |
Запрос | Установите значение true, чтобы обойти кэш |
x-omniroute-no-memory |
Запрос | Установите значение true, чтобы пропустить внедрение памяти и навыков для этого запроса (аналогично no-cache; устраняет накладные расходы на токены и стоимость каждого вызова) |
X-OmniRoute-Progress |
Запрос | Установите значение true для событий прогресса |
X-Session-Id |
Запрос | Ключ закрепления сеанса для привязки внешнего сеанса |
x_session_id |
Запрос | Также принимается вариант с подчёркиванием (прямой HTTP) |
X-OmniRoute-Session-Id |
Запрос | Предоставленный вызывающей стороной тег сеанса/диалога (также передаётся в память). Если указан, сохраняется без изменений в call_logs.session_tag для атрибуции стоимости по сеансам (#8249) — при отсутствии никогда не создаётся автоматически |
Idempotency-Key |
Запрос | Ключ дедупликации (окно 5 с) |
X-Request-Id |
Запрос | Альтернативный ключ дедупликации |
x-omniroute-connection |
Запрос | Закрепляет запрос к одной модели за одним подключением провайдера (учётной записью) по его идентификатору — см. Закрепление учётной записи для запроса |
X-OmniRoute-Cache |
Ответ | HIT или MISS (для непотоковой передачи) |
X-OmniRoute-Idempotent |
Ответ | true, если выполнена дедупликация |
X-OmniRoute-Progress |
Ответ | enabled, если отслеживание прогресса включено |
X-OmniRoute-Session-Id |
Ответ | Фактически использованный OmniRoute идентификатор сеанса |
X-OmniRoute-Request-Id |
Ответ | Идентификатор корреляции запроса (если известен) |
X-OmniRoute-Version |
Ответ | Версия сборки OmniRoute (присутствует всегда) |
X-OmniRoute-Cost-Saved |
Ответ | Сумма в USD, сэкономленная благодаря кэшу при HIT (только для попаданий в кэш) |
X-OmniRoute-Decision |
Ответ | Трассировка маршрутизации: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> — комбинированная стратегия или single для запроса без комбинации) — всегда присутствует в ответах о завершении |
Примечание для Nginx: если вы используете заголовки с подчёркиваниями (например,
x_session_id), включитеunderscores_in_headers on;.
Закрепление учётной записи для запроса
Если у провайдера несколько подключений (учётных записей или ключей), OmniRoute обычно выбирает одно из них
с помощью стратегии выбора учётной записи. Вместо этого запрос может закрепить одно конкретное подключение
с помощью заголовка x-omniroute-connection:
curl http://localhost:20128/v1/chat/completions \
-H "Authorization: Bearer <your OmniRoute API key>" \
-H "Content-Type: application/json" \
-H "x-omniroute-connection: <connection id>" \
-d '{"model": "codex/gpt-5.5", "messages": [{"role": "user", "content": "hi"}]}'
- Где найти идентификатор. Откройте страницу провайдера в дашборде
(Dashboard → Providers → ) и нажмите на чип с идентификатором
xxxxxxxx…в строке подключения — это скопирует полный идентификатор подключения. - Какие запросы его учитывают. Запросы к одной модели (
provider/model) на/v1/chat/completions,/v1/messagesи/v1/responses. Комбинации игнорируют этот заголовок: закрепляйте аккаунт для каждого шага комбинации через собственное подключение этого шага. - Закрепление является строгим, а не предпочтительным. Используется исключительно закреплённое подключение. Сбой внутри запроса фиксирует период ожидания для аккаунта, но не переключает запрос на соседний аккаунт того же провайдера.
- Период ожидания и исчерпание квоты снимают закрепление. Пока для закреплённого подключения действует период ожидания, квота исчерпана или подключение заблокировано политикой квот, последующие запросы переключаются на другие подключения провайдера — точно так же, как незакреплённый трафик.
- Неизвестные или отключённые идентификаторы приводят к ошибке. Если идентификатор отсутствует в активном пуле провайдера (подключение удалено, деактивировано или принадлежит другому провайдеру), подходящий аккаунт не находится, поэтому запрос завершается ошибкой вместо незаметной маршрутизации в другое место.
Claude Code передаёт пользовательские заголовки через ANTHROPIC_CUSTOM_HEADERS. Добавьте его в блок
env файла ~/.claude/settings.json или в файл .claude/settings.json на уровне проекта, чтобы
закрепить другой аккаунт для каждого проекта:
{
"env": {
"ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
"ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
"ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: <connection id>",
},
}
Источник: src/sse/handlers/chat.ts (чтение заголовка), src/sse/services/auth.ts и
src/sse/services/sessionAffinityPin.ts (снятие закрепления и проверка отсутствия в пуле).
Заголовки телеметрии стоимости: ответы об успешном выполнении запросов без потоковой передачи также содержат набор заголовков телеметрии стоимости
X-OmniRoute-*—X-OmniRoute-Response-Cost(USD, фиксированные 10 знаков после запятой;0.0000000000для бесплатных запросов или запросов без указанной стоимости),X-OmniRoute-Tokens-In/X-OmniRoute-Tokens-Out,X-OmniRoute-Model,X-OmniRoute-Provider,X-OmniRoute-Latency-Ms,X-OmniRoute-Cache-HitиX-OmniRoute-Fallback-Attempts(только если значение > 0), а такжеX-OmniRoute-Request-IdиX-OmniRoute-Version. Они добавляются для chat completions,/v1/responses,/v1/messages, а также для конечных точек мультимедиа —/v1/embeddings,/v1/images/generations,/v1/audio/speech,/v1/audio/transcriptions,/v1/rerank,/v1/videos/generations,/v1/music/generationsи/v1/moderations(стоимость всегда0). Стоимость мультимедиа рассчитывается по каждой модальности (за изображение, за секунду, за символ, за единицу поиска), если данные о ценах доступны; в противном случае используется0(fail-open).
Семантика стоимости при попадании в кэш: при попадании в семантический кэш (
X-OmniRoute-Cache-Hit: true) вызов вышестоящего сервиса не выполняется, поэтомуX-OmniRoute-Response-Costравен0.0000000000(это добавочная стоимость обработки попадания в кэш). Исходная стоимость или стоимость, которая была бы начислена, указывается отдельно вX-OmniRoute-Cost-Saved. Системы, обрабатывающие данные для биллинга, должны суммироватьX-OmniRoute-Response-Cost(попадания в кэш ничего не стоят); для аналитики кэша можно агрегироватьX-OmniRoute-Cost-Saved.
Эксклюзивные управляемые лизы сессий
Эксклюзивное управление лизингом сессий — это опциональный, нейтральный по отношению к клиенту контракт маршрутизации: один активный владелец удерживает одно подходящее соединение OmniRoute. Он не предоставляет модель в лизинг, не требует OAuth, не идентифицирует конкретного клиента и не требует конкретного провайдера.
Аутентифицирующий API-ключ должен иметь область действия lease:exclusive и явный непустой список allowedConnections. Граница изменения базы данных обеспечивает наличие обоих полей одновременно при создании ключа и выполнении частичных обновлений.
POST /api/v1/session-leases
Authorization: Bearer <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
{"action":"acquire","model":"glm/glm-4.6"}
Успешные ответы на операции acquire, renew и release содержат временные метки, state и точное положительное значение generation, но никогда не содержат выбранное соединение или учётные данные. Операции renew и release передают значение generation в теле JSON:
{ "action": "renew", "generation": 1 }
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
Активный владелец лизы может явно запросить безопасные с точки зрения конфиденциальности отображаемые метаданные для своей текущей привязки:
{ "action": "status", "generation": 1 }
{
"state": "ACTIVE",
"generation": 1,
"acquiredAt": "2026-08-28T12:00:00.000Z",
"renewedAt": "2026-08-28T12:00:30.000Z",
"expiresAt": "2026-08-28T12:02:30.000Z",
"connection": {
"displayName": "Primary Codex",
"provider": "codex"
}
}
Это опциональное действие status защищено непрозрачным идентификатором владельца, аутентифицированным управляемым API-ключом и точным активным поколением в рамках одной транзакции базы данных. displayName содержит только обрезанное настроенное имя соединения; если безопасное настроенное имя отсутствует, значение равно null. OmniRoute никогда не подставляет адрес электронной почты или сгенерированную идентичность аккаунта. Значение provider — это нечувствительная к данным отображаемая метка, а не сгенерированный идентификатор совместимого провайдера. Учётные данные, токены, cookie, необработанные идентификаторы соединений или API-ключей, хеши владельцев, секреты защиты от устаревших запросов и внутренние данные маршрутизации исключаются.
Запросы с неверным ключом, неверным владельцем, устаревшим поколением, отсутствующим, истёкшим, освобождённым или инвалидированным объектом во всех случаях возвращают одну и ту же ошибку 409 LEASE_FENCE_STALE без метаданных соединения. Клиент, получивший ответ об ожидании доступной ёмкости, не имеет активной привязки, которую можно было бы проверить. Когда маршрутизация переключает активную лизу, то же поколение остаётся действительным, а status атомарно возвращает новую привязку, никогда не возвращая старую. Существующие клиенты не изменяются, поскольку ответы acquire, renew, release и ожидания сохраняют прежнюю структуру.
Этот серверный контракт не изменяет стандартный OpenAI Codex /status. Стандартный Codex в настоящее время сообщает своего провайдера модели и встроенное состояние аутентификации/аккаунта, но не отображает произвольные метаданные аккаунта пользовательского провайдера; последующая интеграция с клиентом должна вызывать это действие и самостоятельно решать, как отображать connection.displayName.
Каждый управляемый запрос инференса затем передаёт оба управляющих заголовка:
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
Точные значения владельца и поколения, активное соединение и аутентифицированный API-ключ проверяются непосредственно перед каждой поддерживаемой попыткой обращения к вышестоящему сервису. Повторное использование владельца и поколения с другим ключом завершается ошибкой, даже если этот ключ разрешает использование того же соединения. Необработанные идентификаторы владельцев не сохраняются, не записываются в журналы, не хранятся в снимке запроса и не передаются вышестоящему сервису.
Временная конкуренция возвращает HTTP 429 с Retry-After и:
{
"state": "WAITING_FOR_CAPACITY",
"error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
"reason": "NO_FREE_ELIGIBLE_CONNECTION",
"retryAfter": 30
}
Этот ответ означает только то, что обычный подходящий набор соединений был непустым, а каждое свободное соединение-кандидат удерживалось чужой активной лизой. Неподдерживаемые модели/провайдеры, несоответствие политике, период охлаждения, квоты, состояние работоспособности и другие обычные причины отсутствия подходящих соединений сохраняют существующие ответы OmniRoute.
x-omniroute-compression
Переопределение плана сжатия для отдельного запроса. Имеет наивысший приоритет — превосходит переопределение комбинации маршрутизации, активный профиль, автоматический триггер и Default на панели. Значения:
| Значение | Эффект |
|---|---|
off |
Для этого запроса сжатие не выполняется. |
default |
Профиль Default, определённый панелью (активный профиль игнорируется). Движки с потерями отключены. |
safe |
Только дедупликация и свёртка пробелов. |
allow-lossy |
Сохранить план оператора для этого запроса, включая сводки и перезапись стиля. |
engine:<id> |
Один движок, если он включён, например engine:rtk. Явное включение этого движка для запроса. |
<combo> |
Именованная комбинация, сначала сопоставляемая по имени (без учёта регистра), затем по id. |
Примечания:
- Неизвестные значения игнорируются (запрос никогда не отклоняется); разрешение продолжается по обычному порядку приоритетов оператора.
- Если несколько комбинаций имеют одно имя, передавайте combo id для детерминированного сопоставления.
- Комбинацию с именем
offилиdefaultнельзя выбрать по имени (сначала интерпретируются эти ключевые слова); ссылайтесь на такую комбинацию по её id. - Главный переключатель сжатия является жёстким ограничением: если сжатие глобально отключено, этот заголовок не может его включить.
Применённый план возвращается в заголовке ответа:
X-OmniRoute-Compression: <mode>; source=<source>
где <source> — одно из значений request-header, routing-override, active-profile, auto-trigger, default или off.
Эмбеддинги
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "nebius/Qwen/Qwen3-Embedding-8B",
"input": "The food was delicious"
}
Доступные провайдеры: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.
Идентификаторы каталога имеют формат provider/model (пример: jina-ai/jina-embeddings-v5-omni-small). Также разрешаются чистые идентификаторы моделей Jina, присутствующие в реестре (например, jina-embeddings-v5-text-small, jina-reranker-v3.5). Для Jina embed/rerank/classify/segment сначала используются учётные данные jina-ai из панели управления; JINA_AI_API_KEY используется только как резервный вариант, если ключ панели управления отсутствует. Карточка jina-reader предназначена только для Reader / r.jina.ai (POST /v1/web/fetch) и никогда не обслуживает эмбеддинги или rerank.
Модели реестра, заявляющие поддержку мультимодальности, также принимают до 32 структурированных элементов, независимых от провайдера. Типы медиаэлементов: text, image, audio, video и document. Их source представляет собой либо {"type":"url","url":"https://..."}, либо {"type":"base64","data":"...","media_type":"..."}.
Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano и псевдоним семейства jina-ai/jina-embeddings-v5-omni → omni-small) также принимает собственные документы Jina EmbeddingsV5Request и передаёт их без изменений на https://api.jina.ai/v1/embeddings:
{
"model": "jina-ai/jina-embeddings-v5-omni-small",
"task": "retrieval.query",
"normalized": true,
"input": [
{ "text": "a red bicycle" },
{ "image": "https://example.com/bike.png" },
{ "content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }] }
]
}
Собственные значения { image | audio | video | pdf } могут быть общедоступным URL HTTPS, URI data: или необработанными данными base64. OmniRoute не преобразует эти объекты в строки и не загружает собственные URL изображений — Jina получает общедоступные медиафайлы самостоятельно. Дополнительные поля Jina (task, normalized, truncate, embedding_type) передаются дальше. Текстовые SKU Jina по-прежнему отклоняют документы, содержащие нетекстовые данные.
Ограничения безопасности и транспорта:
- Удалённые URL медиафайлов должны быть общедоступными и использовать HTTPS. Канонические элементы
{type,source:url}загружаются на стороне сервера (повторная проверка перенаправлений, ограничение времени ожидания, ограничения размера, общедоступный DNS, фиксация подключения) и встраиваются перед вызовом провайдера. Элементы Jina native{image:"https://..."}передаются как есть после той же проверки общедоступного HTTPS; Jina загружает URL. - Размер встроенных медиафайлов в формате base64 ограничен 8 МиБ в декодированном виде на элемент и 16 МиБ в декодированном виде на весь запрос.
Преобразование для провайдеров (канонические элементы никогда не передаются без изменений):
- Мультимодальные модели Jina: каждый элемент верхнего уровня преобразуется в один объект с ключом, соответствующим модальности (
text/image/audio/video/pdf), с использованием URIdata:для встроенных медиафайлов; один вектор на каждый элемент верхнего уровня. - Семейство Gemini Embedding 2: один массив верхнего уровня преобразуется в один собственный запрос
models/{model}:embedContentсcontent.parts(textилиinline_data). - llama.cpp (
llama-cpp/<model>, любая модель, загруженная локальным сервером): канонические элементыtextпреобразуются в обычные строки, аimage/audio/video— в отдельные объекты{"content": [part]}, использующие части содержимого чата llama-server (image_url,input_audioс форматомwav/mp3/flac,input_video) со встроенными данными; один вектор на каждый элемент верхнего уровня. Сервер должен быть запущен с параметрами--embedding --mmproj …; без проектора он сам отклоняет медиафайлы.documentне поддерживается. - Неизвестные/динамические модели без явно заданных метаданных модальностей отклоняют структурированный ввод с HTTP 400.
{
"model": "jina-ai/jina-embeddings-v5-omni-small",
"input": [
{ "type": "text", "text": "A red bicycle" },
{
"type": "image",
"source": { "type": "url", "url": "https://example.com/bicycle.png" }
}
],
"dimensions": 512,
"encoding_format": "float"
}
Неподдерживаемые сочетания моделей и модальностей возвращают HTTP 400, вместо того чтобы принудительно преобразовывать элемент. Поля расширений, не относящиеся к input, в устаревших запросах со строками/токенами по-прежнему передаются без изменений.
# Перечислить все модели эмбеддингов
GET /v1/embeddings
Генерация изображений
POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "openai/gpt-image-2",
"prompt": "A beautiful sunset over mountains",
"size": "1024x1024"
}
Доступны следующие провайдеры: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, ZenMux, SD WebUI (локальный), ComfyUI (локальный).
n возвращает n изображений в data[]. Для провайдеров, API которых возвращает одно изображение за вызов
(Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik,
NVIDIA NIM, Cloudflare Workers AI), выполняется n отдельных вызовов upstream API — одновременно
не более 4. Фиксированное значение seed смещается на индекс вызова (seed, seed + 1, …),
поэтому изображения отличаются, но остаются воспроизводимыми. Максимальное значение n — 10.
Весь запрос завершается с ошибкой, если завершается ошибкой любой вызов. Список форматов с
fan-out — SINGLE_IMAGE_FANOUT_FORMATS в
open-sse/handlers/imageGeneration/fanOut.ts.
ZenMux использует существующее подключение с API-ключом и принимает префиксы zenmux/ или zm/:
zenmux/openai/gpt-image-2использует API изображений OpenAI от ZenMux. Доступны параметрыsize,quality,n,output_format,output_compression,backgroundиresponse_format.- Другие издатели, например
zm/meta/muse-image-1.0, используют конечную точку Vertex AI:predictот ZenMux. Параметрnпреобразуется вsampleCount,aspect_ratio— вaspectRatio, аimage_size(1K,2K,4K) — вsampleImageSize. Параметрsizeв пикселях задаёт только соотношение сторон, но не гарантированные размеры в пикселях. Поддерживаемые соотношения сторон, разрешения и количества изображений зависят от модели. zm/inclusionai/ming-image-0.1-designсамостоятельно выбирает размеры. Не указывайтеsize,aspect_ratioиimage_size; явное задание этих значений приводит к ошибке HTTP 400. Форматы PNG, JPEG и WebP можно запросить с помощьюoutput_format.
Эта интеграция поддерживает генерацию изображений по текстовому описанию, но не редактирование
эталонных изображений. Вывод Vertex нормализуется в data[].b64_json; response_format: "url"
возвращает upstream URL с протоколом HTTPS или URL данных в формате base64, если доступны только
байты изображения. Пустой или отфильтрованный результат возвращается как ошибка, а не как успешный
ответ без данных. Доступ к моделям зависит от учётной записи ZenMux.
См. Vertex API ZenMux и
API изображений OpenAI.
Подключение для входа в Microsoft 365 Copilot предоставляет copilot-m365-web/m365-copilot-image
через встроенный инструмент изображений Copilot: один раунд Copilot на изображение (n от 1 до 4),
параметр size влияет только на ориентацию, а изображения возвращаются непосредственно (b64_json
или URL данных для response_format: "url"). См. Microsoft 365 Copilot.
# Перечислить все модели изображений
GET /v1/images/generations
OCR документов
POST /v1/ocr
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "mistral/mistral-ocr-latest",
"document": {
"type": "document_url",
"document_url": "https://example.com/invoice.pdf"
}
}
model выбирает провайдера OCR с помощью префикса provider/model; идентификатор модели без префикса (например,
mistral-ocr-latest) сопоставляется с зарегистрированным провайдером, а если model не указан, по умолчанию используется
Mistral (mistral-ocr-latest). Зарегистрированные провайдеры (open-sse/config/ocrRegistry.ts):
| Идентификатор провайдера | Идентификатор модели | Значение model |
Примечания |
|---|---|---|---|
mistral |
mistral-ocr-latest |
mistral/mistral-ocr-latest (или без префикса mistral-ocr-latest) |
Синхронный — ответ возвращается непосредственно из единственного upstream-вызова. |
azure-document-intelligence |
prebuilt-read |
azure-document-intelligence/prebuilt-read |
Асинхронный upstream (analyze + опрос) — см. ниже. |
vertex-deepseek-ocr |
deepseek-ocr-maas |
vertex-deepseek-ocr/deepseek-ocr-maas |
Синхронный, через партнёрский endpoint Vertex AI openapi/chat/completions — сведения об аутентификации и URL см. ниже. |
Все три провайдера возвращают тело в одном формате Mistral:
{
"pages": [{ "index": 0, "markdown": "# Extracted text..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
Процесс опроса Azure Document Intelligence
API analyze Azure Document Intelligence является асинхронным: исходный запрос возвращает
заголовок Operation-Location вместо тела, а результат необходимо получать опросом. Обработчик
(open-sse/handlers/ocr.ts) опрашивает этот URL каждую секунду, выполняя до 30 попыток, немедленно завершается с ошибкой (и
не продолжает опрос) при ответе опроса с не-ok или статусом "failed" и возвращает 504, если операция всё ещё выполняется после исчерпания лимита попыток. Итоговый ответ Azure
нормализуется в ту же форму pages/markdown, которая используется Mistral, прежде чем возвращается вызывающей стороне, поэтому клиентскому коду не требуется отдельно обрабатывать провайдера.
Аутентификация и разрешение endpoint Vertex AI DeepSeek OCR
vertex-deepseek-ocr повторно использует ту же аутентификацию Vertex AI, которую OmniRoute уже поддерживает для
обработки чатов и изображений (open-sse/executors/vertex.ts): API-ключ подключения представляет собой либо учётные данные Service Account в формате JSON (обмениваемые на краткоживущий токен доступа OAuth через поток JWT bearer), либо уже выпущенный токен доступа OAuth, используемый как есть. URL upstream endpoint — это универсальный партнёрский endpoint Vertex openapi/chat/completions, сформированный на основе проекта и региона подключения: явно заданные providerSpecificData.project/providerSpecificData.region всегда имеют приоритет; в противном случае проект извлекается из project_id JSON Service Account, а регионом по умолчанию является us-central1. Оба разрешения выполняются в open-sse/handlers/ocr.ts
(resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl), а затем используются в
src/app/api/v1/ocr/route.ts перед передачей управления в handleOcr.
Список моделей
GET /v1/models
Authorization: Bearer your-api-key
→ Возвращает все чат-модели, модели эмбеддингов и изображений, а также комбинации в формате OpenAI
Цены моделей (pricing)
Запись содержит объект pricing, если OmniRoute знает цену модели. Цена берётся из таблицы
цен, которую использует учёт расходов: встроенных значений по умолчанию, синхронизированных
цен и переопределений, заданных через /api/pricing. Это цены из общего прайс-листа, поэтому
для провайдеров с подпиской также отображается цена за токен.
"pricing": {
"prompt": "0.000005",
"completion": "0.000025",
"input_cache_read": "0.0000005",
"input_cache_write": "0.00000625",
"input": 5,
"output": 25,
"cached": 0.5,
"cache_creation": 6.25
}
| Поля | Единица измерения | Примечания |
|---|---|---|
prompt, completion, input_cache_read, input_cache_write |
USD за токен, строка с десятичным числом | Совместимо с OpenRouter, экспоненциальная нотация никогда не используется. Два поля кэша отображаются только при наличии цены кэширования. |
input, output, cached, cache_creation |
USD за 1 млн токенов, число | Поля из более ранних версий каталога, сохранённые для существующих клиентов. reasoning и long_context также отображаются, если они есть в строке цен. |
- Комбинации содержат цену своей первой видимой цели. Встроенные комбинации
auto/*выбирают цель во время выполнения запроса, поэтому у них нетpricing. - Бесплатные модели показывают
"0"(и0), если их цена равна нулю. Модель без строки цен также показывает"0", если каталог помечает её как бесплатную (free: true) или она указана во встроенном каталоге бесплатных моделей. - Неизвестная цена: запись не содержит ключ
pricing. - Провайдеры с оплатой по кредитам (например, Kiro) тарифицируют запросы, а не токены. В их записях сохраняются имевшиеся ранее числовые поля за 1 млн токенов, но отсутствуют строковые поля цены за токен.
- Варианты (идентификаторы уровня усилий рассуждения, псевдонимы без размышления, зеркала обнаружения и шлюза) копируют цену модели, к которой они направляют запросы.
- Поля содержат только базовые тарифы. Уровни для длинного контекста (числовое поле
long_context) и множители тарифных уровней обслуживания (например, быстрый или flex-режим Codex) не изменяютpromptилиcompletion. - Объект одинаков для всех способов аутентификации, включая запрос в стиле Anthropic с
x-api-keyиanthropic-version(ответ по-прежнему имеет вид{ "object": "list", "data": [...] }). Реализация:src/app/api/v1/models/catalogPricing.ts.
Префиксы идентификаторов моделей (?prefix=)
Большинство моделей публикуется с префиксом провайдера. Используемый префикс определяется
флагом функции MODELS_CATALOG_PREFIX_MODE и может быть переопределён для отдельного
запроса с помощью параметра запроса — это удобно для клиента, которому нужен
структурированный список без изменения общесерверной настройки для остальных пользователей:
GET /v1/models?prefix=alias # один идентификатор на модель — префикс короткого псевдонима
GET /v1/models?prefix=dual # обе формы (значение по умолчанию на сервере)
GET /v1/models?prefix=canonical # только полный префикс идентификатора провайдера
| Режим | Выводит | Примечания |
|---|---|---|
dual |
cc/claude-sonnet-4-6 и claude/claude-sonnet-4-6 |
По умолчанию. Оба идентификатора направляют запросы к одной модели; это сохраняется для совместимости с конфигурациями клиентов, в которых жёстко задана любая из форм. Каталог становится примерно вдвое больше. |
alias |
cc/claude-sonnet-4-6 |
Одна запись на модель. Провайдеры без отдельного псевдонима всё равно выводят свою запись, поэтому ничего не теряется. |
canonical |
claude/claude-sonnet-4-6 |
Одна запись на модель с полным префиксом идентификатора провайдера. Провайдеры без отдельного псевдонима (например, antigravity/…, agy/…) также выводят здесь свой единственный идентификатор, поэтому ничего не теряется. |
Зеркало в режиме dual также можно распознать без параметра запроса: оно содержит поле
parent, указывающее на основной идентификатор.
Клиентам, отображающим средство выбора модели, следует запрашивать ?prefix=alias — именно
так работает
расширение OmniCopilot для VS Code.
Фильтры обнаружения (?capability=, ?min_context=, ?kind=, ?q=)
GET /v1/models поддерживает дополнительные фильтры обнаружения. Без них ответ не меняется.
Они сужают каталог, который уже виден вызывающей стороне (сначала применяются разрешения
API-ключа), и выполняются до постраничной выборки в стиле OpenAI с помощью limit / after:
GET /v1/models?capability=vision&capability=tool_calling # все указанные возможности должны быть включены
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding # `type` каталога; строки без него считаются `chat`
GET /v1/models?q=sonnet&limit=10 # регистронезависимое совпадение по идентификатору или имени
| Параметр | Значения |
|---|---|
capability |
attachment, reasoning, structured_output, temperature, thinking, tool_calling, vision |
min_context |
неотрицательное целое число, сравнивается с context_length |
kind |
chat, audio, embedding, image, moderation, music, rerank, video |
q |
от 1 до 200 символов |
Неизвестное значение или min_context, не являющийся неотрицательным целым числом (например, 1.5),
возвращает HTTP 400, а сообщение содержит список допустимых значений. Реализация:
src/app/api/v1/models/catalogFilters.ts.
Краткий список моделей (POST /v1/models/query)
POST /v1/models/query возвращает короткий детерминированный список из того же каталога с той же
аутентификацией и видимостью для каждого ключа, что и GET /v1/models:
POST /v1/models/query
Authorization: Bearer your-api-key
Content-Type: application/json
{ "capabilities": ["vision", "tool_calling"], "min_context": 128000, "max_output": 16000,
"kind": "chat", "q": "gpt", "owned_by": "openai", "exclude": ["openai/gpt-4o"], "limit": 5 }
→ { "object": "list", "data": [ ...models ] }
Все поля необязательны. Для capabilities и exclude можно указать массив или строку, разделённую запятыми;
max_output сравнивается с max_output_tokens. Результаты сортируются по owned_by, затем по id.
Значение limit по умолчанию равно 20, а значения больше 100 ограничиваются значением 100. Недопустимый
JSON, неизвестное поле или недопустимое значение возвращает HTTP 400.
Индивидуально скрытые модели чата
Модель, помеченная как Скрытая на странице своего провайдера, исключается из каталога и при
явном запросе отклоняется с HTTP 404 / model_not_found. Проверка использует разрешённых провайдера
и модель, включая псевдонимы провайдеров, префиксы узлов совместимых провайдеров и значения подключений
по умолчанию. Комбинация пропускает скрытые цели и может использовать видимого родственника; если
исполняемых целей не остаётся, возвращается тот же код ошибки. Снятие скрытия вступает в силу при следующем
запросе. Переопределения видимости только для изображений не скрывают модель чата с тем же идентификатором.
Эта индивидуальная настройка модели отделена от
списков разрешённых/запрещённых моделей, которые фильтруют
представление в каталоге и кандидатов для автоматической маршрутизации, сохраняя явную диспетчеризацию.
Разрешения моделей для API-ключа продолжают применяться независимо. Режим префиксов каталога по умолчанию
остаётся dual.
Варианты моделей без размышлений
Для поддерживающих размышления моделей Claude /v1/models также рекламирует вариант без размышлений,
идентификатор которого имеет префикс claude-3-omniroute-no-thinking/:
claude-3-omniroute-no-thinking/<provider>/<model>
Выбор этого идентификатора (например, в конфигурации Claude Code, которая всегда добавляет блок thinking)
разрешается обратно в реальный <provider>/<model> с отключённым рассуждением — thinking:{type:"disabled"}
на пути /v1/messages или с удалёнными полями reasoning/reasoning_effort на пути
/v1/chat/completions. Вариант отображается только для моделей семейства Claude, которые поддерживают
размышления и учитывают disabled (поэтому, например, модели, поддерживающие только адаптивный режим
и отклоняющие disabled, исключаются). Операторы могут принудительно включить или отключить вариант для
каждой модели через ModelSpec.noThinkingAlias.
Манифест плагина провайдера
GET /api/v1/provider-plugin-manifest
Возвращает безопасный для JSON манифест плагина провайдера, используемый Bifrost, CLIProxyAPI и будущими маршрутизаторами sidecar. Ответ генерируется из реестра провайдеров TypeScript и намеренно исключает секреты OAuth-клиентов, разрешение окружения времени выполнения, функции-исполнители, заголовки запросов и данные учетных записей.
Используйте эту конечную точку, когда sidecar работает в отдельном процессе и не может напрямую
импортировать open-sse/config/providerPluginManifestRegistry.ts.
Генерация аудио ElevenLabs
Настройте подключение провайдера elevenlabs в OmniRoute с вашим API-ключом ElevenLabs.
Клиенты проходят аутентификацию с помощью своего ключа OmniRoute (Authorization: Bearer $OMNIROUTE_API_KEY);
шлюз передает сохраненный ключ провайдера как xi-api-key. Никогда не отправляйте ключ ElevenLabs
в качестве токена bearer шлюза.
| Метод | Путь | Ответ | Категория конечной точки API-ключа |
|---|---|---|---|
| POST | /v1/sound-generation |
Собственные байты аудио | elevenlabs |
| POST | /v1/music |
Собственные байты аудио | music |
| POST | /v1/music/stream |
Потоковые байты аудио | music |
| POST | /v1/music/detailed |
Собственное multipart-аудио и план композиции | music |
| POST | /v1/music/detailed/stream |
Собственные метаданные SSE и фрагменты аудио | music |
| POST | /v1/music/plan |
JSON-план композиции | music |
Эти конечные точки дополняют существующие маршруты /v1/audio/speech, /v1/audio/transcriptions,
/v1/voices, /v1/text-to-speech/{voiceId} и /v1/speech-to-text. Собственные поля JSON
и параметры запроса, такие как output_format и enable_logging, сохраняются.
Ответы /v1/music/detailed сохраняют свои multipart-границы; разбирайте их как multipart.
/v1/music/detailed/stream возвращает text/event-stream с метаданными композиции и
аудиофрагментами в формате base64 в событиях SSE. Все шесть маршрутов поддерживают предварительные
CORS-запросы.
export OMNIROUTE_BASE_URL="http://localhost:20128"
export OMNIROUTE_API_KEY="your-omniroute-api-key"
# Короткий звуковой эффект. Длительность: от 0,5 до 30 секунд.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/sound-generation?output_format=mp3_44100_128" \
-H "Authorization: Bearer $OMNIROUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"A single soft bell chime","duration_seconds":1,"model_id":"eleven_text_to_sound_v2"}' \
--output effect.mp3
# Длительность музыки указывается в миллисекундах: от 3000 до 600000.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music?output_format=mp3_44100_128" \
-H "Authorization: Bearer $OMNIROUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"Gentle instrumental piano","music_length_ms":10000,"force_instrumental":true,"model_id":"music_v1"}' \
--output music.mp3
Используйте /v1/music/stream с тем же телом JSON для поэтапной передачи аудио. Композиция
принимает ровно одно из prompt или composition_plan; /v1/music/plan требует prompt
и опционально принимает source_composition_plan. Собственные схемы сохраняют дополнительные
поля провайдера, поэтому версии планов композиции и параметры тонкой настройки передаются в ElevenLabs.
Унифицированная конечная точка /v1/music/generations также принимает
elevenlabs/music_v1, elevenlabs/music_v2 и elevenlabs/music_v2_5. При активном подключении
ElevenLabs эти модели доступны в каталоге музыки. Эта конечная точка возвращает
{"created":...,"data":[{"b64_json":"...","format":"mp3"}]}. Ее поле duration указывается в
секундах и преобразуется в music_length_ms; явное значение music_length_ms имеет приоритет.
instrumental преобразуется в force_instrumental, причем собственное поле имеет приоритет.
Для потоковой передачи используйте собственные потоковые конечные точки, а для запросов, основанных
только на плане композиции, — собственную конечную точку композиции.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music/generations" \
-H "Authorization: Bearer $OMNIROUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"elevenlabs/music_v1","prompt":"Gentle instrumental piano","duration":10,"instrumental":true}'
Ограничения конечной точки, модели, бюджета и подключения применяются до вызова вышестоящего сервиса. Собственные
маршруты возвращают коды состояния и тела ошибок вышестоящего сервиса без изменений, включая 402 для
ограничения плана и 429 для ограничения квоты. Заголовки character-cost, song-id, request-id и retry-after
сохраняются, если они присутствуют. Наличие бесплатного кредитного баланса не гарантирует доступ ко всем
моделям музыки, форматам вывода или функциям API: ElevenLabs определяет доступность для каждого запроса.
Унифицированная конечная точка сохраняет коды состояния ошибок в нормализованной оболочке ошибок OmniRoute.
Контракты вышестоящего сервиса: звуковые эффекты, композиция музыки и подробности потоковой передачи музыки.
Эндпоинты совместимости
| Method | Path | Format |
|---|---|---|
| POST | /v1/chat/completions |
OpenAI |
| POST | /v1/messages |
Anthropic |
| POST | /v1/responses |
OpenAI Responses |
| POST | /v1/embeddings |
OpenAI |
| POST | /v1/images/generations |
OpenAI Images |
| POST | /v1/images/edits |
OpenAI Images (редактирование/дорисовка) |
| POST | /v1/videos/generations |
Генерация видео в стиле OpenAI |
| POST | /v1/music/generations |
Генерация музыки в стиле OpenAI |
| POST | /v1/audio/transcriptions |
OpenAI Audio (STT) |
| POST | /v1/audio/speech |
OpenAI TTS (возвращает аудиотело) |
| POST | /v1/rerank |
Переранжирование в стиле Cohere/Voyage |
| POST | /v1/classify |
Классификация Jina (api.jina.ai) |
| POST | /v1/segment |
Сегментатор Jina (segment.jina.ai) |
| POST | /v1/moderations |
OpenAI Moderations |
| GET | /v1/models |
OpenAI |
| POST | /v1/models/query |
Отфильтрованный список моделей |
| POST | /v1/messages/count_tokens |
Anthropic |
| GET | /v1beta/models |
Gemini |
| POST | /v1beta/models/{...path} |
Gemini generateContent |
| POST | /v1/api/chat |
Ollama |
| GET | /api/v1/vscode/{token}/ |
Псевдоним каталога OpenAI |
| GET | /api/v1/vscode/{token}/models |
Псевдоним моделей OpenAI |
| POST | /api/v1/vscode/{token}/chat/completions |
Псевдоним OpenAI с токеном |
| POST | /api/v1/vscode/{token}/responses |
Псевдоним OpenAI Responses с токеном |
| POST | /api/v1/vscode/{token}/api/chat |
Псевдоним Ollama с токеном |
| GET | /api/v1/vscode/{token}/api/tags |
Псевдоним тегов Ollama с токеном |
Все маршруты POST используют одну и ту же структуру: Bearer your-api-key + тело JSON, проверяемое с помощью Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema и т. д.; см. src/shared/validation/schemas.ts). При ошибке проверки схемы возвращается ответ 4xx.
Для клиентов, которые не могут добавить Authorization: Bearer ..., OmniRoute также принимает API-ключи в URL через параметры строки запроса для совместимости (?token=..., ?apiKey=..., ?api_key=..., ?key=...) или через специальные эндпоинты /api/v1/vscode/{token}/..., описанные ниже.
# Переранжирование (провайдер из облачного реестра или узел провайдера, совместимый с OpenAI, в формате "<prefix>/<model>")
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Классификация Jina (учётные данные Foundation API)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Сегментатор Jina
POST /v1/segment { "content": "...", "return_chunks": true }
# Поиск Jina (s.jina.ai; псевдонимы провайдера: jina-search, jina-ai, jina)
POST /v1/search { "query": "...", "provider": "jina-search" }
# Модерация
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
# TTS — возвращает тело audio/mpeg (или запрошенный формат)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# Для Soniox TTS требуется язык и голос: `language` по умолчанию имеет значение "en"; отсутствующий
# голос или стандартное имя голоса OpenAI (alloy, nova, …) заменяется на "Adrian"
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }
# Редактирование изображения (multipart)
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
# Генерация видео/музыки (идентификатор модели с префиксом провайдера)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "kie/suno-v4.0", "prompt": "..." }
Узлы провайдеров rerank:
POST /v1/rerankтакже направляется на совместимые с OpenAI узлы провайдеров (oMLX, vLLM, Infinity, TEI за шлюзом и т. д.), адресуемые как<node-prefix>/<model>. Узлы обратной связи (localhost,127.0.0.1,172.16.0.0/12) всегда подходят, как и имена хостов, перечисленные оператором вOMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS(например, имя сервиса Docker/Compose, такое какhttp://reranker:8080/v1; к ним обращаются напрямую, никогда черезHTTP(S)_PROXYили закреплённый прокси соединения). Узлы на любых других хостах — в локальной сети или среди узлов Tailscale — подходят только если оператор включает функциональный флагRERANK_REMOTE_PROVIDER_NODESи базовый URL узла проходит политику исходящих URL провайдера (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS/OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS). Шаг переранжирования движка памяти вызывает этот маршрут через обратную связь, поэтому это же правило применяется кrerankProviderModelв настройках памяти.Форматы локального сервера: к узлу обращаются по адресу
<base>/v1/rerank, а при ответе 404 — по адресу<base>/rerank(Infinity, TEI). Тело запроса к вышестоящему сервису содержит оба варианта написания Cohere/OpenAI (documents,return_documents) и вариант написания TEI (texts,return_text), а ответ вышестоящего сервиса нормализуется в оболочку Cohere: необёрнутый массив TEI[{index, score, text}],{results: [{index, score}]}от тонких шлюзов и вариант Voyage{data: [...]}возвращаются клиенту как{results: [{index, relevance_score, document?}]}, отсортированные по оценке и ограниченные значениемtop_n.
Обнаружение узлов провайдеров: модели на совместимом с OpenAI узле провайдера отображаются в
GET /v1/modelsс префиксом узла. Строки без метаданных конечной точки (что обычно характерно для локальных списков/v1/models) наследуютapiTypeузла, поэтому модели узлаembeddingsимеют значениеtype: "embedding", а модели узлаrerank— значениеtype: "rerank", вместо значения по умолчанию для чата; явноеsupportedEndpointsв синхронизированной или добавленной вручную строке всё же имеет приоритет.
Выделенные маршруты провайдеров
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
Префикс провайдера добавляется автоматически, если он отсутствует. Несоответствующие модели возвращают 400.
API файлов
Совместимый с OpenAI endpoint файлов для пакетных входных/выходных данных и загрузок файлов с указанием назначения.
| Метод | Путь | Описание |
|---|---|---|
| POST | /v1/files |
Загрузить файл (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — максимум 512 MiB |
| GET | /v1/files |
Получить список файлов для аутентифицированного API-ключа |
| GET | /v1/files/[id] |
Получить метаданные файла |
| DELETE | /v1/files/[id] |
Удалить файл |
| GET | /v1/files/[id]/content |
Передать обратно необработанное содержимое файла |
Аутентификация: Bearer API-ключ — файлы изолированы по API-ключу через getApiKeyRequestScope. Ключ
видит, скачивает и удаляет только собственные файлы; сеанс панели управления без ключа читает
весь экземпляр; файл без владельца (загруженный анонимно или через сеанс панели управления)
запрещён для любого клиента, не использующего сеанс. GET /v1/files отклоняет анонимного клиента — а также переданный ключ,
который не удалось разрешить, — с кодом 401, даже если REQUIRE_API_KEY=false, вместо
перечисления файлов всех арендаторов (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).
API пакетной обработки
Совместимая с OpenAI пакетная обработка.
| Метод | Путь | Описание |
|---|---|---|
| POST | /v1/batches |
Создать пакет — тело проверяется с помощью v1BatchCreateSchema (input_file_id, endpoint, completion_window) |
| GET | /v1/batches |
Получить список пакетов |
| GET | /v1/batches/[id] |
Получить статус пакета и request_counts |
| DELETE | /v1/batches/[id] |
Удалить завершённый или завершившийся с ошибкой пакет |
| POST | /v1/batches/[id]/cancel |
Отменить выполняющийся пакет |
Аутентификация: Bearer API-ключ. Пакеты изолированы по API-ключу в соответствии с тем же
трёхсторонним правилом, что и файлы: только собственный ключ, сеанс панели управления — весь экземпляр,
записи с владельцем null запрещены для любого клиента, не использующего сеанс (получение, удаление,
отмена и проверка input_file_id при создании). GET /v1/batches отклоняет анонимного клиента с кодом 401,
даже если REQUIRE_API_KEY=false.
API поиска
Абстракция поставщиков веб-поиска (Tavily, Brave, Exa, Serper и т. д.).
| Метод | Путь | Описание |
|---|---|---|
| GET | /v1/search |
Список настроенных поставщиков поиска и их возможностей |
| POST | /v1/search |
Выполнение поискового запроса — тело проверяется с помощью v1SearchSchema, поддерживаются кэширование и объединение запросов |
| GET | /v1/search/analytics |
Статистика попаданий, задержки и кэша по каждому поставщику |
Аутентификация: Bearer API-ключ (extractApiKey + isValidApiKey). Политика поиска применяется с помощью enforceApiKeyPolicy.
Автоматический выбор: если provider не указан, сначала используется самый дешёвый поставщик с настроенным подключением, а следующий по стоимости становится резервным. Бесплатные резервные поставщики (duckduckgo-free) используются только в том случае, если больше ничего не настроено. Самостоятельно размещённый SearXNG считается настроенным, если его подключение хранит настоящий baseUrl (не значение по умолчанию из каталога http://localhost:8888/search): тогда он занимает позицию поставщика за $0 перед поставщиками с ключами, а резервным становится самый дешёвый поставщик с ключом, в том числе когда SearXNG отвечает с кодом 400, 401, 403 или 404. Значение baseUrl, не являющееся допустимым URL http(s) или указывающее на адрес облачных метаданных, не учитывается. Подключение SearXNG, в котором хранится токен, занимает такую позицию только при использовании https:// или loopback-адреса http://. При удалённом обычном http:// оно никогда не используется как резервное и остаётся последним вариантом: оно используется только если не настроен ни один другой поставщик или если запрошено по имени, поэтому в этих двух случаях токен действительно передаётся в открытом виде.
provider_options для Exa и Tavily
Exa и Tavily считывают специфичные для поставщика поля из пространства имён:
provider_options.exa (или provider_options["exa-search"]) и provider_options.tavily
(или provider_options["tavily-search"]). Передаются только перечисленные ниже ключи. Каждый из них
проверяется собственной схемой Zod в open-sse/handlers/search/providerOptionsPassthrough.ts,
а ключ с неправильным типом отбрасывается. Любые другие ключи игнорируются, включая auth, base URL,
stream и outputSchema. Плоские ключи, используемые другими поставщиками (cx, depth и т. д.),
по-прежнему работают как раньше.
| Поставщик | Поля верхнего уровня | Вложенные |
|---|---|---|
| Exa | type, category, userLocation, moderation, additionalQueries, objective, systemPrompt, compliance (плоские примитивы), startPublishedDate, endPublishedDate |
contents.{text, highlights, summary, extras, livecrawlTimeout, maxAgeHours}, объединённые со значениями по умолчанию { text: true, highlights: true } |
| Tavily | search_depth, chunks_per_source, time_range, start_date, end_date, include_published_date, filter_by_published_date, include_answer, include_raw_content, include_images, include_image_descriptions, include_favicon, include_domains_mode, language, filter_by_language, auto_parameters, exact_match, include_usage, safe_search |
— |
Обобщённые поля всегда имеют приоритет: query, max_results, filters (домены), country и
тема, полученная из search_type. Для Exa значение search_type: "news" сохраняет
category: "news". Tavily также принимает search_type: "finance" (topic: "finance").
Стоимость поиска Firecrawl учитывается за каждый начатый блок из 10 возвращённых результатов по $0.002 (2 кредита) за блок, при этом за каждый вызов учитывается как минимум один блок (тарификация Firecrawl): 11 результатов стоят $0.004.
Обобщённое поле time_range теперь передаётся обоим поставщикам: Exa получает startPublishedDate (метку времени ISO), а Tavily — start_date (YYYY-MM-DD). Явно указанная дата в provider_options переопределяет сопоставленную дату.
Результаты Exa сохраняют id, highlights (каждый фрагмент, а не только первый, использованный как
snippet), highlight_scores, summary, subpages, entities и extras в
provider_raw. Результаты Tavily сохраняют images и favicon.
Стоимость поиска Linkup учитывается в размере $0.005 для depth fast и standard и $0.05 для
deep (тарифы Linkup),
независимо от того, получено ли значение depth из provider_options или из настроек подключения.
Exa type: "lite" (Exa 3.0) принимает меньший набор полей и отклоняет весь запрос, если задано любое другое поле. Для lite additionalQueries, systemPrompt и каждый ключ contents, кроме text и highlights, отбрасываются перед вызовом. Устаревшие subpages, subpageTarget, highlights.numSentences и highlights.highlightsPerUrl больше не передаются.
Учёт затрат ведётся в плоском реестре costPerQuery, за исключением Exa, где применяются
собственные тарифы Exa: $0.007 за вызов для auto (и устаревшего fast) или $0.004 для lite (и
устаревшего instant), включая 10 результатов; $0.001 за каждый последующий результат; и $0.001 за
каждый возвращённый результат, если задано contents.summary. Для Tavily учитывается 1 кредит ($0.008) для
search_depth basic, fast и ultra-fast, а для advanced — 2 кредита ($0.016)
(кредиты API Tavily). Вызов с
auto_parameters: true, при котором Tavily повышает уровень до advanced, по-прежнему учитывается как 1 кредит.
Web Fetch API
Извлекает содержимое из URL через настроенного провайдера веб-запросов (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract).
Parallel Extract (parallel-search, с тем же API-ключом, что и Parallel Search) возвращает
только Markdown — любой другой format приводит к ошибке 400 — и ограничивает содержимое
100 000 символами. Если целевую страницу невозможно извлечь, upstream сообщает об этом
внутри HTTP 200; OmniRoute представляет это как 422 с фиксированным сообщением.
| Метод | Путь | Описание |
|---|---|---|
| POST | /v1/web/fetch |
Получить/извлечь URL — тело проверяется через v1WebFetchSchema |
Аутентификация: Bearer API-ключ (extractApiKey + isValidApiKey). Политика
применяется через enforceApiKeyPolicy.
Резервный вариант с учётом квоты (#8297): если provider явно не указан, пул
(firecrawl → jina-reader → tavily-search → tinyfish → nimble-search →
parallel-search) обходится в фиксированном
порядке приоритета (fill-first) — настроенный провайдер с ограничением частоты пропускается
вместо немедленного завершения запроса, а повторяемая ошибка upstream, связанная с квотой
(HTTP 429 всегда; 402/403 для квотных бесплатных тарифов Firecrawl/Tavily/TinyFish —
но не для Jina Reader и никогда не для обычного некорректного запроса 400), передаётся
следующему ещё не проверенному провайдеру с учётными данными во время выполнения запроса.
Когда все провайдеры в пуле исчерпаны, endpoint возвращает один 429 (с заголовком
Retry-After) вместо прежнего общего 400. Если provider указан явно, тихого
резервного переключения нет — ограниченный по частоте или неисправный явно указанный
провайдер возвращает собственную ошибку (429 при ограничении частоты, в противном случае
статус upstream).
Потоковая передача через WebSocket
GET /v1/ws?handshake=1
Проверяет рукопожатие обновления WebSocket и возвращает примеры сообщений протокола
передачи (request, cancel). Фактические кадры WS обрабатываются встроенным WS-сервером
вне таблицы маршрутов Next.js.
Аутентификация: Bearer API-ключ во время рукопожатия.
Responses API через WebSocket (только codex)
# Тот же host:port, что и у HTTP API (по умолчанию 20128); обновление соединения:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (или: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
# Первый кадр ДОЛЖЕН быть response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
Прокси Responses-API-over-WebSocket подключён исключительно к codex (бэкенду
ChatGPT). Он прослушивает тот же порт, что и API/dashboard, по путям /v1/responses,
/responses и /api/v1/responses. При получении первого кадра response.create он
проходит аутентификацию и подготавливается через внутренний мост
codex-responses-ws, выбирает OAuth-подключение codex и туннелирует запрос к
wss://chatgpt.com/backend-api/codex/responses через транспорт wreq-js.
Модели, отличные от codex, отклоняются (codex_ws_provider_required).
Для маршрутизации с распределением квоты используйте
model: "qtSd/<group>/codex/<model>". Реализовано в
app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs +
src/app/api/internal/codex-responses-ws/route.ts.
Аутентификация: Bearer API-ключ во время рукопожатия. Встроенный HTTP-сервер
(server-ws.mjs) должен быть активной точкой входа (по умолчанию это так, когда существует
app/server-ws.mjs).
Идентификатор модели: используйте базовый идентификатор ChatGPT (без префикса codex/)
OpenAI Codex CLI проверяет имя модели на стороне клиента, когда
supports_websockets = true, и отклоняет идентификаторы с префиксом провайдера,
например codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Передавайте базовый идентификатор (например, gpt-5.5).
Мост OmniRoute работает только с codex, поэтому перед туннелированием upstream он повторно
разрешает базовый идентификатор как модель codex
(resolveCodexWsModelInfo) — даже несмотря на то, что базовый gpt-5.5 в противном
случае направлялся бы к другому провайдеру через HTTP.
Настройка OpenAI Codex CLI
Направьте Codex CLI в OmniRoute, добавив в ~/.codex/config.toml пользовательского
провайдера с поддержкой WebSocket (используйте отдельный CODEX_HOME, чтобы не изменять
существующую конфигурацию):
model = "gpt-5.5" # базовый идентификатор — НЕ "codex/gpt-5.5"
model_provider = "omniroute"
[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1" # без завершающей косой черты; URL WS выводится из него (в production используйте https/wss)
wire_api = "responses" # единственное поддерживаемое значение с февраля 2026 года
supports_websockets = true # включает транспорт Responses-over-WS
env_key = "OMNIROUTE_API_KEY" # содержит API-ключ OmniRoute (Bearer)
export OMNIROUTE_API_KEY=sk-... # API-ключ OmniRoute (любой ключ, если REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
CLI преобразует base_url + /responses в WebSocket, а OmniRoute туннелирует его
к выбранному OAuth-подключению codex. Работа проверена от начала до конца на локальном
сервере: ChatGPT возвращает codex.rate_limits + response.created и передаёт
результат потоково.
Отчёт о квотах и проблемах
| Метод | Путь | Описание |
|---|---|---|
| GET | /v1/quotas/check |
Предварительная проверка квоты для provider + accountId перед выдачей зарегистрированного ключа |
| POST | /v1/issues/report |
Сообщить о сбое выдачи квоты/ключа в GitHub (требуются GITHUB_ISSUES_REPO + токен) |
Аутентификация: Bearer API key (isAuthenticated).
Восстановление сессии квот (опционально)
Нестриминговый POST /v1/chat/completions или POST /v1/responses, завершившийся
терминальной ошибкой квоты (402/429/503), тело которой сообщает об исчерпании квоты или
кредитов, можно приостановить и воспроизвести позже вместо возврата ошибки. Вызывающая сторона
включает эту возможность для каждого запроса с помощью трёх заголовков:
| Заголовок | Значение |
|---|---|
x-omniroute-quota-recovery |
auto |
x-omniroute-session |
идентификатор сессии, [A-Za-z0-9._:-]{1,128} |
x-omniroute-recovery-turn |
идентификатор хода, уникальный в пределах сессии (то же правило) |
Подходят только ходы с stream: false, без инструментов, истории инструментов или
previous_response_id, а также без закрепления x-omniroute-connection; кроме того, должен быть
задан STORAGE_ENCRYPTION_KEY (запрос хранится в зашифрованном виде не более 24 часов). Затем
ответом будет 202 с recovery.poll; опрашивайте GET /v1/quota-recoveries/{id} (202 в
ожидании, 200 с восстановленным телом после завершения) или отмените операцию с помощью
DELETE. Тикеты видны только API-ключу, создавшему их. Если результат воспроизведения
неопределён, операция завершается в состоянии needs_confirmation, а не отправляется дважды.
Источник: src/lib/quota/quotaSessionRecovery.ts.
Использование самообслуживания (/api/usage/om-usage)
Любой ключ API может читать** свой собственный** использование и квоты — без аутентификации управления. Это конечная точка, которую клиент (CLI, панель OmniCopilot ) использует, чтобы показать держателю ключа свои расходы.
# Text form (the historical contract — plain text for a terminal)
curl -H "Authorization: Bearer <your-api-key>" \
http://localhost:20128/api/usage/om-usage
# Structured form — what a UI consumes
curl -H "Authorization: Bearer <your-api-key>" \
"http://localhost:20128/api/usage/om-usage?format=json"
Ключ должен иметь**allowUsageCommand** включено (по умолчанию выключено. — менеджер API-ключей панели управления переключает его для каждого ключа). Без этого конечная точка отвечает 403.
?format=json возвращает распознаваемую форму, поэтому вызывающая сторона никогда не считывает поле данных из отказа. Об успехе:
{
"allowed": true,
// present only when the key opted into per-key usage limits (daily/weekly/5-hour USD):
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// the selected provider quota snapshot, or null when nothing is cached yet:
"provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */} },
// every connection's snapshot, so a UI can render several providers side by side:
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
При отказе (401 плохой ключ / 403 не разрешен) тот же маршрут возвращает { "allowed": false, "error": { "message": "…" } } — присутствующий, но пустой personal/provider (ключ разрешен, еще ничего не изучено) — это состояние, отличное от отказа, и только форма JSON отличает их.
Автор: собственный ключ API носителя вызывающего абонента, подтвержденный с помощью isValidApiKey — это не поверхность управления (/api/keys/…), которая остается за requireManagementAuth.
Необработанные проценты квот по сравнению с процентами квот, скорректированными по предельному значению
При потреблении /api/usage/om-usage вызывающие абоненты должны учитывать разницу между процентами, представленными** текстовый вывод** и структурированные** вывод JSON** :
| Аспект | Обычный текстовый формат (/api/usage/om-usage / @@om-usage) |
формат JSON (?format=json) |
|---|---|---|
| Поле вывода | NN% left (например, 20% left) |
provider.quotas / providers[].quotas |
| Измерение | Используемый надбавка с поправкой на сокращение : оставшаяся емкость выше порога отсечки | Необработанная квота добычи : нескорректированные показатели поставщика |
| Масштабирование отсечки | Масштабируется через effectiveRemainingPercent() поэтому защищенный резерв читается как 0% left |
Нет (необработанные значения моментального снимка, сообщенные поставщиком) |
| Пороговые данные | Включено в отображаемый процент | Хранится в quotaWindowThresholds для каждого соединения (или настроек сервера по умолчанию). |
| Основной потребитель | Интерактивная CLIs, подсказки терминала, люди-операторы | Программные интеграции, информационные панели, аналитика, трекеры биллинга |
Формула корректировки отсечки
OmniRoute поддерживает упреждающее сокращение квот для предотвращения исчерпания восходящего канала (настраивается через соединение quotaWindowThresholds, настройки поставщика по умолчанию или глобальные настройки устойчивости). Когда порог отсечки (например, cutoff = 25%) активен в окне квоты, средство визуализации текста вычисляет оставшееся разрешение как:
- Если
remaining <= cutoff: возвращает0%. - Если
remaining > cutoff: возвращает((remaining - cutoff) / (100 - cutoff)) * 100.
Вывод форматированного текста округляет это значение до ближайшего целого числа (Math.round(...)).
Иллюстративный пример
Рассмотрим окно провайдера с** 60% сырое использование** (следовательно** 40 % необработанной оставшейся квоты** ) и настроенный** 25% ограничение оставшейся квоты** порог:
| Представительство | Расчет | Оставшийся | Подразумевается использование |
|---|---|---|---|
Необработанный JSON (?format=json) |
Снимок восходящего потока (quotas[window]) |
40% | 60% |
Текстовый формат (NN% left) |
((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100 |
20% | 80% (при расчете 100 - remaining) |
- Почему в тексте указано, что осталось 20 %: Из 40 % физической квоты, оставшейся на аккаунте, 25 % зарезервировано в соответствии с политикой отсечения. У вызывающего абонента остается только 15% из 75% полезного запаса, прежде чем маршрутизатор прекратит маршрутизацию к этому соединению. Масштабирование обеспечивает исчерпание сигналов соединения (
0% left) именно тогда, когда маршрутизация прекратится. - Почему JSON сохраняет необработанные значения: Полезная нагрузка JSON возвращает точный снимок поставщика (
UsageSnapshot), поэтому внешние инструменты имеют доступ к достоверной информации об использовании восходящего потока иquotaWindowThresholdsна уровне соединения без масштабирования с потерями на стороне сервера.
Руководство по миграции потребителей
Если внешняя интеграция (например, плагин редактора или расширение агента) ранее очистила конечную точку текста (NN% left) и вычислила процент использования как 100 - NN, переход на ?format=json означает:
- Чтение необработанных значений JSON отразит** фактическое потребление в разведке** (60% использовано в примере выше).
- Если интеграция желает сохранить семантику допустимого использования конечной точки текста, она может оценить эффективную оставшуюся формулу на стороне клиента, используя
quotaWindowThresholdsдля переопределений на уровне соединения.
Семантический кэш
# Получить статистику кэша
GET /api/cache/stats
# Очистить все кэши
DELETE /api/cache/stats
Пример ответа:
{
"semanticCache": {
"memorySize": 42,
"memoryMaxSize": 500,
"dbSize": 128,
"hitRate": 0.65
},
"idempotency": {
"activeKeys": 3,
"windowMs": 5000
}
}
Влияние на задержку
При попадании в семантический кэш ответ возвращается из кэша без
обращения к вышестоящему сервису, поэтому сообщаемая
X-OmniRoute-Response-Latency близка к нулю
(независимо от исходной задержки вышестоящего сервиса). Клиентам, чувствительным к задержке
(бенчмаркинг, мониторинг p50/p99), следует проверять
заголовок ответа X-OmniRoute-Cache-Latency:
| Значение | Описание |
|---|---|
synthetic |
Ответ возвращён из кэша; задержка не является реальным временем обращения к вышестоящему сервису |
| (отсутствует) | Ответ получен в результате реального обращения к вышестоящему сервису |
Отключение кэша для отдельных ключей
API-ключи могут отказаться от чтения семантического кэша с помощью cacheDefaultMode:
| Значение | Поведение |
|---|---|
legacy |
Обычное поведение кэша (по умолчанию) |
bypass |
Полностью пропустить поиск в кэше; всегда обращаться к вышестоящему сервису |
Задаётся при создании ключа (POST /api/keys) или при его обновлении (PATCH /api/keys/[id]):
{ "cacheDefaultMode": "bypass" }
Отключение кэша для отдельного запроса
Любой запрос может обойти кэш независимо от настроек ключа:
X-OmniRoute-No-Cache: true
Совместимость с управлением CLIProxyAPI
OmniRoute отвечает на три конечные точки управления CLIProxyAPI,
к которым обращаются панели мониторинга использования для получения данных об ограничениях подписок Claude и Codex
(например, источник лимитов использования cliproxy в T3 Code). Укажите в клиенте базовый URL
OmniRoute и используйте API-ключ с областью manage в качестве ключа управления. Маршруты
доступны по адресам /v0/management/* и /api/v0/management/*.
| Метод | Путь | Описание |
|---|---|---|
| GET | /v0/management/auth-files |
OAuth-подключения Claude и Codex в виде { files: [{ id, auth_index, provider, email, disabled, id_token }] }. Токены не передаются |
| POST | /v0/management/api-call |
Тело { auth_index, method, url, header?, data? }. Отправляет один разрешённый запрос с токеном учётной записи и возвращает { status_code, body } |
| POST | /v0/management/reset-quota |
Тело { auth_index }. Очищает период ожидания подключения, блокировки моделей и периоды ожидания Codex для отдельных областей одной учётной записи |
auth_index— это идентификатор подключения OmniRoute.provider—claudeилиcodex(только OAuth-подключения; провайдер API-ключейanthropicне включается в список). Для Codexid_token.chatgpt_account_id— это сохранённый идентификатор рабочего пространства, аplan_type— сохранённый тариф.api-callне является универсальным прокси. Он принимает только ClaudeGET https://api.anthropic.com/api/oauth/usageи CodexGET https://chatgpt.com/backend-api/wham/usage,GET .../wham/rate-limit-reset-creditsиPOST .../wham/rate-limit-reset-credits/consume, причём каждый запрос должен выполняться только для учётной записи соответствующего провайдера. Все остальные запросы возвращают403без обращения к вышестоящему сервису. ЗаголовокAuthorizationвызывающего клиента (включая заполнитель$TOKEN$) игнорируется: OmniRoute внедряет токен доступа подключения, предварительно обновляя его, если срок действия скоро истекает, и пересылает только разрешённые заголовки (anthropic-beta;OpenAI-Beta,Originator,Chatgpt-Account-Id;Accept,Content-Type). ЕслиChatgpt-Account-Idотсутствует, по умолчанию используется сохранённый идентификатор рабочего пространства. Время ожидания запросов составляет 15 секунд; запросы выполняются через прокси подключения.reset-quotaне изменяет конечные состояния (banned, expired, credits_exhausted). Неизвестныйauth_indexвозвращает404.
Аутентификация: сеанс панели управления или API-ключ с областью manage; аутентификация обязательна
даже при отключённом входе в систему (пути входят в ALWAYS_PROTECTED_API_PATHS). Ключи только для выполнения запросов получают 403. Источник:
src/lib/cliproxyCompat/managementApi.ts.
Панель управления и управление
Маршруты управления (/api/* кроме общедоступного auth/login)** нет** авторизовано обычными ключами вывода API. Семейства учетных данных, области действия и примеры скручивания: проверка подлинности управления.
Аутентификация
| Конечная точка | Метод | Описание |
|---|---|---|
/api/auth/login |
POST | Авторизоваться |
/api/auth/logout |
POST | Выход из системы |
/api/settings/require-login |
GET/POST | Статус входа (GET, общедоступный). POST устанавливает пароль/переключает вход в систему: только для оператора, если пароль существует (сеанс информационной панели, локальный CLI или вход в систему отключен). Ключи — API и токены oma_ получают 403); сеанс информационной панели отправляет currentPassword для замены пароля |
Управление поставщиками
| Конечная точка | Метод | Описание |
|---|---|---|
/api/providers |
GET/POST | Список/создание поставщиков |
/api/providers/[id] |
GET/PUT/DELETE | Управление провайдером |
/api/providers/[id]/test |
POST | Проверить подключение к провайдеру |
/api/providers/[id]/models |
GET | Получение списка моделей поставщиков |
/api/providers/validate |
POST | Проверка конфигурации провайдера |
/api/providers/bulk |
POST | Массовое добавление ключей API для поставщика ONE |
/api/providers/import |
POST | Импортируйте гетерогенный поставщик LIST из проанализированного файла CSV/JSON (#6836); результаты частичного отказа для каждой строки |
/api/provider-nodes* |
Различный | Управление узлами провайдера |
/api/provider-models |
GET/POST/PUT/PATCH/DELETE | Пользовательские модели и переопределения для каждой модели (добавление, обновление, hide/show, удаление) |
/api/provider-models/validate-and-add |
POST | Аутентификация со стороны руководства, добровольная проверка строгого соединения и атомарная регистрация пользовательской модели; см. проверку модели |
Для моделей synced/imported PUT /api/provider-models принимает provider, modelId и maxOutputTokenOverride: положительное целое число устанавливает ограничение выходного токена вручную, а null очищает его, чтобы восстановить значение по умолчанию. GET /api/provider-models?provider=<provider> возвращает эти значения в modelOutputOverrides, включая модели без строки пользовательской модели. Переопределение использует возможности max_output_tokens среды выполнения и сохраняется при повторной синхронизации модели. Страница поставщика, совместимого с OpenAI, предлагает те же элементы управления edit/clear и модели маркировки с явной поддержкой машинного зрения.
На совместимом узле поставщика пути записи (POST, PUT, PATCH, DELETE и /api/provider-models/validate-and-add) сохраняют идентификатор модели как чистый восходящий идентификатор: идентификатор, вставленный из списка с префиксом, имеет свернутый любой ведущий стек собственного префикса узла, и ответы отражают сохраненный идентификатор. Скошенные идентификаторы канонических провайдеров (например, nvidia/nemotron-…) сохраняются дословно. /v1/models никогда не выдает составной идентификатор <prefix>/<prefix>/<model>.
Узлы пользовательских дополнений в чате адаптируют явный отказ от рассуждений к вышестоящему бэкэнду. Успешный тест соединения автоматически выбирает элементы управления шаблоном чата для каждой конкретной модели ID запись /models которой подтверждает распознанное значение owned_by : vllm, sglang или llamacpp. Прозрачные оболочки, совместимые с OpenAI, могут сохранять исходную запись модели внутри вложенного объекта openai ; обнаружение следует до трех таких конвертов. Модели с отсутствующим, неизвестным или конфликтующим владельцем сохраняют обычное поведение OpenAI. При обнаружении повторно используется существующий запрос каталога, не создаются токены завершения и становится недействительным при изменении конечной точки соединения.
Чтобы закрепить поведение серверной части, которая не предоставляет эти метаданные, используйте существующее частичное обновление поставщика API:
{
"providerSpecificData": {
"reasoningControl": "chat-template"
}
}
Отправьте это тело с помощью PUT /api/providers/<connection-id>. В этом случае явное рассуждение none передается как chat_template_kwargs.thinking=false и chat_template_kwargs.enable_thinking=false. Явные значения собственного шаблона остаются авторитетными, если только правило обоснования на стороне сервера не принуждает к этому. Этот параметр применяется только в том случае, если пользовательское соединение, совместимое с OpenAI, отправляет тело завершения чата; Запросы ответов и обычные поставщики сохраняют свою собственную форму запроса. Установите для reasoningControl openai, чтобы принудительно использовать обычную сквозную передачу OpenAI reasoning_effort, или опустите it/set в null чтобы использовать автоматическое обнаружение.
Классификатор автоматического режима кода Claude требует отключить собственное мышление по умолчанию, если они не содержат явных элементов управления рассуждением. При обнаружении в запросах формата Claude используется системный маркер классификатора, а не имена моделей или пределы завершения. Явные элементы управления телом, поддерживаемые заголовки effort/thinking, правила маршрутизации и разрешенные усилия по модели сохраняют свой существующий приоритет. Обе стадии классификатора сохраняют свои подсказки, пределы завершения, последовательности остановки и реальные вердикты разрешения восходящего потока; второй этап все еще может воспроизводить запрошенное видимое рассуждение в виде обычного текста.
OAuth потоки
| Конечная точка | Метод | Описание |
|---|---|---|
/api/oauth/[provider]/[action] |
Различный | OAuth для конкретного поставщика |
Маршрутизация и конфигурация
| Конечная точка | Метод | Описание |
|---|---|---|
/api/models |
GET/PUT | Обновление списка моделей/псевдонимов |
/api/models/alias |
GET/POST | Псевдонимы моделей |
/api/models/catalog |
GET | Все модели по типу поставщика + |
/api/combos* |
Различный | Комбо-управление |
/api/keys* |
Различный | управление ключами API |
/api/pricing |
GET | Цены на модели |
Предел происхождения модели
GET /api/models?withLimits=1 (также true; 0/false или его отсутствие сохраняет полезную нагрузку по умолчанию неизменной) добавляет contextWindow, maxInputTokens, maxOutputTokens и объект capsSource в каждую строку модели. capsSource называет правило, которое обеспечивает каждое ограничение, поэтому удивительное ограничение (например, 128 тыс. в модели 1M) можно проследить до его происхождения. Разрешенные значения совпадают с теми, которые используются в маршрутизации; флаг только добавляет поля и никогда не меняет значение. Любое другое значение withLimits отклоняется с помощью 400.
значение capsSource |
Источник |
|---|---|
override:context |
Постоянное переопределение контекстного окна (model_context_overrides) |
override:max_input / override:max_output |
Сохраняющееся переопределение возможностей max_input_tokens / max_output_tokens |
static-authoritative:<provider>/<model> |
Статическая авторитетная таблица контекстного окна |
synced:<provider>/<model> |
строка синхронизированных возможностей models.dev |
registry:<provider>/<model> |
Запись в реестре провайдера |
spec:<model> |
Статическая спецификация модели |
префикс effort-base: |
Строка заимствована из базовой модели варианта с суффиксом усилия. |
none |
Ни один источник не объявляет предел (значение — null) |
Реализация: getResolvedModelCapabilitiesWithLimitSources() в src/lib/modelCapabilities.ts и цепочки приоритета в src/lib/modelCapabilityLimits.ts.
Использование и аналитика
| Конечная точка | Метод | Описание |
|---|---|---|
/api/usage/history |
GET | История использования |
/api/usage/logs |
GET | Журналы использования |
/api/usage/request-logs |
GET | Журналы уровня запросов |
/api/usage/[connectionId] |
GET | Использование для каждого соединения |
/api/usage/token-limits |
GET/POST/DELETE | Бюджеты токенов для каждого API-ключа |
/api/usage/model-latency-stats |
GET | Скользящий агрегат задержки per-provider/model (avg/p50/p95/p99, показатель успеха); фильтры: windowHours/minSamples/maxRows/provider/model (#6873) |
/api/usage/cache-health |
GET | Сводная информация о работоспособности кэша подсказок по коэффициенту call_logs — write/read, распределению размера записи p50/p90/p99, концентрации интенсивной записи, разделению по модели и вердикту healthy/degraded/thrash/no-data ; параметры запроса range (1h| 24h| 7d| 30d, 24h по умолчанию ) и необязательный model (#8827) |
разрешения ключа API
PATCH /api/keys/{id} обновляет разрешения существующего ключа. Как и любому маршруту /api/keys* ему требуется авторизация управления (см. «Аутентификация управления »), а не ключ вывода. Отправляйте только те поля, которые хотите изменить; запрос ни с одним из них отклоняется с помощью No valid fields to update. Принимаемые поля определяются updateKeyPermissionsSchema в src/shared/validation/schemas/keys.ts.
| Поле | Тип | Примечания |
|---|---|---|
name |
строка, 1–200 символов | |
isActive |
логическое значение | |
isBanned |
логическое значение | |
expiresAt |
ISO 8601 дата-время или null |
null очищает срок действия |
modelAccessMode |
all | restricted |
allowedModels должен быть пустым, если используется режим all |
allowedModels, blockedModels |
массив строк, до 1000 | |
allowedCombos |
массив строк, до 500 | Ворота, которые комбинируют ключ, могут позвонить; прямые модели регулируются modelAccessMode / allowedModels |
connectionAccessMode |
all | restricted |
allowedConnections не должен быть пустым, если restricted и пустым, если all |
allowedConnections |
массив UUIDs, до 100 | |
allowAutoCombos |
логическое значение | false отклоняет запросы на модели auto/* с этим ключом; ключи, которые никогда не устанавливают его, разрешены |
catalogScope |
all | combos | models |
Что GET /v1/models перечисляет для этого ключа (только комбинации, только модели или и то, и другое); это не меняет того, что может вызывать ключ |
forcedModel |
строка длиной до 300 символов или null |
Направляет запросы чата на этот model/combo через X-Route-Model и body.model; ограничения ключа все еще действуют |
noLog, autoResolve |
логическое значение | |
throttleDelayMs |
целое число, 0–300000 | |
maxSessions |
целое число, 0–10000 | |
rateLimits |
массив { limit, window } (положительные целые числа до 50) или null |
null стирает границы |
accessSchedule |
объект расписания или null |
null очищает расписание |
scopes |
массив строк, до 32 | |
allowedEndpoints |
массив строк, до 20 | |
streamDefaultMode |
legacy | json |
|
cacheDefaultMode |
legacy | bypass |
См. Обход кэша по ключу. |
compressionEnabled |
логическое значение | |
codexServiceMode |
один из режимов обслуживания Codex | |
disableNonPublicModels |
логическое значение | |
allowUsageCommand |
логическое значение | |
usageLimitEnabled |
логическое значение | |
dailyUsageLimitUsd, weeklyUsageLimitUsd |
число >= 0 или null |
|
fiveHourUsageLimitUsd |
число >= 0 или null |
Скользящий 5-часовой бюджет USD, применяемый так же, как дневные и еженедельные лимиты (usageLimitEnabled, UNPRICED_USAGE_BUDGET_POLICY). retry-after — это когда самые старые траты в окне устаревают, что может привести к тому, что ключ, превышающий его лимит, все еще будет заблокирован. |
chaosModeEnabled |
логическое значение |
curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \
-H "Authorization: Bearer <management-credential>" \
-H "Content-Type: application/json" \
-d '{ "allowAutoCombos": false, "catalogScope": "combos" }'
Настройки
| Конечная точка | Метод | Описание |
|---|---|---|
/api/settings |
GET/PUT/PATCH | Общие настройки. Ключам политики безопасности (requireLogin, newPassword, oidc*, corsOrigins, bruteForceProtection) требуется currentPassword а учетные данные оператора — ключи API и токены oma_ получают 403; для каждой мутации требуется область действия токена доступа admin |
/api/settings/proxy |
GET/PUT | Конфигурация сетевого прокси |
/api/settings/proxy/test |
POST | Проверить подключение к прокси |
/api/settings/ip-filter |
GET/PUT | IP allowlist/blocklist |
/api/settings/thinking-budget |
GET/PUT | Thinking/reasoning** запрос** режим перезаписи (сквозной/автополосный/пользовательский/адаптивный). Независимость от сжатия. См. THINKING_BUDGET |
/api/settings/system-prompt |
GET/PUT | Глобальная системная подсказка |
/api/settings/compression |
GET/PUT | Глобальная конфигурация сжатия |
/api/settings/purge-request-history |
POST | Очистите строки журнала запросов и артефакты локального журнала вызовов. |
Контекст и сжатие
| Конечная точка | Метод | Описание |
|---|---|---|
/api/compression/preview |
POST | Предварительный просмотр сжатия off/lite/standard/aggressive/ultra/RTK/stacked |
/api/compression/language-packs |
GET | Список доступных языковых пакетов Caveman |
/api/compression/rules |
GET | Получение списка метаданных правила Caveman |
/api/context/caveman/config |
GET/PUT | Псевдоним настроек, специфичный для Caveman |
/api/context/rtk/config |
GET/PUT | Настройки, специфичные для RTK, включая пользовательские фильтры и сохранение необработанных выходных данных. |
/api/context/rtk/filters |
GET | Каталог фильтров RTK и диагностика настраиваемых фильтров |
/api/context/rtk/test |
POST | Запуск RTK preview/test для текстовых полезных данных |
/api/context/rtk/raw-output/[id] |
GET | Чтение сохраненного отредактированного необработанного вывода по идентификатору указателя. |
/api/context/combos |
GET/POST | Комбинированное сжатие list/create |
/api/context/combos/[id] |
GET/PUT/DELETE | Комбинированное сжатие detail/update/delete |
/api/context/combos/[id]/assignments |
GET/PUT | Назначьте комбинации сжатия для комбинаций маршрутизации |
/api/context/analytics |
GET | Псевдоним аналитики сжатия |
Мониторинг
| Конечная точка | Метод | Описание |
|---|---|---|
/api/sessions |
GET | Отслеживание активных сессий |
/api/rate-limits |
GET | Ограничения ставок для каждого аккаунта |
/api/monitoring/health |
GET | Проверка работоспособности сводки поставщика + (catalogCount, configuredCount, activeCount, monitoredCount). Представление управления включает credentialHealth: скаляры пробного кэша, failedConnections if failed>0 и staleDbNonOkCount (SQLite Sticky test_status, а не датчик). См. MONITORING_GUIDE |
/api/cache/stats |
GET/DELETE | Статистика кэша / очистить |
/api/modality-bridge/stats |
GET | attempts в памяти, успехи/bridged, сбои, попадания в кэш, totalLatencyMs, latencySamples, averageLatencyMs, определяемый выборкой, и время последнего использования (сброс при перезапуске; проверка подлинности управления). |
/api/modality-bridge/video/runtime |
GET | Строгая проверка доверенного шлейфа перед управлением auth/probe; доступность и версии обновленного FFmpeg/ffprobe (без магазина) |
/api/modality-bridge/video/extract |
POST | Внутренний аутентифицированный байтовый брокер с доверенной обратной связью; 50 вход MiB, ограниченный выход queue/32 MiB, емкость 503, отключение 499, крайний срок 504 ; не публичная загрузка API |
Детализация видеокадра
GET /api/v1/video-bridge/drilldown считывает непрозрачный дескриптор, привязанный к клиенту, возвращаемый в x-omniroute-video-drilldown после явного согласия запроса Video Bridge. И чтение, и DELETE всегда требуют действующего ключа API и независимого разрешения modalityBridgeVideoDrilldownRemoteEnabled оператора. Для хранения продукции дополнительно требуется modalityBridgeVideoDrilldownEnabled и строгий drilldown: true для каждой детали. Если ключ имеет непустой список разрешенных конечных точек, он должен включать video как для GET, так и для DELETE, независимо от того, использует ли вызывающая сторона /v1 или /api/v1.
запрос GET : требуется handle; необязательные variant (preview, standard, detail), limit (1–8; устаревший frames принимается, но не может комбинироваться с limit), page с отсчетом от нуля и секунды start/end. Когда обе границы фокуса предоставлены, end должен быть больше, чем start. Ключи запроса Duplicate/unknown отклонены. Успешные ответы содержат derivation, durationSeconds, frames, hasMore, page, variant и необязательный focusWindow; no-store JSON ограничен 32 MiB, включая Base64. Выходные данные увеличенного размера возвращают 413; запросите меньше кадров.
DELETE /api/v1/video-bridge/drilldown?handle=... возвращает { "removed": 0|1 }. Неизвестный, просроченный или перекрестный ключ GETs — это неразличимые ответы 404; перекрестный ключ DELETE не может удалить запись владельца. Отключенный доступ возвращает 403, аутентификация missing/invalid 401, недействительные запросы 400, отмена 499 и временные ошибки 503. Дескрипторы являются локальными для процесса, срок их действия истекает через десять минут и не сохраняются при перезапуске. Новые дескрипторы используют v1. плюс 32-байтовый случайный токен Base64URL ; сохраняются только хеши токенов. Устаревшие 64-шестнадцатеричные токены остаются синтаксически читаемыми для совместимости. См. раздел «Защитные ограждения Video Bridge» для получения информации о согласии, квотах и деталях получения вариантов.
Резервное копирование и Export/Import
| Конечная точка | Метод | Описание |
|---|---|---|
/api/db-backups |
GET | Список доступных резервных копий |
/api/db-backups |
PUT | Создайте резервную копию вручную |
/api/db-backups |
POST | Восстановление из конкретной резервной копии |
/api/db-backups |
PATCH | Сохранение настроек хранения резервных копий (только для оператора) |
/api/db-backups |
DELETE | Удалить сохраненные резервные копии в соответствии с настройками хранения (только для оператора) |
/api/db-backups/export |
GET | Загрузите базу данных в виде файла .sqlite. |
/api/db-backups/import |
POST | Загрузите файл .sqlite для замены базы данных (проверяет только ?dryRun=true ) |
/api/db-backups/exportAll |
GET | Загрузите полную резервную копию в виде архива .tar.gz. |
/api/db-backups/export, /api/db-backups/exportAll и /api/settings/export-json выдают все сохраненные учетные данные, поэтому им требуется сеанс информационной панели или локальный CLI (или вход в систему отключен). Ключи API любой области действия и токены доступа oma_ получают 403. При восстановлении действуют одни и те же границы: POST /api/db-backups/import (включая dryRun=true ), POST /api/db-backups (восстановление по идентификатору) и POST /api/settings/import-json заменяют действующую базу данных или настройки, поэтому учетные данные компьютера также получают 403 ; omniroute sync import отправляет локальные учетные данные CLI. То же самое можно сделать с помощью DELETE /api/db-backups (очистка сохраненных резервных копий) и PATCH /api/db-backups (настройки хранения: сохраненные значения приводят к автоматическому удалению после каждой резервной копии). Листинг (GET) и создание резервной копии вручную (PUT) сохраняют обычную аутентификацию управления.
Облачная синхронизация
| Конечная точка | Метод | Описание |
|---|---|---|
/api/sync/cloud |
Различный | Операции облачной синхронизации |
/api/sync/initialize |
POST | Инициализировать синхронизацию |
/api/cloud/* |
Различный | Облачное управление |
Туннели
| Конечная точка | Метод | Описание |
|---|---|---|
/api/tunnels/cloudflared |
GET | Чтение состояния Cloudflare Quick Tunnel install/runtime для панели мониторинга |
/api/tunnels/cloudflared |
POST | Включите или отключите быстрый туннель Cloudflare (action=enable/disable) |
/api/tunnels/ngrok |
GET | Чтение статуса выполнения туннеля ngrok для панели мониторинга. |
/api/tunnels/ngrok |
POST | Включить или отключить туннель ngrok (action=enable/disable) |
Инструменты CLI
| Конечная точка | Метод | Описание |
|---|---|---|
/api/cli-tools/claude-settings |
GET | статус Claude CLI |
/api/cli-tools/codex-settings |
GET | статус Codex CLI |
/api/cli-tools/droid-settings |
GET | Статус дроида CLI |
/api/cli-tools/openclaw-settings |
GET | статус OpenClaw CLI |
/api/cli-tools/runtime/[toolId] |
GET | Общая среда выполнения CLI |
Ответы CLI включают: installed, runnable, command, commandPath, runtimeMode, reason.
Агенты ACP
| Конечная точка | Метод | Описание |
|---|---|---|
/api/acp/agents |
GET | Список всех обнаруженных агентов (встроенный пользовательский + ) со статусом |
/api/acp/agents |
POST | Добавьте собственный агент или обновите кэш обнаружения. |
/api/acp/agents |
DELETE | Удаление пользовательского агента с помощью параметра запроса id |
Ответ GET включает agents[] (идентификатор, имя, двоичный файл, версию, установленный, протокол, isCustom) и summary (всего, установленный, notFound, builtIn, пользовательский).
Устойчивость и ограничения скорости
| Конечная точка | Метод | Описание |
|---|---|---|
/api/resilience |
GET/PATCH | Очередь запросов Get/update, время восстановления соединения, прерыватель провайдера и настройки ожидания |
/api/resilience/reset |
POST | Сброс автоматических выключателей поставщика |
/api/resilience/model-cooldowns |
GET | Список активных блокировок для каждого (провайдера, соединения, модели), отсортированный по оставшемуся времени. |
/api/resilience/model-cooldowns |
DELETE | Снимите блокировку модели — body {provider, model} или {all: true}, чтобы стереть все |
/api/rate-limits |
GET/POST | Статус ограничения скорости для каждой учетной записи (GET) или переключение защиты ограничения скорости для соединения (POST {connectionId, enabled}). Поддерживаемый путь записи для rateLimitProtection (никогда не изменяемый через PUT /api/providers/[id]). Примечание. enabled: false отключает явную защиту, но не исключает активное соединение с ключом API из глобальной сети автоматического включения безопасности (autoEnableApiKeyProviders). |
/api/rate-limit |
GET | Конфигурация глобального ограничения скорости (устарела; псевдоним /api/rate-limits) |
Все четыре маршрута
/api/resilience/*требуют** авторизация управления** (requireManagementAuth). См. «Устойчивость (расширенная)» для получения полной информации о прерывателе поставщика, времени восстановления соединения и блокировке модели.
Оценки
| Конечная точка | Метод | Описание |
|---|---|---|
/api/evals |
GET/POST | Получение списка пакетов оценки/запуск оценки |
Политика
| Конечная точка | Метод | Описание |
|---|---|---|
/api/policies |
GET/POST/DELETE | Управление политиками маршрутизации |
Согласие
| Конечная точка | Метод | Описание |
|---|---|---|
/api/compliance/audit-log |
GET | Журнал аудита соответствия (последний N) |
v1beta (совместимость с Близнецами)
| Конечная точка | Метод | Описание |
|---|---|---|
/v1beta/models |
GET | Список моделей в формате Gemini |
/v1beta/models/{...path} |
POST | конечная точка Gemini generateContent |
Эти конечные точки отражают формат API Gemini клиентов, которые ожидают встроенной совместимости Gemini SDK.
Внутренний/системный APIs
| Конечная точка | Метод | Описание |
|---|---|---|
/api/init |
GET | Запустить службы фоновой синхронизации (проверка подлинности управления) |
/api/tags |
GET | Теги моделей, совместимые с Ollama (для клиентов Ollama ) |
/api/restart |
POST | Запустить плавный перезапуск сервера |
/api/shutdown |
POST | Запуск корректного завершения работы сервера |
/api/system/env/repair |
POST | Восстановление переменных среды поставщика OAuth |
/api/system/version |
GET | версия Current/latest, статус обновления, канал выпуска |
/api/system/version |
POST | Запустите обновление до последней версии с учетом развертывания. |
Примечание: Эти конечные точки используются внутри системы или для совместимости с клиентом Ollama. Обычно они не вызываются конечными пользователями.
Восстановление среды OAuth (v3.6.1 +)
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
Восстанавливает отсутствующие или поврежденные переменные среды OAuth для определенного поставщика. Возврат:
{
"success": true,
"repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
"backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}
Версия и канал выпуска
GET /api/system/version
Маршрут управления только с обратной связью (авторизация администратора). Возвращает текущую версию, последнюю опубликованную версию и статус автоматического обновления. releaseChannel и channels – аддитивные поля (рельс 3.8.54); channel сохраняет свое значение. — режим развертывания, который использует программа обновления информационной панели (npm, source или docker-compose).
{
"current": "3.8.52",
"latest": "3.8.52",
"updateAvailable": false,
"channel": "npm",
"autoUpdateSupported": true,
"autoUpdateError": null,
"news": null,
"releaseChannel": "latest",
"channels": { "latest": "3.8.52", "next": "3.8.53-rc.1" }
}
releaseChannel— npm канал текущей сборки:nightlyдля версий-nightly.*,nextдля других предварительных выпусков (-rc.*,-beta.*,-alpha.*),ltsдля стабильной версии более старой, чемchannels.latest, в противном случаеlatest. Те же правила, что и уscripts/release/dist-tag.mjs, который выбирает dist-тег npm во время публикации.channels— опубликовал заголовок каждого dist-тега изnpm view omniroute dist-tags(резервный HTTP реестра), кэшированный с тем же 10-минутным TTL что иlatest.latestприсутствует всегда (возврат к полюlatest, затем"unavailable");next,nightlyиltsпоявляются только тогда, когда существует этот dist-тег. ЗапросCache-Control: no-cacheобновляет оба поиска.
Модель канала (latest = v3 до GA 4.0, next = rc, nightly = develop, патчи lts = v3 после версии 4.0 GA) описана в docs/ops/RELEASE_STRATEGY.md.
Транскрибация аудио
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
Транскрибируйте аудиофайлы с помощью любого настроенного провайдера STT. Первый сегмент пути
выбирает нативного провайдера (openai/…, deepgram/…). Шлюзы, которые
повторно экспортируют модель другого поставщика, используют квалифицированный идентификатор
(openrouter/deepgram/nova-3).
Запрос:
curl -X POST http://localhost:20128/v1/audio/transcriptions \
-H "Authorization: Bearer your-api-key" \
-F "file=@recording.mp3" \
-F "model=openai/whisper-1"
Ответ:
{
"text": "Hello, this is the transcribed audio content.",
"task": "transcribe",
"language": "en",
"duration": 12.5
}
Примеры идентификаторов моделей: openai/whisper-1 (требуется ключ OpenAI),
openrouter/deepgram/nova-3 (требуется ключ OpenRouter),
deepgram/nova-3 (требуется нативный ключ Deepgram). Запрос с простым
deepgram/nova-3 не использует OpenRouter.
Поддерживаемые форматы: mp3, wav, m4a, flac, ogg, webm.
Gemini Live (gemini/gemini-3.5-transcribe-live): транскрибация в файловом режиме через
WebSocket Gemini Live (требуется API-ключ Gemini). Загружаемый файл преобразуется в монофонический PCM с частотой 16 кГц с помощью ffmpeg
(ffmpeg должен находиться в PATH, если только файл уже не является WAV-файлом с монофоническим PCM 16 кГц), передаётся
в сеанс, после чего возвращается финализированный текст в виде { "text": "..." }. Необязательные поля формы language и prompt
передаются далее. Ограничения: для загрузок размером более 25 МиБ или декодированного аудио длительностью более 10 минут возвращается
413; преобразование, выполняющееся дольше 60 с, принудительно завершается, и возвращается 504. API-ключ передаётся только
в заголовке x-goog-api-key, но никогда не включается в URL WebSocket.
Совместимость с Ollama
Для клиентов, использующих формат API Ollama:
# Конечная точка чата (формат Ollama)
POST /v1/api/chat
# Список моделей (формат Ollama)
GET /api/tags
Запросы автоматически преобразуются между форматами Ollama и внутренними форматами.
Токенизированные псевдонимы VS Code / псевдонимы без заголовков
Используйте эти псевдонимы, если интеграция не может добавить заголовок Authorization и требует встраивания API-ключа в базовый URL.
# Псевдоним каталога в стиле OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# Псевдонимы чата в стиле OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Псевдонимы в стиле Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
Пример:
curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'
Примечания:
- Токенизированные псевдонимы используют те же обработчики, что и
/v1/*и/api/tags; структуры ответов остаются идентичными. - По возможности используйте
Authorization: Bearer ..., если клиент поддерживает пользовательские заголовки. - Токены в URL могут отображаться в журналах обратного прокси, истории браузера и телеметрии за пределами OmniRoute. Рассматривайте их как вариант совместимости, а не как основной режим аутентификации.
Телеметрия
# Получить сводку телеметрии задержек (p50/p95/p99 для каждого провайдера)
GET /api/telemetry/summary
Ответ:
{
"providers": {
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
}
}
Бюджет
# Получить сведения о бюджете для всех API-ключей
GET /api/usage/budget
# Установить или обновить бюджет
POST /api/usage/budget
Content-Type: application/json
{
"apiKeyId": "key-123",
"dailyLimitUsd": 5.00,
"weeklyLimitUsd": 30.00,
"monthlyLimitUsd": 100.00,
"warningThreshold": 0.8,
"resetInterval": "monthly"
}
Примечания к схеме (
setBudgetSchema):apiKeyIdявляется обязательным; как минимум одно из полейdailyLimitUsd,weeklyLimitUsdилиmonthlyLimitUsdдолжно быть больше нуля. Необязательные поля:warningThreshold(0–1),resetInterval(daily|weekly|monthly),resetTime(HH:MM). Устаревший формат{keyId, limit, period}возвращает400 Bad Request.
Лимиты токенов
Лимиты токенов для каждого API-ключа (отдельно от указанного выше бюджета в USD). Применяются непосредственно в процессе обработки запроса: когда использование в текущем окне для ключа достигает установленного лимита, запросы отклоняются с ошибкой 429 Too Many Requests. Лимиты могут быть ограничены конкретной model, provider или применяться global ко всему ключу; если запросу соответствуют несколько лимитов, применяется наиболее строгий.
# Получить лимиты токенов ключа (включая использование в текущем окне)
GET /api/usage/token-limits?apiKeyId=key-123
# Создать или обновить лимит токенов
POST /api/usage/token-limits
Content-Type: application/json
{
"apiKeyId": "key-123",
"scopeType": "model",
"scopeValue": "openai/gpt-4o",
"tokenLimit": 1000000,
"resetInterval": "monthly",
"enabled": true
}
# Удалить лимит токенов по идентификатору
DELETE /api/usage/token-limits?id=tl-abc
Примечания к схеме (
setTokenLimitSchema): обязательныapiKeyIdиscopeType(model|provider|global).scopeValueобязателен, еслиscopeTypeне равенglobal(например, идентификатор модели для областиmodelили идентификатор провайдера для областиprovider).tokenLimitдолжен быть положительным целым числом (преобразуется из строки). Необязательные поля:id(не указывать при создании, передать при обновлении),resetInterval(daily|weekly|monthly, по умолчаниюmonthly),resetTime(HH:MM),enabled(по умолчаниюtrue). ОтветыGETдополняют каждый лимит полямиtokensUsed,remaining,windowStart,periodStartAtиnextResetAt. Это конечная точка класса управления (аутентификация централизованно обеспечивается конвейером авторизации).
Обработка запросов
- Клиент отправляет запрос в
/v1/* - Обработчик маршрута вызывает
handleChat,handleEmbedding,handleAudioTranscriptionилиhandleImageGeneration - Определяется модель (непосредственно у провайдера/модели или через псевдоним/комбинацию)
- Учетные данные выбираются из локальной БД с фильтрацией доступности учетной записи
- Для чата:
handleChatCoreпроверяет семантический кэш/кэш сигнатур и определяет настройки сжатия комбинации - Если включено, перед переводом для провайдера выполняется проактивное сжатие (
lite, Caveman, RTK или их комбинация) - Исполнитель провайдера отправляет запрос вышестоящему сервису
- Ответ переводится обратно в формат клиента (для чата) или возвращается как есть (для эмбеддингов/изображений/аудио)
- Записываются данные об использовании, аналитика сжатия и журналы запросов
- При возникновении ошибок применяется резервный вариант в соответствии с правилами комбинации
Полный справочник по архитектуре: ARCHITECTURE.md
Управление комбинациями
Комбинации маршрутизации более высокого уровня (уже описанные в разделе /api/combos*) также можно сопоставлять 1:1 с шаблоном идентификатора модели, обеспечивая прозрачное перенаправление идентификатора модели в стиле OpenAI на комбинацию.
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/model-combo-mappings |
Список всех сопоставлений модель→комбинация |
| POST | /api/model-combo-mappings |
Создание сопоставления — тело: {pattern, comboId, priority?, enabled?, description?} |
| GET | /api/model-combo-mappings/[id] |
Получение отдельного сопоставления |
| PUT | /api/model-combo-mappings/[id] |
Обновление полей существующего сопоставления |
| DELETE | /api/model-combo-mappings/[id] |
Удаление сопоставления |
Аутентификация: сессия/API-ключ управления (requireManagementAuth).
Вебхуки
Исходящие подписки на вебхуки для событий OmniRoute (завершение запросов, исчерпание квоты, ротация ключей и т. д.).
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/webhooks |
Список вебхуков (секреты маскируются как <prefix>...) |
| POST | /api/webhooks |
Создать вебхук — тело: {url, events?: ["*"], secret?, description?} |
| GET | /api/webhooks/[id] |
Получить вебхук |
| PUT | /api/webhooks/[id] |
Обновить url/events/secret/description |
| DELETE | /api/webhooks/[id] |
Удалить вебхук |
| POST | /api/webhooks/[id]/test |
Отправить тестовую нагрузку на URL вебхука и вернуть статус доставки |
Аутентификация: сессия/API-ключ управления (requireManagementAuth).
Зарегистрированные ключи (автоматическое управление)
Используются подсистемой автоматического управления ключами для выпуска и ротации API-ключей для поставщика/аккаунта, лежащего в основе, с дневными/почасовыми квотами.
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/v1/registered-keys |
Список зарегистрированных ключей (только замаскированный префикс) |
| POST | /api/v1/registered-keys |
Выпустить новый зарегистрированный ключ — тело: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Необработанный ключ возвращается один раз. При отказе из-за квоты возвращается 429. |
| GET | /api/v1/registered-keys/[id] |
Получить метаданные зарегистрированного ключа (без необработанного материала) |
| DELETE | /api/v1/registered-keys/[id] |
Отозвать зарегистрированный ключ |
| POST | /api/v1/registered-keys/[id]/revoke |
Явная конечная точка отзыва (тот же эффект, что и DELETE) |
Аутентификация: сессия/API-ключ управления (requireManagementAuth) — тот же механизм проверки, что и для /api/keys: сессия панели управления, локальный токен CLI или API-ключ с областью действия manage/admin; API-ключи только для вывода получают 403. См. также /v1/quotas/check и /v1/issues/report.
Протокол агентов
Задачи облачных агентов (Claude Code, Codex Cloud, OpenHands и т. д.), выполняемые удалённо от имени пользователей OmniRoute.
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/v1/agents/tasks |
Список задач — необязательные параметры ?provider=, ?status=, ?limit= (1–500, по умолчанию 50) |
| POST | /api/v1/agents/tasks |
Создание задачи — тело проверяется с помощью CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Возвращает 201 с конвертом задачи |
| DELETE | /api/v1/agents/tasks?id=... |
Удаление задачи |
| GET | /api/v1/agents/tasks/[id] |
Чтение задачи — синхронно обновляет статус из вышестоящего облачного агента, если задан external_id |
| POST | /api/v1/agents/tasks/[id] |
Действие с дискриминацией: {action: "approve"}, {action: "message", message} или {action: "cancel"} |
| DELETE | /api/v1/agents/tasks/[id] |
Удаление конкретной задачи по идентификатору |
Аутентификация: для каждого метода требуется аутентификация управления (
requireCloudAgentManagementAuth). До версии v3.8.0 эти методы не требовали аутентификации — см. коммит588a0333, содержащий критическое изменение.
# Создание облачной задачи Claude Code
curl -X POST http://localhost:20128/api/v1/agents/tasks \
-H "Authorization: Bearer your-management-key" \
-H "Content-Type: application/json" \
-d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'
Прокси управления
Исходящие HTTP(S)/SOCKS-прокси, которые можно назначать провайдерам, аккаунтам или глобально.
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/v1/management/proxies |
Список прокси (с ?id= возвращается один прокси; с ?id=&where_used=1 возвращается граф назначений) |
| POST | /api/v1/management/proxies |
Создание прокси — тело проверяется с помощью createProxyRegistrySchema |
| PATCH | /api/v1/management/proxies |
Обновление прокси — тело проверяется с помощью updateProxyRegistrySchema (требуется id) |
| DELETE | /api/v1/management/proxies?id=...&force=1 |
Удаление прокси (используйте force=1, чтобы отсоединить назначения) |
| GET | /api/v1/management/proxies/assignments |
Список назначений — фильтрация по proxy_id, scope, scope_id; передайте resolve_connection_id=<id>, чтобы определить активный прокси для соединения |
| PUT | /api/v1/management/proxies/assignments |
Назначение — тело проверяется с помощью proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Очищает кэш диспетчера |
| PUT | /api/v1/management/proxies/bulk-assign |
Массовое назначение — тело проверяется с помощью bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?}) |
| GET | /api/v1/management/proxies/health?hours=24 |
Сводка состояния прокси (количество успешных и неудачных запросов, задержка) за указанный период |
Аутентификация: для каждого маршрута требуется сессия/API-ключ управления (requireManagementAuth).
Указанные в описании задачи
POST /api/v1/management/proxies/[id]/assignmentsиPOST /api/v1/management/proxies/[id]/healthобслуживаются плоскими маршрутами/assignmentsи/health, приведёнными выше — в кодовой базе отсутствуют подмаршруты для отдельных идентификаторов.
Отказоустойчивость (расширенная)
OmniRoute предоставляет три независимых механизма временных сбоев; приведённые ниже конечные точки управления позволяют операторам просматривать их состояние и переопределять его:
| Область | Хранилище состояния | Просмотр | Сброс / очистка |
|---|---|---|---|
| Размыкатель провайдера | domain_circuit_breakers + память |
/api/monitoring/health |
POST /api/resilience/reset |
| Период ожидания соединения | rateLimitedUntil для подключений провайдеров |
/api/rate-limits, /api/providers/[id] |
(повторно включает при обращении; очистка через PUT провайдера) |
| Блокировка модели | Реестр доступности моделей в памяти | GET /api/resilience/model-cooldowns |
DELETE /api/resilience/model-cooldowns |
PATCH /api/resilience принимает переопределения размыкателя провайдера в providerBreaker.oauth и providerBreaker.apikey. Каждый профиль поддерживает degradationThreshold, failureThreshold и resetTimeoutMs; те же поля доступны в разделе «Панель управления» → «Настройки» → «Отказоустойчивость».
# Очистить блокировку одной модели
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-H "Content-Type: application/json" \
-d '{"provider":"openai","model":"gpt-4o-mini"}'
# Удалить все блокировки
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
Полный концептуальный справочник и значения по умолчанию для размыкателей см. в CLAUDE.md → «Состояние среды выполнения отказоустойчивости» и docs/architecture/RESILIENCE_GUIDE.md.
Очередь ограничения частоты запросов и защитный механизм автоматического включения
- Поддерживаемый путь записи:
POST /api/rate-limitsс телом{"connectionId": "<id>", "enabled": true|false}— поддерживаемая конечная точка управления для включения или отключения защиты от ограничения частоты запросов для соединения.PUT /api/providers/[id]намеренно не изменяет и не переключаетrateLimitProtection(#11278). - Семантика
enabled: false: установкаenabled: falseудаляет явную защиту для соединения, но не исключает активное соединение с API-ключом из глобального защитного механизма автоматического включения (autoEnableApiKeyProviders = true). ВreconcileEnabledConnections(open-sse/services/rateLimitManager.ts) значенияfalseиundefinedэквивалентны; активные соединения с API-ключом без явной защиты остаются защищёнными благодаря защитному механизму автоматического включения. - Глобальное отключение: чтобы использовать соединения с API-ключом без очередей ограничения частоты запросов, отключите защитный механизм глобально через
RATE_LIMIT_AUTO_ENABLE=false(переменная окружения) илиresilienceSettings.requestQueue.autoEnableApiKeyProviders = false(«Настройки» → «Отказоустойчивость» /PATCH /api/resilience).
Навыки
Инфраструктура навыков для расширения OmniRoute с помощью пользовательских исполняемых обработчиков и интеграций с маркетплейсами.
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/skills |
Список установленных навыков — поддерживается фильтрация по ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, с постраничной выдачей |
| GET | /api/skills/[id] |
Получить один навык |
| PUT | /api/skills/[id] |
Обновить навык (имя, описание, режим, схема, обработчик, теги) |
| DELETE | /api/skills/[id] |
Удалить навык |
| POST | /api/skills/install |
Установить навык из необработанного манифеста — тело: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?} |
| GET | /api/skills/executions |
Список последних выполнений навыков (журнал аудита с входными и выходными данными, длительностью) |
| GET | /api/skills/marketplace?q=... |
Поиск и список популярных навыков в маркетплейсе SkillsMP (требуется настройка skillsmpApiKey) |
| POST | /api/skills/marketplace/install |
Установить навык по идентификатору из SkillsMP |
| GET | /api/skills/skillssh?q=&limit= |
Поиск в реестре skills.sh |
| POST | /api/skills/skillssh/install |
Установить навык по идентификатору из skills.sh |
Аутентификация: сеанс управления/API-ключ. Маршруты поиска в маркетплейсах принимают либо данные аутентификации управления, либо Bearer API-ключ (isAuthenticated).
Память
Постоянное хранилище фактов и сведений из диалогов, доступное в рамках API-ключа / сессии.
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/memory |
Список записей памяти — ?apiKeyId=, ?type=, ?sessionId=, ?q=, с пагинацией offset/limit или page/limit |
| POST | /api/memory |
Создание записи памяти — тело проверяется с помощью Zod: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?} |
| GET | /api/memory/[id] |
Получение одной записи памяти |
| DELETE | /api/memory/[id] |
Удаление записи памяти |
| GET | /api/memory/health |
Состояние подсистемы памяти (подключение к БД, серверная часть эмбеддингов, состояние векторного индекса) |
Аутентификация: сессия/ключ управления (requireManagementAuth). Перечисление type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (см. MemoryType в src/lib/memory/types.ts).
Сервер MCP
OmniRoute поставляется со встроенным сервером Model Context Protocol с 3 транспортами (stdio, SSE, streamable-http) и областями видимости инструментов. Указанные ниже конечные точки панели управления считывают данные о состоянии и аудите, а также проксируют HTTP-транспорты.
| Метод | Путь | Описание | |
|---|---|---|---|
| GET | /api/mcp/status |
Сигнал работоспособности, транспорт, состояние подключения, последний вызов, популярные инструменты, процент успешных вызовов за 24 часа | |
| GET | /api/mcp/tools |
Список инструментов MCP с полями name, description, scopes, phase, auditLevel, sourceEndpoints |
|
| GET | /api/mcp/sse |
Открытие потока SSE для транспорта SSE (возвращает 503, если MCP отключён или транспорт не совпадает) |
|
| POST | /api/mcp/sse |
Отправка кадра JSON-RPC через транспорт SSE | |
| GET | /api/mcp/stream |
Открытие стороны SSE транспорта Streamable HTTP (сообщения, инициированные сервером) | |
| POST | /api/mcp/stream |
Отправка кадра JSON-RPC через транспорт Streamable HTTP | |
| DELETE | /api/mcp/stream |
Завершение сессии Streamable HTTP | |
| GET | /api/mcp/audit |
Запрос журнала аудита — ?limit=, ?offset=, ?tool=, `?success=true |
false, ?apiKeyId=` |
| GET | /api/mcp/audit/stats |
Сводная статистика аудита (общее количество, процент успешных вызовов, средняя длительность, популярные инструменты) |
Аутентификация: транспорты sse/stream используют специальный интерфейс аутентификации MCP (API-ключ Bearer с областью mcp); маршруты status/tools/audit* доступны для чтения из панели управления (дополнительная аутентификация, помимо доступа к хосту панели управления, не требуется).
Оба HTTP-транспорта контролируются параметрами
settings.mcpEnabledиsettings.mcpTransport— несовпадение транспорта возвращает400, а отключённое состояние MCP возвращает503.
Сервер A2A
OmniRoute предоставляет конечную точку A2A (Agent-to-Agent) JSON-RPC 2.0, а также REST-обёртку для инспекции и использования в панели мониторинга.
JSON-RPC
POST /a2a
Authorization: Bearer your-api-key # необязательно, если не задана OMNIROUTE_API_KEY
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "message/send",
"params": {
"skill": "smart-routing",
"messages": [{"role": "user", "content": "Route this coding task"}]
}
}
Поддерживаемые методы (для всех требуется settings.a2aEnabled):
| Метод | Описание |
|---|---|
message/send |
Синхронное выполнение навыка; возвращает {task, artifacts, metadata} |
message/stream |
Потоковое выполнение того же набора навыков через SSE |
tasks/get |
Получить задачу по taskId |
tasks/cancel |
Отменить задачу по taskId |
Встроенные навыки: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.
Карточка агента
GET /.well-known/agent.json
Возвращает общедоступную карточку агента A2A (имя, описание, возможности, каталог навыков, схему аутентификации), кэшируемую публично на 1 час. Аутентификация не требуется.
Вспомогательные REST-методы
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/a2a/status |
Статус A2A, статистика задач и сводка кэшированной карточки агента |
| GET | /api/a2a/tasks |
Список задач — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset= |
| POST | /api/a2a/tasks |
(Не реализовано как REST-метод — создавайте через JSON-RPC message/send) |
| GET | /api/a2a/tasks/[id] |
Получить одну задачу |
| POST | /api/a2a/tasks/[id]/cancel |
Отменить задачу |
Аутентификация: вспомогательные REST-методы работают без управленческой аутентификации (доступны для чтения из панели мониторинга); маршрут JSON-RPC /a2a использует Bearer OMNIROUTE_API_KEY, если он настроен.
Облако, оценки и Assess
| Метод | Путь | Описание | ||
|---|---|---|---|---|
| POST | /api/cloud/auth |
Проверить ключ Bearer и вернуть замаскированные подключения поставщиков и псевдонимы моделей для клиентов синхронизации с облаком | ||
| POST | /api/cloud/credentials/update |
Обновить зашифрованные учётные данные для поставщика, синхронизируемого с облаком | ||
| POST | /api/cloud/model/resolve |
Сопоставить логический идентификатор модели с конкретными поставщиком и моделью с использованием локальной таблицы маршрутизации | ||
| GET | /api/cloud/models/alias |
Получить список псевдонимов моделей в том виде, в котором они предоставляются для синхронизации с облаком | ||
| GET | /api/assess |
Прочитать последние категоризации результатов оценки (для каждого поставщика/модели) | ||
| POST | /api/assess |
Запустить оценку — тело: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | /api/evals |
Получить список встроенных наборов тестов и последних запусков | ||
| POST | /api/evals |
Запустить набор тестов | ||
| POST | /api/evals/suites |
Создать пользовательский набор тестов — тело проверяется с помощью evalSuiteSaveSchema |
||
| GET | /api/evals/suites/[id] |
Получить пользовательский набор тестов |
Аутентификация: /api/cloud/auth напрямую проверяет ключ Bearer и возвращает замаскированный ключ и projectId каждого подключения только для ключа с областью действия manage / admin; остальные маршруты /api/cloud/*, /api/evals/* и /api/assess требуют управленческой сессии/ключа API. POST-запрос к /api/assess использует validateBody со схемой области действия в виде размеченного объединения.
Управление ACP (Agent Client Protocol)
как дочерними процессами. Эти конечные точки управляют обнаружением агентов ACP и регистрацией пользовательских агентов.
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/acp/agents |
Список всех известных CLI-агентов (встроенных и пользовательских) с указанием статуса установки, версии и двоичного файла |
| POST | /api/acp/agents |
Регистрация пользовательского агента ACP или обновление кэша — тело: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} или {action: "refresh"} |
| DELETE | /api/acp/agents |
Удаление пользовательского агента ACP — параметр запроса: ?id=<agentId> |
Пример ответа (GET /api/acp/agents):
{
"agents": [
{
"id": "claude",
"name": "Claude Code CLI",
"binary": "claude",
"version": "1.0.45",
"installed": true,
"protocol": "stdio",
"providerAlias": "claude",
"isCustom": false
},
{
"id": "my-custom-cli",
"name": "My Custom CLI",
"installed": false,
"protocol": "stdio",
"providerAlias": "my-provider",
"isCustom": true
}
],
"cacheTtlMs": 60000,
"cacheAge": 1234
}
Аутентификация: требуется сеанс управления (cookie auth_token панели мониторинга) или
ключ API с областью действия управления.
Полные сведения см. в разделе Фреймворк ACP.
Аналитика и наблюдаемость
Конечные точки аналитики в реальном времени для мониторинга маршрутизации, сжатия и
разнообразия провайдеров. Они обеспечивают работу страниц /dashboard/analytics/*.
Аналитика автоматической маршрутизации
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/analytics/auto-routing |
Сводная статистика автоматической маршрутизации: общее количество вызовов, распределение стратегий, распределение уровней, ведущие провайдеры |
| GET | /api/analytics/auto-routing?days=7 |
Статистика за выбранный период (по умолчанию — 24 ч) |
Пример ответа:
{
"window": "24h",
"totalCalls": 1234,
"strategyBreakdown": {
"rules": 800,
"cost": 200,
"latency": 150,
"sla-aware": 50,
"lkgp": 34
},
"tierBreakdown": {
"ultra": 100,
"pro": 500,
"standard": 400,
"free": 234
},
"topProviders": [
{ "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
{ "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
]
}
Аналитика сжатия
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/analytics/compression |
Сводная статистика сжатия: сэкономленные токены, процент экономии, распределение режимов, использование механизмов |
Пример ответа:
{
"window": "24h",
"totalOriginalTokens": 5000000,
"totalCompressedTokens": 3500000,
"totalSavings": 1500000,
"savingsPct": 30.0,
"modeBreakdown": {
"lite": 400,
"standard": 600,
"aggressive": 100,
"ultra": 50,
"rtk": 84
},
"engineBreakdown": {
"caveman": 800,
"rtk": 434
}
}
Отслеживание разнообразия провайдеров
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/analytics/diversity |
Отслеживание разнообразия на основе энтропии Шеннона: предотвращение единичных точек отказа посредством измерения распределения провайдеров |
Пример ответа:
{
"window": "24h",
"shannonEntropy": 2.45,
"maxEntropy": 3.17,
"diversityRatio": 0.77,
"providerUsage": {
"openai": 0.4,
"anthropic": 0.25,
"google": 0.2,
"kiro": 0.15
},
"warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"]
}
Аутентификация: требуется сеанс управления или ключ API с областью действия управления.
Административные операции
Эндпоинты только для администраторов, предназначенные для операционного управления.
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/admin/concurrency |
Просмотреть текущие ограничения параллелизма (глобальные и для каждого провайдера) |
| POST | /api/admin/concurrency |
Обновить ограничения параллелизма — тело: {global?: number, perProvider?: Record<string, number>} |
Аутентификация: требуется сессия управления с областью действия администратора.
Управление CLI-инструментами
Управление CLI-инструментами, интегрированными с OmniRoute (antigravity, commandCode, devin-cli и т. д.). Полный список см. в разделе Справочник провайдеров.
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/cli-tools/all-statuses |
Статус всех CLI-инструментов (установлен, версия, время последнего обнаружения) |
| GET | /api/cli-tools/status |
Подробная информация о статусе одного CLI-инструмента (параметр запроса ?tool=) |
| POST | /api/cli-tools/apply |
Записать сгенерированную конфигурацию инструмента (dryRun выполняет предварительный просмотр; 422 + containerEphemeralTarget при работе в контейнере; migration указывает на устаревший YAML Codex) |
| GET | /api/cli-tools/backups |
Просмотреть резервные копии конфигураций CLI-инструментов |
| POST | /api/cli-tools/backups |
Создать резервную копию всех конфигураций CLI-инструментов |
| POST | /api/cli-tools/backups |
Восстановить: тот же эндпоинт с {tool, backupId} в теле восстанавливает указанную резервную копию |
| GET | /api/cli-tools/antigravity-mitm |
Статус MITM-прокси Antigravity (CLI-инструмента "antigravity-mitm") |
| POST | /api/cli-tools/antigravity-mitm/alias |
Настроить псевдонимы antigravity-mitm |
Аутентификация: требуется сессия управления.
Навыки агентов
Управление навыками ИИ-агентов (аналогично пользовательским GPT от OpenAI, но для агентов).
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/agent-skills |
Получить список всех навыков агентов (встроенных и пользовательских) |
| GET | /api/agent-skills/[id] |
Получить определённый навык агента |
| POST | /api/agent-skills |
Создать пользовательский навык агента — тело: {name, description, prompt, model?, temperature?} |
| PUT | /api/agent-skills/[id] |
Обновить пользовательский навык агента |
| DELETE | /api/agent-skills/[id] |
Удалить пользовательский навык агента |
| GET | /api/agent-skills/[id]/raw |
Получить исходный промпт и метаданные (без выполнения) |
| POST | /api/agent-skills/generate |
Сгенерировать новый навык с помощью ИИ на основе описания на естественном языке |
Аутентификация: требуется сессия управления или API-ключ с областью действия управления.
Управление кэшем
Управление семантическим кэшем и кэшем рассуждений.
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/cache |
Обзор кэша: общее количество записей, коэффициент попаданий, размер на диске |
| GET | /api/cache/entries |
Список кэшированных записей (с пагинацией) |
| DELETE | /api/cache/entries |
Удаление записей кэша (фильтрация по параметрам запроса) |
| GET | /api/cache/stats |
Подробная статистика кэша (по провайдерам и моделям) |
| GET | /api/cache/reasoning |
Состояние кэша рассуждений (для воспроизведения рассуждений) |
| DELETE | /api/cache/reasoning |
Очистка кэша рассуждений — параметры запроса: ?toolCallId=<id> (один элемент), ?provider=<p> или без параметров (все элементы) |
Аутентификация: требуется сеанс управления.
Система памяти
Управление постоянной памятью (FTS5 + векторные эмбеддинги).
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/memory |
Список записей памяти (фильтрация по области, типу и поисковому запросу) |
| POST | /api/memory |
Создание новой записи памяти — тело: {scope, type, content, metadata?} |
| GET | /api/memory/[id] |
Получение конкретной записи памяти |
| PUT | /api/memory/[id] |
Обновление записи памяти |
| DELETE | /api/memory/[id] |
Удаление записи памяти |
| GET | /api/memory?q= |
Поиск в памяти (FTS5 + векторный поиск) — статистика включена в тот же ответ |
Аутентификация: требуется сеанс управления или ключ API с областью действия управления.
Вебхуки
Управление подписками на вебхуки для событий.
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/webhooks |
Список всех подписок на вебхуки |
| POST | /api/webhooks |
Создание подписки на вебхук — тело: {url, events[], secret?, active?} |
| GET | /api/webhooks/[id] |
Получение конкретной подписки на вебхук |
| PUT | /api/webhooks/[id] |
Обновление подписки на вебхук |
| DELETE | /api/webhooks/[id] |
Удаление подписки на вебхук |
| GET | /api/webhooks/[id]/deliveries |
Список истории доставок для вебхука (журнал успешных и неудачных попыток) |
| POST | /api/webhooks/[id]/test |
Отправка тестового события вебхуку |
Аутентификация: требуется сеанс управления.
Полный список типов событий см. в разделе Фреймворк вебхуков.
Фреймворк навыков
Управление навыками (фреймворком агентных расширений).
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/skills |
Список всех установленных навыков (встроенных и пользовательских) |
| POST | /api/skills/install |
Установка навыка из локального пути или URL |
| DELETE | /api/skills/[id] |
Удаление навыка |
| PUT | /api/skills/[id] |
Включение или отключение навыка — тело запроса: {enabled?: boolean, mode?: "on" | "off" | "auto"} |
| POST | /api/skills/executions |
Выполнение навыка — тело запроса: {skillName, apiKeyId, input?, sessionId?} |
| GET | /api/skills/executions |
Список истории выполнения для всех навыков (фильтрация по ?apiKeyId=) |
Аутентификация: требуется сессия управления или API-ключ с областью действия управления.
Подробнее см. в разделе Фреймворк навыков.
Плагины
Управление плагинами OmniRoute (сторонними расширениями).
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/plugins |
Список установленных плагинов |
| POST | /api/plugins/marketplace/install |
Установка плагина из Marketplace |
| DELETE | /api/plugins/[name] |
Удаление плагина |
| POST | /api/plugins/[name]/activate |
Активация плагина |
| POST | /api/plugins/[name]/deactivate |
Деактивация плагина |
| GET | /api/plugins/[name]/config |
Получение конфигурации плагина |
| PUT | /api/plugins/[name]/config |
Обновление конфигурации плагина |
Аутентификация: требуется сессия управления.
Подробнее см. в разделе Фреймворк плагинов.
Теневая маршрутизация
Теневая маршрутизация / A-B-сравнение провайдеров не является отдельным REST-интерфейсом — она настраивается через комбинированную маршрутизацию (см. раздел Автокомбинации). Метрики сравнения для каждой комбинации предоставляются через GET /api/combos/metrics.
Защитные механизмы
Просмотр защитных механизмов среды выполнения (обнаружение PII, обнаружение инъекций в промпты, связывание визуальных данных). Защитные механизмы выполняются для каждого запроса; отключение для отдельного вызова выполняется через заголовок запроса x-omniroute-disabled-guardrails — сохранённого интерфейса включения/отключения не существует.
| Метод | Путь | Описание |
|---|---|---|
| GET | /api/guardrails |
Список зарегистрированных защитных механизмов и их состояния (имя / включён / приоритет) |
| POST | /api/guardrails/test |
Имитационный запуск конвейера перед вызовом на тестовых входных данных — тело запроса: {input, disabledGuardrails?} |
Аутентификация: требуется сессия управления.
Подробнее см. в разделе Безопасность > Защитные механизмы.
Аутентификация
См. раздел Аутентификация управления, посвящённый четырём семействам учётных данных (сеанс панели управления, локальный токен CLI, токен доступа oma_live_…, API-ключ с областью действия management) и различиям между ними и ключами инференса.
- Маршруты панели управления (
/dashboard/*) используют cookieauth_token - Для входа используется сохранённый хеш пароля; в качестве резервного варианта —
INITIAL_PASSWORD - Переключатель
requireLoginможно изменять через/api/settings/require-login - Маршруты
/v1/*могут требовать Bearer API-ключ, если заданоREQUIRE_API_KEY=true - «Токен управления» / «API-ключ с областью действия management» в этом справочнике означает один из вариантов, описанных в том руководстве, — это не неопределённый дополнительный тип секрета
Критическое изменение (v3.8.0) — для
/api/v1/agents/tasks/*и конечных точек управления периодом ожидания теперь требуется аутентификация управления (cookie панели управленияauth_tokenили API-ключ с областью действия management). Клиенты, которые ранее вызывали эти маршруты без аутентификации, будут получать ответ401 Unauthorized. См. коммит588a0333(fix(auth): require management auth for agent and cooldown APIs).