API Reference (Русский)

Содержание

Завершения чата
Эксклюзивные аренды управляемых сеансов
Векторные представления
Генерация изображений
OCR документов
Список моделей
Манифест плагина провайдера
Эндпоинты совместимости
API файлов
API пакетной обработки
API поиска
Потоковая передача через WebSocket
Квоты и сообщения о проблемах
Семантический кэш
Панель управления и администрирование
Управление комбинациями
Вебхуки
Зарегистрированные ключи (автоматическое управление)
Протокол агентов
Прокси-серверы управления
Отказоустойчивость (расширенная)
Навыки
Память
Сервер MCP
Сервер A2A
Облако, оценки и анализ
Обработка запросов
Аутентификация

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

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
}

Пользовательские заголовки

Заголовок	Направление	Описание
`X-OmniRoute-No-Cache`	Запрос	Установите значение `true`, чтобы обойти кэш
`x-omniroute-no-memory`	Запрос	Установите значение `true`, чтобы пропустить внедрение памяти и навыков для этого запроса (аналогично отключению кэша; позволяет избежать дополнительных затрат токенов и средств для каждого вызова)
`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-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;.

Заголовки телеметрии стоимости: успешные ответы без потоковой передачи также содержат набор заголовков телеметрии стоимости 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. Эти заголовки возвращаются для завершений чата, /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 &lt;managed-api-key&gt;
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"
  }
}

Это опциональное действие статуса ограничено непрозрачным владельцем, аутентифицированным управляемым ключом API и точной активной генерацией в одной транзакции базы данных. displayName — это только усеченное настроенное имя соединения; оно null, если безопасное настроенное имя не существует. OmniRoute никогда не подставляет адрес электронной почты или сгенерированный идентификатор учетной записи. Значение provider является нечувствительной меткой для отображения и никогда не является сгенерированным идентификатором совместимого провайдера. Учетные данные, токены, куки, необработанные идентификаторы соединения или ключа API, хеши владельцев, секреты ограждения и внутренние данные маршрутизации исключены.

Поиски с неверным ключом, неверным владельцем, устаревшей генерацией, отсутствующие, истекшие, освобожденные и недействительные запросы возвращают одну и ту же ошибку 409 LEASE_FENCE_STALE без метаданных соединения. Клиент, получивший ответ об ожидании доступности, не имеет активной привязки для проверки. Когда маршрутизация переводит активную аренду, та же генерация остается действительной, и статус атомарно возвращает новую привязку, а не старую. Существующие клиенты остаются без изменений, потому что ответы acquire, renew, release и waiting сохраняют свои предыдущие формы.

Этот серверный контракт не изменяет стандартный /status OpenAI Codex. Стандартный 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.

Примечания:

Неизвестные значения игнорируются (запрос никогда не отклоняется); разрешение переходит к обычному приоритету оператора.
Если несколько комбинаций имеют одно и то же имя, передайте id комбинации для детерминированного сопоставления.
Комбинация, имя которой off или default, не может быть выбрана по имени (эти ключевые слова интерпретируются первыми); ссылайтесь на такую комбинацию по ее id.
Главный переключатель сжатия является жестким ограничением: если сжатие отключено глобально, этот заголовок не может его включить.

Примененный план возвращается в заголовке ответа:

X-OmniRoute-Compression: &lt;mode&gt;; 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). Для операций embed/rerank/classify/segment Jina сначала используются учётные данные jina-ai из панели управления; JINA_AI_API_KEY используется в качестве резервного варианта, только если ключ в панели управления отсутствует. Карточка jina-reader предназначена только для Reader / r.jina.ai (POST /v1/web/fetch) и никогда не обслуживает эмбеддинги или реранжирование.

Модели в реестре, заявляющие поддержку мультимодальности, также принимают до 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) также принимает нативные документы EmbeddingsV5Request от Jina и перенаправляет их без изменений на 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) перенаправляются. Модели Jina, поддерживающие только текст, по-прежнему отклоняют нетекстовые документы.

Ограничения безопасности и передачи данных:

URL-адреса удалённых медиафайлов должны быть общедоступными и использовать HTTPS. Канонические элементы {type,source:url} загружаются на стороне сервера (с повторной проверкой перенаправлений, тайм-аутом, ограничениями размера, проверкой общедоступности DNS и фиксацией подключения) и встраиваются перед вызовом провайдера. Нативные элементы Jina {image:"https://..."} перенаправляются без изменений после той же проверки общедоступности HTTPS; URL-адрес загружает Jina.
Размер встроенных медиафайлов в формате base64 ограничен 8 МиБ декодированных данных на элемент и 16 МиБ декодированных данных на весь запрос.

Преобразование для провайдеров (канонические элементы никогда не перенаправляются без изменений):

Мультимодальные модели Jina: каждый элемент верхнего уровня преобразуется в один объект с ключом модальности (text / image / audio / video / pdf), использующий URI данных для встроенных медиафайлов; один вектор на каждый элемент верхнего уровня.
Семейство Gemini Embedding 2: один массив верхнего уровня преобразуется в единственный нативный запрос models/{model}:embedContent с content.parts (text или inline_data).
Неизвестные/динамические модели без явных метаданных о модальностях отклоняют структурированный ввод с 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 вместо принудительного преобразования элемента. Поля расширений, не относящиеся к входным данным, в устаревших запросах со строками/токенами по-прежнему передаются без изменений.

# Вывести список всех моделей эмбеддингов
GET /v1/embeddings

Генерация изображений

POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "openai/gpt-image-2",
  "prompt": "Красивый закат над горами",
  "size": "1024x1024"
}

Доступные провайдеры: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (локальный), ComfyUI (локальный).

# Вывести список всех моделей генерации изображений
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` без префикса)	Синхронный — ответ возвращается непосредственно из единственного восходящего запроса.
`azure-document-intelligence`	`prebuilt-read`	`azure-document-intelligence/prebuilt-read`	Асинхронный восходящий запрос (`analyze` + опрос) — см. ниже.
`vertex-deepseek-ocr`	`deepseek-ocr-maas`	`vertex-deepseek-ocr/deepseek-ocr-maas`	Синхронный, через партнёрскую конечную точку Vertex AI `openapi/chat/completions` — сведения об аутентификации и URL см. ниже.

