Files
OmniRoute/docs/i18n/ru/docs/reference/API_REFERENCE.md

260 KiB
Raw Permalink Blame History

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 необходимо задать вручную.


Содержание


Завершение чата

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), с использованием URI data: для встроенных медиафайлов; один вектор на каждый элемент верхнего уровня.
  • Семейство 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 не включается в список). Для Codex id_token.chatgpt_account_id — это сохранённый идентификатор рабочего пространства, а plan_type — сохранённый тариф.
  • api-call не является универсальным прокси. Он принимает только Claude GET https://api.anthropic.com/api/oauth/usage и Codex GET 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. Это конечная точка класса управления (аутентификация централизованно обеспечивается конвейером авторизации).

Обработка запросов

  1. Клиент отправляет запрос в /v1/*
  2. Обработчик маршрута вызывает handleChat, handleEmbedding, handleAudioTranscription или handleImageGeneration
  3. Определяется модель (непосредственно у провайдера/модели или через псевдоним/комбинацию)
  4. Учетные данные выбираются из локальной БД с фильтрацией доступности учетной записи
  5. Для чата: handleChatCore проверяет семантический кэш/кэш сигнатур и определяет настройки сжатия комбинации
  6. Если включено, перед переводом для провайдера выполняется проактивное сжатие (lite, Caveman, RTK или их комбинация)
  7. Исполнитель провайдера отправляет запрос вышестоящему сервису
  8. Ответ переводится обратно в формат клиента (для чата) или возвращается как есть (для эмбеддингов/изображений/аудио)
  9. Записываются данные об использовании, аналитика сжатия и журналы запросов
  10. При возникновении ошибок применяется резервный вариант в соответствии с правилами комбинации

Полный справочник по архитектуре: 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/*) используют cookie auth_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).