Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
API Reference (Español)
🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇪 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 · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW
🌐 Idiomas: 🇺🇸 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á | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)
Referencia principal de la API de OmniRoute. Abarca la interfaz pública /v1 y los endpoints de administración más utilizados; el archivo legible por máquina docs/openapi.yaml y el árbol de rutas ubicado en src/app/api/ son las fuentes exhaustivas.
Para consultar el protocolo específico compatible con OpenAI y la matriz de capacidades de los proveedores, consulta
OPENAI_COMPATIBILITY.md.
Tabla de contenidos
- Completado de chat
- Arrendamientos exclusivos de sesiones administradas
- Embeddings
- Generación de imágenes
- OCR de documentos
- Lista de modelos
- Manifiesto de plugins de proveedores
- Endpoints de compatibilidad
- API de archivos
- API de lotes
- API de búsqueda
- Streaming mediante WebSocket
- Informes de cuotas e incidencias
- Caché semántica
- Panel y administración
- Administración de combos
- Webhooks
- Claves registradas (administración automática)
- Protocolo de agentes
- Proxies de administración
- Resiliencia (ampliada)
- Habilidades
- Memoria
- Servidor MCP
- Servidor A2A
- Nube, evaluaciones y valoración
- Procesamiento de solicitudes
- Autenticación
Finalizaciones de chat
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
}
Encabezados personalizados
| Encabezado | Dirección | Descripción |
|---|---|---|
X-OmniRoute-No-Cache |
Solicitud | Establézcalo en true para omitir la caché |
x-omniroute-no-memory |
Solicitud | Establézcalo en true para omitir la inyección de memoria y habilidades en esta solicitud (equivale a no usar la caché; evita la sobrecarga de tokens/coste por llamada) |
X-OmniRoute-Progress |
Solicitud | Establézcalo en true para recibir eventos de progreso |
X-Session-Id |
Solicitud | Clave de sesión persistente para la afinidad de sesiones externas |
x_session_id |
Solicitud | También se acepta la variante con guion bajo (HTTP directo) |
X-OmniRoute-Session-Id |
Solicitud | Etiqueta de sesión/conversación proporcionada por el llamador (también alimenta la memoria). Cuando está presente, se conserva literalmente en call_logs.session_tag para atribuir costes por sesión (#8249); nunca se genera si está ausente |
Idempotency-Key |
Solicitud | Clave de deduplicación (ventana de 5 s) |
X-Request-Id |
Solicitud | Clave de deduplicación alternativa |
x-omniroute-connection |
Solicitud | Fija una solicitud de un único modelo a una conexión (cuenta) de proveedor mediante su id; consulte Fijación de cuenta por solicitud |
X-OmniRoute-Cache |
Respuesta | HIT o MISS (sin streaming) |
X-OmniRoute-Idempotent |
Respuesta | true si se ha deduplicado |
X-OmniRoute-Progress |
Respuesta | enabled si el seguimiento del progreso está activado |
X-OmniRoute-Session-Id |
Respuesta | ID de sesión efectivo utilizado por OmniRoute |
X-OmniRoute-Request-Id |
Respuesta | ID de correlación de la solicitud (cuando se conoce) |
X-OmniRoute-Version |
Respuesta | Versión de compilación de OmniRoute (siempre presente) |
X-OmniRoute-Cost-Saved |
Respuesta | Importe en USD que la caché evitó en un HIT (solo aciertos de caché) |
X-OmniRoute-Decision |
Respuesta | Traza de enrutamiento: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> es la estrategia combinada, o single para una solicitud no combinada); siempre presente en las respuestas de finalización |
Nota sobre Nginx: si depende de encabezados con guiones bajos (por ejemplo,
x_session_id), habiliteunderscores_in_headers on;.
Fijación de cuenta por solicitud
Cuando un proveedor tiene varias conexiones (cuentas o claves), OmniRoute normalmente selecciona una
mediante su estrategia de selección de cuentas. En su lugar, una solicitud puede fijar una conexión específica
con el encabezado 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"}]}'
- Dónde encontrar el id. Abre la página del proveedor en el panel
(Panel → Proveedores → ) y haz clic en la etiqueta de id
xxxxxxxx…de una fila de conexión; esto copia el id completo de la conexión. - Qué solicitudes lo respetan. Las solicitudes de un solo modelo (
provider/model) en/v1/chat/completions,/v1/messagesy/v1/responses. Los combos ignoran la cabecera: fija una cuenta para cada paso del combo mediante la conexión propia del paso. - La fijación es estricta, no una preferencia. La conexión fijada se utiliza de forma exclusiva. Un fallo dentro de la solicitud registra el período de espera de la cuenta, pero no cambia a otra cuenta del mismo proveedor.
- El período de espera y la cuota liberan la fijación. Mientras la conexión fijada está en período de espera, tiene la cuota agotada o está bloqueada por una política de cuotas, las solicitudes posteriores recurren a las demás conexiones del proveedor, exactamente igual que el tráfico sin fijar.
- Los ids desconocidos o deshabilitados provocan un fallo. Un id que no esté en el grupo activo del proveedor (eliminado, desactivado o perteneciente a otro proveedor) no deja ninguna cuenta apta, por lo que la solicitud falla en lugar de redirigirse silenciosamente a otro destino.
Claude Code envía cabeceras personalizadas mediante ANTHROPIC_CUSTOM_HEADERS. Inclúyelo en el bloque env
de ~/.claude/settings.json, o en un archivo .claude/settings.json a nivel de proyecto para fijar una
cuenta diferente por proyecto:
{
"env": {
"ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
"ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
"ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: <connection id>",
},
}
Fuente: src/sse/handlers/chat.ts (lectura de la cabecera), src/sse/services/auth.ts y
src/sse/services/sessionAffinityPin.ts (liberación de la fijación y comprobación de ausencia en el grupo).
Cabeceras de telemetría de costes: las respuestas correctas sin streaming también incluyen el conjunto de telemetría de costes
X-OmniRoute-*:X-OmniRoute-Response-Cost(USD, con 10 decimales fijos;0.0000000000cuando es gratuito o no tiene precio),X-OmniRoute-Tokens-In/X-OmniRoute-Tokens-Out,X-OmniRoute-Model,X-OmniRoute-Provider,X-OmniRoute-Latency-Ms,X-OmniRoute-Cache-HityX-OmniRoute-Fallback-Attempts(solo cuando > 0), además deX-OmniRoute-Request-IdyX-OmniRoute-Version. Estas cabeceras se emiten para las finalizaciones de chat,/v1/responses,/v1/messagesy los endpoints multimedia:/v1/embeddings,/v1/images/generations,/v1/audio/speech,/v1/audio/transcriptions,/v1/rerank,/v1/videos/generations,/v1/music/generationsy/v1/moderations(siempre con coste0). El coste multimedia se calcula por modalidad (por imagen, por segundo, por carácter o por unidad de búsqueda) cuando hay precios disponibles; de lo contrario, es0(fail-open).
Semántica de costes de los aciertos de caché: en un acierto de caché semántica (
X-OmniRoute-Cache-Hit: true) no se realiza ninguna llamada al proveedor ascendente, por lo queX-OmniRoute-Response-Costes0.0000000000(el coste incremental de servir el acierto). El coste original o que se habría producido se informa por separado enX-OmniRoute-Cost-Saved. Los consumidores de facturación deben sumarX-OmniRoute-Response-Cost(los aciertos no cuestan nada); los análisis de caché pueden agregarX-OmniRoute-Cost-Saved.
Concesiones exclusivas de sesiones administradas
La concesión exclusiva de sesiones administradas es un contrato de enrutamiento opcional y neutral respecto al cliente: un propietario activo mantiene una conexión de OmniRoute apta. No concede un modelo, no requiere OAuth, no identifica a un cliente específico ni requiere un proveedor específico.
La clave de API usada para la autenticación debe tener el ámbito lease:exclusive y una lista
allowedConnections explícita y no vacía. El límite de mutación de la base de datos exige ambos campos
conjuntamente al crear claves y realizar actualizaciones parciales.
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"}
Las respuestas correctas de adquisición, renovación y liberación exponen marcas de tiempo, state y la
generation positiva exacta, pero nunca la conexión seleccionada ni las credenciales. La renovación y la
liberación proporcionan la generación en el cuerpo JSON:
{ "action": "renew", "generation": 1 }
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
El propietario de una concesión activa puede solicitar explícitamente metadatos de visualización seguros para la privacidad correspondientes a su vinculación actual:
{ "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"
}
}
Esta acción de estado opcional queda protegida por el propietario opaco, la clave de API administrada
autenticada y la generación activa exacta dentro de una única transacción de base de datos. displayName
es únicamente el nombre de conexión configurado y sin espacios circundantes; es null cuando no existe
un nombre configurado seguro. OmniRoute nunca lo sustituye por un correo electrónico ni por una identidad
de cuenta generada. El valor del proveedor es una etiqueta de visualización no confidencial y nunca un
identificador generado de proveedor compatible. Se excluyen las credenciales, los tokens, las cookies,
los identificadores sin procesar de conexiones o claves de API, los hashes de propietarios, los secretos
de protección y los datos internos de enrutamiento.
Las consultas con una clave incorrecta, un propietario incorrecto, una generación obsoleta, datos
ausentes, una concesión caducada, liberada o invalidada devuelven todas el mismo error
409 LEASE_FENCE_STALE sin metadatos de conexión. Un cliente que haya recibido la respuesta de espera
por capacidad no tiene ninguna vinculación activa que inspeccionar. Cuando el enrutamiento cambia una
concesión activa, la misma generación continúa siendo válida y el estado devuelve atómicamente la nueva
vinculación, nunca la anterior. Los clientes existentes no sufren cambios porque las respuestas de
adquisición, renovación, liberación y espera conservan sus formatos anteriores.
Este contrato del servidor no modifica /status de OpenAI Codex estándar. Actualmente, Codex estándar
informa de su proveedor de modelos y del estado integrado de autenticación/cuenta, pero no representa
metadatos arbitrarios de cuentas de proveedores personalizados; una futura integración del cliente deberá
invocar esta acción y decidir cómo mostrar connection.displayName.
A continuación, cada solicitud de inferencia administrada proporciona ambos encabezados de control:
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
El propietario exacto, la generación, la conexión activa y la clave de API autenticada se validan inmediatamente antes de cada intento ascendente compatible. La reutilización del propietario y la generación con otra clave falla incluso cuando esa clave permite la misma conexión. Los propietarios sin procesar no se conservan, no se registran, no se retienen en la instantánea de la solicitud ni se reenvían al servidor ascendente.
La contención temporal devuelve HTTP 429 con Retry-After y:
{
"state": "WAITING_FOR_CAPACITY",
"error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
"reason": "NO_FREE_ELIGIBLE_CONNECTION",
"retryAfter": 30
}
Esta respuesta solo significa que el conjunto apto ordinario no estaba vacío y que cada candidato libre estaba ocupado por una concesión activa ajena. Los modelos/proveedores no compatibles, las discrepancias de políticas, los períodos de espera, las cuotas, el estado de salud y otros fallos ordinarios de elegibilidad conservan sus respuestas existentes de OmniRoute.
x-omniroute-compression
Anulación por solicitud del plan de compresión. Tiene la máxima precedencia: se impone a la anulación de la combinación de enrutamiento, al perfil activo, al activador automático y al valor Predeterminado del panel. Valores:
| Valor | Efecto |
|---|---|
off |
Sin compresión para esta solicitud. |
default |
El perfil Predeterminado derivado del panel (ignora el perfil activo). Los motores con pérdida permanecen desactivados. |
safe |
Solo deduplicación y normalización de espacios en blanco. |
allow-lossy |
Mantiene el plan del operador para esta solicitud, incluidos los resúmenes y las reescrituras de estilo. |
engine:<id> |
Un único motor cuando está habilitado, p. ej., engine:rtk. Activación por solicitud para ese motor. |
<combo> |
Una combinación con nombre, buscada primero por nombre (sin distinguir mayúsculas y minúsculas) y después por id. |
Notas:
- Los valores desconocidos se ignoran (la solicitud nunca se rechaza); la resolución continúa según la precedencia normal del operador.
- Si varias combinaciones comparten un nombre, proporcione el id de la combinación para obtener una coincidencia determinista.
- Una combinación cuyo nombre sea
offodefaultno puede seleccionarse por nombre (esas palabras clave se interpretan primero); haga referencia a dicha combinación mediante su id. - El interruptor principal de compresión es una restricción absoluta: cuando la compresión está deshabilitada globalmente, este encabezado no puede habilitarla.
El plan aplicado se devuelve en el encabezado de respuesta:
X-OmniRoute-Compression: <mode>; source=<source>
donde <source> es uno de request-header, routing-override, active-profile, auto-trigger, default u off.
Embeddings
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "nebius/Qwen/Qwen3-Embedding-8B",
"input": "The food was delicious"
}
Proveedores disponibles: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.
Los identificadores del catálogo tienen el formato provider/model (ejemplo: jina-ai/jina-embeddings-v5-omni-small). Los identificadores de modelos de Jina sin prefijo que aparecen en el registro (por ejemplo, jina-embeddings-v5-text-small, jina-reranker-v3.5) también se resuelven. Las operaciones embed/rerank/classify/segment de Jina usan primero las credenciales jina-ai del panel; JINA_AI_API_KEY solo se usa como alternativa cuando no existe ninguna clave en el panel. La tarjeta jina-reader corresponde únicamente a Reader / r.jina.ai (POST /v1/web/fetch) y nunca proporciona embeddings ni rerank.
Los modelos del registro que anuncian compatibilidad multimodal también aceptan hasta 32 elementos estructurados neutrales respecto al proveedor. Los tipos de elementos multimedia son text, image, audio, video y document. Su source multimedia puede ser {"type":"url","url":"https://..."} o {"type":"base64","data":"...","media_type":"..."}.
Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano y el alias de familia jina-ai/jina-embeddings-v5-omni → omni-small) también acepta documentos EmbeddingsV5Request nativos de Jina y los reenvía intactos a 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,..." }]
}
]
}
Los valores nativos { image | audio | video | pdf } pueden ser una URL HTTPS pública, un URI data: o datos base64 sin procesar. OmniRoute no convierte esos objetos en cadenas ni obtiene las URL de imágenes nativas: Jina recupera directamente el contenido multimedia público. Los campos adicionales de Jina (task, normalized, truncate, embedding_type) se reenvían. Los SKU de Jina que solo admiten texto siguen rechazando documentos que no sean de texto.
Límites de seguridad y transporte:
- Las URL de contenido multimedia remoto deben ser HTTPS públicas. Los elementos canónicos
{type,source:url}se obtienen en el servidor (revalidación de redirecciones, tiempo de espera, límites de tamaño, DNS público y fijación de conexión) y se incorporan antes de la llamada al proveedor. Los elementos nativos de Jina{image:"https://..."}se reenvían tal cual después de aplicar la misma comprobación de HTTPS público; Jina obtiene la URL. - El contenido multimedia base64 incorporado está limitado a 8 MiB decodificados por elemento y 16 MiB decodificados en toda la solicitud.
Traducción para proveedores (los elementos canónicos nunca se reenvían sin cambios):
- Modelos multimodales de Jina: cada elemento de nivel superior se convierte en un objeto con una clave de modalidad (
text/image/audio/video/pdf), usando URI de datos para el contenido multimedia incorporado; un vector por elemento de nivel superior. - Familia Gemini Embedding 2: un único array de nivel superior se convierte en una única solicitud nativa
models/{model}:embedContentconcontent.parts(textoinline_data). - llama.cpp (
llama-cpp/<model>, cualquier modelo cargado por el servidor local): los elementos canónicostextse convierten en cadenas simples, yimage/audio/videose convierten, cada uno, en un objeto{"content": [part]}, usando las partes de contenido de chat de llama-server (image_url,input_audiocon formatowav/mp3/flac,input_video) con datos incorporados; un vector por elemento de nivel superior. El servidor debe ejecutarse con--embedding --mmproj …; sin un proyector, el propio servidor rechaza el contenido multimedia.documentno es compatible. - Los modelos desconocidos o dinámicos sin metadatos explícitos de modalidad rechazan la entrada estructurada con 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"
}
Las combinaciones de modelo y modalidad no compatibles devuelven HTTP 400 en lugar de convertir el elemento. Los campos de extensión distintos de la entrada en las solicitudes heredadas de cadenas/tokens siguen transmitiéndose sin cambios.
# Enumerar todos los modelos de embeddings
GET /v1/embeddings
Generación de imágenes
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"
}
Los proveedores disponibles incluyen OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, ZenMux, SD WebUI (local) y ComfyUI (local).
n devuelve n imágenes en data[]. Para los proveedores cuya API de origen devuelve una imagen por llamada
(Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik,
NVIDIA NIM, Cloudflare Workers AI), se realizan n llamadas independientes al servicio de origen, con un máximo de 4 simultáneas. Una
seed fija se incrementa según el índice de la llamada (seed, seed + 1, …), de modo que las imágenes sean diferentes pero sigan
siendo reproducibles. n está limitado a 10. La solicitud falla por completo si falla alguna llamada. La lista
de formatos con distribución en abanico es SINGLE_IMAGE_FANOUT_FORMATS en
open-sse/handlers/imageGeneration/fanOut.ts.
ZenMux reutiliza la conexión existente mediante clave de API y acepta los prefijos zenmux/ o zm/:
zenmux/openai/gpt-image-2utiliza la API de imágenes de OpenAI de ZenMux. Las opciones incluyensize,quality,n,output_format,output_compression,backgroundyresponse_format.- Otros proveedores, como
zm/meta/muse-image-1.0, utilizan el endpoint:predictde Vertex AI de ZenMux.nse asigna asampleCount,aspect_ratioaaspectRatioeimage_size(1K,2K,4K) asampleImageSize. Unsizeen píxeles solo proporciona una relación de aspecto, no dimensiones de píxeles garantizadas. Las relaciones de aspecto, resoluciones y cantidades compatibles varían según el modelo. zm/inclusionai/ming-image-0.1-designelige sus propias dimensiones. Omitasize,aspect_ratioeimage_size; los valores explícitos devuelven HTTP 400. Se pueden solicitar PNG, JPEG y WebP medianteoutput_format.
Esta integración admite la generación de texto a imagen, no la edición mediante imágenes de referencia. La salida de Vertex
se normaliza como data[].b64_json; response_format: "url" devuelve una URL HTTPS del servicio de origen
o una URL de datos en base64 cuando solo están disponibles los bytes de la imagen. Las salidas vacías o filtradas
devuelven un error en lugar de una respuesta satisfactoria vacía. El acceso a los modelos depende de la cuenta de ZenMux.
Consulte la API de Vertex de ZenMux y la
API de imágenes de OpenAI.
# Enumerar todos los modelos de imágenes
GET /v1/images/generations
OCR de documentos
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 selecciona el proveedor de OCR mediante un prefijo provider/model; un id de modelo sin prefijo (p. ej.,
mistral-ocr-latest) se resuelve con su proveedor registrado, y si se omite model, se utiliza de forma predeterminada
Mistral (mistral-ocr-latest). Proveedores registrados (open-sse/config/ocrRegistry.ts):
| Id del proveedor | Id del modelo | Valor de model |
Notas |
|---|---|---|---|
mistral |
mistral-ocr-latest |
mistral/mistral-ocr-latest (o mistral-ocr-latest solo) |
Síncrono: la respuesta se devuelve directamente desde la única llamada al servicio externo. |
azure-document-intelligence |
prebuilt-read |
azure-document-intelligence/prebuilt-read |
Servicio externo asíncrono (analyze + sondeo): consulte la información a continuación. |
vertex-deepseek-ocr |
deepseek-ocr-maas |
vertex-deepseek-ocr/deepseek-ocr-maas |
Síncrono, mediante el endpoint asociado openapi/chat/completions de Vertex AI; consulte más abajo la autenticación/URL. |
Los tres proveedores responden con el mismo cuerpo con formato de Mistral:
{
"pages": [{ "index": 0, "markdown": "# Texto extraído..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
Flujo de sondeo de Azure Document Intelligence
La API analyze de Azure Document Intelligence es asíncrona: la solicitud inicial devuelve un
encabezado Operation-Location en lugar de un cuerpo, y se debe sondear el resultado. El controlador
(open-sse/handlers/ocr.ts) sondea esa URL cada segundo durante un máximo de 30 intentos, produce un error de inmediato (sin
seguir sondeando) ante una respuesta de sondeo que no sea ok o un estado "failed", y devuelve 504 si la
operación continúa ejecutándose después de agotar el límite de intentos. La respuesta final de Azure se
normaliza con la misma estructura pages/markdown utilizada por Mistral antes de devolverse al
cliente, por lo que el código del cliente no necesita tratar al proveedor como un caso especial.
Autenticación y resolución del endpoint de OCR de Vertex AI DeepSeek
vertex-deepseek-ocr reutiliza la misma autenticación de Vertex AI que OmniRoute ya admite para el
tráfico de chat/imágenes (open-sse/executors/vertex.ts): la clave de API de la conexión es una
credencial JSON de cuenta de servicio (intercambiada por un token de acceso OAuth de corta duración mediante el flujo JWT Bearer)
o un token de acceso OAuth ya emitido que se utiliza tal cual. La URL del endpoint del servicio externo es el endpoint
asociado genérico openapi/chat/completions de Vertex, creado a partir del proyecto y la
región de la conexión: un valor explícito de providerSpecificData.project/providerSpecificData.region siempre tiene prioridad;
de lo contrario, el proyecto se obtiene del project_id del JSON de la cuenta de servicio y la región
tiene como valor predeterminado us-central1. Ambas resoluciones se realizan en open-sse/handlers/ocr.ts
(resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl) y son utilizadas por
src/app/api/v1/ocr/route.ts antes de delegar la solicitud a handleOcr.
Listar modelos
GET /v1/models
Authorization: Bearer your-api-key
→ Devuelve todos los modelos de chat, embeddings e imágenes, además de las combinaciones, en formato OpenAI
Prefijos de id de modelo (?prefix=)
La mayoría de los modelos se anuncian bajo un prefijo de proveedor. El prefijo que se obtiene está controlado por
la marca de funcionalidad MODELS_CATALOG_PREFIX_MODE y puede sobrescribirse por solicitud mediante un
parámetro de consulta, lo que resulta útil para un cliente que desea una lista limpia sin cambiar la
configuración global del servidor para todos los demás:
GET /v1/models?prefix=alias # un id por modelo: el prefijo de alias corto
GET /v1/models?prefix=dual # ambas formas (valor predeterminado del servidor)
GET /v1/models?prefix=canonical # solo el prefijo completo del id del proveedor
| Modo | Emite | Notas |
|---|---|---|
dual |
cc/claude-sonnet-4-6 y claude/claude-sonnet-4-6 |
Predeterminado. Ambos ids se enrutan al mismo modelo; se conservan para que sigan funcionando las configuraciones de clientes que codificaron de forma fija cualquiera de las dos variantes. Prácticamente duplica el catálogo. |
alias |
cc/claude-sonnet-4-6 |
Una entrada por modelo. Los proveedores sin un alias distinto siguen emitiendo su entrada, por lo que no se pierde nada. |
canonical |
claude/claude-sonnet-4-6 |
Una entrada por modelo bajo el prefijo completo del id del proveedor. Los proveedores sin un alias distinto (p. ej., antigravity/…, agy/…) también emiten aquí su único id, por lo que no se pierde nada. |
Una réplica del modo dual también puede reconocerse sin el parámetro de consulta: contiene un campo parent
que apunta al id principal.
Los clientes que muestran un selector de modelos deben solicitar ?prefix=alias; esto es lo que hace la
extensión OmniCopilot para VS Code.
Filtros de descubrimiento (?capability=, ?min_context=, ?kind=, ?q=)
GET /v1/models acepta filtros de descubrimiento opcionales. Sin ninguno de ellos, la respuesta
no cambia. Estos restringen el catálogo que ya puede ver el solicitante (los permisos de la clave de API se aplican primero)
y se ejecutan antes de la paginación limit / after al estilo OpenAI:
GET /v1/models?capability=vision&capability=tool_calling # todas las capacidades indicadas deben ser verdaderas
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding # `type` del catálogo; las filas que no lo tienen son `chat`
GET /v1/models?q=sonnet&limit=10 # coincidencia sin distinguir mayúsculas y minúsculas en el id o el nombre
| Parámetro | Valores |
|---|---|
capability |
attachment, reasoning, structured_output, temperature, thinking, tool_calling, vision |
min_context |
entero no negativo, comparado con context_length |
kind |
chat, audio, embedding, image, moderation, music, rerank, video |
q |
entre 1 y 200 caracteres |
Un valor desconocido, o un min_context que no sea un entero no negativo (por ejemplo, 1.5),
devuelve HTTP 400 y el mensaje enumera los valores válidos. Implementación:
src/app/api/v1/models/catalogFilters.ts.
Lista reducida de modelos (POST /v1/models/query)
POST /v1/models/query devuelve una lista breve y determinista del mismo catálogo, con la misma
autenticación y visibilidad por clave que 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 ] }
Todos los campos son opcionales. capabilities y exclude aceptan un array o una cadena separada por comas;
max_output se compara con max_output_tokens. Los resultados se ordenan primero por owned_by y después por id.
El valor predeterminado de limit es 20, y los valores superiores a 100 se limitan a 100. Un JSON no válido, un campo desconocido
o un valor no válido devuelve HTTP 400.
Modelos de chat ocultos individualmente
Un modelo marcado como Oculto en la página de su proveedor se excluye del catálogo y se rechaza
con HTTP 404 / model_not_found cuando se solicita explícitamente. La comprobación utiliza el
proveedor y el modelo resueltos, incluidos los alias de proveedores, los prefijos de nodo de proveedores compatibles y
los valores predeterminados de conexión. Una combinación omite los destinos ocultos y puede utilizar otro destino visible; cuando no
queda ningún destino ejecutable, devuelve el mismo código de error. Al dejar de ocultarlo, el cambio entra en vigor en la siguiente
solicitud. Las sobrescrituras de visibilidad exclusivas para imágenes no ocultan el modelo de chat con el mismo ID.
Esta configuración individual del modelo es independiente de las
listas de modelos permitidos/denegados para su exposición, que filtran la
publicación en el catálogo y los candidatos de enrutamiento automático, a la vez que conservan el envío explícito. Los permisos de modelos
de las claves de API siguen aplicándose de forma independiente. El modo de prefijo predeterminado del catálogo continúa siendo dual.
Variantes de modelos sin razonamiento
Para los modelos Claude con capacidad de razonamiento, /v1/models también anuncia una variante sin razonamiento cuyo id tiene el prefijo claude-3-omniroute-no-thinking/:
claude-3-omniroute-no-thinking/<provider>/<model>
Seleccionar este id (p. ej., en una configuración de Claude Code que siempre adjunta un bloque thinking) se resuelve de nuevo al <provider>/<model> real con el razonamiento desactivado: thinking:{type:"disabled"} en la ruta /v1/messages, o se omiten los campos reasoning/reasoning_effort en la ruta /v1/chat/completions. La variante solo se muestra para los modelos de la familia Claude que admiten el razonamiento y respetan disabled (por lo que, p. ej., se excluyen los modelos exclusivamente adaptativos que rechazan disabled). Los operadores pueden forzar la activación o desactivación de la variante por modelo mediante ModelSpec.noThinkingAlias.
Manifiesto de plugins de proveedores
GET /api/v1/provider-plugin-manifest
Devuelve el manifiesto JSON seguro de plugins de proveedores utilizado por Bifrost, CLIProxyAPI y futuros enrutadores sidecar. La respuesta se genera a partir del registro de proveedores de TypeScript y excluye intencionadamente los secretos de clientes OAuth, la resolución del entorno de ejecución, las funciones ejecutoras, los encabezados de solicitud y los datos de las cuentas.
Utilice este endpoint cuando un sidecar se ejecute fuera de proceso y no pueda importar
open-sse/config/providerPluginManifestRegistry.ts directamente.
Endpoints de compatibilidad
| Método | Ruta | Formato |
|---|---|---|
| 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 (edición/relleno generativo) |
| POST | /v1/videos/generations |
Generación de vídeo al estilo de OpenAI |
| POST | /v1/music/generations |
Generación de música al estilo de OpenAI |
| POST | /v1/audio/transcriptions |
OpenAI Audio (STT) |
| POST | /v1/audio/speech |
OpenAI TTS (devuelve el cuerpo de audio) |
| POST | /v1/rerank |
Reclasificación al estilo de Cohere/Voyage |
| POST | /v1/classify |
Clasificación de Jina (api.jina.ai) |
| POST | /v1/segment |
Segmentador de Jina (segment.jina.ai) |
| POST | /v1/moderations |
Moderaciones de OpenAI |
| GET | /v1/models |
OpenAI |
| POST | /v1/models/query |
Lista reducida de modelos filtrados |
| 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}/ |
Alias del catálogo de OpenAI |
| GET | /api/v1/vscode/{token}/models |
Alias de modelos de OpenAI |
| POST | /api/v1/vscode/{token}/chat/completions |
Alias con token de OpenAI |
| POST | /api/v1/vscode/{token}/responses |
Alias con token de OpenAI Responses |
| POST | /api/v1/vscode/{token}/api/chat |
Alias con token de Ollama |
| GET | /api/v1/vscode/{token}/api/tags |
Alias con token de etiquetas de Ollama |
Todas las rutas POST siguen la misma estructura: Bearer your-api-key + cuerpo JSON validado con Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema, etc.; consulta src/shared/validation/schemas.ts). Se devuelve un error 4xx si falla la validación del esquema.
Para los clientes que no pueden adjuntar Authorization: Bearer ..., OmniRoute también acepta claves de API en la URL mediante compatibilidad con parámetros de consulta (?token=..., ?apiKey=..., ?api_key=..., ?key=...) o mediante los endpoints específicos /api/v1/vscode/{token}/... documentados a continuación.
# Reclasificación (proveedor del registro en la nube o nodo de proveedor compatible con OpenAI como "<prefix>/<model>")
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Clasificación de Jina (credenciales de Foundation API)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Segmentador de Jina
POST /v1/segment { "content": "...", "return_chunks": true }
# Búsqueda de Jina (s.jina.ai; alias de proveedores: jina-search, jina-ai, jina)
POST /v1/search { "query": "...", "provider": "jina-search" }
# Moderaciones
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
# TTS — devuelve un cuerpo audio/mpeg (o en el formato solicitado)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# Soniox TTS requiere un idioma y una voz: `language` utiliza "en" de forma predeterminada; una
# voz ausente o un nombre de voz estándar de OpenAI (alloy, nova, …) se convierte en "Adrian"
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }
# Edición de imagen (multipart)
POST /v1/images/edits -F [email protected] -F prompt="..." -F [email protected]
# Generación de vídeo/música (ID de modelo con prefijo del proveedor)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "kie/suno-v4.0", "prompt": "..." }
Nodos de proveedores de rerank:
POST /v1/reranktambién enruta a nodos de proveedores compatibles con OpenAI (oMLX, vLLM, Infinity, TEI detrás de una puerta de enlace, …) identificados como<node-prefix>/<model>. Los nodos de bucle invertido (localhost,127.0.0.1,172.16.0.0/12) siempre son aptos, al igual que los nombres de host que el operador enumera enOMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS(p. ej., un nombre de servicio de Docker/Compose comohttp://reranker:8080/v1; se accede a ellos directamente, nunca medianteHTTP(S)_PROXYni el proxy fijado de una conexión). Los nodos de cualquier otro host —un equipo de la LAN o un par de Tailscale— solo son aptos cuando el operador habilita la marca de funcionalidadRERANK_REMOTE_PROVIDER_NODESy la URL base del nodo cumple la política de URL salientes del proveedor (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS/OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS). El paso de rerank del motor de memoria llama a esta ruta mediante el bucle invertido, por lo que la misma regla rigererankProviderModelen la configuración de Memoria.Formatos de servidores locales: se llama al nodo en
<base>/v1/reranky, si devuelve 404, en<base>/rerank(Infinity, TEI). El cuerpo enviado al servicio de origen incluye tanto la nomenclatura de Cohere/OpenAI (documents,return_documents) como la de TEI (texts,return_text), y la respuesta del servicio de origen se normaliza al envoltorio de Cohere: la matriz sin envoltorio de TEI[{index, score, text}],{results: [{index, score}]}de puertas de enlace ligeras y{data: [...]}al estilo de Voyage se devuelven al cliente como{results: [{index, relevance_score, document?}]}, ordenados por puntuación y limitados atop_n.
Descubrimiento de nodos de proveedores: los modelos de un nodo de proveedor compatible con OpenAI aparecen en
GET /v1/modelsbajo el prefijo del nodo. Las filas que no contienen metadatos de endpoint (lo habitual en los listados locales de/v1/models) heredan elapiTypedel nodo, de modo que los modelos de un nodoembeddingstienentype: "embedding"y los de un nodoreranktienentype: "rerank"en lugar de usar chat de forma predeterminada; un valor explícito desupportedEndpointsen una fila sincronizada o añadida manualmente sigue teniendo prioridad.
Rutas de proveedor dedicadas
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
El prefijo del proveedor se añade automáticamente si falta. Los modelos que no coincidan devuelven 400.
API de archivos
Endpoint de archivos compatible con OpenAI para entrada/salida por lotes y cargas de archivos con propósito.
| Método | Ruta | Descripción |
|---|---|---|
| POST | /v1/files |
Cargar un archivo (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — máximo de 512 MiB |
| GET | /v1/files |
Listar los archivos de la clave de API autenticada |
| GET | /v1/files/[id] |
Obtener los metadatos de un archivo |
| DELETE | /v1/files/[id] |
Eliminar un archivo |
| GET | /v1/files/[id]/content |
Transmitir el contenido sin procesar del archivo |
Autenticación: Clave de API Bearer — los archivos se limitan por clave de API mediante getApiKeyRequestScope. Una clave
solo puede ver, descargar y eliminar sus propios archivos; una sesión del panel sin clave puede leer toda la
instancia; el acceso a un archivo sin propietario (carga anónima o realizada desde una sesión del panel) se deniega a cualquier
cliente sin sesión. GET /v1/files rechaza a un cliente anónimo —y a una clave proporcionada que no
se pueda resolver— con 401, incluso cuando REQUIRE_API_KEY=false, en lugar de listar los archivos de
todos los tenants (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).
API de lotes
Procesamiento por lotes compatible con OpenAI.
| Método | Ruta | Descripción |
|---|---|---|
| POST | /v1/batches |
Crear un lote — cuerpo validado mediante v1BatchCreateSchema (input_file_id, endpoint, completion_window) |
| GET | /v1/batches |
Listar lotes |
| GET | /v1/batches/[id] |
Obtener el estado del lote + request_counts |
| DELETE | /v1/batches/[id] |
Eliminar un lote finalizado/fallido |
| POST | /v1/batches/[id]/cancel |
Cancelar un lote en curso |
Autenticación: Clave de API Bearer. Los lotes se limitan por clave de API conforme a la misma regla de tres casos que
los archivos: solo la clave propietaria, la sesión del panel para toda la instancia y los registros sin propietario denegados a cualquier
cliente sin sesión (obtención, eliminación, cancelación y comprobación de input_file_id al crear).
GET /v1/batches rechaza a un cliente anónimo con 401, incluso cuando REQUIRE_API_KEY=false.
API de búsqueda
Abstracción de proveedores web/de búsqueda (Tavily, Brave, Exa, Serper, etc.).
| Método | Ruta | Descripción |
|---|---|---|
| GET | /v1/search |
Enumera los proveedores de búsqueda configurados y sus capacidades |
| POST | /v1/search |
Ejecuta una consulta de búsqueda; el cuerpo se valida mediante v1SearchSchema y admite caché/coalescencia |
| GET | /v1/search/analytics |
Estadísticas de aciertos/latencia/caché por proveedor |
Autenticación: clave de API Bearer (extractApiKey + isValidApiKey). La política de búsqueda se aplica mediante enforceApiKeyPolicy.
provider_options de Exa y Tavily
Exa y Tavily leen los campos específicos del proveedor desde un contenedor con espacio de nombres:
provider_options.exa (o provider_options["exa-search"]) y provider_options.tavily
(o provider_options["tavily-search"]). Solo se reenvían las claves indicadas a continuación. Cada una se
comprueba con su propio esquema de Zod en open-sse/handlers/search/providerOptionsPassthrough.ts,
y cualquier clave con un tipo incorrecto se descarta. Se ignora cualquier otra clave, incluidas las de autenticación, la URL base,
stream y outputSchema. Las claves planas utilizadas por otros proveedores (cx, depth, ...) funcionan
como antes.
| Proveedor | Campos de nivel superior | Anidados |
|---|---|---|
| Exa | type, category, userLocation, moderation, additionalQueries, objective, systemPrompt, compliance (primitivos planos), startPublishedDate, endPublishedDate |
contents.{text, highlights, summary, extras, subpages, subpageTarget, livecrawlTimeout, maxAgeHours} combinado sobre el valor predeterminado { 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 |
— |
Los campos genéricos siempre tienen prioridad: query, max_results, filters (dominios), country y el
tema derivado de search_type. En Exa, search_type: "news" conserva category: "news".
Tavily también acepta search_type: "finance" (topic: "finance").
El campo genérico time_range ahora llega a ambos proveedores: Exa recibe startPublishedDate (marca de tiempo
ISO) y Tavily recibe start_date (YYYY-MM-DD). Una fecha explícita en provider_options
reemplaza la fecha asignada.
Los resultados de Exa conservan id, highlight_scores, summary, subpages, entities y extras en
provider_raw. Los resultados de Tavily conservan images y favicon.
La contabilidad de costes sigue utilizando el registro plano costPerQuery. Tavily cobra
más créditos por llamada cuando search_depth: "advanced", y esa diferencia no se refleja en
usage.search_cost_usd.
API de obtención web
Extrae contenido de una URL mediante un proveedor de obtención web configurado (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract).
Parallel Extract (parallel-search, misma clave de API que Parallel Search) devuelve únicamente
Markdown — cualquier otro format da como resultado un 400 — y limita el contenido a 100 000 caracteres. Cuando
la propia página de destino no se puede extraer, el servicio ascendente lo informa dentro de una respuesta HTTP 200;
OmniRoute lo expone como un 422 con un mensaje fijo.
| Método | Ruta | Descripción |
|---|---|---|
| POST | /v1/web/fetch |
Obtiene/extrae una URL — cuerpo validado por v1WebFetchSchema |
Autenticación: clave de API Bearer (extractApiKey + isValidApiKey). La política se aplica mediante enforceApiKeyPolicy.
Alternativa con reconocimiento de cuota (#8297): cuando no se proporciona un provider explícito, el grupo
(firecrawl → jina-reader → tavily-search → tinyfish → nimble-search →
parallel-search) se
recorre en un orden de
prioridad fijo (llenado del primero) — un proveedor configurado pero con límite de solicitudes se omite
en lugar de interrumpir la solicitud, y un fallo reintentable o de cuota del servicio ascendente
(HTTP 429 siempre; 402/403 para los niveles gratuitos con límites de cuota de Firecrawl/Tavily/TinyFish —
no para Jina Reader, y nunca para una solicitud incorrecta simple con código 400) pasa al
siguiente proveedor con credenciales que aún no se haya intentado durante la solicitud. Cuando se han agotado todos los proveedores del
grupo, el endpoint devuelve un único 429 (con un encabezado Retry-After)
en lugar del anterior 400 genérico. Cuando se solicita un provider
explícito, no hay una alternativa silenciosa — un proveedor explícito con límite de solicitudes o que falle
expone su propio error (429 si tiene un límite de solicitudes; de lo contrario, el estado del servicio
ascendente).
Streaming mediante WebSocket
GET /v1/ws?handshake=1
Valida un protocolo de enlace de actualización a WebSocket y devuelve los mensajes de ejemplo del protocolo de comunicación (request, cancel). Los frames de WS reales los gestiona el servidor WS incluido fuera de la tabla de rutas de Next.js.
Autenticación: clave de API Bearer durante el protocolo de enlace.
API Responses mediante WebSocket (solo codex)
# Mismo host:puerto que la API HTTP (20128 de forma predeterminada); actualice la conexión:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (o bien: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
# El primer frame DEBE ser response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
Un proxy de la API Responses mediante WebSocket está conectado exclusivamente a codex (backend de ChatGPT). Escucha en el mismo puerto que la API/el panel en las rutas /v1/responses,
/responses y /api/v1/responses. En el primer frame response.create,
autentica y prepara mediante el puente interno codex-responses-ws, selecciona una
conexión OAuth de codex y crea un túnel hacia wss://chatgpt.com/backend-api/codex/responses
mediante el transporte wreq-js. Los modelos que no son codex se rechazan (codex_ws_provider_required).
Para el enrutamiento por cuota compartida, use model: "qtSd/<group>/codex/<model>". Implementado en
app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.
Autenticación: clave de API Bearer durante el protocolo de enlace. El servidor HTTP incluido (server-ws.mjs)
debe ser el punto de entrada activo (lo es de forma predeterminada cuando existe app/server-ws.mjs).
ID del modelo: use el ID de ChatGPT sin prefijo (sin el prefijo codex/)
La CLI de Codex de OpenAI valida el nombre del modelo en el cliente cuando
supports_websockets = true y rechaza los ID con prefijo de proveedor, como
codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Envíe el ID sin prefijo (por ejemplo, gpt-5.5). El puente de OmniRoute es
exclusivo para codex, por lo que vuelve a resolver un ID sin prefijo como un modelo de codex
(resolveCodexWsModelInfo) antes de crear el túnel ascendente, aunque un
gpt-5.5 sin prefijo se enrutaría de otro modo a otro proveedor mediante HTTP.
Configuración de la CLI de Codex de OpenAI
Dirija la CLI de Codex hacia OmniRoute añadiendo un proveedor personalizado con compatibilidad con WebSocket
a ~/.codex/config.toml (use un CODEX_HOME independiente para evitar modificar
una configuración existente):
model = "gpt-5.5" # ID sin prefijo; NO "codex/gpt-5.5"
model_provider = "omniroute"
[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1" # sin barra diagonal final; la URL de WS se deriva (use https/wss en producción)
wire_api = "responses" # único valor compatible desde febrero de 2026
supports_websockets = true # habilita el transporte de Responses mediante WS
env_key = "OMNIROUTE_API_KEY" # contiene la clave de API de OmniRoute (Bearer)
export OMNIROUTE_API_KEY=sk-... # una clave de API de OmniRoute (cualquier clave si REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
La CLI actualiza base_url + /responses a un WebSocket y OmniRoute crea un túnel
hacia la conexión OAuth de codex seleccionada. Validado de extremo a extremo con el servidor
local: ChatGPT devuelve codex.rate_limits + response.created y transmite la
finalización.
Cuotas e informes de incidencias
| Método | Ruta | Descripción |
|---|---|---|
| GET | /v1/quotas/check |
Valida previamente la cuota de un provider + accountId antes de emitir una clave registrada |
| POST | /v1/issues/report |
Informa a GitHub de un fallo de cuota/emisión de clave (requiere GITHUB_ISSUES_REPO + token) |
Autenticación: clave de API Bearer (isAuthenticated).
Uso de autoservicio (/api/usage/om-usage)
Cualquier clave de API puede consultar su propio uso y sus cuotas, sin autenticación de administración. Este es el endpoint que utiliza un cliente (CLI, el panel de OmniCopilot) para mostrar al titular de una clave su gasto.
# Formato de texto (el contrato histórico: texto sin formato para una terminal)
curl -H "Authorization: Bearer <your-api-key>" \
http://localhost:20128/api/usage/om-usage
# Formato estructurado: el que consume una interfaz de usuario
curl -H "Authorization: Bearer <your-api-key>" \
"http://localhost:20128/api/usage/om-usage?format=json"
La clave debe tener allowUsageCommand habilitado (está deshabilitado de forma predeterminada; el administrador de claves de API del panel
lo activa individualmente para cada clave). Sin esta opción, el endpoint responde con 403.
?format=json devuelve una estructura discriminada para que quien realiza la llamada nunca lea un campo de datos de una
respuesta de rechazo. En caso de éxito:
{
"allowed": true,
// presente solo cuando la clave ha habilitado límites de uso por clave (USD diarios/semanales):
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// instantánea de cuota del proveedor seleccionado, o null cuando todavía no hay nada en caché:
"provider": {
"connectionId": "…",
"provider": "claude",
"plan": "…",
"quotas": {/* … */},
},
// instantánea de cada conexión, para que una interfaz pueda mostrar varios proveedores en paralelo:
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
En caso de rechazo (401 por clave incorrecta / 403 por falta de permiso), la misma ruta devuelve
{ "allowed": false, "error": { "message": "…" } }: un campo personal/provider presente pero vacío
(clave autorizada, pero todavía no se ha obtenido información) es un estado distinto de un rechazo, y solo el formato JSON
permite distinguirlos.
Autenticación: la propia clave de API Bearer de quien realiza la llamada, validada con isValidApiKey; esta no es la
interfaz de administración (/api/keys/…), que permanece protegida mediante requireManagementAuth.
Porcentajes de cuota sin procesar frente a porcentajes ajustados por el umbral de corte
Al consumir /api/usage/om-usage, se debe tener en cuenta la diferencia entre los
porcentajes presentados por la salida de texto sin formato y la salida JSON estructurada:
| Aspecto | Formato de texto sin formato (/api/usage/om-usage / @@om-usage) |
Formato JSON (?format=json) |
|---|---|---|
| Campo de salida | NN% left (p. ej., 20% left) |
provider.quotas / providers[].quotas |
| Medición | Asignación utilizable ajustada por el umbral de corte: capacidad restante por encima del umbral | Cuota original del proveedor: medición sin ajustar proporcionada por este |
| Escalado del corte | Escalado mediante effectiveRemainingPercent() para que la reserva protegida indique 0% left |
Ninguno (valores originales de la instantánea notificados por el proveedor) |
| Datos del umbral | Incorporados en el porcentaje mostrado | Almacenados en quotaWindowThresholds por conexión (o valores predeterminados del servidor) |
| Consumidor principal | CLI interactivas, solicitudes de terminal, operadores humanos | Integraciones programáticas, paneles, análisis, sistemas de seguimiento de facturación |
Fórmula de ajuste del umbral de corte
OmniRoute admite umbrales de corte de cuota proactivos para evitar agotar la capacidad del proveedor (configurados mediante
quotaWindowThresholds de la conexión, valores predeterminados del proveedor o ajustes globales de resiliencia). Cuando hay un umbral de corte
(p. ej., cutoff = 25%) activo en una ventana de cuota, el generador de texto calcula la asignación restante de la siguiente manera:
- Si
remaining <= cutoff: devuelve0%. - Si
remaining > cutoff: devuelve((remaining - cutoff) / (100 - cutoff)) * 100.
La salida de texto con formato redondea este valor al entero más cercano (Math.round(...)).
Ejemplo ilustrativo
Considere una ventana de proveedor con un 60% de uso original (por tanto, un 40% de cuota original restante) y un umbral de corte configurado del 25% de cuota restante:
| Representación | Cálculo | Restante | Uso implícito |
|---|---|---|---|
JSON original (?format=json) |
Instantánea del proveedor (quotas[window]) |
40% | 60% |
Formato de texto (NN% left) |
((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100 |
20% | 80% (si se calcula 100 - remaining) |
- Por qué el texto muestra un 20% restante: Del 40% de cuota física restante en la cuenta, el 25% está reservado por la
política de corte. Quien realiza la llamada solo dispone de un 15% de los 75 puntos porcentuales de margen utilizable antes de que el router deje de
dirigir solicitudes a esta conexión. El escalado garantiza que la conexión indique agotamiento (
0% left) exactamente cuando deje de utilizarse para el enrutamiento. - Por qué JSON conserva los valores originales: La carga útil JSON devuelve la instantánea exacta del proveedor (
UsageSnapshot) para que las herramientas externas tengan acceso al uso real proporcionado por el proveedor y a losquotaWindowThresholdsde cada conexión sin un escalado con pérdida aplicado por el servidor.
Guía de migración para consumidores
Si una integración externa (como un complemento de editor o una extensión de agente) analizaba anteriormente el endpoint de texto
(NN% left) y calculaba el porcentaje utilizado como 100 - NN, migrar a ?format=json implica lo siguiente:
- La lectura de los valores JSON originales reflejará el consumo real del proveedor (un 60% utilizado en el ejemplo anterior).
- Si la integración desea conservar la semántica de asignación utilizable del endpoint de texto, puede evaluar
la fórmula de capacidad restante efectiva en el lado del cliente utilizando
quotaWindowThresholdspara las anulaciones específicas de cada conexión.
Caché semántica
# Obtener estadísticas de la caché
GET /api/cache/stats
# Borrar todas las cachés
DELETE /api/cache/stats
Ejemplo de respuesta:
{
"semanticCache": {
"memorySize": 42,
"memoryMaxSize": 500,
"dbSize": 128,
"hitRate": 0.65
},
"idempotency": {
"activeKeys": 3,
"windowMs": 5000
}
}
Impacto en la latencia
Un acierto de la caché semántica sirve la respuesta desde la caché sin realizar una llamada
al proveedor, por lo que el valor informado en X-OmniRoute-Response-Latency es cercano a cero
(independientemente de la latencia original del proveedor). Los clientes sensibles a la latencia
(pruebas de rendimiento, supervisión de p50/p99) deben comprobar el encabezado de respuesta
X-OmniRoute-Cache-Latency:
| Valor | Significado |
|---|---|
synthetic |
Respuesta servida desde la caché; la latencia no es tiempo real del proveedor |
| (ausente) | Respuesta procedente de una llamada real al proveedor |
Omisión de la caché por clave
Las claves de API pueden excluirse de las lecturas de la caché semántica mediante cacheDefaultMode:
| Valor | Comportamiento |
|---|---|
legacy |
Comportamiento normal de la caché (predeterminado) |
bypass |
Omite por completo la consulta de la caché; siempre llama al proveedor |
Se configura al crear la clave (POST /api/keys) o al actualizarla (PATCH /api/keys/[id]):
{ "cacheDefaultMode": "bypass" }
Omisión por solicitud
Cualquier solicitud puede omitir la caché independientemente de la configuración de la clave:
X-OmniRoute-No-Cache: true
Panel de control y gestión
Las rutas de gestión (/api/*, excepto las rutas públicas de autenticación/inicio de sesión) no admiten la autorización mediante claves de API de inferencia comunes. Familias de credenciales, ámbitos y ejemplos con curl:
Autenticación de gestión.
Autenticación
| Endpoint | Método | Descripción |
|---|---|---|
/api/auth/login |
POST | Iniciar sesión |
/api/auth/logout |
POST | Cerrar sesión |
/api/settings/require-login |
GET/POST | Estado del inicio de sesión (GET, público). POST establece la contraseña o activa/desactiva el inicio de sesión: solo para operadores una vez que existe una contraseña (sesión del panel, CLI local o inicio de sesión deshabilitado; las claves de API y los tokens oma_ reciben 403); una sesión del panel envía currentPassword para reemplazar la contraseña |
Gestión de proveedores
| Endpoint | Método | Descripción |
|---|---|---|
/api/providers |
GET/POST | Enumerar/crear proveedores |
/api/providers/[id] |
GET/PUT/DELETE | Gestionar un proveedor |
/api/providers/[id]/test |
POST | Probar la conexión del proveedor |
/api/providers/[id]/models |
GET | Enumerar los modelos del proveedor |
/api/providers/validate |
POST | Validar la configuración del proveedor |
/api/providers/bulk |
POST | Añadir claves de API en bloque para UN proveedor |
/api/providers/import |
POST | Importar una LISTA heterogénea de proveedores desde un archivo CSV/JSON analizado (#6836); resultados de errores parciales por fila |
/api/provider-nodes* |
Varios | Gestión de nodos de proveedores |
/api/provider-models |
GET/POST/PUT/PATCH/DELETE | Modelos personalizados y anulaciones por modelo (añadir, actualizar, ocultar/mostrar, eliminar) |
/api/provider-models/validate-and-add |
POST | Validación de conexión estricta, opcional y autenticada para gestión, y registro atómico de modelos personalizados; consulte Validación de modelos |
Para los modelos sincronizados/importados, PUT /api/provider-models acepta provider, modelId y
maxOutputTokenOverride: un entero positivo establece el límite manual de tokens de salida, y null
lo elimina para restaurar el valor predeterminado. GET /api/provider-models?provider=<provider> devuelve estos
valores en modelOutputOverrides, incluidos los modelos sin una fila de modelo personalizado. La anulación
utiliza la capacidad max_output_tokens del entorno de ejecución y se conserva tras volver a sincronizar el modelo. La página
del proveedor compatible con OpenAI ofrece los mismos controles de edición/eliminación e identifica los modelos con compatibilidad explícita con visión.
Los nodos personalizados de Chat Completions adaptan al backend de nivel superior las exclusiones explícitas del razonamiento. Una
prueba de conexión correcta selecciona automáticamente los controles de plantilla de chat para cada ID exacto de modelo
cuya entrada /models demuestre un valor owned_by reconocido: vllm, sglang o llamacpp.
Los wrappers transparentes compatibles con OpenAI pueden conservar la entrada original del modelo dentro de un objeto
openai anidado; la detección examina hasta tres de estos envoltorios. Los modelos cuya propiedad esté ausente, sea desconocida o
presente conflictos mantienen el comportamiento habitual de OpenAI. La detección reutiliza la solicitud de catálogo existente,
no genera tokens de finalización y se invalida cuando cambia el endpoint de conexión.
Para fijar el comportamiento de un backend que no expone esos metadatos, utilice la API existente de actualización parcial del proveedor:
{
"providerSpecificData": {
"reasoningControl": "chat-template"
}
}
Envíe ese cuerpo con PUT /api/providers/<connection-id>. En esa conexión, un esfuerzo de
razonamiento explícito de none se envía como chat_template_kwargs.thinking=false y
chat_template_kwargs.enable_thinking=false. Los valores explícitos de la plantilla nativa siguen teniendo prioridad,
a menos que una regla de razonamiento del servidor fuerce un esfuerzo. La configuración solo se aplica cuando una conexión
personalizada compatible con OpenAI envía un cuerpo de Chat Completions; las solicitudes de Responses y los proveedores
ordinarios conservan la estructura nativa de sus solicitudes. Establezca reasoningControl en openai para forzar el paso
directo del reasoning_effort ordinario de OpenAI, u omítalo/establézcalo en null para usar la detección automática.
Las solicitudes del clasificador del modo automático de Claude Code desactivan de forma predeterminada el pensamiento nativo cuando no contienen controles de razonamiento explícitos. La detección utiliza el marcador de sistema del clasificador en solicitudes con formato de Claude, no los nombres de modelo ni los límites de finalización. Los controles explícitos del cuerpo, los encabezados de esfuerzo/pensamiento compatibles, las reglas de enrutamiento y el esfuerzo resuelto del modelo conservan su prioridad actual. Ambas etapas del clasificador conservan sus prompts, límites de finalización, secuencias de detención y veredictos reales de permisos del servicio ascendente; la segunda etapa aún puede generar el razonamiento visible solicitado como texto ordinario.
Flujos de OAuth
| Endpoint | Método | Descripción |
|---|---|---|
/api/oauth/[provider]/[action] |
Varios | OAuth específico del proveedor |
Enrutamiento y configuración
| Endpoint | Método | Descripción |
|---|---|---|
/api/models/alias |
GET/POST | Alias de modelos |
/api/models/catalog |
GET | Todos los modelos por proveedor + tipo |
/api/combos* |
Varios | Gestión de combinaciones |
/api/keys* |
Varios | Gestión de claves de API |
/api/pricing |
GET | Precios de los modelos |
Uso y análisis
| Endpoint | Método | Descripción |
|---|---|---|
/api/usage/history |
GET | Historial de uso |
/api/usage/logs |
GET | Registros de uso |
/api/usage/request-logs |
GET | Registros a nivel de solicitud |
/api/usage/[connectionId] |
GET | Uso por conexión |
/api/usage/token-limits |
GET/POST/DELETE | Presupuestos de límites de tokens por clave de API |
/api/usage/model-latency-stats |
GET | Agregado continuo de latencia por proveedor/modelo (promedio/p50/p95/p99, tasa de éxito); filtros: windowHours/minSamples/maxRows/provider/model (#6873) |
/api/usage/cache-health |
GET | Resumen del estado de la caché de prompts sobre call_logs: proporción de escritura/lectura, distribución p50/p90/p99 del tamaño de escritura, concentración de escrituras intensivas, desglose por modelo y un veredicto healthy/degraded/thrash/no-data; parámetros de consulta range (1h|24h|7d|30d, valor predeterminado 24h) y model opcional (#8827) |
Permisos de claves de API
PATCH /api/keys/{id} actualiza los permisos de una clave existente. Como todas las rutas /api/keys*, requiere autorización de administración (consulte Autenticación de administración), no una clave de inferencia. Envíe únicamente los campos que desee cambiar; una solicitud que no incluya ninguno de ellos se rechaza con No valid fields to update. Los campos aceptados están definidos por updateKeyPermissionsSchema en src/shared/validation/schemas/keys.ts.
| Campo | Tipo | Notas |
|---|---|---|
name |
cadena, entre 1 y 200 caracteres | |
isActive |
booleano | |
isBanned |
booleano | |
expiresAt |
fecha y hora ISO 8601 o null |
null elimina la fecha de expiración |
modelAccessMode |
all | restricted |
allowedModels debe estar vacío cuando el modo es all |
allowedModels, blockedModels |
matriz de cadenas, hasta 1000 | |
allowedCombos |
matriz de cadenas, hasta 500 | Controla qué combos puede invocar la clave; los modelos directos se rigen por modelAccessMode / allowedModels |
connectionAccessMode |
all | restricted |
allowedConnections no debe estar vacío con restricted y debe estar vacío con all |
allowedConnections |
matriz de UUID, hasta 100 | |
allowAutoCombos |
booleano | false rechaza solicitudes de modelos auto/* con esta clave; se permiten las claves que nunca lo hayan configurado |
catalogScope |
all | combos | models |
Lo que GET /v1/models enumera para esta clave (solo combos, solo modelos o ambos); no cambia lo que puede invocar |
forcedModel |
cadena de hasta 300 caracteres o null |
Enruta las solicitudes de chat a este modelo/combo, con prioridad sobre X-Route-Model y body.model; los límites de la clave siguen aplicándose |
noLog, autoResolve |
booleano | |
throttleDelayMs |
entero, 0-300000 | |
maxSessions |
entero, 0-10000 | |
rateLimits |
matriz de { limit, window } (enteros positivos, hasta 50) o null |
null elimina los límites |
accessSchedule |
objeto de programación o null |
null elimina la programación |
scopes |
matriz de cadenas, hasta 32 | |
allowedEndpoints |
matriz de cadenas, hasta 20 | |
streamDefaultMode |
legacy | json |
|
cacheDefaultMode |
legacy | bypass |
Consulte Omisión de caché por clave |
compressionEnabled |
booleano | |
codexServiceMode |
uno de los modos de servicio de Codex | |
disableNonPublicModels |
boolean | |
allowUsageCommand |
boolean | |
usageLimitEnabled |
boolean | |
dailyUsageLimitUsd, weeklyUsageLimitUsd |
number >= 0 o null |
|
chaosModeEnabled |
boolean |
curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \
-H "Authorization: Bearer <credencial-de-administración>" \
-H "Content-Type: application/json" \
-d '{ "allowAutoCombos": false, "catalogScope": "combos" }'
Configuración
| Endpoint | Método | Descripción |
|---|---|---|
/api/settings |
GET/PUT/PATCH | Configuración general. Las claves de políticas de seguridad (requireLogin, newPassword, oidc*, corsOrigins, bruteForceProtection) requieren currentPassword y una credencial de operador; las claves de API y los tokens oma_ reciben 403; cada modificación requiere el alcance admin del token de acceso |
/api/settings/proxy |
GET/PUT | Configuración del proxy de red |
/api/settings/proxy/test |
POST | Probar la conexión del proxy |
/api/settings/ip-filter |
GET/PUT | Lista de direcciones IP permitidas/bloqueadas |
/api/settings/thinking-budget |
GET/PUT | Modo de reescritura de solicitudes de pensamiento/razonamiento (passthrough / auto-strip / custom / adaptive). Independiente de la compresión. Consulte THINKING_BUDGET.md. |
/api/settings/system-prompt |
GET/PUT | Prompt global del sistema |
/api/settings/compression |
GET/PUT | Configuración global de compresión |
/api/settings/purge-request-history |
POST | Borrar las filas del registro de solicitudes y los artefactos locales del registro de llamadas |
Contexto y compresión
| Endpoint | Método | Descripción |
|---|---|---|
/api/compression/preview |
POST | Previsualizar la compresión off/lite/standard/aggressive/ultra/RTK/stacked |
/api/compression/language-packs |
GET | Listar los paquetes de idioma de Caveman disponibles |
/api/compression/rules |
GET | Listar los metadatos de las reglas de Caveman |
/api/context/caveman/config |
GET/PUT | Alias de configuración específica de Caveman |
/api/context/rtk/config |
GET/PUT | Configuración específica de RTK, incluidos filtros personalizados y retención de la salida sin procesar |
/api/context/rtk/filters |
GET | Catálogo de filtros de RTK y diagnósticos de filtros personalizados |
/api/context/rtk/test |
POST | Ejecutar una previsualización/prueba de RTK con una carga útil de texto |
/api/context/rtk/raw-output/[id] |
GET | Leer la salida sin procesar anonimizada y retenida mediante el id del puntero |
/api/context/combos |
GET/POST | Listar/crear combinaciones de compresión |
/api/context/combos/[id] |
GET/PUT/DELETE | Ver/actualizar/eliminar los detalles de una combinación de compresión |
/api/context/combos/[id]/assignments |
GET/PUT | Asignar combinaciones de compresión a combinaciones de enrutamiento |
/api/context/analytics |
GET | Alias de análisis de compresión |
Monitorización
| Endpoint | Método | Descripción |
|---|---|---|
/api/sessions |
GET | Seguimiento de sesiones activas |
/api/rate-limits |
GET | Límites de frecuencia por cuenta |
/api/monitoring/health |
GET | Comprobación de estado y resumen de proveedores (catalogCount, configuredCount, activeCount, monitoredCount). La vista de administración incluye credentialHealth: valores escalares de la caché de sondeos, failedConnections cuando failed>0 y staleDbNonOkCount (test_status persistente de SQLite, no el indicador). Consulte MONITORING_GUIDE.md. |
/api/cache/stats |
GET/DELETE | Estadísticas de caché / vaciar |
/api/modality-bridge/stats |
GET | attempts en memoria, éxitos/bridged, fallos, aciertos de caché, totalLatencyMs, latencySamples, averageLatencyMs calculada según el número de muestras y hora del último uso (se restablece al reiniciar; autenticación de administración) |
/api/modality-bridge/video/runtime |
GET | Comprobación estricta del bucle invertido de confianza antes de la autenticación/sondeo de administración; disponibilidad y versiones saneadas de FFmpeg/ffprobe (no-store) |
/api/modality-bridge/video/extract |
POST | Intermediario interno autenticado de bytes mediante bucle invertido de confianza; entrada de 50 MiB, cola limitada/salida de 32 MiB, capacidad 503, desconexión 499, plazo agotado 504; no es una API pública de carga de archivos |
Copia de seguridad y exportación/importación
| Endpoint | Método | Descripción |
|---|---|---|
/api/db-backups |
GET | Lista las copias de seguridad disponibles |
/api/db-backups |
PUT | Crea una copia de seguridad manual |
/api/db-backups |
POST | Restaura desde una copia de seguridad específica |
/api/db-backups |
PATCH | Guarda la configuración de retención de copias de seguridad (solo operadores) |
/api/db-backups |
DELETE | Elimina las copias de seguridad almacenadas según la configuración de retención (solo operadores) |
/api/db-backups/export |
GET | Descarga la base de datos como archivo .sqlite |
/api/db-backups/import |
POST | Carga un archivo .sqlite para reemplazar la base de datos (?dryRun=true solo valida) |
/api/db-backups/exportAll |
GET | Descarga la copia de seguridad completa como archivo .tar.gz |
/api/db-backups/export, /api/db-backups/exportAll y /api/settings/export-json exponen
todas las credenciales almacenadas, por lo que requieren la sesión del panel o la CLI local (o que el inicio de sesión
esté deshabilitado). Las claves de API de cualquier ámbito y los tokens de acceso oma_ reciben un 403. Las restauraciones mantienen el mismo
límite: POST /api/db-backups/import (incluido dryRun=true), POST /api/db-backups (restauración
por id) y POST /api/settings/import-json reemplazan la base de datos activa o la configuración, por lo que una credencial
de máquina también recibe un 403; omniroute sync import envía la credencial de la CLI local. Lo mismo ocurre con
DELETE /api/db-backups (elimina copias de seguridad almacenadas) y PATCH /api/db-backups (configuración de retención:
los valores persistidos determinan la eliminación automática después de cada copia de seguridad). El listado (GET) y la creación
de una copia de seguridad manual (PUT) mantienen la autenticación de administración habitual.
Sincronización en la nube
| Endpoint | Método | Descripción |
|---|---|---|
/api/sync/cloud |
Varios | Operaciones de sincronización en la nube |
/api/sync/initialize |
POST | Inicializa la sincronización |
/api/cloud/* |
Varios | Administración de la nube |
Túneles
| Endpoint | Método | Descripción |
|---|---|---|
/api/tunnels/cloudflared |
GET | Consulta el estado de instalación/ejecución de Cloudflare Quick Tunnel para el panel |
/api/tunnels/cloudflared |
POST | Habilita o deshabilita Cloudflare Quick Tunnel (action=enable/disable) |
/api/tunnels/ngrok |
GET | Consulta el estado de ejecución de ngrok Tunnel para el panel |
/api/tunnels/ngrok |
POST | Habilita o deshabilita ngrok Tunnel (action=enable/disable) |
Herramientas de CLI
| Endpoint | Método | Descripción |
|---|---|---|
/api/cli-tools/claude-settings |
GET | Estado de Claude CLI |
/api/cli-tools/codex-settings |
GET | Estado de Codex CLI |
/api/cli-tools/droid-settings |
GET | Estado de Droid CLI |
/api/cli-tools/openclaw-settings |
GET | Estado de OpenClaw CLI |
/api/cli-tools/runtime/[toolId] |
GET | Entorno de ejecución genérico de la CLI |
Las respuestas de la CLI incluyen: installed, runnable, command, commandPath, runtimeMode, reason.
Agentes ACP
| Endpoint | Método | Descripción |
|---|---|---|
/api/acp/agents |
GET | Lista todos los agentes detectados (integrados + personalizados) con su estado |
/api/acp/agents |
POST | Añade un agente personalizado o actualiza la caché de detección |
/api/acp/agents |
DELETE | Elimina un agente personalizado mediante el parámetro de consulta id |
La respuesta GET incluye agents[] (id, name, binary, version, installed, protocol, isCustom) y summary (total, installed, notFound, builtIn, custom).
Resiliencia y límites de velocidad
| Endpoint | Método | Descripción |
|---|---|---|
/api/resilience |
GET/PATCH | Obtiene/actualiza la cola de solicitudes, el tiempo de espera de conexión, el disyuntor del proveedor y la configuración de espera |
/api/resilience/reset |
POST | Restablece los disyuntores de circuito de los proveedores |
/api/resilience/model-cooldowns |
GET | Lista los bloqueos activos por (proveedor, conexión, modelo), ordenados por tiempo restante |
/api/resilience/model-cooldowns |
DELETE | Elimina un bloqueo de modelo — cuerpo {provider, model} o {all: true} para eliminarlo todo |
/api/rate-limits |
GET | Estado del límite de velocidad por cuenta |
/api/rate-limit |
GET | Configuración global del límite de velocidad |
Las cuatro rutas
/api/resilience/*requieren autenticación de administración (requireManagementAuth). Consulta Resiliencia (ampliada) para obtener un desglose completo del disyuntor del proveedor frente al tiempo de espera de conexión y al bloqueo del modelo.
Evaluaciones
| Endpoint | Método | Descripción |
|---|---|---|
/api/evals |
GET/POST | Lista conjuntos de evaluación / ejecuta una evaluación |
Políticas
| Endpoint | Método | Descripción |
|---|---|---|
/api/policies |
GET/POST/DELETE | Administra las políticas de enrutamiento |
Cumplimiento normativo
| Endpoint | Método | Descripción |
|---|---|---|
/api/compliance/audit-log |
GET | Registro de auditoría de cumplimiento (últimos N) |
v1beta (compatible con Gemini)
| Endpoint | Método | Descripción |
|---|---|---|
/v1beta/models |
GET | Lista los modelos en formato Gemini |
/v1beta/models/{...path} |
POST | Endpoint generateContent de Gemini |
Estos endpoints reproducen el formato de la API de Gemini para clientes que requieren compatibilidad nativa con el SDK de Gemini.
APIs internas/del sistema
| Endpoint | Método | Descripción |
|---|---|---|
/api/init |
GET | Comprobación de inicialización de la aplicación (usada en la primera ejecución) |
/api/tags |
GET | Etiquetas de modelos compatibles con Ollama (para clientes de Ollama) |
/api/restart |
POST | Inicia un reinicio controlado del servidor |
/api/shutdown |
POST | Inicia un apagado controlado del servidor |
/api/system/env/repair |
POST | Repara las variables de entorno del proveedor de OAuth |
/api/system/version |
GET | Versión actual/más reciente, estado de actualización y canal de versiones |
/api/system/version |
POST | Inicia una actualización adaptada al despliegue a la versión más reciente |
Nota: El sistema utiliza estos endpoints internamente o para ofrecer compatibilidad con clientes de Ollama. Normalmente, los usuarios finales no los invocan.
Reparación del entorno de OAuth (v3.6.1+)
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
Repara las variables de entorno de OAuth que falten o estén dañadas para un proveedor específico. Devuelve:
{
"success": true,
"repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
"backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}
Versión y canal de versiones
GET /api/system/version
Ruta de administración limitada a la interfaz de bucle invertido (con autenticación de administrador). Devuelve la versión en ejecución, la última versión publicada y el estado de actualización automática. releaseChannel y channels son campos adicionales (rama 3.8.54); channel conserva su significado: el modo de despliegue que utiliza el actualizador del panel (npm, source o 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— canal de npm de la compilación en ejecución:nightlypara versiones-nightly.*,nextpara otras versiones preliminares (-rc.*,-beta.*,-alpha.*),ltspara una versión estable de una edición principal anterior achannels.latesty, en los demás casos,latest. Sigue las mismas reglas quescripts/release/dist-tag.mjs, que selecciona la etiqueta de distribución de npm al publicar.channels— versión más reciente publicada de cada etiqueta de distribución, obtenida mediantenpm view omniroute dist-tags(con HTTP del registro como alternativa), almacenada en caché con el mismo TTL de 10 minutos quelatest.latestsiempre está presente (utiliza como alternativa el campolatesty, después,"unavailable");next,nightlyyltssolo aparecen cuando existe la etiqueta de distribución correspondiente. Una solicitud conCache-Control: no-cacheactualiza ambas consultas.
El modelo de canales (latest = v3 hasta la disponibilidad general de 4.0, next = rc, nightly = compilaciones de develop, lts = parches de v3 después de la disponibilidad general de 4.0) se describe en docs/ops/RELEASE_STRATEGY.md.
Transcripción de audio
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
Transcribe archivos de audio mediante cualquier proveedor de STT configurado. El primer segmento de la ruta selecciona el proveedor nativo (openai/…, deepgram/…). Las puertas de enlace que vuelven a exponer el modelo de otro proveedor utilizan un identificador cualificado (openrouter/deepgram/nova-3).
Solicitud:
curl -X POST http://localhost:20128/v1/audio/transcriptions \
-H "Authorization: Bearer your-api-key" \
-F "[email protected]" \
-F "model=openai/whisper-1"
Respuesta:
{
"text": "Hello, this is the transcribed audio content.",
"task": "transcribe",
"language": "en",
"duration": 12.5
}
Ejemplos de identificadores de modelos: openai/whisper-1 (requiere una clave de OpenAI), openrouter/deepgram/nova-3 (requiere una clave de OpenRouter), deepgram/nova-3 (requiere una clave nativa de Deepgram). Una solicitud simple a deepgram/nova-3 no utiliza OpenRouter.
Formatos compatibles: mp3, wav, m4a, flac, ogg, webm.
Compatibilidad con Ollama
Para clientes que utilizan el formato de API de Ollama:
# Endpoint de chat (formato de Ollama)
POST /v1/api/chat
# Listado de modelos (formato de Ollama)
GET /api/tags
Las solicitudes se traducen automáticamente entre los formatos de Ollama y los formatos internos.
Alias tokenizados de VS Code / sin encabezados
Utilice estos alias cuando una integración no pueda inyectar un encabezado Authorization y necesite que la clave de API esté integrada en la URL base.
# Alias del catálogo al estilo OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# Alias de chat al estilo OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Alias al estilo Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
Ejemplo:
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"}]}'
Notas:
- Los alias tokenizados reutilizan los mismos controladores que
/v1/*y/api/tags; las estructuras de las respuestas permanecen idénticas. - Utilice preferentemente
Authorization: Bearer ...siempre que el cliente admita encabezados personalizados. - Los tokens incluidos en las URL pueden aparecer en los registros del proxy inverso, el historial del navegador y la telemetría externa a OmniRoute. Trátelos como una opción de compatibilidad, no como el modo de autenticación predeterminado.
Telemetría
# Obtener el resumen de telemetría de latencia (p50/p95/p99 por proveedor)
GET /api/telemetry/summary
Respuesta:
{
"providers": {
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
}
}
Presupuesto
# Obtener el estado del presupuesto de todas las claves de API
GET /api/usage/budget
# Establecer o actualizar un presupuesto
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"
}
Notas sobre el esquema (
setBudgetSchema):apiKeyIdes obligatorio; al menos uno dedailyLimitUsd,weeklyLimitUsdomonthlyLimitUsddebe ser mayor que cero. Campos opcionales:warningThreshold(0–1),resetInterval(daily|weekly|monthly),resetTime(HH:MM). El formato heredado{keyId, limit, period}devuelve400 Bad Request.
Límites de tokens
Presupuestos de tokens por clave de API (distintos del Presupuesto basado en USD indicado anteriormente). Se aplican directamente en la ruta de la solicitud: cuando el uso de una clave durante la ventana actual alcanza su límite, las solicitudes se rechazan con 429 Too Many Requests. Los límites pueden restringirse a un model específico, a un provider o aplicarse de forma global a toda la clave; cuando varios límites coinciden con una solicitud, prevalece el más restrictivo.
# Enumerar los límites de tokens de una clave (incluye el uso actual de la ventana)
GET /api/usage/token-limits?apiKeyId=key-123
# Crear o actualizar un límite de tokens
POST /api/usage/token-limits
Content-Type: application/json
{
"apiKeyId": "key-123",
"scopeType": "model",
"scopeValue": "openai/gpt-4o",
"tokenLimit": 1000000,
"resetInterval": "monthly",
"enabled": true
}
# Eliminar un límite de tokens por id
DELETE /api/usage/token-limits?id=tl-abc
Notas del esquema (
setTokenLimitSchema):apiKeyIdyscopeType(model|provider|global) son obligatorios.scopeValuees obligatorio, salvo quescopeTypeseaglobal(por ejemplo, un id de modelo para el ámbitomodelo un id de proveedor para el ámbitoprovider).tokenLimitdebe ser un entero positivo (convertido desde una cadena). Opcionales:id(omítalo para crear, inclúyalo para actualizar),resetInterval(daily|weekly|monthly, valor predeterminadomonthly),resetTime(HH:MM),enabled(valor predeterminadotrue). Las respuestas deGETenriquecen cada límite contokensUsed,remaining,windowStart,periodStartAtynextResetAt. Este es un endpoint de administración (la autenticación se aplica de forma centralizada mediante la canalización de autorización).
Procesamiento de solicitudes
- El cliente envía una solicitud a
/v1/* - El controlador de rutas llama a
handleChat,handleEmbedding,handleAudioTranscriptionohandleImageGeneration - Se resuelve el modelo (proveedor/modelo directo o alias/combo)
- Se seleccionan las credenciales de la base de datos local aplicando el filtrado por disponibilidad de la cuenta
- Para el chat:
handleChatCorecomprueba la caché semántica/de firmas y resuelve la configuración de compresión del combo - La compresión proactiva se ejecuta antes de la traducción al formato del proveedor cuando está habilitada (
lite, Caveman, RTK o apilada) - El ejecutor del proveedor envía la solicitud al servicio ascendente
- La respuesta se vuelve a traducir al formato del cliente (chat) o se devuelve tal cual (embeddings/imágenes/audio)
- Se registran el uso, los análisis de compresión y los registros de solicitudes
- En caso de error, se aplica la alternativa de respaldo según las reglas del combo
Referencia completa de la arquitectura: ARCHITECTURE.md
Administración de combos
Los combos de enrutamiento de nivel superior (ya resumidos en /api/combos*) también pueden asignarse individualmente a partir de un patrón de id de modelo, lo que permite redirigir de forma transparente un id de modelo con estilo de OpenAI a un combo.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/model-combo-mappings |
Enumerar todas las asignaciones modelo→combo |
| POST | /api/model-combo-mappings |
Crear una asignación — cuerpo: {pattern, comboId, priority?, enabled?, description?} |
| GET | /api/model-combo-mappings/[id] |
Recuperar una asignación individual |
| PUT | /api/model-combo-mappings/[id] |
Actualizar los campos de una asignación existente |
| DELETE | /api/model-combo-mappings/[id] |
Eliminar una asignación |
Autenticación: sesión/clave de API de administración (requireManagementAuth).
Webhooks
Suscripciones a webhooks salientes para eventos de OmniRoute (finalización de solicitudes, agotamiento de cuotas, rotación de claves, etc.).
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/webhooks |
Enumera los webhooks (los secretos se ocultan como <prefix>...) |
| POST | /api/webhooks |
Crea un webhook — cuerpo: {url, events?: ["*"], secret?, description?} |
| GET | /api/webhooks/[id] |
Recupera un webhook |
| PUT | /api/webhooks/[id] |
Actualiza url/events/secret/description |
| DELETE | /api/webhooks/[id] |
Elimina un webhook |
| POST | /api/webhooks/[id]/test |
Envía una carga útil de prueba a la URL del webhook y devuelve el estado de la entrega |
Autenticación: sesión de administración/clave de API (requireManagementAuth).
Claves registradas (gestión automática)
Utilizado por el subsistema de gestión automática de claves para emitir y rotar claves de API con un proveedor o una cuenta subyacente, con cuotas diarias y por hora.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/v1/registered-keys |
Enumera las claves registradas (solo el prefijo enmascarado) |
| POST | /api/v1/registered-keys |
Emite una nueva clave registrada — cuerpo: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Devuelve la clave sin enmascarar una sola vez. Devuelve 429 si se rechaza por cuota. |
| GET | /api/v1/registered-keys/[id] |
Recupera los metadatos de una clave registrada (sin el material sin enmascarar) |
| DELETE | /api/v1/registered-keys/[id] |
Revoca una clave registrada |
| POST | /api/v1/registered-keys/[id]/revoke |
Endpoint de revocación explícita (tiene el mismo efecto que DELETE) |
Autenticación: sesión de gestión/clave de API (requireManagementAuth) — la misma protección que /api/keys: una sesión del panel, el token de la CLI local o una clave de API con alcance manage/admin; las claves de API exclusivas para inferencia reciben 403. Consulta también /v1/quotas/check y /v1/issues/report.
Protocolo de agentes
Tareas de agentes en la nube (Claude Code, Codex Cloud, OpenHands, etc.) ejecutadas de forma remota en nombre de los usuarios de OmniRoute.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/v1/agents/tasks |
Enumera las tareas — admite opcionalmente ?provider=, ?status=, ?limit= (1–500, valor predeterminado: 50) |
| POST | /api/v1/agents/tasks |
Crea una tarea — cuerpo validado mediante CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Devuelve 201 con el contenedor de la tarea |
| DELETE | /api/v1/agents/tasks?id=... |
Elimina una tarea |
| GET | /api/v1/agents/tasks/[id] |
Lee una tarea — actualiza de forma síncrona el estado desde el agente en la nube de origen cuando se ha establecido un external_id |
| POST | /api/v1/agents/tasks/[id] |
Acción discriminada: {action: "approve"}, {action: "message", message} o {action: "cancel"} |
| DELETE | /api/v1/agents/tasks/[id] |
Elimina una tarea específica por id |
Autenticación: se requiere autenticación de gestión en todos los métodos (
requireCloudAgentManagementAuth). Antes de v3.8.0, estos no requerían autenticación; consulte el commit588a0333para conocer el cambio incompatible.
# Crear una tarea de Claude Code en la nube
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":"..."}}'
Proxies de gestión
Proxies HTTP(S)/SOCKS salientes que se pueden asignar a proveedores, cuentas o globalmente.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/v1/management/proxies |
Enumera los proxies (con ?id= devuelve uno; con ?id=&where_used=1 devuelve el grafo de asignaciones) |
| POST | /api/v1/management/proxies |
Crea un proxy — cuerpo validado mediante createProxyRegistrySchema |
| PATCH | /api/v1/management/proxies |
Actualiza un proxy — cuerpo validado mediante updateProxyRegistrySchema (requiere id) |
| DELETE | /api/v1/management/proxies?id=...&force=1 |
Elimina un proxy (use force=1 para desvincular las asignaciones) |
| GET | /api/v1/management/proxies/assignments |
Enumera las asignaciones — se puede filtrar por proxy_id, scope, scope_id; pase resolve_connection_id=<id> para resolver el proxy activo de una conexión |
| PUT | /api/v1/management/proxies/assignments |
Asigna — cuerpo validado mediante proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Limpia la caché del despachador |
| PUT | /api/v1/management/proxies/bulk-assign |
Asigna en bloque — cuerpo validado mediante bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?}) |
| GET | /api/v1/management/proxies/health?hours=24 |
Agrega el estado de los proxies (recuentos de éxitos/fallos y latencia) durante un intervalo |
Autenticación: sesión de gestión/clave de API en cada ruta (requireManagementAuth).
Los endpoints
POST /api/v1/management/proxies/[id]/assignmentsyPOST /api/v1/management/proxies/[id]/healthde la descripción de la tarea se atienden mediante las rutas planas/assignmentsy/healthque se muestran arriba; no hay subrutas por id en el código base.
Resiliencia (ampliada)
OmniRoute ofrece tres mecanismos independientes para fallos temporales; los siguientes endpoints de administración permiten a los operadores consultarlos y sobrescribirlos:
| Ámbito | Almacenamiento del estado | Consulta | Restablecimiento / limpieza |
|---|---|---|---|
| Disyuntor de proveedor | domain_circuit_breakers + memoria interna |
/api/monitoring/health |
POST /api/resilience/reset |
| Pausa de conexión | rateLimitedUntil en conexiones de proveedor |
/api/rate-limits, /api/providers/[id] |
(se reactiva de forma diferida; se limpia mediante PUT del proveedor) |
| Bloqueo de modelo | Registro de disponibilidad de modelos en memoria | GET /api/resilience/model-cooldowns |
DELETE /api/resilience/model-cooldowns |
PATCH /api/resilience acepta sobrescrituras del disyuntor de proveedor en providerBreaker.oauth y providerBreaker.apikey. Cada perfil admite degradationThreshold, failureThreshold y resetTimeoutMs; los mismos campos están disponibles en Panel de control → Configuración → Resiliencia.
# Limpiar el bloqueo de un único modelo
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"}'
# Eliminar todos los bloqueos
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
Referencia conceptual completa y valores predeterminados del disyuntor: consulte CLAUDE.md → "Estado de ejecución de la resiliencia".
Habilidades
Marco de habilidades para ampliar OmniRoute con controladores ejecutables personalizados, además de integraciones con marketplaces.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/skills |
Enumera las habilidades instaladas; admite filtros mediante ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local y paginación |
| GET | /api/skills/[id] |
Recupera una habilidad |
| PUT | /api/skills/[id] |
Actualiza una habilidad (nombre, descripción, modo, esquema, controlador, etiquetas) |
| DELETE | /api/skills/[id] |
Desinstala una habilidad |
| POST | /api/skills/install |
Instala una habilidad desde un manifiesto sin procesar — cuerpo: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?} |
| GET | /api/skills/executions |
Enumera las ejecuciones recientes de habilidades (registro de auditoría con entradas, salidas y duración) |
| GET | /api/skills/marketplace?q=... |
Busca u obtiene la lista de elementos populares del marketplace SkillsMP (requiere la configuración skillsmpApiKey) |
| POST | /api/skills/marketplace/install |
Instala una habilidad por id desde SkillsMP |
| GET | /api/skills/skillssh?q=&limit= |
Busca en el registro skills.sh |
| POST | /api/skills/skillssh/install |
Instala una habilidad por id desde skills.sh |
Autenticación: sesión de administración/clave de API. Las rutas de búsqueda del marketplace aceptan autenticación de administración o una clave de API Bearer (isAuthenticated).
Memoria
Almacén persistente de memoria conversacional/factual, limitado por clave de API / sesión.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/memory |
Enumera memorias — ?apiKeyId=, ?type=, ?sessionId=, ?q=, con paginación mediante offset/limit o page/limit |
| POST | /api/memory |
Crea una memoria — cuerpo validado por Zod: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?} |
| GET | /api/memory/[id] |
Recupera una memoria |
| DELETE | /api/memory/[id] |
Elimina una memoria |
| GET | /api/memory/health |
Estado del subsistema de memoria (conectividad de la BD, backend de embeddings, estado del índice vectorial) |
Autenticación: sesión de administración/clave de API (requireManagementAuth). Enumeración type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (consulta MemoryType en src/lib/memory/types.ts).
Servidor MCP
OmniRoute incluye un servidor Model Context Protocol integrado con 3 transportes (stdio, SSE, streamable-http) y herramientas con ámbitos definidos. Los endpoints del panel que aparecen a continuación leen datos de estado/auditoría y actúan como proxy de los transportes HTTP.
| Método | Ruta | Descripción |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | /api/mcp/status | Señal de actividad, transporte, estado en línea, última llamada, herramientas principales, tasa de éxito de las últimas 24 h |
| GET | /api/mcp/tools | Lista de herramientas MCP con name, description, scopes, phase, auditLevel, sourceEndpoints |
| GET | /api/mcp/sse | Abre un flujo SSE para el transporte SSE (devuelve 503 si MCP está deshabilitado o el transporte no coincide) |
| POST | /api/mcp/sse | Envía una trama JSON-RPC mediante el transporte SSE |
| GET | /api/mcp/stream | Abre el lado SSE del transporte HTTP transmitible (mensajes iniciados por el servidor) |
| POST | /api/mcp/stream | Envía una trama JSON-RPC mediante el transporte HTTP transmitible |
| DELETE | /api/mcp/stream | Finaliza una sesión HTTP transmitible |
| GET | /api/mcp/audit | Consulta el registro de auditoría — ?limit=, ?offset=, ?tool=, ?success=true | false, ?apiKeyId= |
| GET | /api/mcp/audit/stats | Estadísticas de auditoría agregadas (totales, tasa de éxito, duración media, herramientas principales) |
Autenticación: los transportes sse/stream respetan la superficie de autenticación específica de MCP (clave de API Bearer con el ámbito mcp); las rutas status/tools/audit* pueden consultarse desde el panel (no se requiere autenticación adicional aparte de poder acceder al host del panel).
Ambos transportes HTTP están controlados por
settings.mcpEnabledysettings.mcpTransport: si el transporte no coincide, se devuelve400; si MCP está deshabilitado, se devuelve503.
Servidor A2A
OmniRoute expone un endpoint A2A (agente a agente) JSON-RPC 2.0, además de un contenedor REST para su uso en inspección/paneles.
JSON-RPC
POST /a2a
Authorization: Bearer your-api-key # opcional, salvo que OMNIROUTE_API_KEY esté configurada
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "message/send",
"params": {
"skill": "smart-routing",
"messages": [{"role": "user", "content": "Route this coding task"}]
}
}
Métodos compatibles (todos condicionados por settings.a2aEnabled):
| Método | Descripción |
|---|---|
message/send |
Ejecución síncrona de habilidades; devuelve {task, artifacts, metadata} |
message/stream |
Ejecución SSE en streaming del mismo conjunto de habilidades |
tasks/get |
Obtiene una tarea por taskId |
tasks/cancel |
Cancela una tarea por taskId |
Habilidades integradas: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.
Tarjeta del agente
GET /.well-known/agent.json
Devuelve la tarjeta pública del agente A2A (nombre, descripción, capacidades, catálogo de habilidades y esquema de autenticación), almacenada públicamente en caché durante 1 h. No requiere autenticación.
Utilidades REST
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/a2a/status |
Estado de activación de A2A + estadísticas de tareas + resumen almacenado en caché de la tarjeta del agente |
| GET | /api/a2a/tasks |
Enumera las tareas — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset= |
| POST | /api/a2a/tasks |
(No implementado como utilidad REST; créela mediante JSON-RPC message/send) |
| GET | /api/a2a/tasks/[id] |
Recupera una tarea |
| POST | /api/a2a/tasks/[id]/cancel |
Cancela una tarea |
Autenticación: las utilidades REST se ejecutan sin autenticación de administración (pueden leerse desde el panel); la ruta JSON-RPC /a2a utiliza Bearer OMNIROUTE_API_KEY si está configurada.
Nube, evaluaciones y valoración
| Método | Ruta | Descripción |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | /api/cloud/auth | Verifica una clave Bearer y devuelve conexiones de proveedores enmascaradas + alias de modelos para clientes de sincronización en la nube |
| POST | /api/cloud/credentials/update | Actualiza las credenciales cifradas de un proveedor sincronizado con la nube |
| POST | /api/cloud/model/resolve | Resuelve un id de modelo lógico en un proveedor/modelo concreto mediante la tabla de enrutamiento local |
| GET | /api/cloud/models/alias | Enumera los alias de modelos expuestos a la sincronización en la nube |
| GET | /api/assess | Lee las categorizaciones de la evaluación más reciente (por proveedor/modelo) |
| POST | /api/assess | Ejecuta una evaluación — cuerpo: {scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?} |
| GET | /api/evals | Enumera los conjuntos de evaluaciones integrados + las ejecuciones más recientes |
| POST | /api/evals | Inicia una ejecución de evaluación |
| POST | /api/evals/suites | Crea un conjunto de evaluaciones personalizado — cuerpo validado mediante evalSuiteSaveSchema |
| GET | /api/evals/suites/[id] | Recupera un conjunto de evaluaciones personalizado |
Autenticación: /api/cloud/auth valida directamente una clave Bearer y devuelve la clave enmascarada y el projectId de cada conexión únicamente para una clave con el ámbito manage / admin; las demás rutas /api/cloud/*, /api/evals/* y /api/assess requieren una sesión de gestión/clave de API. El método POST de /api/assess utiliza validateBody con un esquema de ámbito de unión discriminada.
Gestión de ACP (Agent Client Protocol)
como procesos secundarios. Estos endpoints gestionan la detección de agentes ACP y el registro de agentes personalizados.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/acp/agents |
Enumera todos los agentes de CLI conocidos (integrados y personalizados) con su estado de instalación, versión y binario |
| POST | /api/acp/agents |
Registra un agente ACP personalizado o actualiza la caché — cuerpo: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} o {action: "refresh"} |
| DELETE | /api/acp/agents |
Elimina un agente ACP personalizado — parámetro de consulta: ?id=<agentId> |
Ejemplo de respuesta (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
}
Autenticación: Requiere una sesión de administración (cookie auth_token del panel) o una
clave de API con ámbito de administración.
Consulta Framework ACP para obtener todos los detalles.
Analítica y observabilidad
Endpoints de analítica en tiempo real para supervisar el enrutamiento, la compresión y la diversidad
de proveedores. Estos endpoints alimentan las páginas de /dashboard/analytics/*.
Analítica de enrutamiento automático
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/analytics/auto-routing |
Estadísticas agregadas de enrutamiento automático: llamadas totales, distribución de estrategias, distribución de niveles y principales proveedores |
| GET | /api/analytics/auto-routing?days=7 |
Estadísticas para un intervalo temporal (24 h de forma predeterminada) |
Ejemplo de respuesta:
{
"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 }
]
}
Analítica de compresión
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/analytics/compression |
Estadísticas agregadas de compresión: tokens ahorrados, porcentaje de ahorro, distribución de modos y uso de motores |
Ejemplo de respuesta:
{
"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
}
}
Seguimiento de la diversidad de proveedores
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/analytics/diversity |
Seguimiento de la diversidad basado en la entropía de Shannon: evita puntos únicos de fallo midiendo la distribución entre proveedores |
Ejemplo de respuesta:
{
"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"]
}
Autenticación: Requiere una sesión de administración o una clave de API con ámbito de administración.
Operaciones de administración
Endpoints exclusivos para administradores destinados a la gestión operativa.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/admin/concurrency |
Consulta los límites de concurrencia actuales (globales y por proveedor) |
| POST | /api/admin/concurrency |
Actualiza los límites de concurrencia — cuerpo: {global?: number, perProvider?: Record<string, number>} |
Autenticación: Requiere una sesión de gestión con alcance de administrador.
Gestión de herramientas CLI
Gestiona las herramientas CLI que se integran con OmniRoute (antigravity, commandCode, devin-cli, etc.). Consulta la Referencia de proveedores para ver la lista completa.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/cli-tools/all-statuses |
Estado de todas las herramientas CLI (instalación, versión, última detección) |
| GET | /api/cli-tools/status |
Detalles del estado de una herramienta CLI (consulta ?tool=) |
| POST | /api/cli-tools/apply |
Escribe la configuración generada de una herramienta (dryRun ofrece una vista previa; 422 + containerEphemeralTarget cuando se ejecuta en un contenedor; migration indica un archivo YAML heredado de Codex) |
| GET | /api/cli-tools/backups |
Enumera las copias de seguridad de configuración de las herramientas CLI |
| POST | /api/cli-tools/backups |
Crea una copia de seguridad de las configuraciones de todas las herramientas CLI |
| POST | /api/cli-tools/backups |
Restauración: el mismo endpoint con {tool, backupId} en el cuerpo restaura esa copia de seguridad |
| GET | /api/cli-tools/antigravity-mitm |
Estado del proxy MITM de Antigravity (la herramienta CLI "antigravity-mitm") |
| POST | /api/cli-tools/antigravity-mitm/alias |
Configura los alias de antigravity-mitm |
Autenticación: Requiere una sesión de administración.
Habilidades de agentes
Gestiona las habilidades de los agentes de IA (similares a los GPT personalizados de OpenAI, pero para agentes).
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/agent-skills |
Enumera todas las habilidades de agentes (integradas y personalizadas) |
| GET | /api/agent-skills/[id] |
Obtiene una habilidad de agente específica |
| POST | /api/agent-skills |
Crea una habilidad de agente personalizada — cuerpo: {name, description, prompt, model?, temperature?} |
| PUT | /api/agent-skills/[id] |
Actualiza una habilidad de agente personalizada |
| DELETE | /api/agent-skills/[id] |
Elimina una habilidad de agente personalizada |
| GET | /api/agent-skills/[id]/raw |
Obtiene el prompt sin procesar y los metadatos (sin ejecución) |
| POST | /api/agent-skills/generate |
Genera mediante IA una nueva habilidad a partir de una descripción en lenguaje natural |
Autenticación: Requiere una sesión de gestión o una clave de API con alcance de gestión.
Gestión de caché
Gestiona la caché semántica y la caché de razonamiento.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/cache |
Resumen de la caché: entradas totales, tasa de aciertos, tamaño en disco |
| GET | /api/cache/entries |
Lista las entradas almacenadas en caché (con paginación) |
| DELETE | /api/cache/entries |
Elimina entradas de la caché (filtradas por parámetros de consulta) |
| GET | /api/cache/stats |
Estadísticas detalladas de la caché (por proveedor y por modelo) |
| GET | /api/cache/reasoning |
Estado de la caché de razonamiento (para la reproducción del razonamiento) |
| DELETE | /api/cache/reasoning |
Vacía la caché de razonamiento — parámetros de consulta: ?toolCallId=<id> (uno), ?provider=<p> o sin parámetros (todos) |
Autenticación: Requiere una sesión de administración.
Sistema de memoria
Gestiona la memoria persistente (FTS5 + incrustaciones vectoriales).
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/memory |
Lista las entradas de memoria (filtradas por ámbito, tipo o consulta de búsqueda) |
| POST | /api/memory |
Crea una nueva entrada de memoria — cuerpo: {scope, type, content, metadata?} |
| GET | /api/memory/[id] |
Obtiene una entrada de memoria específica |
| PUT | /api/memory/[id] |
Actualiza una entrada de memoria |
| DELETE | /api/memory/[id] |
Elimina una entrada de memoria |
| GET | /api/memory?q= |
Busca en la memoria (FTS5 + vectores) — las estadísticas se incluyen en la misma respuesta |
Autenticación: Requiere una sesión de administración o una clave de API con ámbito de administración.
Webhooks
Gestiona las suscripciones de webhooks para eventos.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/webhooks |
Lista todas las suscripciones de webhooks |
| POST | /api/webhooks |
Crea una suscripción de webhook — cuerpo: {url, events[], secret?, active?} |
| GET | /api/webhooks/[id] |
Obtiene una suscripción de webhook específica |
| PUT | /api/webhooks/[id] |
Actualiza una suscripción de webhook |
| DELETE | /api/webhooks/[id] |
Elimina una suscripción de webhook |
| GET | /api/webhooks/[id]/deliveries |
Lista el historial de entregas de un webhook (registro de éxitos y errores) |
| POST | /api/webhooks/[id]/test |
Envía un evento de prueba a un webhook |
Autenticación: Requiere una sesión de administración.
Consulta Marco de webhooks para conocer todos los tipos de eventos.
Framework de Skills
Gestiona Skills (el framework de extensiones agénticas).
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/skills |
Enumera todas las skills instaladas (integradas + personalizadas) |
| POST | /api/skills/install |
Instala una skill desde una ruta local o URL |
| DELETE | /api/skills/[id] |
Desinstala una skill |
| PUT | /api/skills/[id] |
Habilita o deshabilita una skill — cuerpo: {enabled?: boolean, mode?: "on" | "off" | "auto"} |
| POST | /api/skills/executions |
Ejecuta una skill — cuerpo: {skillName, apiKeyId, input?, sessionId?} |
| GET | /api/skills/executions |
Enumera el historial de ejecuciones de todas las skills (filtra mediante ?apiKeyId=) |
Autenticación: Requiere una sesión de administración o una clave de API con ámbito de administración.
Consulta Framework de Skills para obtener todos los detalles.
Plugins
Gestiona los plugins de OmniRoute (extensiones de terceros).
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/plugins |
Enumera los plugins instalados |
| POST | /api/plugins/marketplace/install |
Instala un plugin desde el marketplace |
| DELETE | /api/plugins/[name] |
Desinstala un plugin |
| POST | /api/plugins/[name]/activate |
Activa un plugin |
| POST | /api/plugins/[name]/deactivate |
Desactiva un plugin |
| GET | /api/plugins/[name]/config |
Obtiene la configuración del plugin |
| PUT | /api/plugins/[name]/config |
Actualiza la configuración del plugin |
Autenticación: Requiere una sesión de administración.
Consulta Framework de Plugins para obtener todos los detalles.
Enrutamiento en sombra
La comparación en sombra / A-B de proveedores no es una superficie REST independiente; se configura mediante el enrutamiento combinado (consulta Auto-Combo). Las métricas de comparación por combinación se proporcionan mediante GET /api/combos/metrics.
Barreras de protección
Inspecciona las barreras de protección en tiempo de ejecución (detección de PII, detección de inyección de prompts, puente de visión). Las barreras de protección se ejecutan en cada solicitud; la exclusión voluntaria por llamada se realiza mediante el encabezado de solicitud x-omniroute-disabled-guardrails; no existe una interfaz persistente para habilitarlas o deshabilitarlas.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/guardrails |
Enumera las barreras de protección registradas y su estado (nombre / habilitada / prioridad) |
| POST | /api/guardrails/test |
Ejecuta en modo de prueba el pipeline previo a la llamada sobre una entrada de ejemplo — cuerpo: {input, disabledGuardrails?} |
Autenticación: Requiere una sesión de administración.
Consulta Seguridad > Barreras de protección para obtener todos los detalles.
Autenticación
Consulta Autenticación de administración para conocer las cuatro
familias de credenciales (sesión del panel, token de CLI local, token de acceso
oma_live_…, clave de API con ámbito de administración) y en qué se diferencian de las claves de inferencia.
- Las rutas del panel (
/dashboard/*) usan la cookieauth_token - El inicio de sesión usa el hash de contraseña guardado; como alternativa, usa
INITIAL_PASSWORD requireLoginse puede activar o desactivar mediante/api/settings/require-login- Las rutas
/v1/*pueden requerir opcionalmente una clave de API Bearer cuandoREQUIRE_API_KEY=true - En esta referencia, «token de administración» / «clave de API con ámbito de administración» significa una de las familias descritas en esa guía, no un tipo de secreto adicional sin definir
Cambio incompatible (v3.8.0) —
/api/v1/agents/tasks/*y los endpoints de administración del período de espera ahora requieren autenticación de administración (cookieauth_tokendel panel o una clave de API con ámbito de administración). Los clientes que anteriormente llamaban a estas rutas sin autenticación recibirán401 Unauthorized. Consulta el commit588a0333(fix(auth): require management auth for agent and cooldown APIs).