pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-19 13:23:50 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
4be690736c5f85e1c7a35fa26e2fbbd2b7eb2c91
OmniRoute/docs/i18n/fr/docs/reference/API_REFERENCE.md
Diego Rodrigues de Sa e Souza b637350680 fix(docs): re-sync the 65 documentation mirror sets; section-level docs pipeline; drift gate blocking (#13940) 
1,104 mirrors rewritten over five passes of run-translation on the 22-source core set: the 14 sources edited since their translation, the 322 mirrors that were still English copies, and the frontmatter the old extractor leaked into the newer locales' bodies. The pipeline now caches per-`## `-section hashes and retranslates only changed sections, never reuses a section that is still English, rebuilds English-copy / leaked mirrors even when the source is unchanged, merges the state on save (parallel runs), and the drift gate (scoped to the core set) is blocking. Final audit: 0 stale, 0 English copies, 0 leaked frontmatter across 1,430 core mirrors.

⚠️ base-red inherited: #12732
2026-09-17 02:55:31 -03:00

1739 lines
134 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API Reference (Français)
🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)
---
🌐 **Langues :** 🇺🇸 [English](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md)
Référence principale de l’API OmniRoute. Elle couvre l’interface publique `/v1` et les points de terminaison de gestion les plus utilisés ; le fichier lisible par machine [`docs/openapi.yaml`](../openapi.yaml) et l’arborescence des routes sous `src/app/api/` constituent les sources exhaustives.
---
## Table des matières
- [Complétions de chat](#chat-completions)
- [Baux exclusifs de sessions gérées](#exclusive-managed-session-leases)
- [Embeddings](#embeddings)
- [Génération d’images](#image-generation)
- [OCR de documents](#document-ocr)
- [Liste des modèles](#list-models)
- [Manifeste du plugin fournisseur](#provider-plugin-manifest)
- [Points de terminaison de compatibilité](#compatibility-endpoints)
- [API des fichiers](#files-api)
- [API des traitements par lots](#batches-api)
- [API de recherche](#search-api)
- [Diffusion en continu via WebSocket](#websocket-streaming)
- [Quotas et signalement des problèmes](#quotas--issues-reporting)
- [Cache sémantique](#semantic-cache)
- [Tableau de bord et gestion](#dashboard--management)
- [Gestion des combinaisons](#combo-management)
- [Webhooks](#webhooks)
- [Clés enregistrées (gestion automatique)](#registered-keys-auto-management)
- [Protocole des agents](#agents-protocol)
- [Proxys de gestion](#management-proxies)
- [Résilience (étendue)](#resilience-extended)
- [Compétences](#skills)
- [Mémoire](#memory)
- [Serveur MCP](#mcp-server)
- [Serveur A2A](#a2a-server)
- [Cloud, évaluations et appréciation](#cloud-evals--assess)
- [Traitement des requêtes](#request-processing)
- [Authentification](#authentication)
---
## Complétions de chat
```bash
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
}
```
### En-têtes personnalisés
| En-tête | Direction | Description |
| ------------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache` | Requête | Définissez-le sur `true` pour contourner le cache |
| `x-omniroute-no-memory` | Requête | Définissez-le sur `true` pour ignorer l’injection de mémoire et de compétences pour cette requête (reproduit le comportement sans cache et évite le surcoût en jetons et en coût pour chaque appel) |
| `X-OmniRoute-Progress` | Requête | Définissez-le sur `true` pour recevoir les événements de progression |
| `X-Session-Id` | Requête | Clé de session persistante pour l’affinité de session externe |
| `x_session_id` | Requête | Variante avec trait de soulignement également acceptée (HTTP direct) |
| `X-OmniRoute-Session-Id` | Requête | Étiquette de session/conversation fournie par l’appelant (également transmise à la mémoire). Lorsqu’elle est présente, elle est conservée telle quelle dans `call_logs.session_tag` pour l’attribution des coûts par session (#8249) — elle n’est jamais générée lorsqu’elle est absente |
| `Idempotency-Key` | Requête | Clé de déduplication (fenêtre de 5 s) |
| `X-Request-Id` | Requête | Clé de déduplication alternative |
| `X-OmniRoute-Cache` | Réponse | `HIT` ou `MISS` (hors diffusion en continu) |
| `X-OmniRoute-Idempotent` | Réponse | `true` en cas de déduplication |
| `X-OmniRoute-Progress` | Réponse | `enabled` si le suivi de la progression est activé |
| `X-OmniRoute-Session-Id` | Réponse | ID de session effectif utilisé par OmniRoute |
| `X-OmniRoute-Request-Id` | Réponse | ID de corrélation de la requête (lorsqu’il est connu) |
| `X-OmniRoute-Version` | Réponse | Version de build d’OmniRoute (toujours présente) |
| `X-OmniRoute-Cost-Saved` | Réponse | Montant en USD économisé grâce au cache lors d’un `HIT` (uniquement pour les accès au cache) |
| `X-OmniRoute-Decision` | Réponse | Trace de routage : `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` est la stratégie de combinaison, ou `single` pour une requête sans combinaison) — toujours présente dans les réponses finales |
> Remarque concernant Nginx : si vous utilisez des en-têtes contenant des traits de soulignement (par exemple `x_session_id`), activez `underscores_in_headers on;`.
> **En-têtes de télémétrie des coûts :** les réponses réussies non diffusées en continu incluent également l’ensemble d’en-têtes de télémétrie des coûts `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, avec exactement 10 décimales ; `0.0000000000` si gratuit ou sans tarification), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit` et `X-OmniRoute-Fallback-Attempts` (uniquement lorsque > 0), ainsi que `X-OmniRoute-Request-Id` et `X-OmniRoute-Version`. Ils sont émis par les complétions de chat, `/v1/responses`, `/v1/messages`, **ainsi que par les points de terminaison multimédias** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` et `/v1/moderations` (coût toujours égal à `0`). Le coût des contenus multimédias est calculé selon la modalité (par image, par seconde, par caractère ou par unité de recherche) lorsque la tarification est disponible ; dans le cas contraire, il est égal à `0` (mode ouvert en cas d’échec).
> **Sémantique du coût en cas d’accès au cache :** lors d’un accès au cache sémantique (`X-OmniRoute-Cache-Hit: true`), aucun appel en amont n’est effectué ; `X-OmniRoute-Response-Cost` vaut donc `0.0000000000` (le coût **incrémental** du traitement de cet accès). Le coût initial ou celui qui aurait été engagé est indiqué séparément dans `X-OmniRoute-Cost-Saved`. Les systèmes de facturation doivent additionner les valeurs de `X-OmniRoute-Response-Cost` (les accès au cache ne coûtent rien) ; les outils d’analyse du cache peuvent agréger les valeurs de `X-OmniRoute-Cost-Saved`.
## Baux exclusifs de sessions gérées
La location exclusive de sessions gérées est un contrat de routage facultatif et indépendant du client : un propriétaire actif détient une connexion OmniRoute éligible. Elle ne réserve pas un modèle, n’exige pas OAuth, n’identifie pas un client particulier et n’impose pas de fournisseur particulier.
La clé API utilisée pour l’authentification doit disposer de la portée `lease:exclusive` et d’une liste `allowedConnections` explicite et non vide. La limite transactionnelle des mutations de la base de données impose conjointement ces deux champs lors de la création d’une clé et des mises à jour partielles.
```http
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"}
```
Les réponses réussies d’acquisition, de renouvellement et de libération exposent les horodatages, `state` et la valeur positive exacte de `generation`, mais jamais la connexion sélectionnée ni les identifiants d’authentification. Pour le renouvellement et la libération, la génération est fournie dans le corps JSON :
```json
{ "action": "renew", "generation": 1 }
```
```json
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
```
Le propriétaire d’un bail actif peut demander explicitement des métadonnées d’affichage respectueuses de la confidentialité pour son association actuelle :
```json
{ "action": "status", "generation": 1 }
```
```json
{
"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"
}
}
```
Cette action d’état facultative est protégée par le propriétaire opaque, la clé API gérée authentifiée et la génération active exacte, au sein d’une même transaction de base de données. `displayName` correspond uniquement au nom configuré de la connexion, après suppression des espaces superflus ; sa valeur est `null` lorsqu’aucun nom configuré sûr n’existe. OmniRoute ne lui substitue jamais une adresse e-mail ni une identité de compte générée. La valeur du fournisseur est une étiquette d’affichage non sensible et jamais un identifiant généré de fournisseur compatible. Les identifiants d’authentification, jetons, cookies, identifiants bruts de connexion ou de clé API, empreintes de propriétaires, secrets de cloisonnement et données de routage internes sont exclus.
Les recherches avec une clé incorrecte, un propriétaire incorrect, une génération obsolète, un bail manquant, expiré, libéré ou invalidé renvoient toutes la même erreur `409 LEASE_FENCE_STALE`, sans métadonnées de connexion. Un client ayant reçu la réponse d’attente de capacité ne dispose d’aucune association active à inspecter. Lorsque le routage fait basculer un bail actif, la même génération reste valide et l’état renvoie atomiquement la nouvelle association, jamais l’ancienne. Les clients existants restent inchangés, car les réponses d’acquisition, de renouvellement, de libération et d’attente conservent leurs structures précédentes.
Ce contrat serveur ne modifie pas `/status` dans la version standard d’OpenAI Codex. À l’heure actuelle, la version standard de Codex indique son fournisseur de modèle et l’état intégré de l’authentification et du compte, mais n’affiche pas les métadonnées de compte arbitraires des fournisseurs personnalisés ; une future intégration côté client devra appeler cette action et déterminer comment afficher `connection.displayName`.
Chaque requête d’inférence gérée fournit ensuite les deux en-têtes de contrôle :
```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```
Le propriétaire exact, la génération, la connexion active et la clé API authentifiée sont cloisonnés immédiatement avant chaque tentative en amont prise en charge. La réutilisation du propriétaire et de la génération avec une autre clé échoue, même lorsque cette clé autorise la même connexion. Les propriétaires bruts ne sont ni conservés, ni journalisés, ni retenus dans l’instantané de la requête, ni transmis en amont.
Une contention temporaire renvoie le code HTTP `429` avec `Retry-After` et :
```json
{
"state": "WAITING_FOR_CAPACITY",
"error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
"reason": "NO_FREE_ELIGIBLE_CONNECTION",
"retryAfter": 30
}
```
Cette réponse signifie uniquement que l’ensemble éligible ordinaire n’était pas vide et que chaque candidat libre était détenu par un bail actif tiers. Les modèles ou fournisseurs non pris en charge, les incompatibilités de politique, les périodes de récupération, les quotas, l’état de santé et les autres échecs ordinaires d’éligibilité conservent leurs réponses OmniRoute existantes.
### `x-omniroute-compression`
Remplacement, pour chaque requête, du plan de compression. Priorité la plus élevée — prévaut sur le remplacement de la combinaison de routage, le profil actif, le déclenchement automatique et la valeur par défaut du panneau. Valeurs :
| Valeur | Effet |
| ------------- | --------------------------------------------------------------------------------------------------------- |
| `off` | Aucune compression pour cette requête. |
| `default` | Le profil par défaut dérivé du panneau (ignore le profil actif). |
| `engine:<id>` | Un moteur unique lorsqu’il est activé, par ex. `engine:rtk`. |
| `<combo>` | Une combinaison nommée, recherchée d’abord par nom (sans tenir compte de la casse), puis par identifiant. |
Remarques :
- Les valeurs inconnues sont ignorées (la requête n’est jamais rejetée) ; la résolution passe alors à l’ordre de priorité normal des opérateurs.
- Si plusieurs combinaisons partagent le même nom, transmettez l’**id** de la combinaison pour obtenir une correspondance déterministe.
- Une combinaison dont le nom est `off` ou `default` ne peut pas être sélectionnée par son nom (ces mots-clés sont interprétés en premier) ; référencez une telle combinaison par son identifiant.
- Le commutateur principal de compression constitue un verrou absolu : lorsque la compression est désactivée globalement, cet en-tête ne peut pas l’activer.
Le plan appliqué est renvoyé dans l’en-tête de réponse :
```
X-OmniRoute-Compression: <mode>; source=<source>
```
où `<source>` est l’une des valeurs suivantes : `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` ou `off`.
---
## Embeddings
```bash
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "nebius/Qwen/Qwen3-Embedding-8B",
"input": "The food was delicious"
}
```
Fournisseurs disponibles : Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.
Les identifiants du catalogue suivent le format `provider/model` (exemple : `jina-ai/jina-embeddings-v5-omni-small`). Les identifiants de modèles Jina sans préfixe qui figurent dans le registre (par exemple `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) sont également résolus. Pour les opérations d’embedding, de reranking, de classification et de segmentation de Jina, les identifiants `jina-ai` du tableau de bord sont utilisés en priorité ; `JINA_AI_API_KEY` n’est utilisé comme solution de secours que lorsqu’aucune clé du tableau de bord n’existe. La fiche `jina-reader` est réservée à Reader / `r.jina.ai` (`POST /v1/web/fetch`) et ne fournit jamais d’embeddings ni de reranking.
Les modèles du registre qui annoncent une prise en charge multimodale acceptent également jusqu’à 32 éléments structurés indépendants du fournisseur. Les types d’éléments multimédias sont `text`, `image`, `audio`, `video` et `document`. Leur `source` multimédia est soit `{"type":"url","url":"https://..."}`, soit `{"type":"base64","data":"...","media_type":"..."}`.
Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano` et l’alias de famille `jina-ai/jina-embeddings-v5-omni` → omni-small) accepte également les documents EmbeddingsV5Request natifs de Jina et **les transmet sans modification** à `https://api.jina.ai/v1/embeddings` :
```json
{
"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,..." }]
}
]
}
```
Les valeurs natives `{ image | audio | video | pdf }` peuvent être une URL HTTPS publique, un URI `data:` ou des données base64 brutes. OmniRoute ne convertit pas ces objets en chaînes et ne récupère pas les URL d’images natives — Jina récupère lui-même les médias publics. Les champs Jina supplémentaires (`task`, `normalized`, `truncate`, `embedding_type`) sont transmis. Les SKU Jina exclusivement textuels continuent de rejeter les documents non textuels.
Limites de sécurité et de transport :
- Les URL de médias distants doivent être des URL HTTPS publiques. Les éléments canoniques `{type,source:url}` sont récupérés côté serveur (nouvelle validation des redirections, délai d’expiration, limites de taille, DNS public, épinglage de connexion) et intégrés avant l’appel au fournisseur. Les éléments Jina natifs `{image:"https://..."}` sont transmis tels quels après la même vérification HTTPS publique ; Jina récupère l’URL.
- Les médias base64 intégrés sont limités à 8 Mio décodés par élément et à 16 Mio décodés pour l’ensemble de la requête.
Traduction pour le fournisseur (les éléments canoniques ne sont jamais transmis sans modification) :
- Modèles multimodaux Jina : chaque élément de premier niveau devient un objet associé à une modalité (`text` / `image` / `audio` / `video` / `pdf`), utilisant des URI de données pour les médias intégrés ; un vecteur par élément de premier niveau.
- Famille Gemini Embedding 2 : un tableau de premier niveau devient une seule requête native `models/{model}:embedContent` avec `content.parts` (`text` ou `inline_data`).
- Les modèles inconnus/dynamiques dépourvus de métadonnées explicites sur les modalités rejettent les entrées structurées avec HTTP 400.
```json
{
"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"
}
```
Les combinaisons modèle/modalité non prises en charge renvoient HTTP 400 au lieu de convertir de force l’élément. Les champs d’extension autres que ceux d’entrée dans les requêtes héritées de chaînes/jetons continuent d’être transmis sans modification.
```bash
# Répertorier tous les modèles d’embedding
GET /v1/embeddings
```
---
## Génération d’images
```bash
POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "openai/gpt-image-2",
"prompt": "Un magnifique coucher de soleil sur les montagnes",
"size": "1024x1024"
}
```
Fournisseurs disponibles : OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (local), ComfyUI (local).
```bash
# Répertorier tous les modèles d’image
GET /v1/images/generations
```
---
## OCR de documents
```bash
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` sélectionne le fournisseur d’OCR via un préfixe `provider/model` ; un identifiant de modèle seul (par ex.
`mistral-ocr-latest`) est associé à son fournisseur enregistré, tandis que si `model` est omis, Mistral
(`mistral-ocr-latest`) est utilisé par défaut. Fournisseurs enregistrés (`open-sse/config/ocrRegistry.ts`) :
| Identifiant du fournisseur | Identifiant du modèle | Valeur de `model` | Remarques |
| ----------------------------- | --------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (ou simplement `mistral-ocr-latest`) | Synchrone — la réponse est renvoyée directement à partir de l’unique appel en amont. |
| `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Traitement en amont asynchrone (`analyze` + interrogation) — voir ci-dessous. |
| `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Synchrone, via le point de terminaison partenaire `openapi/chat/completions` de Vertex AI — voir ci-dessous pour l’authentification et l’URL. |
Les trois fournisseurs renvoient le même corps au format Mistral :
```json
{
"pages": [{ "index": 0, "markdown": "# Texte extrait..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
```
### Flux d’interrogation d’Azure Document Intelligence
L’API `analyze` d’Azure Document Intelligence est asynchrone : la requête initiale renvoie un
en-tête `Operation-Location` au lieu d’un corps, et le résultat doit être récupéré par interrogations successives. Le gestionnaire
(`open-sse/handlers/ocr.ts`) interroge cette URL toutes les secondes, jusqu’à 30 tentatives, échoue immédiatement (sans
poursuivre les interrogations) si une réponse d’interrogation n’est pas `ok` ou si le statut est `"failed"`, et renvoie `504` si
l’opération est toujours en cours une fois le nombre maximal de tentatives épuisé. La réponse Azure finale est
normalisée dans le même format `pages`/`markdown` que celui utilisé par Mistral avant d’être renvoyée à
l’appelant, de sorte que le code client n’a pas besoin de traiter le fournisseur comme un cas particulier.
### Authentification et résolution du point de terminaison Vertex AI DeepSeek OCR
`vertex-deepseek-ocr` réutilise la même authentification Vertex AI qu’OmniRoute prend déjà en charge pour
le trafic de chat et d’images (`open-sse/executors/vertex.ts`) : la clé API de la connexion est soit un
identifiant Service Account JSON (échangé contre un jeton d’accès OAuth de courte durée via le flux JWT bearer),
soit un jeton d’accès OAuth déjà généré, utilisé tel quel. L’URL du point de terminaison en amont est le
point de terminaison partenaire générique `openapi/chat/completions` de Vertex, construit à partir du projet et de
la région de la connexion — une valeur explicite `providerSpecificData.project`/`providerSpecificData.region` est toujours prioritaire ;
sinon, le projet est déduit du champ `project_id` du Service Account JSON et la région
prend par défaut la valeur `us-central1`. Ces deux résolutions ont lieu dans `open-sse/handlers/ocr.ts`
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`) et sont utilisées par
`src/app/api/v1/ocr/route.ts` avant la délégation à `handleOcr`.
---
## Lister les modèles
```bash
GET /v1/models
Authorization: Bearer your-api-key
→ Renvoie tous les modèles de chat, d'embedding et d'image ainsi que les combinaisons au format OpenAI
```
### Préfixes des identifiants de modèle (`?prefix=`)
La plupart des modèles sont publiés sous un **préfixe de fournisseur**. Le préfixe obtenu est contrôlé par
le feature flag `MODELS_CATALOG_PREFIX_MODE` et peut être remplacé **pour chaque requête** à l'aide d'un
paramètre de requête — pratique pour un client qui souhaite une liste épurée sans modifier le paramètre
global du serveur pour tous les autres utilisateurs :
```bash
GET /v1/models?prefix=alias # un identifiant par modèle — le préfixe d'alias court
GET /v1/models?prefix=dual # les deux formes (valeur par défaut du serveur)
GET /v1/models?prefix=canonical # uniquement le préfixe complet de l'identifiant du fournisseur
```
| Mode | Émet | Remarques |
| ----------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual` | `cc/claude-sonnet-4-6` **et** `claude/claude-sonnet-4-6` | **Par défaut.** Les deux identifiants sont routés vers le même modèle ; ils sont conservés afin que les configurations clientes ayant codé en dur l'une ou l'autre forme continuent de fonctionner. Double approximativement la taille du catalogue. |
| `alias` | `cc/claude-sonnet-4-6` | Une entrée par modèle. Les fournisseurs sans alias distinct publient tout de même leur entrée, donc rien n'est perdu. |
| `canonical` | `claude/claude-sonnet-4-6` | Une entrée par modèle sous le préfixe complet de l'identifiant du fournisseur. Les fournisseurs sans alias distinct (p. ex. `antigravity/…`, `agy/…`) publient également ici leur identifiant unique, donc rien n'est perdu. |
Un miroir en mode `dual` peut également être reconnu sans le paramètre de requête : il comporte un champ `parent`
qui pointe vers l'identifiant principal.
Les clients qui affichent un sélecteur de modèles doivent demander `?prefix=alias` — c'est ce que fait
[l'extension OmniCopilot pour VS Code](../guides/VSCODE-COPILOT.md).
### Variantes de modèles sans raisonnement
Pour les modèles Claude capables de raisonnement, `/v1/models` publie également une variante **sans raisonnement** dont l'identifiant est préfixé par `claude-3-omniroute-no-thinking/` :
```
claude-3-omniroute-no-thinking/<provider>/<model>
```
La sélection de cet identifiant (p. ex. dans une configuration Claude Code qui ajoute systématiquement un bloc `thinking`) le résout vers le véritable `<provider>/<model>` avec le raisonnement désactivé — `thinking:{type:"disabled"}` sur le chemin `/v1/messages`, ou les champs `reasoning`/`reasoning_effort` supprimés sur le chemin `/v1/chat/completions`. La variante n'est répertoriée que pour les modèles de la famille Claude qui prennent en charge le raisonnement **et** respectent `disabled` (ainsi, par exemple, les modèles exclusivement adaptatifs qui rejettent `disabled` sont exclus). Les opérateurs peuvent forcer l'activation ou la désactivation de la variante pour chaque modèle via `ModelSpec.noThinkingAlias`.
---
## Manifeste des plugins de fournisseurs
```bash
GET /api/v1/provider-plugin-manifest
```
Renvoie le manifeste JSON sécurisé des plugins de fournisseurs utilisé par Bifrost, CLIProxyAPI et les futurs routeurs side-car. La réponse est générée à partir du registre TypeScript des fournisseurs et exclut volontairement les secrets clients OAuth, la résolution de l’environnement d’exécution, les fonctions d’exécution, les en-têtes de requête et les données de compte.
Utilisez ce point de terminaison lorsqu’un side-car s’exécute dans un processus distinct et ne peut pas importer directement `open-sse/config/providerPluginManifestRegistry.ts`.
---
## Points de terminaison de compatibilité
| Méthode | Chemin | Format |
| ------- | ----------------------------------------- | ------------------------------------ |
| POST | `/v1/chat/completions` | OpenAI |
| POST | `/v1/messages` | Anthropic |
| POST | `/v1/responses` | OpenAI Responses |
| POST | `/v1/embeddings` | OpenAI |
| POST | `/v1/images/generations` | OpenAI Images |
| POST | `/v1/images/edits` | OpenAI Images (édition/inpainting) |
| POST | `/v1/videos/generations` | Génération vidéo de style OpenAI |
| POST | `/v1/music/generations` | Génération musicale de style OpenAI |
| POST | `/v1/audio/transcriptions` | OpenAI Audio (reconnaissance vocale) |
| POST | `/v1/audio/speech` | OpenAI TTS (renvoie un corps audio) |
| POST | `/v1/rerank` | Reclassement de style Cohere/Voyage |
| POST | `/v1/classify` | Classification Jina (`api.jina.ai`) |
| POST | `/v1/segment` | Segmenteur Jina (`segment.jina.ai`) |
| POST | `/v1/moderations` | OpenAI Moderations |
| GET | `/v1/models` | OpenAI |
| POST | `/v1/messages/count_tokens` | Anthropic |
| GET | `/v1beta/models` | Gemini |
| POST | `/v1beta/models/{...path}` | Gemini generateContent |
| POST | `/v1/api/chat` | Ollama |
| GET | `/api/v1/vscode/{token}/` | Alias du catalogue OpenAI |
| GET | `/api/v1/vscode/{token}/models` | Alias des modèles OpenAI |
| POST | `/api/v1/vscode/{token}/chat/completions` | Alias OpenAI avec jeton |
| POST | `/api/v1/vscode/{token}/responses` | Alias OpenAI Responses avec jeton |
| POST | `/api/v1/vscode/{token}/api/chat` | Alias Ollama avec jeton |
| GET | `/api/v1/vscode/{token}/api/tags` | Alias des balises Ollama avec jeton |
Toutes les routes POST suivent la même structure : `Bearer your-api-key` + corps JSON validé par Zod (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, etc., voir `src/shared/validation/schemas.ts`). Une erreur 4xx est renvoyée en cas d’échec de validation du schéma.
Pour les clients qui ne peuvent pas joindre `Authorization: Bearer ...`, OmniRoute accepte également les clés API dans l’URL, soit via les paramètres de requête compatibles (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`), soit via les points de terminaison dédiés `/api/v1/vscode/{token}/...` documentés ci-dessous.
```bash
# Reclassement
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Classification Jina (identifiants de l’API Foundation)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Segmenteur Jina
POST /v1/segment { "content": "...", "return_chunks": true }
# Recherche Jina (s.jina.ai ; alias de fournisseurs : jina-search, jina-ai, jina)
POST /v1/search { "query": "...", "provider": "jina-search" }
# Modérations
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
# TTS — renvoie un corps audio/mpeg (ou dans le format demandé)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# Édition d’image (multipart)
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
# Génération vidéo/musicale (identifiant de modèle préfixé par le fournisseur)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." }
```
### Routes dédiées aux fournisseurs
```bash
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
```
Le préfixe du fournisseur est ajouté automatiquement s’il est absent. Les modèles incompatibles renvoient `400`.
---
## API Files
Point de terminaison compatible avec OpenAI pour les fichiers d’entrée/sortie par lots et les téléversements associés à un usage spécifique.
| Méthode | Chemin | Description |
| ------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/files` | Téléverser un fichier (multipart : `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — 512 Mio maximum |
| GET | `/v1/files` | Répertorier les fichiers associés à la clé API authentifiée |
| GET | `/v1/files/[id]` | Récupérer les métadonnées d’un fichier |
| DELETE | `/v1/files/[id]` | Supprimer un fichier |
| GET | `/v1/files/[id]/content` | Diffuser en continu le contenu brut du fichier |
**Authentification :** clé API Bearer — les fichiers sont isolés par clé API via `getApiKeyRequestScope`. Une clé
peut uniquement voir, télécharger et supprimer ses propres fichiers ; une session du tableau de bord sans clé peut lire
l’ensemble de l’instance ; un fichier sans propriétaire (téléversement anonyme ou depuis une session du tableau de bord) est inaccessible à tout
appelant hors session. `GET /v1/files` rejette un appelant anonyme — ainsi qu’une clé fournie qui ne peut pas
être résolue — avec `401`, même lorsque `REQUIRE_API_KEY=false`, au lieu de répertorier les fichiers de tous les locataires
(GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).
---
## API Batches
Traitement par lots compatible avec OpenAI.
| Méthode | Chemin | Description |
| ------- | ------------------------- | -------------------------------------------------------------------------------------------------------- |
| POST | `/v1/batches` | Créer un lot — corps validé par `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
| GET | `/v1/batches` | Répertorier les lots |
| GET | `/v1/batches/[id]` | Récupérer l’état du lot et `request_counts` |
| DELETE | `/v1/batches/[id]` | Supprimer un lot terminé ou ayant échoué |
| POST | `/v1/batches/[id]/cancel` | Annuler un lot en cours |
**Authentification :** clé API Bearer. Les lots sont isolés par clé API selon la même règle à trois niveaux que les
fichiers : accès limité à la clé propriétaire, accès à l’ensemble de l’instance pour une session du tableau de bord, enregistrements sans propriétaire inaccessibles à tout
appelant hors session (récupération, suppression, annulation et vérification de `input_file_id` lors de la création).
`GET /v1/batches` rejette un appelant anonyme avec `401`, même lorsque `REQUIRE_API_KEY=false`.
---
## API de recherche
Abstraction des fournisseurs de recherche Web (Tavily, Brave, Exa, Serper, etc.).
| Méthode | Chemin | Description |
| ------- | ---------------------- | -------------------------------------------------------------------------------------------------------- |
| GET | `/v1/search` | Répertorie les fournisseurs de recherche configurés et leurs capacités |
| POST | `/v1/search` | Exécute une requête de recherche — corps validé par `v1SearchSchema`, prend en charge le cache/la fusion |
| GET | `/v1/search/analytics` | Statistiques par fournisseur sur les résultats/latences/caches |
**Authentification :** clé d’API Bearer (`extractApiKey` + `isValidApiKey`). La politique de recherche est appliquée via `enforceApiKeyPolicy`.
---
## API de récupération Web
Extrait le contenu d’une URL via un fournisseur de récupération Web configuré (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).
| Méthode | Chemin | Description |
| ------- | --------------- | -------------------------------------------------------------- |
| POST | `/v1/web/fetch` | Récupère/extrait une URL — corps validé par `v1WebFetchSchema` |
**Authentification :** clé d’API Bearer (`extractApiKey` + `isValidApiKey`). La politique est appliquée via `enforceApiKeyPolicy`.
**Repli tenant compte des quotas (#8297) :** lorsqu’aucun `provider` explicite n’est indiqué, le pool
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) est
parcouru selon un ordre de priorité fixe (remplissage prioritaire) — un fournisseur configuré mais soumis
à une limitation de débit est ignoré au lieu d’interrompre immédiatement la requête, et un échec amont
réessayable ou lié au quota (HTTP 429 dans tous les cas ; 402/403 pour les offres gratuites de type quota
de Firecrawl/Tavily/TinyFish — pas pour Jina Reader, et jamais pour une simple requête incorrecte 400)
provoque le passage au fournisseur suivant, non encore essayé et disposant d’identifiants, au moment de la requête.
Lorsque tous les fournisseurs du pool sont épuisés, le point de terminaison renvoie un unique `429`
(avec un en-tête `Retry-After`) au lieu de l’ancien `400` générique. Lorsqu’un `provider` explicite est
demandé, il n’y a **aucun** repli silencieux — un fournisseur explicite soumis à une limitation de débit
ou en échec expose sa propre erreur (`429` en cas de limitation de débit, sinon le statut amont).
---
## Diffusion WebSocket
```bash
GET /v1/ws?handshake=1
```
Valide une négociation de mise à niveau WebSocket et renvoie les exemples de messages du protocole filaire (`request`, `cancel`). Les trames WS réelles sont gérées par le serveur WS inclus, en dehors de la table de routage Next.js.
**Authentification :** clé d’API Bearer pendant la négociation.
### API Responses via WebSocket (codex uniquement)
```bash
# Même hôte:port que l’API HTTP (20128 par défaut) ; mettez à niveau la connexion :
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (ou : -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
# La première trame DOIT être response.create :
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```
Un proxy de l’API Responses via WebSocket est relié **exclusivement à `codex`** (backend
ChatGPT). Il écoute sur le même port que l’API/le tableau de bord aux chemins `/v1/responses`,
`/responses` et `/api/v1/responses`. À la première trame `response.create`, il
authentifie et prépare la requête via le pont interne `codex-responses-ws`, sélectionne une
connexion OAuth codex et établit un tunnel vers `wss://chatgpt.com/backend-api/codex/responses`
via le transport `wreq-js`. **Les modèles non-codex sont rejetés** (`codex_ws_provider_required`).
Pour le routage par partage de quota, utilisez `model: "qtSd/<group>/codex/<model>"`. Implémenté dans
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.
**Authentification :** clé d’API Bearer pendant la négociation. Le serveur HTTP inclus (`server-ws.mjs`)
doit être le point d’entrée actif (c’est le cas par défaut lorsque `app/server-ws.mjs` existe).
#### Identifiant du modèle : utilisez l’identifiant ChatGPT brut (sans préfixe `codex/`)
L’interface en ligne de commande **Codex d’OpenAI** valide le nom du modèle côté client lorsque
`supports_websockets = true` et **rejette les identifiants préfixés par un fournisseur** tels que
`codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). Envoyez l’identifiant **brut** (par ex. `gpt-5.5`). Le pont d’OmniRoute est
réservé à codex ; il résout donc à nouveau un identifiant brut comme modèle codex
(`resolveCodexWsModelInfo`) avant d’établir le tunnel vers le service amont — même si un identifiant brut
`gpt-5.5` serait autrement acheminé vers un autre fournisseur via HTTP.
#### Configuration de l’interface en ligne de commande Codex d’OpenAI
Orientez l’interface en ligne de commande Codex vers OmniRoute en ajoutant un fournisseur personnalisé prenant en charge
WebSocket dans `~/.codex/config.toml` (utilisez un `CODEX_HOME` distinct afin de ne pas modifier
une configuration existante) :
```toml
model = "gpt-5.5" # identifiant brut — PAS "codex/gpt-5.5"
model_provider = "omniroute"
[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1" # sans barre oblique finale ; l’URL WS est dérivée (utilisez https/wss en production)
wire_api = "responses" # seule valeur prise en charge depuis févr. 2026
supports_websockets = true # active le transport Responses via WS
env_key = "OMNIROUTE_API_KEY" # contient la clé d’API OmniRoute (Bearer)
```
```bash
export OMNIROUTE_API_KEY=sk-... # une clé d’API OmniRoute (n’importe quelle clé si REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```
L’interface en ligne de commande met à niveau `base_url + /responses` vers une connexion WebSocket, et OmniRoute établit un tunnel
vers la connexion OAuth codex sélectionnée. Validation de bout en bout effectuée avec le serveur
local : ChatGPT renvoie `codex.rate_limits` + `response.created` et diffuse progressivement la
réponse.
---
## Quotas et signalement des problèmes
| Méthode | Chemin | Description |
| ------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
| GET | `/v1/quotas/check` | Prévalider le quota pour un `provider` + `accountId` avant d’émettre une clé enregistrée |
| POST | `/v1/issues/report` | Signaler à GitHub un échec de quota ou d’émission de clé (nécessite `GITHUB_ISSUES_REPO` + un jeton) |
**Authentification :** clé API Bearer (`isAuthenticated`).
---
## Utilisation en libre-service (`/api/usage/om-usage`)
Toute clé API peut consulter **sa propre** utilisation et ses propres quotas, sans authentification de gestion. Il s’agit du point de terminaison qu’un
client (CLI, panneau OmniCopilot) utilise pour afficher les dépenses du détenteur d’une clé.
```bash
# Format texte (le contrat historique — texte brut pour un terminal)
curl -H "Authorization: Bearer <votre-clé-api>" \
http://localhost:20128/api/usage/om-usage
# Format structuré — celui qu’utilise une interface utilisateur
curl -H "Authorization: Bearer <votre-clé-api>" \
"http://localhost:20128/api/usage/om-usage?format=json"
```
La clé doit avoir **`allowUsageCommand`** activé (désactivé par défaut — le gestionnaire de clés API
du tableau de bord l’active ou le désactive pour chaque clé). Sans cette option, le point de terminaison répond avec `403`.
`?format=json` renvoie une structure discriminée afin qu’un appelant ne lise jamais un champ de données dans une
réponse de refus. En cas de réussite :
```jsonc
{
"allowed": true,
// présent uniquement lorsque la clé a activé des limites d’utilisation propres à la clé (USD quotidiens/hebdomadaires) :
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// instantané du quota du fournisseur sélectionné, ou null si rien n’est encore mis en cache :
"provider": {
"connectionId": "…",
"provider": "claude",
"plan": "…",
"quotas": {/* … */},
},
// instantané de chaque connexion, afin qu’une interface puisse afficher plusieurs fournisseurs côte à côte :
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
```
En cas de refus (`401` clé incorrecte / `403` accès non autorisé), la même route renvoie
`{ "allowed": false, "error": { "message": "…" } }` — un champ `personal`/`provider` présent mais vide
(clé autorisée, aucune donnée obtenue pour le moment) représente un état différent d’un refus, et seul le format JSON
permet de les distinguer.
**Authentification :** la propre clé API Bearer de l’appelant, validée avec `isValidApiKey` — il ne s’agit _pas_ de
l’interface de gestion (`/api/keys/…`), qui reste protégée par `requireManagementAuth`.
---
## Cache sémantique
```bash
# Obtenir les statistiques du cache
GET /api/cache/stats
# Vider tous les caches
DELETE /api/cache/stats
```
Exemple de réponse :
```json
{
"semanticCache": {
"memorySize": 42,
"memoryMaxSize": 500,
"dbSize": 128,
"hitRate": 0.65
},
"idempotency": {
"activeKeys": 3,
"windowMs": 5000
}
}
```
### Impact sur la latence
Une correspondance dans le cache sémantique sert la réponse depuis le cache **sans appel
en amont** ; la valeur `X-OmniRoute-Response-Latency` indiquée est donc proche de zéro
(indépendamment de la latence initiale du service en amont). Les clients sensibles à la latence
(évaluation des performances, surveillance p50/p99) doivent vérifier l’en-tête de réponse
`X-OmniRoute-Cache-Latency` :
| Valeur | Signification |
| ----------- | ------------------------------------------------------------------------------------ |
| `synthetic` | Réponse servie depuis le cache ; la latence ne correspond pas au temps réel en amont |
| _(absent)_ | Réponse issue d’un véritable appel en amont |
### Contournement du cache par clé
Les clés API peuvent désactiver la lecture du cache sémantique via `cacheDefaultMode` :
| Valeur | Comportement |
| -------- | ------------------------------------------------------------------------------------ |
| `legacy` | Comportement normal du cache (par défaut) |
| `bypass` | Ignore entièrement la recherche dans le cache ; appelle toujours le service en amont |
À définir lors de la création de la clé (`POST /api/keys`) ou de sa mise à jour (`PATCH /api/keys/[id]`) :
```json
{ "cacheDefaultMode": "bypass" }
```
### Contournement par requête
Toute requête peut contourner le cache, quels que soient les paramètres de la clé :
```
X-OmniRoute-No-Cache: true
```
---
## Tableau de bord et gestion
Les routes de gestion (`/api/*` à l’exception de l’authentification/connexion publique) ne sont **pas** autorisées par les clés API d’inférence ordinaires. Familles d’identifiants, portées et exemples curl :
[Authentification de gestion](../guides/MANAGEMENT-AUTH.md).
### Authentification
| Point de terminaison | Méthode | Description |
| ----------------------------- | ------- | --------------------------------------- |
| `/api/auth/login` | POST | Connexion |
| `/api/auth/logout` | POST | Déconnexion |
| `/api/settings/require-login` | GET/PUT | Activer/désactiver la connexion requise |
### Gestion des fournisseurs
| Point de terminaison | Méthode | Description |
| ---------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `/api/providers` | GET/POST | Répertorier/créer des fournisseurs |
| `/api/providers/[id]` | GET/PUT/DELETE | Gérer un fournisseur |
| `/api/providers/[id]/test` | POST | Tester la connexion au fournisseur |
| `/api/providers/[id]/models` | GET | Répertorier les modèles du fournisseur |
| `/api/providers/validate` | POST | Valider la configuration du fournisseur |
| `/api/providers/bulk` | POST | Ajouter en masse des clés API pour UN fournisseur |
| `/api/providers/import` | POST | Importer une LISTE hétérogène de fournisseurs depuis un fichier CSV/JSON analysé (#6836) ; résultats d’échec partiel par ligne |
| `/api/provider-nodes*` | Diverses | Gestion des nœuds de fournisseurs |
| `/api/provider-models` | GET/POST/PATCH/DELETE | Modèles personnalisés (ajouter, mettre à jour, masquer/afficher, supprimer) |
### Flux OAuth
| Point de terminaison | Méthode | Description |
| -------------------------------- | -------- | ------------------------------- |
| `/api/oauth/[provider]/[action]` | Diverses | OAuth spécifique au fournisseur |
### Routage et configuration
| Point de terminaison | Méthode | Description |
| --------------------- | -------- | ---------------------------------------- |
| `/api/models/alias` | GET/POST | Alias de modèles |
| `/api/models/catalog` | GET | Tous les modèles par fournisseur et type |
| `/api/combos*` | Diverses | Gestion des combinaisons |
| `/api/keys*` | Diverses | Gestion des clés API |
| `/api/pricing` | GET | Tarification des modèles |
### Utilisation et analyses
| Point de terminaison | Méthode | Description |
| -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history` | GET | Historique d’utilisation |
| `/api/usage/logs` | GET | Journaux d’utilisation |
| `/api/usage/request-logs` | GET | Journaux au niveau des requêtes |
| `/api/usage/[connectionId]` | GET | Utilisation par connexion |
| `/api/usage/token-limits` | GET/POST/DELETE | Budgets de limite de jetons par clé API |
| `/api/usage/model-latency-stats` | GET | Agrégat glissant de latence par fournisseur/modèle (moyenne/p50/p95/p99, taux de réussite) ; filtres : `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) |
| `/api/usage/cache-health` | GET | Résumé de l’état du cache de prompts sur `call_logs` — ratio écriture/lecture, distribution p50/p90/p99 de la taille des écritures, concentration des écritures volumineuses, ventilation par modèle et verdict `healthy`/`degraded`/`thrash`/`no-data` ; paramètres de requête `range` (`1h`\|`24h`\|`7d`\|`30d`, valeur par défaut `24h`) et `model` facultatif (#8827) |
### Paramètres
| Point de terminaison | Méthode | Description |
| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings` | GET/PUT/PATCH | Paramètres généraux |
| `/api/settings/proxy` | GET/PUT | Configuration du proxy réseau |
| `/api/settings/proxy/test` | POST | Tester la connexion au proxy |
| `/api/settings/ip-filter` | GET/PUT | Liste d’autorisation/liste de blocage des adresses IP |
| `/api/settings/thinking-budget` | GET/PUT | Mode de réécriture des **requêtes** pour le budget de réflexion/raisonnement (transmission directe / suppression automatique / personnalisé / adaptatif). Indépendant de la compression. Voir [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). |
| `/api/settings/system-prompt` | GET/PUT | Prompt système global |
| `/api/settings/compression` | GET/PUT | Configuration globale de la compression |
| `/api/settings/purge-request-history` | POST | Effacer les lignes du journal des requêtes et les artefacts locaux du journal des appels |
### Contexte et compression
| Endpoint | Méthode | Description |
| -------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------- |
| `/api/compression/preview` | POST | Prévisualiser la compression off/lite/standard/aggressive/ultra/RTK/stacked |
| `/api/compression/language-packs` | GET | Répertorier les packs linguistiques Caveman disponibles |
| `/api/compression/rules` | GET | Répertorier les métadonnées des règles Caveman |
| `/api/context/caveman/config` | GET/PUT | Alias des paramètres propres à Caveman |
| `/api/context/rtk/config` | GET/PUT | Paramètres propres à RTK, notamment les filtres personnalisés et la conservation de la sortie brute |
| `/api/context/rtk/filters` | GET | Catalogue des filtres RTK et diagnostics des filtres personnalisés |
| `/api/context/rtk/test` | POST | Exécuter une prévisualisation/un test RTK sur une charge utile textuelle |
| `/api/context/rtk/raw-output/[id]` | GET | Lire la sortie brute expurgée conservée à l’aide de l’identifiant de pointeur |
| `/api/context/combos` | GET/POST | Répertorier/créer des combinaisons de compression |
| `/api/context/combos/[id]` | GET/PUT/DELETE | Détails/mise à jour/suppression d’une combinaison de compression |
| `/api/context/combos/[id]/assignments` | GET/PUT | Affecter des combinaisons de compression à des combinaisons de routage |
| `/api/context/analytics` | GET | Alias des analyses de compression |
### Surveillance
| Endpoint | Méthode | Description |
| ------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions` | GET | Suivi des sessions actives |
| `/api/rate-limits` | GET | Limites de débit par compte |
| `/api/monitoring/health` | GET | Contrôle d’intégrité + résumé des fournisseurs (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). La vue de gestion inclut `credentialHealth` : valeurs scalaires du cache de sondes, `failedConnections` lorsque `failed>0`, et `staleDbNonOkCount` (`test_status` persistant de SQLite, et non la jauge). Voir [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/api/cache/stats` | GET/DELETE | Statistiques du cache / effacement |
| `/api/modality-bridge/stats` | GET | `attempts` en mémoire, réussites/`bridged`, échecs, accès au cache, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` calculée selon le nombre d’échantillons et heure de la dernière utilisation (réinitialisés au redémarrage ; authentification de gestion) |
| `/api/modality-bridge/video/runtime` | GET | Vérification stricte de la boucle locale de confiance avant l’authentification/la sonde de gestion ; disponibilité et versions nettoyées de FFmpeg/ffprobe (sans stockage) |
| `/api/modality-bridge/video/extract` | POST | Courtier interne authentifié d’octets sur boucle locale de confiance ; entrée de 50 Mio, file d’attente limitée/sortie de 32 Mio, capacité `503`, déconnexion `499`, délai dépassé `504` ; ne constitue pas une API publique de téléversement |
### Sauvegarde et exportation/importation
| Endpoint | Méthode | Description |
| --------------------------- | ------- | --------------------------------------------------------------- |
| `/api/db-backups` | GET | Répertorier les sauvegardes disponibles |
| `/api/db-backups` | PUT | Créer une sauvegarde manuelle |
| `/api/db-backups` | POST | Restaurer à partir d’une sauvegarde spécifique |
| `/api/db-backups/export` | GET | Télécharger la base de données au format .sqlite |
| `/api/db-backups/import` | POST | Importer un fichier .sqlite pour remplacer la base de données |
| `/api/db-backups/exportAll` | GET | Télécharger la sauvegarde complète sous forme d’archive .tar.gz |
### Synchronisation cloud
| Endpoint | Méthode | Description |
| ---------------------- | ------- | ----------------------------------- |
| `/api/sync/cloud` | Divers | Opérations de synchronisation cloud |
| `/api/sync/initialize` | POST | Initialiser la synchronisation |
| `/api/cloud/*` | Divers | Gestion du cloud |
### Tunnels
| Endpoint | Méthode | Description |
| -------------------------- | ------- | ------------------------------------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET | Consulter l’état d’installation et d’exécution de Cloudflare Quick Tunnel dans le tableau de bord |
| `/api/tunnels/cloudflared` | POST | Activer ou désactiver Cloudflare Quick Tunnel (`action=enable/disable`) |
| `/api/tunnels/ngrok` | GET | Consulter l’état d’exécution de ngrok Tunnel dans le tableau de bord |
| `/api/tunnels/ngrok` | POST | Activer ou désactiver ngrok Tunnel (`action=enable/disable`) |
### Outils CLI
| Endpoint | Méthode | Description |
| ---------------------------------- | ------- | --------------------------------------- |
| `/api/cli-tools/claude-settings` | GET | État de Claude CLI |
| `/api/cli-tools/codex-settings` | GET | État de Codex CLI |
| `/api/cli-tools/droid-settings` | GET | État de Droid CLI |
| `/api/cli-tools/openclaw-settings` | GET | État d’OpenClaw CLI |
| `/api/cli-tools/runtime/[toolId]` | GET | Environnement d’exécution CLI générique |
Les réponses CLI incluent : `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
### Agents ACP
| Endpoint | Méthode | Description |
| ----------------- | ------- | ------------------------------------------------------------------------------- |
| `/api/acp/agents` | GET | Répertorier tous les agents détectés (intégrés et personnalisés) avec leur état |
| `/api/acp/agents` | POST | Ajouter un agent personnalisé ou actualiser le cache de détection |
| `/api/acp/agents` | DELETE | Supprimer un agent personnalisé via le paramètre de requête `id` |
La réponse GET inclut `agents[]` (id, name, binary, version, installed, protocol, isCustom) et `summary` (total, installed, notFound, builtIn, custom).
### Résilience et limites de débit
| Endpoint | Méthode | Description |
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/resilience` | GET/PATCH | Consulter/mettre à jour la file d’attente des requêtes, le délai de récupération des connexions, le disjoncteur des fournisseurs et les paramètres d’attente |
| `/api/resilience/reset` | POST | Réinitialiser les disjoncteurs des fournisseurs |
| `/api/resilience/model-cooldowns` | GET | Répertorier les blocages actifs par (fournisseur, connexion, modèle), triés par durée restante |
| `/api/resilience/model-cooldowns` | DELETE | Supprimer un blocage de modèle — corps `{provider, model}` ou `{all: true}` pour tout effacer |
| `/api/rate-limits` | GET | État de la limite de débit par compte |
| `/api/rate-limit` | GET | Configuration globale de la limite de débit |
> Les quatre routes `/api/resilience/*` nécessitent une **authentification de gestion** (`requireManagementAuth`). Consultez [Résilience (détaillée)](#resilience-extended) pour une présentation complète des différences entre le disjoncteur de fournisseur, le délai de récupération de connexion et le blocage de modèle.
### Évaluations
| Endpoint | Méthode | Description |
| ------------ | -------- | ------------------------------------------------------------- |
| `/api/evals` | GET/POST | Répertorier les suites d’évaluation / exécuter une évaluation |
### Politiques
| Endpoint | Méthode | Description |
| --------------- | --------------- | ------------------------------- |
| `/api/policies` | GET/POST/DELETE | Gérer les politiques de routage |
### Conformité
| Endpoint | Méthode | Description |
| --------------------------- | ------- | ------------------------------------------ |
| `/api/compliance/audit-log` | GET | Journal d’audit de conformité (N derniers) |
### v1beta (compatible avec Gemini)
| Endpoint | Méthode | Description |
| -------------------------- | ------- | ---------------------------------------- |
| `/v1beta/models` | GET | Répertorier les modèles au format Gemini |
| `/v1beta/models/{...path}` | POST | Endpoint Gemini `generateContent` |
Ces endpoints reproduisent le format de l’API Gemini pour les clients qui nécessitent une compatibilité native avec le SDK Gemini.
### API internes / système
| Endpoint | Méthode | Description |
| ------------------------ | ------- | --------------------------------------------------------------------------------- |
| `/api/init` | GET | Vérification de l'initialisation de l'application (utilisée au premier démarrage) |
| `/api/tags` | GET | Étiquettes de modèles compatibles avec Ollama (pour les clients Ollama) |
| `/api/restart` | POST | Déclenche le redémarrage contrôlé du serveur |
| `/api/shutdown` | POST | Déclenche l'arrêt contrôlé du serveur |
| `/api/system/env/repair` | POST | Répare les variables d'environnement du fournisseur OAuth |
> **Remarque :** Ces endpoints sont utilisés en interne par le système ou pour assurer la compatibilité avec les clients Ollama. Ils ne sont généralement pas appelés par les utilisateurs finaux.
### Réparation de l'environnement OAuth _(v3.6.1+)_
```bash
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
```
Répare les variables d'environnement OAuth manquantes ou corrompues pour un fournisseur spécifique. Renvoie :
```json
{
"success": true,
"repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
"backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}
```
---
## Transcription audio
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```
Transcrivez des fichiers audio à l’aide de n’importe quel fournisseur STT configuré. Le premier segment du chemin sélectionne le fournisseur natif (`openai/…`, `deepgram/…`). Les passerelles qui réexportent le modèle d’un autre fournisseur utilisent un identifiant qualifié (`openrouter/deepgram/nova-3`).
**Requête :**
```bash
curl -X POST http://localhost:20128/v1/audio/transcriptions \
-H "Authorization: Bearer your-api-key" \
-F "file=@recording.mp3" \
-F "model=openai/whisper-1"
```
**Réponse :**
```json
{
"text": "Bonjour, ceci est le contenu audio transcrit.",
"task": "transcribe",
"language": "en",
"duration": 12.5
}
```
**Exemples d’identifiants de modèles :** `openai/whisper-1` (nécessite une clé OpenAI),
`openrouter/deepgram/nova-3` (nécessite une clé OpenRouter),
`deepgram/nova-3` (nécessite une clé Deepgram native). Une requête simple
`deepgram/nova-3` n’utilise **pas** OpenRouter.
**Formats pris en charge :** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
---
## Compatibilité avec Ollama
Pour les clients qui utilisent le format d’API d’Ollama :
```bash
# Point de terminaison de chat (format Ollama)
POST /v1/api/chat
# Liste des modèles (format Ollama)
GET /api/tags
```
Les requêtes sont automatiquement traduites entre les formats Ollama et internes.
## Alias avec jeton pour VS Code / sans en-tête
Utilisez ces alias lorsqu’une intégration ne peut pas injecter d’en-tête `Authorization` et nécessite que la clé API soit intégrée dans l’URL de base.
```bash
# Alias du catalogue au format OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# Alias de chat au format OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Alias au format Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```
Exemple :
```bash
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":"bonjour"}]}'
```
Remarques :
- Les alias avec jeton réutilisent les mêmes gestionnaires que `/v1/*` et `/api/tags` ; les formats de réponse restent identiques.
- Privilégiez `Authorization: Bearer ...` lorsque le client prend en charge les en-têtes personnalisés.
- Les jetons intégrés aux URL peuvent apparaître dans les journaux des proxys inverses, l’historique des navigateurs et la télémétrie en dehors d’OmniRoute. Considérez-les comme une option de compatibilité, et non comme le mode d’authentification par défaut.
---
## Télémétrie
```bash
# Obtenir le résumé de la télémétrie de latence (p50/p95/p99 par fournisseur)
GET /api/telemetry/summary
```
**Réponse :**
```json
{
"providers": {
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
}
}
```
---
## Budget
```bash
# Obtenir l’état du budget pour toutes les clés API
GET /api/usage/budget
# Définir ou mettre à jour un budget
POST /api/usage/budget
Content-Type: application/json
{
"apiKeyId": "key-123",
"dailyLimitUsd": 5.00,
"weeklyLimitUsd": 30.00,
"monthlyLimitUsd": 100.00,
"warningThreshold": 0.8,
"resetInterval": "monthly"
}
```
> **Remarques sur le schéma** (`setBudgetSchema`) : `apiKeyId` est obligatoire ; au moins l’une des valeurs `dailyLimitUsd`, `weeklyLimitUsd` ou `monthlyLimitUsd` doit être supérieure à zéro. Champs facultatifs : `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). L’ancien format `{keyId, limit, period}` renvoie `400 Bad Request`.
## Limites de jetons
Budgets de **jetons** par clé d’API (distincts du budget en USD ci-dessus). Ils sont appliqués directement lors du traitement de la requête : lorsque l’utilisation d’une clé pendant la fenêtre en cours atteint sa limite, les requêtes sont rejetées avec `429 Too Many Requests`. Les limites peuvent être restreintes à un `model` spécifique, à un `provider`, ou appliquées `global`ement à l’ensemble de la clé ; lorsque plusieurs limites correspondent à une requête, la plus restrictive l’emporte.
```bash
# Répertorier les limites de jetons d’une clé (inclut l’utilisation en temps réel de la fenêtre)
GET /api/usage/token-limits?apiKeyId=key-123
# Créer ou mettre à jour une limite de jetons
POST /api/usage/token-limits
Content-Type: application/json
{
"apiKeyId": "key-123",
"scopeType": "model",
"scopeValue": "openai/gpt-4o",
"tokenLimit": 1000000,
"resetInterval": "monthly",
"enabled": true
}
# Supprimer une limite de jetons par identifiant
DELETE /api/usage/token-limits?id=tl-abc
```
> **Remarques sur le schéma** (`setTokenLimitSchema`) : `apiKeyId` et `scopeType` (`model` | `provider` | `global`) sont obligatoires. `scopeValue` est obligatoire, sauf si `scopeType` vaut `global` (par exemple, un identifiant de modèle pour la portée `model`, ou un identifiant de fournisseur pour la portée `provider`). `tokenLimit` doit être un entier positif (converti depuis une chaîne). Facultatifs : `id` (omettre pour créer, fournir pour mettre à jour), `resetInterval` (`daily` | `weekly` | `monthly`, valeur par défaut `monthly`), `resetTime` (`HH:MM`), `enabled` (valeur par défaut `true`). Les réponses `GET` enrichissent chaque limite avec `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` et `nextResetAt`. Il s’agit d’un point de terminaison de gestion (l’authentification est appliquée de manière centralisée par le pipeline d’autorisation).
## Traitement des requêtes
1. Le client envoie une requête à `/v1/*`
2. Le gestionnaire de route appelle `handleChat`, `handleEmbedding`, `handleAudioTranscription` ou `handleImageGeneration`
3. Le modèle est résolu (fournisseur/modèle direct ou alias/combo)
4. Les identifiants sont sélectionnés depuis la base de données locale avec filtrage selon la disponibilité des comptes
5. Pour le chat : `handleChatCore` vérifie le cache sémantique/de signature et résout les paramètres de compression du combo
6. La compression proactive s’exécute avant la traduction pour le fournisseur lorsqu’elle est activée (`lite`, Caveman, RTK ou empilée)
7. L’exécuteur du fournisseur envoie la requête en amont
8. La réponse est retraduite au format du client (chat) ou renvoyée telle quelle (embeddings/images/audio)
9. L’utilisation, les analyses de compression et les journaux de requêtes sont enregistrés
10. Un repli est appliqué en cas d’erreur conformément aux règles du combo
Référence complète de l’architecture : [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)
---
## Gestion des combos
Les combos de routage de plus haut niveau (déjà résumés sous `/api/combos*`) peuvent également être associés individuellement à partir d’un motif d’identifiant de modèle, ce qui permet la redirection transparente d’un identifiant de modèle de style OpenAI vers un combo.
| Méthode | Chemin | Description |
| ------- | -------------------------------- | --------------------------------------------------------------------------------------- |
| GET | `/api/model-combo-mappings` | Répertorier toutes les associations modèle→combo |
| POST | `/api/model-combo-mappings` | Créer une association — corps : `{pattern, comboId, priority?, enabled?, description?}` |
| GET | `/api/model-combo-mappings/[id]` | Récupérer une association spécifique |
| PUT | `/api/model-combo-mappings/[id]` | Mettre à jour les champs d’une association existante |
| DELETE | `/api/model-combo-mappings/[id]` | Supprimer une association |
**Authentification :** session/clé d’API de gestion (`requireManagementAuth`).
---
## Webhooks
Abonnements aux webhooks sortants pour les événements OmniRoute (fin d’une requête, épuisement d’un quota, rotation d’une clé, etc.).
| Méthode | Chemin | Description |
| ------- | ------------------------- | -------------------------------------------------------------------------------------- |
| GET | `/api/webhooks` | Répertorier les webhooks (les secrets sont masqués sous la forme `<prefix>...`) |
| POST | `/api/webhooks` | Créer un webhook — corps : `{url, events?: ["*"], secret?, description?}` |
| GET | `/api/webhooks/[id]` | Récupérer un webhook |
| PUT | `/api/webhooks/[id]` | Mettre à jour url/events/secret/description |
| DELETE | `/api/webhooks/[id]` | Supprimer un webhook |
| POST | `/api/webhooks/[id]/test` | Envoyer une charge utile de test à l’URL du webhook et renvoyer l’état de la livraison |
**Authentification :** session de gestion/clé d’API (`requireManagementAuth`).
---
## Clés enregistrées (gestion automatique)
Utilisées par le sous-système de gestion automatique des clés pour émettre et renouveler des clés d’API auprès d’un fournisseur/compte sous-jacent, avec des quotas quotidiens/horaires.
| Méthode | Chemin | Description |
| ------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/v1/registered-keys` | Répertorier les clés enregistrées (préfixe masqué uniquement) |
| POST | `/api/v1/registered-keys` | Émettre une nouvelle clé enregistrée — corps : `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Renvoie la clé brute **une seule fois**. Renvoie `429` en cas de refus lié au quota. |
| GET | `/api/v1/registered-keys/[id]` | Récupérer les métadonnées d’une clé enregistrée (sans données brutes) |
| DELETE | `/api/v1/registered-keys/[id]` | Révoquer une clé enregistrée |
| POST | `/api/v1/registered-keys/[id]/revoke` | Point de terminaison de révocation explicite (même effet que DELETE) |
**Authentification :** clé d’API Bearer (`isAuthenticated`). Voir également `/v1/quotas/check` et `/v1/issues/report`.
---
## Protocole des agents
Tâches d’agents cloud (Claude Code, Codex Cloud, OpenHands, etc.) exécutées à distance pour le compte des utilisateurs d’OmniRoute.
| Méthode | Chemin | Description |
| ------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/agents/tasks` | Répertorie les tâches — paramètres facultatifs `?provider=`, `?status=`, `?limit=` (1–500, 50 par défaut) |
| POST | `/api/v1/agents/tasks` | Crée une tâche — corps validé par `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Renvoie `201` avec l’enveloppe de la tâche |
| DELETE | `/api/v1/agents/tasks?id=...` | Supprime une tâche |
| GET | `/api/v1/agents/tasks/[id]` | Lit la tâche — actualise de manière synchrone son statut depuis l’agent cloud en amont lorsqu’un `external_id` est défini |
| POST | `/api/v1/agents/tasks/[id]` | Action discriminée : `{action: "approve"}`, `{action: "message", message}` ou `{action: "cancel"}` |
| DELETE | `/api/v1/agents/tasks/[id]` | Supprime une tâche spécifique par identifiant |
> **Authentification :** une authentification de gestion est requise pour chaque méthode (`requireCloudAgentManagementAuth`). Avant la v3.8.0, ces méthodes n’étaient pas authentifiées — consultez le commit `588a0333` pour cette modification incompatible.
```bash
# Créer une tâche cloud Claude Code
curl -X POST http://localhost:20128/api/v1/agents/tasks \
-H "Authorization: Bearer your-management-key" \
-H "Content-Type: application/json" \
-d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'
```
---
## Proxys de gestion
Proxys HTTP(S)/SOCKS sortants pouvant être affectés à des fournisseurs, à des comptes ou globalement.
| Méthode | Chemin | Description |
| ------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/management/proxies` | Répertorie les proxys (avec `?id=`, en renvoie un ; avec `?id=&where_used=1`, renvoie le graphe des affectations) |
| POST | `/api/v1/management/proxies` | Crée un proxy — corps validé par `createProxyRegistrySchema` |
| PATCH | `/api/v1/management/proxies` | Met à jour un proxy — corps validé par `updateProxyRegistrySchema` (`id` requis) |
| DELETE | `/api/v1/management/proxies?id=...&force=1` | Supprime un proxy (utilisez `force=1` pour dissocier les affectations) |
| GET | `/api/v1/management/proxies/assignments` | Répertorie les affectations — filtrables par `proxy_id`, `scope`, `scope_id` ; transmettez `resolve_connection_id=<id>` pour déterminer le proxy actif d’une connexion |
| PUT | `/api/v1/management/proxies/assignments` | Affecte — corps validé par `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Vide le cache du répartiteur |
| PUT | `/api/v1/management/proxies/bulk-assign` | Affecte en masse — corps validé par `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) |
| GET | `/api/v1/management/proxies/health?hours=24` | Agrège l’état de santé des proxys (nombre de réussites/d’échecs, latence) sur une période donnée |
**Authentification :** session de gestion/clé d’API requise sur chaque route (`requireManagementAuth`).
> Les routes `POST /api/v1/management/proxies/[id]/assignments` et `POST /api/v1/management/proxies/[id]/health` mentionnées dans la description de la tâche sont fournies par les routes plates `/assignments` et `/health` présentées ci-dessus — il n’existe aucune sous-route par identifiant dans la base de code.
---
## Résilience (étendue)
OmniRoute expose trois mécanismes indépendants de gestion des défaillances temporaires ; les points de terminaison de gestion ci-dessous permettent aux opérateurs de les consulter et de les remplacer :
| Portée | Stockage de l’état | Consultation | Réinitialisation / effacement |
| -------------------------- | ------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------- |
| Disjoncteur du fournisseur | `domain_circuit_breakers` + en mémoire | `/api/monitoring/health` | `POST /api/resilience/reset` |
| Délai de connexion | `rateLimitedUntil` sur les connexions fournisseur | `/api/rate-limits`, `/api/providers/[id]` | (réactivation différée ; effacement via PUT sur le fournisseur) |
| Verrouillage du modèle | Registre en mémoire de disponibilité des modèles | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` |
`PATCH /api/resilience` accepte les remplacements de disjoncteur du fournisseur sous `providerBreaker.oauth` et `providerBreaker.apikey`. Chaque profil prend en charge `degradationThreshold`, `failureThreshold` et `resetTimeoutMs` ; les mêmes champs sont disponibles dans Tableau de bord → Paramètres → Résilience.
```bash
# Effacer le verrouillage d’un seul modèle
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"}'
# Effacer tous les verrouillages
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
```
Pour la référence conceptuelle complète et les valeurs par défaut des disjoncteurs, consultez [`CLAUDE.md`](../../CLAUDE.md) → « État d’exécution de la résilience ».
---
## Compétences
Cadre de compétences permettant d’étendre OmniRoute avec des gestionnaires exécutables personnalisés, ainsi que des intégrations de places de marché.
| Méthode | Chemin | Description |
| ------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/skills` | Répertorie les compétences installées — filtrables par `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, avec pagination |
| GET | `/api/skills/[id]` | Récupère une compétence |
| PUT | `/api/skills/[id]` | Met à jour une compétence (nom, description, mode, schéma, gestionnaire, étiquettes) |
| DELETE | `/api/skills/[id]` | Désinstalle une compétence |
| POST | `/api/skills/install` | Installe une compétence à partir d’un manifeste brut — corps : `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
| GET | `/api/skills/executions` | Répertorie les exécutions récentes de compétences (journal d’audit avec entrées/sorties/durée) |
| GET | `/api/skills/marketplace?q=...` | Recherche/liste des compétences populaires de la place de marché SkillsMP (nécessite le paramètre `skillsmpApiKey`) |
| POST | `/api/skills/marketplace/install` | Installe une compétence par identifiant depuis SkillsMP |
| GET | `/api/skills/skillssh?q=&limit=` | Recherche dans le registre skills.sh |
| POST | `/api/skills/skillssh/install` | Installe une compétence par identifiant depuis skills.sh |
**Authentification :** session de gestion/clé API. Les routes de recherche des places de marché acceptent soit l’authentification de gestion, soit une clé API Bearer (`isAuthenticated`).
---
## Mémoire
Stockage persistant de la mémoire conversationnelle/factuelle, limité par clé API / session.
| Méthode | Chemin | Description |
| ------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/memory` | Répertorie les souvenirs — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, avec une pagination `offset/limit` ou `page/limit` |
| POST | `/api/memory` | Crée un souvenir — corps validé par Zod : `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET | `/api/memory/[id]` | Récupère un souvenir |
| DELETE | `/api/memory/[id]` | Supprime un souvenir |
| GET | `/api/memory/health` | État du sous-système de mémoire (connectivité à la base de données, backend d'embeddings, état de l'index vectoriel) |
**Authentification :** session de gestion/clé API (`requireManagementAuth`). Énumération `type` : `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (voir `MemoryType` dans `src/lib/memory/types.ts`).
---
## Serveur MCP
OmniRoute intègre un serveur Model Context Protocol avec 3 transports (stdio, SSE, streamable-http) et des outils à portée limitée. Les endpoints du tableau de bord ci-dessous lisent les données d'état/d'audit et servent de proxy aux transports HTTP.
| Méthode | Chemin | Description |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Signal de présence, transport, état en ligne, dernier appel, principaux outils, taux de réussite sur 24 h |
| GET | `/api/mcp/tools` | Liste des outils MCP avec `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
| GET | `/api/mcp/sse` | Ouvre un flux SSE pour le transport SSE (renvoie `503` si MCP est désactivé ou si le transport ne correspond pas) |
| POST | `/api/mcp/sse` | Envoie une trame JSON-RPC sur le transport SSE |
| GET | `/api/mcp/stream` | Ouvre le côté SSE du transport HTTP streamable (messages initiés par le serveur) |
| POST | `/api/mcp/stream` | Envoie une trame JSON-RPC sur le transport HTTP streamable |
| DELETE | `/api/mcp/stream` | Met fin à une session HTTP streamable |
| GET | `/api/mcp/audit` | Interroge le journal d'audit — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | Statistiques d'audit agrégées (totaux, taux de réussite, durée moyenne, principaux outils) |
**Authentification :** les transports `sse`/`stream` respectent le mécanisme d'authentification propre à MCP (clé API Bearer avec la portée `mcp`) ; les routes `status`/`tools`/`audit*` sont accessibles depuis le tableau de bord (aucune authentification supplémentaire n'est requise au-delà de l'accès à l'hôte du tableau de bord).
> Les deux transports HTTP sont contrôlés par `settings.mcpEnabled` et `settings.mcpTransport` — une incompatibilité de transport renvoie `400`, tandis qu'un état MCP désactivé renvoie `503`.
---
## Serveur A2A
OmniRoute expose un endpoint A2A (Agent-to-Agent) JSON-RPC 2.0 ainsi qu’une surcouche REST pour les besoins d’inspection et de tableau de bord.
### JSON-RPC
```bash
POST /a2a
Authorization: Bearer your-api-key # facultatif, sauf si OMNIROUTE_API_KEY est défini
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éthodes prises en charge (toutes conditionnées par `settings.a2aEnabled`) :
| Méthode | Description |
| ---------------- | ---------------------------------------------------------------------------- |
| `message/send` | Exécution synchrone d’une compétence ; renvoie `{task, artifacts, metadata}` |
| `message/stream` | Exécution SSE en streaming du même ensemble de compétences |
| `tasks/get` | Récupère une tâche par `taskId` |
| `tasks/cancel` | Annule une tâche par `taskId` |
Compétences intégrées : `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.
### Fiche de l’agent
```bash
GET /.well-known/agent.json
```
Renvoie la fiche publique de l’agent A2A (nom, description, capacités, catalogue des compétences, schéma d’authentification) — mise en cache publiquement pendant 1 h. Aucune authentification requise.
### Assistants REST
| Méthode | Chemin | Description |
| ------- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/a2a/status` | Activation d’A2A + statistiques des tâches + résumé de la fiche d’agent mise en cache |
| GET | `/api/a2a/tasks` | Répertorie les tâches — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST | `/api/a2a/tasks` | (Non implémenté comme assistant REST — créer via JSON-RPC `message/send`) |
| GET | `/api/a2a/tasks/[id]` | Récupère une tâche |
| POST | `/api/a2a/tasks/[id]/cancel` | Annule une tâche |
**Authentification :** les assistants REST fonctionnent sans authentification de gestion (lisibles depuis le tableau de bord) ; la route JSON-RPC `/a2a` utilise le jeton Bearer `OMNIROUTE_API_KEY` s’il est configuré.
---
## Cloud, évaluations et appréciations
| Méthode | Chemin | Description |
| ------- | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Vérifie une clé Bearer et renvoie les connexions masquées aux fournisseurs ainsi que les alias de modèles pour les clients de synchronisation cloud |
| POST | `/api/cloud/credentials/update` | Met à jour les identifiants chiffrés d’un fournisseur synchronisé avec le cloud |
| POST | `/api/cloud/model/resolve` | Résout un identifiant logique de modèle en un fournisseur/modèle concret à l’aide de la table de routage locale |
| GET | `/api/cloud/models/alias` | Répertorie les alias de modèles tels qu’ils sont exposés à la synchronisation cloud |
| GET | `/api/assess` | Lit les catégorisations de la dernière appréciation (par fournisseur/modèle) |
| POST | `/api/assess` | Exécute une appréciation — corps : `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Répertorie les suites d’évaluation intégrées et les exécutions les plus récentes |
| POST | `/api/evals` | Déclenche une exécution d’évaluation |
| POST | `/api/evals/suites` | Crée une suite d’évaluation personnalisée — corps validé par `evalSuiteSaveSchema` |
| GET | `/api/evals/suites/[id]` | Récupère une suite d’évaluation personnalisée |
**Authentification :** `/api/cloud/auth` valide directement une clé Bearer ; les autres routes `/api/cloud/*`, `/api/evals/*` et `/api/assess` nécessitent une session de gestion/clé API. La requête POST vers `/api/assess` utilise `validateBody` avec un schéma de portée sous forme d’union discriminée.
---
## Gestion d’ACP (Agent Client Protocol)
en tant que processus enfants. Ces points de terminaison gèrent la détection des agents ACP et l’enregistrement d’agents
personnalisés.
| Méthode | Chemin | Description |
| ------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/acp/agents` | Répertorie tous les agents CLI connus (intégrés + personnalisés) avec leur statut d’installation, leur version et leur binaire |
| POST | `/api/acp/agents` | Enregistre un agent ACP personnalisé ou actualise le cache — corps : `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` ou `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Supprime un agent ACP personnalisé — paramètre de requête : `?id=<agentId>` |
**Exemple de réponse** (`GET /api/acp/agents`) :
```json
{
"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
}
```
**Authentification :** nécessite une session de gestion (cookie `auth_token` du tableau de bord) ou une
clé API avec une portée de gestion.
Consultez [Framework ACP](../frameworks/ACP.md) pour plus de détails.
---
## Analytique et observabilité
Points de terminaison d’analytique en temps réel permettant de surveiller le routage, la compression et la diversité
des fournisseurs. Ils alimentent les pages `/dashboard/analytics/*`.
### Analytique du routage automatique
| Méthode | Chemin | Description |
| ------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/auto-routing` | Statistiques agrégées du routage automatique : nombre total d’appels, répartition par stratégie, niveau et fournisseur |
| GET | `/api/analytics/auto-routing?days=7` | Statistiques sur une fenêtre temporelle (24 h par défaut) |
**Exemple de réponse** :
```json
{
"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 }
]
}
```
### Analytique de la compression
| Méthode | Chemin | Description |
| ------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/compression` | Statistiques agrégées de compression : jetons économisés, pourcentage d’économie, répartition par mode et moteur |
**Exemple de réponse** :
```json
{
"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
}
}
```
### Suivi de la diversité des fournisseurs
| Méthode | Chemin | Description |
| ------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/diversity` | Suivi de la diversité fondé sur l’entropie de Shannon : évite les points de défaillance uniques en mesurant la répartition des fournisseurs |
**Exemple de réponse** :
```json
{
"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 représente 40 % du trafic — envisagez de diversifier les fournisseurs"]
}
```
**Authentification :** nécessite une session de gestion ou une clé API avec une portée de gestion.
---
## Opérations d’administration
Points de terminaison réservés aux administrateurs pour la gestion opérationnelle.
| Méthode | Chemin | Description |
| ------- | ------------------------ | ------------------------------------------------------------------------------------------------------------ |
| GET | `/api/admin/concurrency` | Lire les limites de concurrence actuelles (globales et par fournisseur) |
| POST | `/api/admin/concurrency` | Mettre à jour les limites de concurrence — corps : `{global?: number, perProvider?: Record<string, number>}` |
**Authentification :** nécessite une session de gestion avec une portée d’administrateur.
---
## Gestion des outils CLI
Gérez les outils CLI qui s’intègrent à OmniRoute (antigravity, chipotle, commandCode,
devin-cli, etc.). Consultez la [Référence des fournisseurs](./PROVIDER_REFERENCE.md) pour obtenir la liste complète.
| Méthode | Chemin | Description |
| ------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/cli-tools/all-statuses` | État de tous les outils CLI (installation, version, dernière détection) |
| GET | `/api/cli-tools/status` | Détails de l’état d’un outil CLI (`?tool=` dans la requête) |
| POST | `/api/cli-tools/apply` | Écrire la configuration générée d’un outil (`dryRun` fournit un aperçu ; `422` + `containerEphemeralTarget` en cas de conteneurisation ; `migration` signale une ancienne configuration YAML de Codex) |
| GET | `/api/cli-tools/backups` | Répertorier les sauvegardes de configuration des outils CLI |
| POST | `/api/cli-tools/backups` | Créer une sauvegarde de toutes les configurations des outils CLI |
| POST | `/api/cli-tools/backups` | Restaurer : le même point de terminaison avec `{tool, backupId}` dans le corps restaure cette sauvegarde |
| GET | `/api/cli-tools/antigravity-mitm` | État du proxy MITM Antigravity (l’outil CLI « antigravity-mitm ») |
| POST | `/api/cli-tools/antigravity-mitm/alias` | Configurer les alias d’antigravity-mitm |
**Authentification :** nécessite une session de gestion.
---
## Compétences d’agent
Gérez les compétences des agents d’IA (similaires aux GPT personnalisés d’OpenAI, mais destinées aux agents).
| Méthode | Chemin | Description |
| ------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- |
| GET | `/api/agent-skills` | Répertorier toutes les compétences d’agent (intégrées et personnalisées) |
| GET | `/api/agent-skills/[id]` | Obtenir une compétence d’agent spécifique |
| POST | `/api/agent-skills` | Créer une compétence d’agent personnalisée — corps : `{name, description, prompt, model?, temperature?}` |
| PUT | `/api/agent-skills/[id]` | Mettre à jour une compétence d’agent personnalisée |
| DELETE | `/api/agent-skills/[id]` | Supprimer une compétence d’agent personnalisée |
| GET | `/api/agent-skills/[id]/raw` | Obtenir le prompt brut et les métadonnées (sans exécution) |
| POST | `/api/agent-skills/generate` | Générer par IA une nouvelle compétence à partir d’une description en langage naturel |
**Authentification :** nécessite une session de gestion ou une clé API avec une portée de gestion.
---
## Gestion du cache
Gérez le cache sémantique et le cache de raisonnement.
| Méthode | Chemin | Description |
| ------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cache` | Vue d’ensemble du cache : nombre total d’entrées, taux de succès, taille sur le disque |
| GET | `/api/cache/entries` | Répertorier les entrées mises en cache (avec pagination) |
| DELETE | `/api/cache/entries` | Supprimer des entrées du cache (filtrage par paramètres de requête) |
| GET | `/api/cache/stats` | Statistiques détaillées du cache (par fournisseur, par modèle) |
| GET | `/api/cache/reasoning` | État du cache de raisonnement (pour la relecture du raisonnement) |
| DELETE | `/api/cache/reasoning` | Vider le cache de raisonnement — paramètres de requête : `?toolCallId=<id>` (un seul), `?provider=<p>` ou aucun paramètre (tout) |
**Authentification :** nécessite une session de gestion.
---
## Système de mémoire
Gérez la mémoire persistante (FTS5 + plongements vectoriels).
| Méthode | Chemin | Description |
| ------- | ------------------ | -------------------------------------------------------------------------------------------------- |
| GET | `/api/memory` | Répertorier les entrées de mémoire (filtrage par portée, type et requête de recherche) |
| POST | `/api/memory` | Créer une entrée de mémoire — corps : `{scope, type, content, metadata?}` |
| GET | `/api/memory/[id]` | Obtenir une entrée de mémoire spécifique |
| PUT | `/api/memory/[id]` | Mettre à jour une entrée de mémoire |
| DELETE | `/api/memory/[id]` | Supprimer une entrée de mémoire |
| GET | `/api/memory?q=` | Rechercher dans la mémoire (FTS5 + vecteurs) — les statistiques sont incluses dans la même réponse |
**Authentification :** nécessite une session de gestion ou une clé d’API limitée à la gestion.
---
## Webhooks
Gérez les abonnements webhook aux événements.
| Méthode | Chemin | Description |
| ------- | ------------------------------- | -------------------------------------------------------------------------------- |
| GET | `/api/webhooks` | Répertorier tous les abonnements webhook |
| POST | `/api/webhooks` | Créer un abonnement webhook — corps : `{url, events[], secret?, active?}` |
| GET | `/api/webhooks/[id]` | Obtenir un abonnement webhook spécifique |
| PUT | `/api/webhooks/[id]` | Mettre à jour un abonnement webhook |
| DELETE | `/api/webhooks/[id]` | Supprimer un abonnement webhook |
| GET | `/api/webhooks/[id]/deliveries` | Répertorier l’historique des livraisons d’un webhook (journal des succès/échecs) |
| POST | `/api/webhooks/[id]/test` | Envoyer un événement de test à un webhook |
**Authentification :** nécessite une session de gestion.
Consultez [Infrastructure des webhooks](../frameworks/WEBHOOKS.md) pour obtenir la liste complète des types d’événements.
---
## Framework de compétences
Gérez les compétences (le framework d’extensions agentiques).
| Méthode | Chemin | Description |
| ------- | ------------------------ | ---------------------------------------------------------------------------------------------------- |
| GET | `/api/skills` | Répertorier toutes les compétences installées (intégrées + personnalisées) |
| POST | `/api/skills/install` | Installer une compétence depuis un chemin local ou une URL |
| DELETE | `/api/skills/[id]` | Désinstaller une compétence |
| PUT | `/api/skills/[id]` | Activer ou désactiver une compétence — corps : `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST | `/api/skills/executions` | Exécuter une compétence — corps : `{skillName, apiKeyId, input?, sessionId?}` |
| GET | `/api/skills/executions` | Répertorier l’historique d’exécution de toutes les compétences (filtrer par `?apiKeyId=`) |
**Authentification :** nécessite une session de gestion ou une clé API avec une portée de gestion.
Consultez [Framework de compétences](../frameworks/SKILLS.md) pour plus de détails.
---
## Plugins
Gérez les plugins OmniRoute (extensions tierces).
| Méthode | Chemin | Description |
| ------- | ---------------------------------- | ----------------------------------------- |
| GET | `/api/plugins` | Répertorier les plugins installés |
| POST | `/api/plugins/marketplace/install` | Installer un plugin depuis la marketplace |
| DELETE | `/api/plugins/[name]` | Désinstaller un plugin |
| POST | `/api/plugins/[name]/activate` | Activer un plugin |
| POST | `/api/plugins/[name]/deactivate` | Désactiver un plugin |
| GET | `/api/plugins/[name]/config` | Obtenir la configuration du plugin |
| PUT | `/api/plugins/[name]/config` | Mettre à jour la configuration du plugin |
**Authentification :** nécessite une session de gestion.
Consultez [Framework des plugins](../frameworks/PLUGIN_SDK.md) pour plus de détails.
---
## Routage fantôme
La comparaison fantôme / A-B des fournisseurs **ne constitue pas une surface REST autonome** — elle est configurée via le routage combiné (consultez [Auto-Combo](../routing/AUTO-COMBO.md)). Les métriques de comparaison par combinaison sont fournies par `GET /api/combos/metrics`.
---
## Garde-fous
Inspectez les garde-fous d’exécution (détection des informations personnelles, détection des injections de prompt, passerelle de vision). Les garde-fous s’exécutent à chaque requête ; la désactivation pour un appel spécifique s’effectue via l’en-tête de requête `x-omniroute-disabled-guardrails` — il n’existe aucune interface persistante d’activation ou de désactivation.
| Méthode | Chemin | Description |
| ------- | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| GET | `/api/guardrails` | Répertorier les garde-fous enregistrés et leur statut (nom / activé / priorité) |
| POST | `/api/guardrails/test` | Exécuter à blanc le pipeline de pré-appel sur un exemple d’entrée — corps : `{input, disabledGuardrails?}` |
**Authentification :** nécessite une session de gestion.
Consultez [Sécurité > Garde-fous](../security/GUARDRAILS.md) pour plus de détails.
---
---
## Authentification
Consultez [Authentification de gestion](../guides/MANAGEMENT-AUTH.md) pour découvrir les quatre
familles d’identifiants (session du tableau de bord, jeton CLI local, jeton d’accès
`oma_live_…`, clé API avec portée de gestion) et leurs différences avec les clés d’inférence.
- Les routes du tableau de bord (`/dashboard/*`) utilisent le cookie `auth_token`
- La connexion utilise le hachage du mot de passe enregistré, avec repli sur `INITIAL_PASSWORD`
- `requireLogin` peut être activé ou désactivé via `/api/settings/require-login`
- Les routes `/v1/*` peuvent exiger une clé API Bearer lorsque `REQUIRE_API_KEY=true`
- Dans cette référence, « jeton de gestion » / « clé API avec portée de gestion » désigne l’une des familles décrites dans ce guide, et non un type de secret supplémentaire non défini
> **Modification avec rupture de compatibilité (v3.8.0)** — `/api/v1/agents/tasks/*` et les points de terminaison de gestion des délais de récupération exigent désormais une **authentification de gestion** (cookie `auth_token` du tableau de bord ou clé API avec portée de gestion). Les clients qui appelaient auparavant ces routes sans authentification recevront `401 Unauthorized`. Consultez le commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).
Reference in New Issue View Git Blame Copy Permalink