Все три провайдера возвращают тело ответа в одинаковом формате Mistral:

{
  "pages": [{ "index": 0, "markdown": "# Извлечённый текст..." }],
  "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, поэтому клиентскому коду не требуется отдельно обрабатывать этого провайдера.

Аутентификация и разрешение конечной точки Vertex AI DeepSeek OCR

vertex-deepseek-ocr повторно использует тот же механизм аутентификации Vertex AI, который OmniRoute уже поддерживает для трафика чатов и изображений (open-sse/executors/vertex.ts): API-ключ подключения представляет собой либо учётные данные Service Account в формате JSON (обмениваемые на краткосрочный токен доступа OAuth посредством потока JWT-bearer), либо уже выпущенный токен доступа OAuth, используемый без изменений. В качестве восходящего URL конечной точки используется универсальная партнёрская конечная точка 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

Префиксы идентификаторов моделей (`?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.

Варианты моделей без размышлений

Для поддерживающих размышления моделей Claude /v1/models также публикует вариант без размышлений, идентификатор которого имеет префикс claude-3-omniroute-no-thinking/:

claude-3-omniroute-no-thinking/&lt;provider&gt;/&lt;model&gt;

При выборе этого идентификатора (например, в конфигурации 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 и будущими маршрутизаторами-сайдкарами. Ответ формируется на основе реестра провайдеров TypeScript и намеренно не включает секреты OAuth-клиентов, разрешение переменных среды во время выполнения, функции-исполнители, заголовки запросов и данные учётных записей.

Используйте эту конечную точку, когда сайдкар выполняется вне процесса и не может напрямую импортировать open-sse/config/providerPluginManifestRegistry.ts.

Конечные точки совместимости

Метод	Путь	Формат
POST	`/v1/chat/completions`	OpenAI
POST	`/v1/messages`	Anthropic
POST	`/v1/responses`	Ответы OpenAI
POST	`/v1/embeddings`	OpenAI
POST	`/v1/images/generations`	Изображения OpenAI
POST	`/v1/images/edits`	Изображения OpenAI (редактирование/заполнение)
POST	`/v1/videos/generations`	Генерация видео в стиле OpenAI
POST	`/v1/music/generations`	Генерация музыки в стиле OpenAI
POST	`/v1/audio/transcriptions`	Аудио OpenAI (STT)
POST	`/v1/audio/speech`	TTS OpenAI (возвращает тело аудио)
POST	`/v1/rerank`	Переранжирование в стиле Cohere/Voyage
POST	`/v1/classify`	Классификация Jina (`api.jina.ai`)
POST	`/v1/segment`	Сегментатор Jina (`segment.jina.ai`)
POST	`/v1/moderations`	Модерации OpenAI
GET	`/v1/models`	OpenAI
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
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, в формате "&lt;prefix&gt;/&lt;model&gt;")
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" }

# Редактирование изображения (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": "..." }

Узлы поставщиков переранжирования: POST /v1/rerank также маршрутизируется к узлам поставщиков, совместимым с OpenAI (oMLX, vLLM, Infinity, TEI за шлюзом, …), адресуемым как <node-prefix>/<model>. Узлы обратной связи (localhost, 127.0.0.1, 172.16.0.0/12) всегда доступны. Узлы на любом другом хосте — локальной сети или пире 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: голое [{index, score, text}] от TEI, {results: [{index, score}]} от тонких шлюзов и {data: [...]} в стиле Voyage — все возвращаются клиенту как {results: [{index, relevance_score, document?}]}, отсортированные по оценке и ограниченные top_n.

Обнаружение узлов поставщиков: модели на узле поставщика, совместимом с OpenAI, появляются в GET /v1/models под префиксом узла. Строки, не содержащие метаданных конечной точки (что типично для локальных списков /v1/models), наследуют apiType узла, поэтому модели узла embeddings имеют type: "embedding", а модели узла rerank имеют type: "rerank" вместо значения по умолчанию chat; явный supportedEndpoints в синхронизированной или добавленной вручную строке по-прежнему имеет приоритет.

Выделенные маршруты поставщиков

POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations

Префикс провайдера автоматически добавляется, если он отсутствует. Несоответствующие модели возвращают 400.

Files API

Совместимый с OpenAI эндпоинт для пакетного ввода/вывода файлов и загрузки файлов с указанием назначения.

Метод	Путь	Описание
POST	`/v1/files`	Загрузить файл (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — не более 512 МиБ
GET	`/v1/files`	Получить список файлов для аутентифицированного API-ключа
GET	`/v1/files/[id]`	Получить метаданные файла
DELETE	`/v1/files/[id]`	Удалить файл
GET	`/v1/files/[id]/content`	Получить необработанное содержимое файла в потоковом режиме

Аутентификация: API-ключ Bearer — область видимости файлов ограничивается каждым API-ключом с помощью getApiKeyRequestScope. Ключ может просматривать, скачивать и удалять только собственные файлы; сеанс панели управления без ключа имеет доступ ко всему экземпляру; доступ к файлу без владельца (загруженному анонимно или через сеанс панели управления) запрещён для любого вызывающего клиента без сеанса. GET /v1/files отклоняет запрос анонимного клиента — а также запрос с предоставленным ключом, который не удаётся разрешить, — с кодом 401, даже если REQUIRE_API_KEY=false, вместо предоставления списка файлов всех арендаторов (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

Batches 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`	Отменить выполняющийся пакет

Аутентификация: API-ключ Bearer. Область видимости пакетов ограничивается каждым API-ключом по тому же трёхвариантному правилу, что и для файлов: доступ только по собственному ключу, доступ ко всему экземпляру через сеанс панели управления, запрет доступа к записям с владельцем null для любого вызывающего клиента без сеанса (при получении, удалении, отмене и проверке input_file_id во время создания). GET /v1/batches отклоняет запрос анонимного клиента с кодом 401, даже если REQUIRE_API_KEY=false.

Search API

Абстракция провайдеров веб-поиска (Tavily, Brave, Exa, Serper и т. д.).

Метод	Путь	Описание
GET	`/v1/search`	Список настроенных поисковых провайдеров и их возможностей
POST	`/v1/search`	Выполнение поискового запроса — тело проверяется с помощью `v1SearchSchema`, поддерживает кеширование/объединение запросов
GET	`/v1/search/analytics`	Статистика попаданий, задержек и кеша по каждому провайдеру

Аутентификация: API-ключ Bearer (extractApiKey + isValidApiKey). Политика поиска применяется через enforceApiKeyPolicy.

Web Fetch API

Извлечение содержимого из URL через настроенного провайдера веб-загрузки (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

Метод	Путь	Описание
POST	`/v1/web/fetch`	Загрузка/скрейпинг URL — тело проверяется с помощью `v1WebFetchSchema`

Аутентификация: API-ключ Bearer (extractApiKey + isValidApiKey). Политика применяется через enforceApiKeyPolicy.

Резервное переключение с учётом квот (#8297): если явный provider не указан, пул (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) перебирается в фиксированном порядке приоритета (сначала заполняется первый) — настроенный провайдер, достигший ограничения частоты запросов, пропускается вместо немедленного завершения запроса, а повторяемая ошибка вышестоящего сервиса или ошибка квоты (HTTP 429 всегда; 402/403 для бесплатных тарифов Firecrawl/Tavily/TinyFish с ограничениями квоты — не для Jina Reader и никогда для обычного некорректного запроса 400) приводит к переходу к следующему ещё не опробованному провайдеру с настроенными учётными данными во время выполнения запроса. Когда все провайдеры в пуле исчерпаны, конечная точка возвращает единый 429 (с заголовком Retry-After) вместо прежнего общего 400. Когда явно запрошен provider, скрытого резервного переключения нет — для явно указанного провайдера, достигшего ограничения частоты запросов или завершившегося ошибкой, возвращается его собственная ошибка (429 при ограничении частоты запросов, в остальных случаях — статус вышестоящего сервиса).

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

GET /v1/ws?handshake=1

Проверяет рукопожатие обновления соединения до WebSocket и возвращает примеры сообщений протокола передачи (request, cancel). Фактические кадры WS обрабатываются встроенным сервером WS вне таблицы маршрутов Next.js.

Аутентификация: API-ключ Bearer во время рукопожатия.

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 через WebSocket подключён исключительно к codex (бэкенд ChatGPT). Он прослушивает тот же порт, что и API/панель управления, по путям /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.

Аутентификация: API-ключ Bearer во время рукопожатия. Встроенный 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, поэтому перед созданием туннеля к вышестоящему сервису он повторно определяет простой идентификатор как модель codex (resolveCodexWsModelInfo) — даже несмотря на то, что простой gpt-5.5 при использовании HTTP в ином случае был бы направлен к другому провайдеру.

Настройка OpenAI Codex CLI

Настройте Codex CLI для работы с OmniRoute, добавив пользовательского провайдера с поддержкой WebSocket в ~/.codex/config.toml (используйте отдельный 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 формируется автоматически (в рабочей среде используйте https/wss)
wire_api = "responses"                    # единственное поддерживаемое значение с февраля 2026 года
supports_websockets = true                # включает транспорт Responses через 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` и токен)

Аутентификация: API-ключ Bearer (isAuthenticated).

Самостоятельный просмотр использования (`/api/usage/om-usage`)

Любой API-ключ может просматривать собственное использование и квоты — управленческая аутентификация не требуется. Это эндпоинт, который клиент (CLI, панель OmniCopilot) использует, чтобы показать владельцу ключа его расходы.

# Текстовая форма (исторически сложившийся контракт — обычный текст для терминала)
curl -H "Authorization: Bearer &lt;your-api-key&gt;" \
  http://localhost:20128/api/usage/om-usage

# Структурированная форма — используется пользовательским интерфейсом
curl -H "Authorization: Bearer &lt;your-api-key&gt;" \
  "http://localhost:20128/api/usage/om-usage?format=json"

Для ключа необходимо включить allowUsageCommand (по умолчанию отключено — диспетчер API-ключей в панели управления переключает этот параметр отдельно для каждого ключа). В противном случае эндпоинт возвращает 403.

?format=json возвращает дискриминированную структуру, поэтому вызывающая сторона никогда не пытается прочитать поле данных из ответа с отказом. При успешном запросе:

{
  "allowed": true,
  // присутствует, только когда для ключа включены индивидуальные лимиты использования (дневные/недельные в USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // снимок квоты выбранного провайдера или null, если в кеше пока ничего нет:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // снимки всех подключений, чтобы пользовательский интерфейс мог отображать несколько провайдеров рядом:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

При отказе (401 — неверный ключ / 403 — доступ не разрешён) тот же маршрут возвращает { "allowed": false, "error": { "message": "…" } } — присутствующее, но пустое значение personal/provider (ключ разрешён, но данные ещё не получены) отличается от отказа, и различить эти состояния можно только в формате JSON.

Аутентификация: собственный API-ключ Bearer вызывающей стороны, проверяемый с помощью isValidApiKey — это не интерфейс управления (/api/keys/…), который по-прежнему защищён requireManagementAuth.

Семантический кеш

# Получить статистику кеша
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

Панель управления и администрирование

Маршруты управления (/api/*, кроме общедоступных маршрутов аутентификации/входа) не авторизуются с помощью обычных API-ключей инференса. Семейства учетных данных, области доступа и примеры curl: Аутентификация для управления.

Аутентификация

Конечная точка	Метод	Описание
`/api/auth/login`	POST	Вход
`/api/auth/logout`	POST	Выход
`/api/settings/require-login`	GET/PUT	Включение требования входа

Управление провайдерами

Конечная точка	Метод	Описание
`/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-ключей для ОДНОГО провайдера
`/api/providers/import`	POST	Импорт неоднородного СПИСКА провайдеров из обработанного файла CSV/JSON (#6836); результаты с частичными ошибками по строкам
`/api/provider-nodes*`	Различные	Управление узлами провайдеров
`/api/provider-models`	GET/POST/PATCH/DELETE	Пользовательские модели (добавление, обновление, скрытие/отображение, удаление)

Потоки OAuth

Конечная точка	Метод	Описание
`/api/oauth/[provider]/[action]`	Различные	OAuth для конкретного провайдера

Маршрутизация и конфигурация

Конечная точка	Метод	Описание
`/api/models/alias`	GET/POST	Псевдонимы моделей
`/api/models/catalog`	GET	Все модели по провайдерам и типам
`/api/combos*`	Различные	Управление комбинациями
`/api/keys*`	Различные	Управление API-ключами
`/api/pricing`	GET	Цены моделей

Использование и аналитика

Endpoint	Метод	Описание
`/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	Скользящие агрегированные показатели задержки по провайдерам/моделям (среднее значение/p50/p95/p99, доля успешных запросов); фильтры: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)
`/api/usage/cache-health`	GET	Сводка о состоянии кеша промптов на основе `call_logs` — соотношение записей и чтений, распределение размера записей по p50/p90/p99, концентрация крупных записей, разбивка по моделям и заключение `healthy`/`degraded`/`thrash`/`no-data`; параметры запроса `range` (`1h`\|`24h`\|`7d`\|`30d`, по умолчанию `24h`) и необязательный `model` (#8827)

Настройки

Endpoint	Метод	Описание
`/api/settings`	GET/PUT/PATCH	Общие настройки
`/api/settings/proxy`	GET/PUT	Конфигурация сетевого прокси
`/api/settings/proxy/test`	POST	Проверка подключения через прокси
`/api/settings/ip-filter`	GET/PUT	Список разрешённых/заблокированных IP-адресов
`/api/settings/thinking-budget`	GET/PUT	Режим преобразования запросов для мышления/рассуждений (сквозная передача / автоматическое удаление / пользовательский / адаптивный). Не зависит от сжатия. См. THINKING_BUDGET.md.
`/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 на текстовых данных
`/api/context/rtk/raw-output/[id]`	GET	Чтение сохранённого отредактированного необработанного вывода по идентификатору указателя
`/api/context/combos`	GET/POST	Получение списка/создание комбинаций сжатия
`/api/context/combos/[id]`	GET/PUT/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`, когда `failed>0`, и `staleDbNonOkCount` (фиксированное значение `test_status` в SQLite, а не датчик). См. MONITORING_GUIDE.md.
`/api/cache/stats`	GET/DELETE	Статистика кэша / очистка
`/api/modality-bridge/stats`	GET	Хранящиеся в памяти `attempts`, успешные операции/`bridged`, сбои, попадания в кэш, `totalLatencyMs`, `latencySamples`, рассчитанное по числу выборок значение `averageLatencyMs` и время последнего использования (сбрасываются при перезапуске; требуется аутентификация управления)
`/api/modality-bridge/video/runtime`	GET	Строгая проверка доверенного loopback-адреса перед аутентификацией управления/проверкой; санитизированные данные о доступности и версиях FFmpeg/ffprobe (без сохранения в кэше)
`/api/modality-bridge/video/extract`	POST	Внутренний аутентифицированный брокер байтов через доверенный loopback-адрес; входные данные до 50 МиБ, ограниченная очередь/выходные данные до 32 МиБ, `503` при исчерпании ресурсов, `499` при отключении, `504` при истечении срока; не является публичным API загрузки файлов

Резервное копирование и экспорт/импорт

Конечная точка	Метод	Описание
`/api/db-backups`	GET	Вывести список доступных резервных копий
`/api/db-backups`	PUT	Создать резервную копию вручную
`/api/db-backups`	POST	Восстановить из указанной резервной копии
`/api/db-backups/export`	GET	Скачать базу данных в виде файла .sqlite
`/api/db-backups/import`	POST	Загрузить файл .sqlite для замены базы данных
`/api/db-backups/exportAll`	GET	Скачать полную резервную копию в архиве .tar.gz

Облачная синхронизация

Конечная точка	Метод	Описание
`/api/sync/cloud`	Различные	Операции облачной синхронизации
`/api/sync/initialize`	POST	Инициализировать синхронизацию
`/api/cloud/*`	Различные	Управление облаком

Туннели

Конечная точка	Метод	Описание
`/api/tunnels/cloudflared`	GET	Получить для панели управления состояние установки и выполнения Cloudflare Quick Tunnel
`/api/tunnels/cloudflared`	POST	Включить или отключить Cloudflare Quick Tunnel (`action=enable/disable`)
`/api/tunnels/ngrok`	GET	Получить для панели управления состояние выполнения ngrok Tunnel
`/api/tunnels/ngrok`	POST	Включить или отключить ngrok Tunnel (`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	Состояние Droid 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[] (id, name, binary, version, installed, protocol, isCustom) и summary (total, installed, notFound, builtIn, custom).

Отказоустойчивость и ограничения частоты запросов

Конечная точка	Метод	Описание
`/api/resilience`	GET/PATCH	Получить или обновить настройки очереди запросов, периода ожидания подключения, прерывателя провайдера и ожидания
`/api/resilience/reset`	POST	Сбросить прерыватели цепи провайдеров
`/api/resilience/model-cooldowns`	GET	Вывести список активных блокировок для комбинаций (провайдер, подключение, модель), отсортированный по оставшемуся времени
`/api/resilience/model-cooldowns`	DELETE	Снять блокировку модели — тело `{provider, model}` или `{all: true}` для полной очистки
`/api/rate-limits`	GET	Состояние ограничения частоты запросов для каждой учётной записи
`/api/rate-limit`	GET	Глобальная конфигурация ограничения частоты запросов

Все четыре маршрута /api/resilience/* требуют аутентификации управления (requireManagementAuth). Полное описание различий между прерывателем провайдера, периодом ожидания подключения и блокировкой модели см. в разделе Отказоустойчивость (расширенное описание).

Оценки

Конечная точка	Метод	Описание
`/api/evals`	GET/POST	Вывести наборы тестов / запустить оценку

Политики

Конечная точка	Метод	Описание
`/api/policies`	GET/POST/DELETE	Управление политиками маршрутизации

Соответствие требованиям

Конечная точка	Метод	Описание
`/api/compliance/audit-log`	GET	Журнал аудита соответствия требованиям (последние N записей)

v1beta (совместимость с Gemini)

Конечная точка	Метод	Описание
`/v1beta/models`	GET	Вывести список моделей в формате Gemini
`/v1beta/models/{...path}`	POST	Конечная точка Gemini `generateContent`

Эти конечные точки воспроизводят формат API Gemini для клиентов, которым требуется нативная совместимость с Gemini SDK.

Внутренние / системные API

Конечная точка	Метод	Описание
`/api/init`	GET	Проверка инициализации приложения (используется при первом запуске)
`/api/tags`	GET	Совместимые с Ollama теги моделей (для клиентов Ollama)
`/api/restart`	POST	Запуск корректного перезапуска сервера
`/api/shutdown`	POST	Запуск корректного завершения работы сервера
`/api/system/env/repair`	POST	Восстановление переменных окружения провайдера OAuth

Примечание: Эти конечные точки используются системой для внутренних нужд или для совместимости с клиентами 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"
}

Транскрипция аудио

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": "Здравствуйте, это транскрибированное содержимое аудиозаписи.",
  "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.

Совместимость с Ollama

Для клиентов, использующих формат API Ollama:

# Эндпоинт чата (формат Ollama)
POST /v1/api/chat

# Получение списка моделей (формат Ollama)
GET /api/tags

Запросы автоматически преобразуются между форматами Ollama и внутренними форматами.

Токенизированные псевдонимы VS Code без заголовков

Используйте эти псевдонимы, если интеграция не может добавить заголовок Authorization и требуется встроить ключ API в базовый URL.

# Псевдоним каталога в стиле OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Псевдонимы чата в стиле OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Псевдонимы в стиле Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Пример:

curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'

Примечания:

Токенизированные псевдонимы используют те же обработчики, что и /v1/* и /api/tags; структуры ответов остаются идентичными.
По возможности используйте Authorization: Bearer ..., если клиент поддерживает пользовательские заголовки.
Токены в URL могут появляться в журналах обратного прокси, истории браузера и телеметрии за пределами OmniRoute. Рассматривайте их как вариант для обеспечения совместимости, а не как режим аутентификации по умолчанию.

Телеметрия

# Получение сводки телеметрии задержек (p50/p95/p99 для каждого провайдера)
GET /api/telemetry/summary

Ответ:

{
  "providers": {
    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
  }
}

Бюджет

# Получение состояния бюджета для всех ключей API
GET /api/usage/budget

# Установка или обновление бюджета
POST /api/usage/budget
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "dailyLimitUsd": 5.00,
  "weeklyLimitUsd": 30.00,
  "monthlyLimitUsd": 100.00,
  "warningThreshold": 0.8,
  "resetInterval": "monthly"
}

Примечания к схеме (setBudgetSchema): поле apiKeyId является обязательным; хотя бы одно из полей dailyLimitUsd, weeklyLimitUsd или monthlyLimitUsd должно иметь значение больше нуля. Необязательные поля: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Устаревшая структура {keyId, limit, period} возвращает 400 Bad Request.

Лимиты токенов

Бюджеты токенов для каждого API-ключа (отличаются от указанного выше бюджета в USD). Применяются непосредственно при обработке запроса: когда использование ключа в текущем временном окне достигает установленного лимита, запросы отклоняются с ошибкой 429 Too Many Requests. Лимиты могут быть привязаны к конкретной model, provider или применяться global ко всему ключу; если запрос соответствует нескольким лимитам, применяется самый строгий из них.

# Получить список лимитов токенов ключа (включая текущее использование окна)
GET /api/usage/token-limits?apiKeyId=key-123

# Создать или обновить лимит токенов
POST /api/usage/token-limits
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "scopeType": "model",
  "scopeValue": "openai/gpt-4o",
  "tokenLimit": 1000000,
  "resetInterval": "monthly",
  "enabled": true
}

# Удалить лимит токенов по идентификатору
DELETE /api/usage/token-limits?id=tl-abc

Примечания к схеме (setTokenLimitSchema): apiKeyId и scopeType (model | provider | global) обязательны. scopeValue обязателен, кроме случаев, когда scopeType имеет значение global (например, идентификатор модели для области действия model или идентификатор провайдера для области действия provider). tokenLimit должен быть положительным целым числом (строка автоматически преобразуется в число). Необязательные поля: id (не указывайте для создания, укажите для обновления), resetInterval (daily | weekly | monthly, по умолчанию monthly), resetTime (HH:MM), enabled (по умолчанию true). Ответы GET дополняют каждый лимит полями tokensUsed, remaining, windowStart, periodStartAt и nextResetAt. Это конечная точка класса управления (аутентификация централизованно обеспечивается конвейером авторизации).

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

Клиент отправляет запрос в /v1/*
Обработчик маршрута вызывает handleChat, handleEmbedding, handleAudioTranscription или handleImageGeneration
Определяется модель (непосредственно через провайдера/модель либо через псевдоним/комбинацию)
Учётные данные выбираются из локальной базы данных с фильтрацией по доступности учётной записи
Для чата: handleChatCore проверяет семантический кэш/кэш сигнатур и определяет настройки сжатия комбинации
Если включено упреждающее сжатие, оно выполняется до преобразования запроса для провайдера (lite, Caveman, RTK или их сочетание)
Исполнитель провайдера отправляет восходящий запрос
Ответ преобразуется обратно в клиентский формат (для чата) или возвращается без изменений (для векторных представлений, изображений и аудио)
Регистрируются использование, аналитика сжатия и журналы запросов
При ошибках применяется резервный вариант в соответствии с правилами комбинации

Полное описание архитектуры: ARCHITECTURE.md

Управление комбинациями

Комбинации маршрутизации более высокого уровня (уже описанные в разделе /api/combos*) также можно сопоставлять с шаблоном идентификатора модели в отношении 1:1, обеспечивая прозрачное перенаправление идентификатора модели в стиле OpenAI на комбинацию.

Метод	Путь	Описание
GET	`/api/model-combo-mappings`	Получить список всех сопоставлений модель→комбинация
POST	`/api/model-combo-mappings`	Создать сопоставление — тело: `{pattern, comboId, priority?, enabled?, description?}`
GET	`/api/model-combo-mappings/[id]`	Получить отдельное сопоставление
PUT	`/api/model-combo-mappings/[id]`	Обновить поля существующего сопоставления
DELETE	`/api/model-combo-mappings/[id]`	Удалить сопоставление

Аутентификация: сессия управления/API-ключ (requireManagementAuth).

Вебхуки

Подписки на исходящие вебхуки для событий OmniRoute (завершение запроса, исчерпание квоты, ротация ключей и т. д.).

Метод	Путь	Описание
GET	`/api/webhooks`	Список вебхуков (секреты маскируются в формате `<prefix>...`)
POST	`/api/webhooks`	Создание вебхука — тело: `{url, events?: ["*"], secret?, description?}`
GET	`/api/webhooks/[id]`	Получение вебхука
PUT	`/api/webhooks/[id]`	Обновление url/events/secret/description
DELETE	`/api/webhooks/[id]`	Удаление вебхука
POST	`/api/webhooks/[id]/test`	Отправка тестовой полезной нагрузки на URL вебхука и возврат статуса доставки

Аутентификация: сеанс управления/API-ключ (requireManagementAuth).

Зарегистрированные ключи (автоматическое управление)

Используется подсистемой автоматического управления ключами для выпуска и ротации API-ключей через базового поставщика/учётную запись с дневными/часовыми квотами.

Метод	Путь	Описание
GET	`/api/v1/registered-keys`	Список зарегистрированных ключей (отображается только маскированный префикс)
POST	`/api/v1/registered-keys`	Выпуск нового зарегистрированного ключа — тело: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Необработанный ключ возвращается один раз. При отказе из-за квоты возвращается `429`.
GET	`/api/v1/registered-keys/[id]`	Получение метаданных зарегистрированного ключа (без необработанного ключевого материала)
DELETE	`/api/v1/registered-keys/[id]`	Отзыв зарегистрированного ключа
POST	`/api/v1/registered-keys/[id]/revoke`	Явная конечная точка отзыва (имеет тот же эффект, что и DELETE)

Аутентификация: Bearer API-ключ (isAuthenticated). См. также /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]`	Удаление конкретной задачи по 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 — в кодовой базе нет отдельных подмаршрутов для каждого id.

Отказоустойчивость (расширенная)

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 → «Состояние среды выполнения отказоустойчивости».

Навыки

Платформа навыков для расширения 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`	Состояние подсистемы памяти (подключение к БД, серверная часть эмбеддингов, состояние векторного индекса)

Аутентификация: сессия управления/API-ключ (requireManagementAuth). Перечисление type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (см. MemoryType в src/lib/memory/types.ts).

Сервер MCP

OmniRoute поставляется со встроенным сервером Model Context Protocol с 3 транспортами (stdio, SSE, streamable-http) и инструментами с разграниченными областями доступа. Приведённые ниже конечные точки панели управления считывают данные о состоянии/аудите и проксируют HTTP-транспорты.

Аутентификация: транспорты sse/stream используют специализированный механизм аутентификации MCP (Bearer API-ключ с областью доступа 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": "Маршрутизируй эту задачу по программированию"}]
  }
}

Поддерживаемые методы (все зависят от 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, если он настроен.

Облако, оценки и анализ

| Метод | Путь | Описание | | —– | —————————–– | ———————————————————————————————–– | —————————– | ———————————– | | 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-ключ; остальные маршруты /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`	Отправка тестового события вебхуку

Аутентификация: Требуется сеанс управления.

Полный список типов событий см. в разделе Фреймворк вебхуков.

Фреймворк Skills

Управление Skills (фреймворком агентных расширений).

Метод	Путь	Описание
GET	`/api/skills`	Получить список всех установленных skills (встроенных и пользовательских)
POST	`/api/skills/install`	Установить skill из локального пути или URL
DELETE	`/api/skills/[id]`	Удалить skill
PUT	`/api/skills/[id]`	Включить или отключить skill — тело: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}`
POST	`/api/skills/executions`	Выполнить skill — тело: `{skillName, apiKeyId, input?, sessionId?}`
GET	`/api/skills/executions`	Получить историю выполнения всех skills (фильтр по `?apiKeyId=`)

Аутентификация: Требуется управляющая сессия или API-ключ с областью управления.

Полную информацию см. в разделе Фреймворк Skills.

Плагины

Управление плагинами OmniRoute (сторонними расширениями).

Метод	Путь	Описание
GET	`/api/plugins`	Получить список установленных плагинов
POST	`/api/plugins/marketplace/install`	Установить плагин из маркетплейса
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.

Защитные механизмы

Просмотр защитных механизмов среды выполнения (обнаружение персональных данных, обнаружение инъекций в промпты, промежуточная обработка изображений). Защитные механизмы выполняются при каждом запросе; отказаться от их использования для отдельного вызова можно с помощью заголовка запроса x-omniroute-disabled-guardrails — сохраняемого интерфейса включения/отключения не предусмотрено.

Метод	Путь	Описание
GET	`/api/guardrails`	Получить список зарегистрированных защитных механизмов и их состояний (имя / включён / приоритет)
POST	`/api/guardrails/test`	Выполнить пробный прогон конвейера предварительной обработки для примера входных данных — тело: `{input, disabledGuardrails?}`

Аутентификация: Требуется управляющая сессия.

Полную информацию см. в разделе Безопасность > Защитные механизмы.

Аутентификация

Описание четырёх типов учётных данных (сессия панели управления, локальный токен CLI, токен доступа oma_live_…, API-ключ с областью управления) и их отличий от ключей для инференса см. в разделе Аутентификация управления.

Маршруты панели управления (/dashboard/*) используют cookie auth_token
Для входа используется сохранённый хеш пароля; резервный вариант — INITIAL_PASSWORD
Параметр requireLogin можно переключать через /api/settings/require-login
Маршруты /v1/* могут требовать Bearer API-ключ, если REQUIRE_API_KEY=true
Термины «токен управления» / «API-ключ с областью управления» в этом справочнике означают один из типов, описанных в указанном руководстве, а не какой-либо дополнительный неопределённый тип секрета

Критическое изменение (v3.8.0) — /api/v1/agents/tasks/* и эндпоинты управления периодом ожидания теперь требуют аутентификацию управления (cookie auth_token панели управления или API-ключ с областью управления). Клиенты, которые ранее обращались к этим маршрутам без аутентификации, теперь получат ответ 401 Unauthorized. См. коммит 588a0333 (fix(auth): require management auth for agent and cooldown APIs).

Исходный код OmniRoute (a58000c7685f)

HagiCode

HagiCode — агентная среда разработки со структурированными процессами, параллельным выполнением несколькими агентами и интерфейсами Hero Dungeon.

Превращайте идеи в полезное ПО с более умным, быстрым и увлекательным агентным рабочим процессом.

SmartСтруктурированные процессы превращают намерение в исполнимый путь от идеи до готового изменения.
EfficientМультиагентные процессы параллельно продвигают исследование, реализацию и проверку.
FunHero Dungeon делает длительную совместную разработку наглядной и увлекательной.

Перейти на HagiCode

API Reference (Русский)

Содержание

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

Пользовательские заголовки

Эксклюзивные управляемые аренды сессий

x-omniroute-compression

Эмбеддинги

Генерация изображений

OCR документов

Процесс опроса Azure Document Intelligence

Аутентификация и разрешение конечной точки Vertex AI DeepSeek OCR

Список моделей

Префиксы идентификаторов моделей (?prefix=)

Варианты моделей без размышлений

Манифест плагинов провайдеров

Конечные точки совместимости

Выделенные маршруты поставщиков

Files API

Batches API

Search API

Web Fetch API

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

Responses API через WebSocket (только codex)

Идентификатор модели: используйте простой идентификатор ChatGPT (без префикса codex/)

Настройка OpenAI Codex CLI

Квоты и сообщения о проблемах

Самостоятельный просмотр использования (/api/usage/om-usage)

Семантический кеш

Влияние на задержку

Обход кеша для отдельных ключей

Обход кеша для отдельного запроса

Панель управления и администрирование

Аутентификация

Управление провайдерами

Потоки OAuth

Маршрутизация и конфигурация

Использование и аналитика

Настройки

Контекст и сжатие

Мониторинг

Резервное копирование и экспорт/импорт

Облачная синхронизация

Туннели

Инструменты CLI

Агенты ACP

Отказоустойчивость и ограничения частоты запросов

Оценки

Политики

Соответствие требованиям

v1beta (совместимость с Gemini)

Внутренние / системные API

Восстановление окружения OAuth (v3.6.1+)

Транскрипция аудио

Совместимость с Ollama

Токенизированные псевдонимы VS Code без заголовков

Телеметрия

Бюджет

Лимиты токенов

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

Управление комбинациями

Вебхуки

Зарегистрированные ключи (автоматическое управление)

Протокол агентов

Управление прокси

Отказоустойчивость (расширенная)

Навыки

Память

Сервер MCP

Сервер A2A

JSON-RPC

Карточка агента

Вспомогательные REST-маршруты

Облако, оценки и анализ

Управление ACP (Agent Client Protocol)

Аналитика и наблюдаемость

Аналитика автоматической маршрутизации

Аналитика сжатия

Отслеживание разнообразия провайдеров

Административные операции

Управление инструментами CLI

`x-omniroute-compression`

Префиксы идентификаторов моделей (`?prefix=`)

Идентификатор модели: используйте простой идентификатор ChatGPT (без префикса `codex/`)

Самостоятельный просмотр использования (`/api/usage/om-usage`)