pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-19 21:32:20 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
c07cebbab72106f6d31c259491ff03e6feb954e4
OmniRoute/docs/i18n/et/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

1761 lines
120 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 (Eesti)
🌐 **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) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/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)
---
🌐 **Keeled:** 🇺🇸 [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)
OmniRoute API põhiviide. See hõlmab avalikku `/v1` liidest ja enim kasutatavaid halduse lõpp-punkte; täielikud allikad on masinloetav [`docs/openapi.yaml`](../openapi.yaml) ja marsruudipuu kataloogis `src/app/api/`.
---
## Sisukord
- [Vestluse lõpetused (Chat Completions)](#chat-completions)
- [Eksklusiivsed hallatud seansirendid](#exclusive-managed-session-leases)
- [Manused (Embeddings)](#embeddings)
- [Pildi genereerimine](#image-generation)
- [Dokumendi OCR](#document-ocr)
- [Mudelite loend](#list-models)
- [Teenusepakkuja pluginate manifest](#provider-plugin-manifest)
- [Ühilduvuse lõpp-punktid](#compatibility-endpoints)
- [Failide API](#files-api)
- [Partiide API](#batches-api)
- [Otsingu API](#search-api)
- [WebSocket voogesitus](#websocket-streaming)
- [Kvoodid ja probleemidest teavitamine](#quotas--issues-reporting)
- [Semantiline vahemälu](#semantic-cache)
- [Töölaud ja haldus](#dashboard--management)
- [Kombode haldus](#combo-management)
- [Veebihäälestused (Webhooks)](#webhooks)
- [Registreeritud võtmed (automaatne haldus)](#registered-keys-auto-management)
- [Agentide protokoll](#agents-protocol)
- [Halduse proksid](#management-proxies)
- [Vastupidavus (laiendatud)](#resilience-extended)
- [Oskused](#skills)
- [Mälu](#memory)
- [MCP server](#mcp-server)
- [A2A server](#a2a-server)
- [Pilv, hindamised ja hinnangud (Cloud, Evals & Assess)](#cloud-evals--assess)
- [Päringute töötlemine](#request-processing)
- [Autentimine](#authentication)
---
## Vestluse lõpetused (Chat Completions)
```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
}
```
### Kohandatud päised
| Päis | Suund | Kirjeldus |
| ------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache` | Päring | Määra `true`, et vahemälu mööda jätta |
| `x-omniroute-no-memory` | Päring | Määra `true`, et jätta selle päringu puhul mälu- ja oskuste süstimine vahele (peegeldab no-cache käitumist; hoiab ära iga kõne kohta arvutatud token/kulu üldkulu) |
| `X-OmniRoute-Progress` | Päring | Määra `true`, et saada edenemise sündmusi |
| `X-Session-Id` | Päring | Fikseeritud seansi võti välise seansi püsivuse jaoks |
| `x_session_id` | Päring | Alakriipsuga variant on ka lubatud (otsene HTTP) |
| `X-OmniRoute-Session-Id` | Päring | Kutsuja poolt esitatud seansi/vestluse silt (toidab ka mälu). Kui see on olemas, salvestatakse see sõna-sõnalt väljale `call_logs.session_tag` seansipõhise kulude jaotuse jaoks (#8249) — kunagi ei genereerita, kui see puudub |
| `Idempotency-Key` | Päring | Dubleerimise vastu kaitsev võti (5 s aken) |
| `X-Request-Id` | Päring | Alternatiivne dubleerimise vastane võti |
| `X-OmniRoute-Cache` | Vastus | `HIT` või `MISS` (mitte-voogedastuse korral) |
| `X-OmniRoute-Idempotent` | Vastus | `true`, kui dubleerimine tuvastatud |
| `X-OmniRoute-Progress` | Vastus | `enabled`, kui edenemise jälgimine on sisse lülitatud |
| `X-OmniRoute-Session-Id` | Vastus | OmniRoute'i poolt kasutatud tegelik seansi ID |
| `X-OmniRoute-Request-Id` | Vastus | Päringu korrelatsiooni ID (kui teada) |
| `X-OmniRoute-Version` | Vastus | OmniRoute'i väljalaske versioon (alati olemas) |
| `X-OmniRoute-Cost-Saved` | Vastus | USA dollarites summa, mille vahemälu HIT-i korral vältis (ainult vahemälu tabamuste puhul) |
| `X-OmniRoute-Decision` | Vastus | Ruutimise jälg: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` on kombo strateegia või `single`, kui päring ei ole kombo) — esineb alati lõpetatud vastuste juures |
> Nginxi märkus: kui kasutate alakriipsuga päiseid (näiteks `x_session_id`), lülitage sisse `underscores_in_headers on;`.
> **Kulu telemeetria päised:** edukad mitte-voogedastuse vastused kannavad ka `X-OmniRoute-*` kulu-telemeetria komplekti — `X-OmniRoute-Response-Cost` (USA dollarites, fikseeritud 10 kümnendkohta; `0.0000000000` tasuta/hindamata juhtudel), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit` ja `X-OmniRoute-Fallback-Attempts` (ainult kui > 0), lisaks `X-OmniRoute-Request-Id` ja `X-OmniRoute-Version`. Need saadetakse vestluse lõpetuste, `/v1/responses`, `/v1/messages` **ja meedia lõpp-punktide** poolt — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` ja `/v1/moderations` (kulu alati `0`). Meedia kulu arvutatakse modaliteedi kaupa (pildi, sekundi, tähemärgi või otsinguühiku kohta), kui hinnastamine on olemas, vastasel juhul `0` (fail-open).
> **Vahemälu tabamuse kulu semantika:** semantilise vahemälu HIT-i korral (`X-OmniRoute-Cache-Hit: true`) ei tehta ülesvoolu kõnet, mistõttu `X-OmniRoute-Response-Cost` on `0.0000000000` (tabamuse teenindamise **lisakulu**). Algne/oleks-olnud kulu esitatakse eraldi väljal `X-OmniRoute-Cost-Saved`. Arveldust tegevad tarbijad peaksid liitma `X-OmniRoute-Response-Cost` väärtused (tabamused ei maksa midagi); vahemälu analüütika saab koguda `X-OmniRoute-Cost-Saved` väärtusi.
## Eksklusiivsed halllatavate seansside rendid (leases)
Eksklusiivne halllatava seansi rentimine on liitumispõhine, kliendist sõltumatu ruutimislepe: üks aktiivne omanik hoiab üht sobivat OmniRoute ühendust. See ei rendi mudelit, ei nõua OAuth-i, ei tuvasta konkreetset klienti ega nõua konkreetset teenusepakkujat.
Autentivat API-võtmel peab olema skoop `lease:exclusive` ja selgesõnaline mittetühi `allowedConnections` loend. Andmebaasi mutatsioonipiir jõustab mõlemad väljad koos võtme loomisel ja osalisel uuendamisel.
```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"}
```
Õnnestunud acquire, renew ja release vastused avaldavad ajatemplid, `state` ja täpse positiivse `generation`, kuid mitte kunagi valitud ühendust või mandaate. Renew ja release edastavad generation väärtuse JSON-kehas:
```json
{ "action": "renew", "generation": 1 }
```
```json
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
```
Aktiivne rendi omanik saab selgesõnaliselt küsida privaatsust arvestavat kuvamismetaandmestikku oma praeguse seose kohta:
```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"
}
}
```
See liitumispõhine status-tegevus on tõkestatud ühes andmebaasitehingus opaakse omaniku, autenditud halllatava API-võtme ja täpse aktiivse generation väärtuse abil. `displayName` on ainult puhastatud (trimmed) konfigureeritud ühenduse nimi; see on `null`, kui turvalist konfigureeritud nime pole olemas. OmniRoute ei asenda seda kunagi e-postiga või loodud kontoidentiteediga. Provider väärtus on mittetundlik kuvasilt ja mitte kunagi loodud ühilduva teenusepakkuja identifikaator. Mandaadid, tunnusluba (tokens), küpsised, toored ühenduse või API-võtme id-d, omaniku räsid, tõkestussaladused ja sisemine ruutimisandmestik on välja jäetud.
Vale võti, vale omanik, aegunud generation, puuduv, aegunud, vabastatud ja kehtetuks tunnistatud otsingud tagastavad kõik sama `409 LEASE_FENCE_STALE` vea ühendusmetaandmeteta. Klient, kes sai mahupiirangu ootevastuse, ei omab aktiivset seost, mida kontrollida. Kui ruutimine teeb aktiivse rendi puhul ülemineku, jääb sama generation kehtivaks ja status tagastab tehinguna korrektselt uue seose, mitte kunagi vana. Olemasolevad kliendid jäävad muutumatuks, kuna acquire, renew, release ja ootevastused säilitavad oma varasemad kujud.
See serveri lepe ei muuda vaikimisi OpenAI Codexi `/status` käitumist. Vaikimisi Codex teatab praegu oma mudeli teenusepakkujat ja sisseehitatud autentimise/konto olekut, kuid ei kuva suvalisi kohandatud teenusepakkuja konto metaandmeid; hilisem kliendi integreerimine peab kutsuma selle tegevuse ja otsustama, kuidas kuvada `connection.displayName`.
Iga halllatav järeldamispäring edastab siis mõlemad kontrollpäised:
```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```
Täpne omanik, generation, aktiivne ühendus ja autenditud API-võti on tõkestatud vahetult enne iga toetatud ülesvoolu katset. Omaniku ja generation kordamine teise võtmega ebaõnnestub isegi kui see võti võimaldab sama ühendust. Toored omanikud ei säilitata, ei logita, ei säilitata päringu jäljendis ega edastata ülesvoolu.
Ajutine ressursikonflikt tagastab HTTP `429` koos `Retry-After` päisega ja:
```json
{
"state": "WAITING_FOR_CAPACITY",
"error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
"reason": "NO_FREE_ELIGIBLE_CONNECTION",
"retryAfter": 30
}
```
See vastus tähendab ainult seda, et tavapärane sobivate ühenduste hulk oli mittetühi ja kõik vabad kandidaadid oli hõivanud võõra aktiivne rent. Toetamata mudelid/teenusepakkujad, poliitika mittevastavus, jahtumisaeg (cooldown), kvoot, tervis ja teised tavapärased sobivuse ebaõnnestumised säilitavad oma olemasolevad OmniRoute vastused.
### `x-omniroute-compression`
Päringupõhine ülekirjutamine (override) tihenduse (compression) plaani jaoks. Kõrgeim eelisõigus — see edestab ruutimiskombinatsiooni (routing-combo) ülekirjutust, aktiivset profiili, automaatpäästikut (auto-trigger) ja paneeli Default väärtust. Väärtused:
| Väärtus | Mõju |
| ------------- | ------------------------------------------------------------------------------------------- |
| `off` | Selle päringu jaoks tihendust ei kasutata. |
| `default` | Paneelist tulenev Default profiil (ignoreerib aktiivset profiili). |
| `engine:<id>` | Üks mootor, kui see on lubatud, nt `engine:rtk`. |
| `<combo>` | Nimeline kombinatsioon, otsitakse nime järgi (tõstutundetu) esimesena, seejärel id-i järgi. |
Märkused:
- Tundmatuid väärtusi ignoreeritakse (päringut ei lükata kunagi tagasi); lahendamine langeb tagasi tavapärasele operaatori eelisjärjekorrale.
- Kui mitmel kombinatsioonil on samasugune nimi, edasta deterministliku vastavuse jaoks kombinatsiooni **id**.
- Kombinatsiooni, mille nimi on `off` või `default`, ei saa nime järgi valida (need märksõnad tõlgendatakse esimesena); viita sellisele kombinatsioonile tema id-i järgi.
- Peamine tihenduslüliti on kõva blokaator: kui tihendus on globaalselt keelatud, ei saa see päis seda lubada.
Rakendatud plaan kajastatakse vastuse päises:
```
X-OmniRoute-Compression: <mode>; source=<source>
```
kus `<source>` on üks järgnevatest: `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` või `off`.
---
## Manused (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"
}
```
Saadaolevad pakkujad: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.
Kataloogi id-d on kujul `provider/model` (näide: `jina-ai/jina-embeddings-v5-omni-small`). Registris esinevad Jina lühikesed mudeli id-d (näiteks `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) lahenduvad ka. Jina embed/rerank/classify/segment kasutavad esmalt armatuurlaua (dashboard) `jina-ai` mandaate; `JINA_AI_API_KEY` on varulahendus ainult juhul, kui armatuurlaua võtit ei eksisteeri. Kaart `jina-reader` on ainult Reader / `r.jina.ai` jaoks (`POST /v1/web/fetch`) ja ei pakuta sellega kunagi manuseid (embeddings) ega ümberjärjestamist (rerank).
Registri mudelid, mis reklaamivad multimodaalset toetust, aktsepteerivad ka kuni 32 pakkujaneutraalset struktureeritud
elementi. Meediaelementide tüübid on `text`, `image`, `audio`, `video` ja `document`. Nende meedia `source`
on kas `{"type":"url","url":"https://..."}` või
`{"type":"base64","data":"...","media_type":"..."}`.
Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`,
ja perekonna alias `jina-ai/jina-embeddings-v5-omni` → omni-small) aktsepteerib ka Jina natiivseid
EmbeddingsV5Request dokumente ja **edastab need muutmata kujul** aadressile `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,..." }]
}
]
}
```
Natiivsed `{ image | audio | video | pdf }` väärtused võivad olla avalik HTTPS URL, `data:` URI või
puhas base64. OmniRoute ei muuda neid objekte stringiks ega too natiivseid pildi URL-e —
Jina toob avaliku meedia iseseisvalt. Täiendavad Jina väljad (`task`, `normalized`, `truncate`, `embedding_type`) edastatakse
muutmata kujul. Ainult tekstipõhised Jina SKU-d lükkavad mitte-teksti dokumendid endiselt tagasi.
Turvalisuse ja edastuse piirid:
- Kaugmeedia URL-id peavad olema avalikud HTTPS aadressid. Kanoonilised `{type,source:url}` elemendid tuuakse
serveripoolselt (ümbersuunamise taaskinnitus, ajapiirang, suuruspiirangud, avalik DNS, ühenduse fikseerimine) ja
põimitakse enne pakkujale edastamist. Jina natiivsed `{image:"https://..."}` elemendid edastatakse muutmata kujul
pärast sama avaliku HTTPS kontrolli — Jina toob URL-i ise.
- Manustatud base64 meedia on piiratud dekodeerituna 8 MiB elemendi kohta ja 16 MiB dekodeerituna kogu päringu peale.
Pakkuja tõlgendus (kanoonilisi elemente ei edastata kunagi muutmata kujul):
- Jina multimodaalsed mudelid: igast tipptaseme elemendist saab üks modaalsuse võtmega objekt
(`text` / `image` / `audio` / `video` / `pdf`), kasutades manustatud meedia jaoks data URI-sid; üks vektor per
tipptaseme element.
- Gemini Embedding 2 perekond: ühest tipptaseme massiivist saab üks natiivne
`models/{model}:embedContent` päring, kus on `content.parts` (`text` või `inline_data`).
- Tundmatud/dünaamilised mudelid, millel puudub selgesõnaline modaalsuse metaandmestik, lükkavad struktureeritud sisendi tagasi HTTP 400 veaga.
```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"
}
```
Toetamata mudeli/modaalsuse kombinatsioonid tagastavad HTTP 400, mitte ei sundi elementi teisendama. Pärandtüüpi
string/token päringute muud kui sisendi laiendusväljad edastatakse endiselt muutmata kujul.
```bash
# Loetleb kõik manuste (embeddings) mudelid
GET /v1/embeddings
```
---
## Pildigenereerimine
```bash
POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "openai/gpt-image-2",
"prompt": "A beautiful sunset over mountains",
"size": "1024x1024"
}
```
Saadaolevad pakkujad: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (kohalik), ComfyUI (kohalik).
```bash
# Kuva kõik pildimudelid
GET /v1/images/generations
```
---
## Dokumentide OCR
```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` väli määrab OCR-pakkuja `provider/model` eesliite abil; ainuüksi mudeli ID (nt
`mistral-ocr-latest`) lahendub oma registreeritud pakkuja järgi, ja kui `model` on puudu, kasutatakse
vaikimisi Mistrali (`mistral-ocr-latest`). Registreeritud pakkujad (`open-sse/config/ocrRegistry.ts`):
| Pakkuja ID | Mudeli ID | `model` väärtus | Märkused |
| ----------------------------- | -------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (või ainult `mistral-ocr-latest`) | Sünkroonne — vastus tagastatakse otse ühest upstream-päringust. |
| `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Asünkroonne upstream (`analyze` + pollimine) — vaata allpool. |
| `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Sünkroonne, Vertex AI `openapi/chat/completions` partneri lõpp-punkti kaudu — autentimise/URL-i kohta vaata allpool. |
Kõik kolm pakkujat vastavad samas Mistrali kujuga kehas:
```json
{
"pages": [{ "index": 0, "markdown": "# Väljavõetud tekst..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
```
### Azure Document Intelligence pollimise vood
Azure Document Intelligence'i `analyze` API on asünkroonne: esialgne päring tagastab
`Operation-Location` päise, mitte keha, ja tulemust tuleb pollida. Handler
(`open-sse/handlers/ocr.ts`) pollib seda URL-i iga sekundi tagant kuni 30 katse jooksul, nurjub kiiresti (ei
jätka pollimist) mitte-`ok` polli vastuse või `"failed"` staatuse korral, ja tagastab `504`, kui
operatsioon on veel pooleli pärast katsete eelarve ammendumist. Lõplik Azure vastus
normaliseeritakse samasse `pages`/`markdown` kujusse, mida kasutab Mistral, enne kui see tagastatakse
kutsujale, nii et kliendikood ei pea pakkuja jaoks erandit teha.
### Vertex AI DeepSeek OCR autentimine ja lõpp-punkti lahendamine
`vertex-deepseek-ocr` kasutab taaskord sama Vertex AI autentimist, mida OmniRoute juba toetab
vestlus-/pildiliikluse jaoks (`open-sse/executors/vertex.ts`): ühenduse API-võti on kas
teenusekonto JSON mandaat (vahetatakse lühiajalise OAuth pöörduspääsu tõendi vastu JWT-bearer
voo kaudu) või juba valmis genereeritud OAuth pöörduspääsu tõend, mida kasutatakse sellisena. Upstream lõpp-punkti URL on Vertexi
generaalne `openapi/chat/completions` partneri lõpp-punkt, mis moodustatakse ühenduse projekti ja
regiooni põhjal — otsene `providerSpecificData.project`/`providerSpecificData.region` võidab alati;
vastasel juhul tuletatakse projekt teenusekonto JSON-i `project_id` väljast ja regioon
vaikimisi on `us-central1`. Mõlemad lahendused toimuvad failis `open-sse/handlers/ocr.ts`
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), mida kasutab
`src/app/api/v1/ocr/route.ts` enne `handleOcr`-ile saatmist.
---
## Mudelite loend
```bash
GET /v1/models
Authorization: Bearer your-api-key
→ Tagastab kõik vestlus-, embeddingu- ja pildimudelid ning kombinatsioonid OpenAI formaadis
```
### Mudeli id eesliited (`?prefix=`)
Enamik mudeleid on reklaamitud **teenusepakkuja eesliite** all. Millist eesliidet saad, määrab
`MODELS_CATALOG_PREFIX_MODE` funktsioonilipp, ja seda saab **päringu kaupa** üle kirjutada
päringuparameetriga — kasulik kliendile, kes soovib puhast loendit, muutmata serveripoolset
seadistust kõigi teiste jaoks:
```bash
GET /v1/models?prefix=alias # üks id mudeli kohta — lühike aliase eesliide
GET /v1/models?prefix=dual # mõlemad vormid (serveri vaikeseadistus)
GET /v1/models?prefix=canonical # ainult täielik teenusepakkuja-id eesliide
```
| Režiim | Väljastab | Märkused |
| ----------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual` | `cc/claude-sonnet-4-6` **ja** `claude/claude-sonnet-4-6` | **Vaikimisi.** Mõlemad id-d suunavad samale mudelile; säilitatud, et kliendikonfiguratsioonid, mis kasutasid kõvakoodituna ükskõik kumba vormi, jätkaksid toimimist. Suurendab kataloogi mahtu peaaegu kahekordseks. |
| `alias` | `cc/claude-sonnet-4-6` | Üks kirje mudeli kohta. Teenusepakkujad, kellel puudub eraldi alias, väljastavad ikkagi oma kirje, nii et midagi ei jää kaduma. |
| `canonical` | `claude/claude-sonnet-4-6` | Üks kirje mudeli kohta täieliku teenusepakkuja-id eesliite all. Teenusepakkujad, kellel puudub eraldi alias (nt `antigravity/…`, `agy/…`), väljastavad siin oma ainsa id, nii et midagi ei jää kaduma. |
`dual`-režiimi peegeldust saab tuvastada ka ilma päringuparameetrita: sellel on `parent`
väli, mis viitab peamisele id-le.
Kliendid, mis kuvavad mudeli valija, peaksid päringu tegema `?prefix=alias` — see on see, mida
[OmniCopilot VS Code laiendus](../guides/VSCODE-COPILOT.md) teeb.
### Mittemõtlevad mudelivariandid
Mõtlemisvõimeliste Claude mudelite jaoks reklaamib `/v1/models` ka **mittemõtlemise** varianti, mille id-le on lisatud eesliide `claude-3-omniroute-no-thinking/`:
```
claude-3-omniroute-no-thinking/<provider>/<model>
```
Selle id valimine (nt Claude Code konfiguratsioonis, mis lisab alati `thinking` bloki) lahendub tagasi tegeliku `<provider>/<model>` peale, kusjuures põhjendamine (reasoning) on maha surutud — `thinking:{type:"disabled"}` `/v1/messages` teel, või `reasoning`/`reasoning_effort` väljad jäetakse `/v1/chat/completions` teel välja. Variant on loetletud ainult Claude-perekonna mudelite jaoks, mis toetavad mõtlemist **ja** aktsepteerivad `disabled` väärtust (nii et nt ainult-adaptiivsed mudelid, mis lükkavad `disabled` tagasi, on välja jäetud). Operaatorid saavad varianti mudeli kaupa sundlubada või -keelata `ModelSpec.noThinkingAlias` kaudu.
---
## Provider'i pluginate manifest
```bash
GET /api/v1/provider-plugin-manifest
```
Tagastab Bifrosti, CLIProxyAPI ja tulevaste sidecar-ruuterite kasutatava JSON-turvalise provider'i pluginate manifesti. Vastus genereeritakse TypeScripti provider'i registrist ja jätab teadlikult välja OAuth kliendisaladused, käitusaja keskkonnamuutujate lahendamise, täitmisfunktsioonid (executor functions), päringu päised ja kontoandmed.
Kasuta seda endpointi, kui sidecar töötab väliselt (out-of-process) ja ei saa importida `open-sse/config/providerPluginManifestRegistry.ts` otse.
---
## Ühilduvuse endpointid
| Meetod | Tee | Formaat |
| ------ | ----------------------------------------- | ------------------------------------------------- |
| 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 (redigeerimine/inpaint) |
| POST | `/v1/videos/generations` | OpenAI-laadne video genereerimine |
| POST | `/v1/music/generations` | OpenAI-laadne muusika genereerimine |
| POST | `/v1/audio/transcriptions` | OpenAI Audio (STT) |
| POST | `/v1/audio/speech` | OpenAI TTS (tagastab audio sisu) |
| POST | `/v1/rerank` | Cohere/Voyage-laadne uuesti järjestamine (rerank) |
| POST | `/v1/classify` | Jina klassifitseerimine (`api.jina.ai`) |
| POST | `/v1/segment` | Jina segmenteerija (`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}/` | OpenAI kataloogi alias |
| GET | `/api/v1/vscode/{token}/models` | OpenAI mudelite alias |
| POST | `/api/v1/vscode/{token}/chat/completions` | OpenAI tokenitud alias |
| POST | `/api/v1/vscode/{token}/responses` | OpenAI Responses tokenitud alias |
| POST | `/api/v1/vscode/{token}/api/chat` | Ollama tokenitud alias |
| GET | `/api/v1/vscode/{token}/api/tags` | Ollama tags tokenitud alias |
Kõik POST-teed järgivad sama struktuuri: `Bearer your-api-key` + Zod-valideeritud JSON-sisu (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` jne, vaata `src/shared/validation/schemas.ts`). Skeemi valideerimise ebaõnnestumisel tagastatakse 4xx.
Klientidele, kes ei saa lisada `Authorization: Bearer ...`, aktsepteerib OmniRoute API võtmeid ka URL-is, kas päringustringi ühilduvuse kaudu (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) või allpool dokumenteeritud eraldi `/api/v1/vscode/{token}/...` endpointide kaudu.
```bash
# Uuesti järjestamine (rerank)
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Jina klassifitseerimine (Foundation API mandaadid)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Jina segmenteerija
POST /v1/segment { "content": "...", "return_chunks": true }
# Jina otsing (s.jina.ai; provider'i aliased: jina-search, jina-ai, jina)
POST /v1/search { "query": "...", "provider": "jina-search" }
# Modereerimine
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
# TTS — tagastab audio/mpeg (või soovitud vormingus) sisu
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# Pildi redigeerimine (multipart)
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
# Video / muusika genereerimine (provider'i eesliitega mudeli ID)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." }
```
### Provider'ile pühendatud teed
```bash
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
```
Provider'i eesliide lisatakse automaatselt, kui see puudub. Mittevastavate mudelite korral tagastatakse `400`.
---
## Files API
OpenAI-ga ühilduv failide lõpp-punkt pakksisendi ja -väljundi ning faili eesmärgipõhiste üleslaadimiste jaoks.
| Meetod | Tee | Kirjeldus |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/files` | Laadi fail üles (mitmeosaline: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — kuni 512 MiB |
| GET | `/v1/files` | Loetle autentitud API-võtme failid |
| GET | `/v1/files/[id]` | Too faili metaandmed |
| DELETE | `/v1/files/[id]` | Kustuta fail |
| GET | `/v1/files/[id]/content` | Voogedasta faili töötlemata sisu tagasi |
**Autentimine:** Bearer API-võti — failid on `getApiKeyRequestScope` kaudu API-võtme kaupa piiritletud. Võti
näeb ja saab alla laadida ning kustutada ainult enda faile; võtmeta juhtpaneeli seanss saab lugeda
kogu eksemplari; omanikuta failile (anonüümne või juhtpaneeli seansi kaudu üles laaditud) keelatakse juurdepääs kõigile
seansivälistele kutsujatele. `GET /v1/files` lükkab anonüümse kutsuja — ja esitatud võtme, mida
ei õnnestu tuvastada — tagasi vastusega `401` isegi siis, kui `REQUIRE_API_KEY=false`, selle asemel et loetleda kõigi rentnike
faile (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).
---
## Batches API
OpenAI-ga ühilduv pakktöötlus.
| Meetod | Tee | Kirjeldus |
| ------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/batches` | Pakktöö loomine — keha valideeritakse skeemiga `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
| GET | `/v1/batches` | Pakktööde loendi hankimine |
| GET | `/v1/batches/[id]` | Pakktöö oleku ja `request_counts` hankimine |
| DELETE | `/v1/batches/[id]` | Lõpetatud/nurjunud pakktöö kustutamine |
| POST | `/v1/batches/[id]/cancel` | Poolelioleva pakktöö tühistamine |
**Autentimine:** Bearer API-võti. Pakktööd on API-võtme põhised ning neile kehtib sama kolmeosaline reegel nagu
failidele: juurdepääs ainult oma võtmega, juhtpaneeli seansil kogu eksemplari ulatuses, null-omanikuga kirjetele on juurdepääs keelatud kõigile
seansivälistele kutsujatele (hankimine, kustutamine, tühistamine ja loomisel tehtav `input_file_id` kontroll).
`GET /v1/batches` lükkab anonüümse kutsuja tagasi vastusega `401` isegi siis, kui `REQUIRE_API_KEY=false`.
---
## Search API
Veebi/otsingu pakkuja abstraktsioon (Tavily, Brave, Exa, Serper jne).
| Meetod | Tee | Kirjeldus |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| GET | `/v1/search` | Loetle konfigureeritud otsingupakkujad + võimalused |
| POST | `/v1/search` | Käivita otsingupäring — keha valideeritakse skeemiga `v1SearchSchema`, toetab vahemällu salvestamist/liitmist |
| GET | `/v1/search/analytics` | Pakkujapõhine tabamuste/latentsuse/vahemälu statistika |
**Autentimine:** Bearer API-võti (`extractApiKey` + `isValidApiKey`). Otsingupoliitikat rakendatakse `enforceApiKeyPolicy` kaudu.
---
## Web Fetch API
Ekstraheeri sisu URL-ilt konfigureeritud web-fetch pakkuja kaudu (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).
| Meetod | Tee | Kirjeldus |
| ------ | --------------- | ------------------------------------------------------------------------ |
| POST | `/v1/web/fetch` | URL-i toomine/scrape'imine — keha valideeritakse `v1WebFetchSchema` abil |
**Autentimine:** Bearer API võti (`extractApiKey` + `isValidApiKey`). Poliitika jõustatakse `enforceApiKeyPolicy` abil.
**Kvoodist teadlik varulahendus (#8297):** kui selget `provider` parameetrit ei antud, käiakse pool
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) läbi
fikseeritud prioriteetsuse järjekorras (fill-first) — kiirusepiirangu alla jäänud, kuid konfigureeritud pakkuja
jäetakse vahele, mitte ei katkestata päringut kohe — ning korratav/kvoodiga seotud
ülemvoolu viga (HTTP 429 alati; 402/403 Firecrawl/Tavily/TinyFish kvoodilaadsete tasuta pakettide puhul —
mitte Jina Reader puhul ja mitte kunagi lihtsa 400 halva päringu puhul) langeb läbi
järgmisele proovimata volitatud pakkujale päringu tegemise ajal. Kui kõik pakkujad
poolis on ammendatud, tagastab lõpp-punkt ühe `429` (koos `Retry-After`
päisega) endise üldise `400` asemel. Kui taotletakse selget `provider` parameetrit,
puudub **vaikne** varulahendus — kiirusepiirangu alla jäänud või ebaõnnestunud selge
pakkuja näitab enda viga (`429` kiirusepiirangu korral, muul juhul ülemvoolu
staatus).
---
## WebSocket Voogedastus
```bash
GET /v1/ws?handshake=1
```
Valideerib WebSocket upgrade käepigistuse ja tagastab wire-protokolli näidissõnumid (`request`, `cancel`). Tegelikke WS kaadreid käsitleb kaasasolev WS server, mis on väljaspool Next.js marsruuditabelit.
**Autentimine:** Bearer API võti käepigistuse ajal.
### Responses API üle WebSocket (ainult codex)
```bash
# Sama host:port nagu HTTP API (vaikimisi 20128); uuenda ühendus:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (või: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
# Esimene kaader PEAB olema response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```
Responses-API-over-WebSocket proksi on ühendatud **eranditult `codex`-iga** (ChatGPT
taustasüsteem). See kuulab sama porti kui API/juhtpaneel teedel `/v1/responses`,
`/responses` ja `/api/v1/responses`. Esimese `response.create` kaadri peale
autendib see ja valmistab ette sisemise `codex-responses-ws` silla abil, valib
codex OAuth ühenduse ning tunneldab `wss://chatgpt.com/backend-api/codex/responses`
kaudu, kasutades `wreq-js` transporti. **Mitte-codex mudelid lükatakse tagasi**
(`codex_ws_provider_required`). Kvoodijagamise ruutimiseks kasuta
`model: "qtSd/<group>/codex/<model>"`. Rakendatud failides
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.
**Autentimine:** Bearer API võti käepigistuse ajal. Kaasasolev HTTP server (`server-ws.mjs`)
peab olema aktiivne sisenemispunkt (see on vaikimisi nii, kui `app/server-ws.mjs` on olemas).
#### Mudeli id: kasuta lihtsat ChatGPT id-d (ilma `codex/` eesliiteta)
OpenAI **Codex CLI** valideerib mudeli nime kliendipoolselt, kui
`supports_websockets = true`, ja **lükkab tagasi pakkuja-eesliitega id-d**, nagu
`codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). Saada **lihtne** id (nt `gpt-5.5`). OmniRoute'i sild on
mõeldud ainult codex-ile, seega lahendab see lihtsa id ümber codex mudeliks
(`resolveCodexWsModelInfo`) enne ülemvoolu tunneldamist — hoolimata sellest, et
lihtne `gpt-5.5` suunataks muidu HTTP kaudu teise pakkuja juurde.
#### OpenAI Codex CLI konfigureerimine
Suuna Codex CLI OmniRoute'ile, lisades kohandatud pakkuja WebSocket
toega faili `~/.codex/config.toml` (kasuta eraldi `CODEX_HOME` väärtust, et vältida
olemasoleva konfiguratsiooni muutmist):
```toml
model = "gpt-5.5" # lihtne id — MITTE "codex/gpt-5.5"
model_provider = "omniroute"
[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1" # ei lõpe kaldkriipsuga; WS URL tuletatakse (kasuta produktsioonis https/wss)
wire_api = "responses" # ainus toetatud väärtus alates 2026. aasta veebruarist
supports_websockets = true # lubab Responses-over-WS transpordi
env_key = "OMNIROUTE_API_KEY" # hoiab OmniRoute API võtit (Bearer)
```
```bash
export OMNIROUTE_API_KEY=sk-... # OmniRoute API võti (suvaline võti, kui REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```
CLI uuendab `base_url + /responses` WebSocket-iks ja OmniRoute tunneldab selle
valitud codex OAuth ühendusele. Valideeritud otsast-otsani kohaliku serveri vastu:
ChatGPT tagastab `codex.rate_limits` + `response.created` ja voogesitab
lõpetamise.
---
## Kvoodid ja probleemidest teavitamine
| Meetod | Tee | Kirjeldus |
| ------ | ------------------- | ------------------------------------------------------------------------------------------ |
| GET | `/v1/quotas/check` | Kontrolli eelnevalt `provider` + `accountId` kvooti enne registreeritud võtme väljastamist |
| POST | `/v1/issues/report` | Teavita kvoodi/võtme väljastamise tõrkest GitHubile (vajab `GITHUB_ISSUES_REPO` + tokenit) |
**Autentimine:** Bearer API võti (`isAuthenticated`).
---
## Isikliku kasutuse aruandlus (`/api/usage/om-usage`)
Iga API võti saab lugeda **enda** kasutust ja kvoote — haldusautentimist ei vajata. See on
lõpp-punkt, mida klient (CLI, OmniCopiloti paneel) kasutab, et näidata võtme omanikule tema kulutusi.
```bash
# Tekstivorming (ajalooline lepe — lihttekst terminalile)
curl -H "Authorization: Bearer <your-api-key>" \
http://localhost:20128/api/usage/om-usage
# Struktureeritud vorming — mida kasutajaliides tarbib
curl -H "Authorization: Bearer <your-api-key>" \
"http://localhost:20128/api/usage/om-usage?format=json"
```
Võtmel peab olema lubatud **`allowUsageCommand`** (vaikimisi väljas — armatuurlaua
API-võtmete haldur lülitab selle sisse võtmehaaval). Selle puudumisel vastab lõpp-punkt
`403`-ga.
`?format=json` tagastab eristatava kuju, nii et helistaja ei loeks andmevälja tagasilükkamisest.
Õnnestumisel:
```jsonc
{
"allowed": true,
// esineb vaid siis, kui võti kasutab võtmepõhiseid kasutuspiiranguid (päevane/nädalane USD):
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// valitud teenusepakkuja kvoodi hetkeseis, või null kui midagi veel puudub vahemällu salvestatuna:
"provider": {
"connectionId": "…",
"provider": "claude",
"plan": "…",
"quotas": {/* … */},
},
// iga ühenduse hetkeseis, et kasutajaliides saaks kuvada mitu teenusepakkujat kõrvuti:
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
```
Tagasilükkamisel (`401` vale võti / `403` ei lubatud) tagastab samas rajas
`{ "allowed": false, "error": { "message": "…" } }` — olemasolev, kuid tühi `personal`/`provider`
(võti lubatud, veel midagi õpitud pole) on erinev olek kui tagasilükkamine, ja vaid JSON-vorming
neid eristab.
**Autentimine:** helistaja enda Bearer API võti, valideeritud `isValidApiKey`-ga — see **ei ole**
haldusliides (`/api/keys/…`), mis jääb `requireManagementAuth` taha.
---
## Semantiline vahemälu
```bash
# Hangi vahemälu statistika
GET /api/cache/stats
# Tühjenda kõik vahemälud
DELETE /api/cache/stats
```
Vastuse näide:
```json
{
"semanticCache": {
"memorySize": 42,
"memoryMaxSize": 500,
"dbSize": 128,
"hitRate": 0.65
},
"idempotency": {
"activeKeys": 3,
"windowMs": 5000
}
}
```
### Latentsuse mõju
Semantilise vahemälu **TABAMUS (HIT)** teenindab vastuse vahemälust **ilma
päritolusüsteemi (upstream) kõnet tegemata**, seega raporteeritud
`X-OmniRoute-Response-Latency` on ligilähedaselt null (sõltumata algsest
päritolusüsteemi latentsusest). Latentsustundlikud kliendid
(jõudlustestimine, p50/p99 jälgimine) peaksid kontrollima
`X-OmniRoute-Cache-Latency` vastuse päist:
| Väärtus | Tähendus |
| ----------- | --------------------------------------------------------------------- |
| `synthetic` | Vastus tuli vahemälust; latentsus ei ole tegelik päritolusüsteemi aeg |
| _(puudub)_ | Vastus tuli tegelikust päritolusüsteemi kõnest |
### Võtmepõhine vahemälust möödaminek
API võtmed saavad loobuda semantilise vahemälu lugemisest `cacheDefaultMode` seadega:
| Väärtus | Käitumine |
| -------- | --------------------------------------------------------------------------- |
| `legacy` | Tavapärane vahemälu käitumine (vaikimisi) |
| `bypass` | Jäta vahemälust otsimine täielikult vahele; alati minnakse päritolusüsteemi |
Määra võtme loomisel (`POST /api/keys`) või uuendamisel (`PATCH /api/keys/[id]`):
```json
{ "cacheDefaultMode": "bypass" }
```
### Päringupõhine möödaminek
Igasugune päring saab minna vahemälust mööda, sõltumata võtme seadistustest:
```
X-OmniRoute-No-Cache: true
```
---
## Töölaud ja haldus
Haldusmarsruute (`/api/*`, v.a avalik autentimine/sisselogimine) ei volitata
tavaliste päringu API võtmetega. Volituste perekonnad, ulatused ja curl-näited:
[Halduse autentimine](../guides/MANAGEMENT-AUTH.md).
### Autentimine
| Lõpp-punkt | Meetod | Kirjeldus |
| ----------------------------- | ------- | ---------------------------------- |
| `/api/auth/login` | POST | Sisselogimine |
| `/api/auth/logout` | POST | Väljalogimine |
| `/api/settings/require-login` | GET/PUT | Sisselogimise kohustuse lülitamine |
### Pakkujate haldus
| Lõpp-punkt | Meetod | Kirjeldus |
| ---------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `/api/providers` | GET/POST | Pakkujate loend / loomine |
| `/api/providers/[id]` | GET/PUT/DELETE | Pakkuja haldamine |
| `/api/providers/[id]/test` | POST | Pakkuja ühenduse testimine |
| `/api/providers/[id]/models` | GET | Pakkuja mudelite loend |
| `/api/providers/validate` | POST | Pakkuja konfiguratsiooni valideerimine |
| `/api/providers/bulk` | POST | Massiline API võtmete lisamine ÜHELE pakkujale |
| `/api/providers/import` | POST | Heterogeense pakkujate LOENDI importimine parsitud CSV/JSON failist (#6836); iga rea osalised ebaõnnestumised tagastatakse |
| `/api/provider-nodes*` | Erinevad | Pakkuja sõlmede haldus |
| `/api/provider-models` | GET/POST/PATCH/DELETE | Kohandatud mudelid (lisamine, uuendamine, peitmine/näitamine, kustutamine) |
### OAuth vood
| Lõpp-punkt | Meetod | Kirjeldus |
| -------------------------------- | -------- | -------------------------- |
| `/api/oauth/[provider]/[action]` | Erinevad | Pakkujaspetsiifiline OAuth |
### Ruutimine ja konfiguratsioon
| Lõpp-punkt | Meetod | Kirjeldus |
| --------------------- | -------- | ---------------------------------- |
| `/api/models/alias` | GET/POST | Mudeli aliased |
| `/api/models/catalog` | GET | Kõik mudelid pakkuja + tüübi kaupa |
| `/api/combos*` | Erinevad | Kombode haldus |
| `/api/keys*` | Erinevad | API võtmete haldus |
| `/api/pricing` | GET | Mudeli hinnastamine |
### Kasutus ja analüütika
| Lõpp-punkt | Meetod | Kirjeldus |
| -------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history` | GET | Kasutuse ajalugu |
| `/api/usage/logs` | GET | Kasutuslogid |
| `/api/usage/request-logs` | GET | Päringutaseme logid |
| `/api/usage/[connectionId]` | GET | Ühenduse-põhine kasutus |
| `/api/usage/token-limits` | GET/POST/DELETE | API-võtme-põhised tokenilimiidi eelarved |
| `/api/usage/model-latency-stats` | GET | Liikuv pakkuja/mudeli-põhine viivituse koondstatistika (keskmine/p50/p95/p99, edukuse määr); filtrid: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) |
| `/api/usage/cache-health` | GET | Vahemälu (prompt-cache) tervise kokkuvõte `call_logs` põhjal — kirjutamise/lugemise suhe, p50/p90/p99 kirjutamise suuruse jaotus, suurte kirjutuste kontsentratsioon, mudeli-põhine jaotus ning `healthy`/`degraded`/`thrash`/`no-data` hinnang; päringuparameetrid `range` (`1h`\|`24h`\|`7d`\|`30d`, vaikimisi `24h`) ja valikuline `model` (#8827) |
### Seaded
| Lõpp-punkt | Meetod | Kirjeldus |
| ------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings` | GET/PUT/PATCH | Üldised seaded |
| `/api/settings/proxy` | GET/PUT | Võrguproksi konfiguratsioon |
| `/api/settings/proxy/test` | POST | Proksi ühenduse testimine |
| `/api/settings/ip-filter` | GET/PUT | IP lubatud/keelatud loend |
| `/api/settings/thinking-budget` | GET/PUT | Mõtlemise/arutlemise **päringu** ümberkirjutamise režiim (läbilaskmine / automaatne eemaldamine / kohandatud / adaptiivne). Kompressioonist sõltumatu. Vaata [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). |
| `/api/settings/system-prompt` | GET/PUT | Globaalne süsteemipromt |
| `/api/settings/compression` | GET/PUT | Globaalne kompressiooni konfiguratsioon |
| `/api/settings/purge-request-history` | POST | Kustutab päringulogi read ja kohalikud kõnelogi artefaktid |
### Kontekst ja kompressioon
| Lõpp-punkt | Meetod | Kirjeldus |
| -------------------------------------- | -------------- | ----------------------------------------------------------------------------------- |
| `/api/compression/preview` | POST | Eelvaade off/lite/standard/aggressive/ultra/RTK/kihilise kompressiooni jaoks |
| `/api/compression/language-packs` | GET | Saadaolevate Caveman keelepakettide loend |
| `/api/compression/rules` | GET | Caveman reeglite metaandmete loend |
| `/api/context/caveman/config` | GET/PUT | Caveman-spetsiifiliste seadete alias |
| `/api/context/rtk/config` | GET/PUT | RTK-spetsiifilised seaded, sh kohandatud filtrid ja töötlemata väljundi säilitamine |
| `/api/context/rtk/filters` | GET | RTK filtrite katalog ja kohandatud filtrite diagnostika |
| `/api/context/rtk/test` | POST | RTK eelvaate/testi käivitamine teksti sisu peal |
| `/api/context/rtk/raw-output/[id]` | GET | Säilitatud tsenseeritud töötlemata väljundi lugemine viitaja id järgi |
| `/api/context/combos` | GET/POST | Kompressioonikombode loend/loomine |
| `/api/context/combos/[id]` | GET/PUT/DELETE | Kompressioonikombo üksikasjad/uuendamine/kustutamine |
| `/api/context/combos/[id]/assignments` | GET/PUT | Kompressioonikombode määramine ruutimiskombodele |
| `/api/context/analytics` | GET | Kompressiooni analüütika alias |
### Jälgimine
| Lõpp-punkt | Meetod | Kirjeldus |
| ------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions` | GET | Aktiivsete seansside jälgimine |
| `/api/rate-limits` | GET | Kontopõhised kiiruspiirangud |
| `/api/monitoring/health` | GET | Tervisekontroll + pakkujate kokkuvõte (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) |
| `/api/cache/stats` | GET/DELETE | Vahemälu statistika / tühjendamine |
| `/api/modality-bridge/stats` | GET | Mälupõhine `attempts`, õnnestumised/`bridged`, ebaõnnestumised, vahemälutabamused, `totalLatencyMs`, `latencySamples`, näidistel põhinev `averageLatencyMs`, ja viimase kasutuse ajahetk (lähtestub taaskäivitusel; halduse autentimine) |
| `/api/modality-bridge/video/runtime` | GET | Range usaldusväärse loopback-kontroll enne halduse autentimist/testimist; puhastatud FFmpeg/ffprobe kättesaadavus ja versioonid (no-store) |
| `/api/modality-bridge/video/extract` | POST | Sisemine autenditud usaldusväärse loopback'i baidivahendaja; 50 MiB sisend, piiratud järjekord/32 MiB väljund, `503` mahupiirang, `499` katkestus, `504` tähtaeg; ei ole avalik üleslaadimise API |
### Varundus ja eksport/import
| Lõpp-punkt | Meetod | Kirjeldus |
| --------------------------- | ------ | --------------------------------------------------- |
| `/api/db-backups` | GET | Saadaolevate varukoopiate loend |
| `/api/db-backups` | PUT | Manuaalse varukoopia loomine |
| `/api/db-backups` | POST | Taastamine konkreetsest varukoopiast |
| `/api/db-backups/export` | GET | Andmebaasi allalaadimine .sqlite failina |
| `/api/db-backups/import` | POST | .sqlite faili üleslaadimine andmebaasi asendamiseks |
| `/api/db-backups/exportAll` | GET | Täieliku varukoopia allalaadimine .tar.gz arhiivina |
### Pilve sünkroonimine
| Lõpp-punkt | Meetod | Kirjeldus |
| ---------------------- | -------- | ----------------------------- |
| `/api/sync/cloud` | Erinevad | Pilve sünkroonimise toimingud |
| `/api/sync/initialize` | POST | Sünkroonimise algatamine |
| `/api/cloud/*` | Erinevad | Pilve haldus |
### Tunnelid
| Lõpp-punkt | Meetod | Kirjeldus |
| -------------------------- | ------ | -------------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET | Cloudflare Quick Tunneli paigalduse/käitusaja oleku lugemine töölaua jaoks |
| `/api/tunnels/cloudflared` | POST | Cloudflare Quick Tunneli lubamine või keelamine (`action=enable/disable`) |
| `/api/tunnels/ngrok` | GET | ngrok Tunneli käitusaja oleku lugemine töölaua jaoks |
| `/api/tunnels/ngrok` | POST | ngrok Tunneli lubamine või keelamine (`action=enable/disable`) |
### CLI tööriistad
| Lõpp-punkt | Meetod | Kirjeldus |
| ---------------------------------- | ------ | -------------------- |
| `/api/cli-tools/claude-settings` | GET | Claude CLI olek |
| `/api/cli-tools/codex-settings` | GET | Codex CLI olek |
| `/api/cli-tools/droid-settings` | GET | Droid CLI olek |
| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI olek |
| `/api/cli-tools/runtime/[toolId]` | GET | Üldine CLI käitusaeg |
CLI vastused sisaldavad: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
### ACP agendid
| Lõpp-punkt | Meetod | Kirjeldus |
| ----------------- | ------ | --------------------------------------------------------------------------- |
| `/api/acp/agents` | GET | Kõikide tuvastatud agentide (sisseehitatud + kohandatud) loend koos olekuga |
| `/api/acp/agents` | POST | Kohandatud agendi lisamine või tuvastamise vahemälu uuendamine |
| `/api/acp/agents` | DELETE | Kohandatud agendi eemaldamine `id` päringuparameetri järgi |
GET vastus sisaldab `agents[]` (id, name, binary, version, installed, protocol, isCustom) ja `summary` (total, installed, notFound, builtIn, custom).
### Vastupidavus ja kiiruspiirangud
| Lõpp-punkt | Meetod | Kirjeldus |
| --------------------------------- | --------- | ----------------------------------------------------------------------------------------------------- |
| `/api/resilience` | GET/PATCH | Päringujärjekorra, ühenduse jahtumisaja, pakkuja katkestaja ja ootamise seadete lugemine/uuendamine |
| `/api/resilience/reset` | POST | Pakkuja lülitite (circuit breaker) lähtestamine |
| `/api/resilience/model-cooldowns` | GET | Aktiivsete (pakkuja, ühendus, mudel) lukustuste loend, sorteeritud järelejäänud aja järgi |
| `/api/resilience/model-cooldowns` | DELETE | Mudeli lukustuse tühistamine — päringu keha `{provider, model}` või `{all: true}` kõige kustutamiseks |
| `/api/rate-limits` | GET | Kontopõhine kiiruspiirangu olek |
| `/api/rate-limit` | GET | Globaalne kiiruspiirangu konfiguratsioon |
> Kõik neli `/api/resilience/*` marsruuti nõuavad **halduse autentimist** (`requireManagementAuth`). Vaata [Vastupidavus (laiendatud)](#resilience-extended), et saada täielik ülevaade pakkuja katkestaja, ühenduse jahtumisaja ja mudeli lukustuse erinevustest.
### Hindamised (Evals)
| Lõpp-punkt | Meetod | Kirjeldus |
| ------------ | -------- | ------------------------------------------------- |
| `/api/evals` | GET/POST | Hindamiskomplektide loend / hindamise käivitamine |
### Poliitikad
| Lõpp-punkt | Meetod | Kirjeldus |
| --------------- | --------------- | -------------------------- |
| `/api/policies` | GET/POST/DELETE | Ruutimispoliitikate haldus |
### Vastavus (Compliance)
| Lõpp-punkt | Meetod | Kirjeldus |
| --------------------------- | ------ | --------------------------------- |
| `/api/compliance/audit-log` | GET | Vastavuse auditilogi (viimased N) |
### v1beta (Gemini-ühilduv)
| Lõpp-punkt | Meetod | Kirjeldus |
| -------------------------- | ------ | ----------------------------------- |
| `/v1beta/models` | GET | Mudelite loend Gemini vormingus |
| `/v1beta/models/{...path}` | POST | Gemini `generateContent` lõpp-punkt |
Need lõpp-punktid järgivad Gemini API vormingut klientidele, kes eeldavad ühilduvust otse Gemini SDK-ga.
### Sisemised / süsteemi API-d
| Lõpp-punkt | Meetod | Kirjeldus |
| ------------------------ | ------ | ------------------------------------------------------------------ |
| `/api/init` | GET | Rakenduse initsialiseerimise kontroll (kasutatakse esmakäivitusel) |
| `/api/tags` | GET | Ollama-ühilduvad mudeli sildid (Ollama klientidele) |
| `/api/restart` | POST | Käivitab serveri sujuva taaskäivituse |
| `/api/shutdown` | POST | Käivitab serveri sujuva seiskamise |
| `/api/system/env/repair` | POST | OAuth pakkuja keskkonnamuutujate parandamine |
> **Märkus:** Need lõpp-punktid on kasutusel süsteemi sisemiselt või Ollama kliendi ühilduvuse jaoks. Lõppkasutajad neid tavaliselt otse ei kutsu.
### OAuth keskkonna parandamine _(v3.6.1+)_
```bash
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
```
Parandab konkreetse pakkuja puuduvad või rikutud OAuth keskkonnamuutujad. Tagastab:
```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"
}
```
---
## Audio transkribeerimine
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```
Transkribeeri audiofailid, kasutades mis tahes konfigureeritud STT-teenusepakkujat. Esimene tee segment valib natiivse teenusepakkuja (`openai/…`, `deepgram/…`). Lüüsid, mis reekspordivad teise tootja mudelit, kasutavad kvalifitseeritud id-d
(`openrouter/deepgram/nova-3`).
**Päring:**
```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"
```
**Vastus:**
```json
{
"text": "Hello, this is the transcribed audio content.",
"task": "transcribe",
"language": "en",
"duration": 12.5
}
```
**Näidis mudeli id-d:** `openai/whisper-1` (vajab OpenAI võtit),
`openrouter/deepgram/nova-3` (vajab OpenRouter võtit),
`deepgram/nova-3` (vajab natiivset Deepgram võtit). Puhas
`deepgram/nova-3` päring **ei** kasuta OpenRouter'it.
**Toetatud vormingud:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
---
## Ollama ühilduvus
Klientidele, mis kasutavad Ollama API vormingut:
```bash
# Vestluse lõpp-punkt (Ollama vorming)
POST /v1/api/chat
# Mudelite loend (Ollama vorming)
GET /api/tags
```
Päringud teisendatakse automaatselt Ollama ja sisemiste vormingute vahel.
## Tokenitud VS Code / päisevabad aliased
Kasuta neid aliaseid, kui integratsioon ei saa `Authorization` päist sisestada ja vajab API võtme baas-URL-i sisse manustamist.
```bash
# OpenAI-stiilis kataloogi alias
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# OpenAI-stiilis vestluse aliased
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Ollama-stiilis aliased
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```
Näide:
```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":"hello"}]}'
```
Märkused:
- Tokenitud aliased kasutavad samu handlereid kui `/v1/*` ja `/api/tags`; vastuse kujud jäävad identseks.
- Eelista `Authorization: Bearer ...` alati, kui klient toetab kohandatud päiseid.
- URL-põhised tokenid võivad ilmuda pöördproksi logidesse, brauseri ajalukku ja telemeetriasse väljaspool OmniRoute'i. Käsitle neid ühilduvusvõimalusena, mitte vaikimisi autentimisrežiimina.
---
## Telemeetria
```bash
# Hangi latentsuse telemeetria kokkuvõte (p50/p95/p99 iga teenusepakkuja kohta)
GET /api/telemetry/summary
```
**Vastus:**
```json
{
"providers": {
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
}
}
```
---
## Eelarve
```bash
# Hangi eelarve staatus kõigile API võtmetele
GET /api/usage/budget
# Määra või uuenda eelarvet
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"
}
```
> **Skeemi märkused** (`setBudgetSchema`): `apiKeyId` on kohustuslik; vähemalt üks väärtustest `dailyLimitUsd`, `weeklyLimitUsd` või `monthlyLimitUsd` peab olema suurem kui null. Valikulised väljad: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Vananenud `{keyId, limit, period}` kuju tagastab `400 Bad Request`.
## Token'ite piirmäärad
API-võtme kohased **token'ite** eelarve piirid (erinevad ülalpool käsitletud USD-põhisest Eelarvest). Neid jõustatakse otse päringu töötlemise käigus: kui võtme praeguse akna kasutus jõuab piirmäärani, lükatakse päringud tagasi vastusega `429 Too Many Requests`. Piirmäärasid saab rakendada konkreetsele `model`-ile, `provider`-ile või `global`-ilt kogu võtme lõikes; kui päringule vastab mitu piirmäära, kehtib kõige piiravam.
```bash
# Kuva võtme token'ite piirmäärad (sisaldab reaalajas akna kasutust)
GET /api/usage/token-limits?apiKeyId=key-123
# Loo või uuenda token'ite piirmäära
POST /api/usage/token-limits
Content-Type: application/json
{
"apiKeyId": "key-123",
"scopeType": "model",
"scopeValue": "openai/gpt-4o",
"tokenLimit": 1000000,
"resetInterval": "monthly",
"enabled": true
}
# Kustuta token'ite piirmäär id järgi
DELETE /api/usage/token-limits?id=tl-abc
```
> **Skeemi märkused** (`setTokenLimitSchema`): `apiKeyId` ja `scopeType` (`model` | `provider` | `global`) on kohustuslikud. `scopeValue` on kohustuslik, välja arvatud kui `scopeType` on `global` (nt mudeli id `model`-scope'i puhul või provider'i id `provider`-scope'i puhul). `tokenLimit` peab olema positiivne täisarv (teisendatakse stringist). Valikulised: `id` (jäta ära loomisel, lisa uuendamisel), `resetInterval` (`daily` | `weekly` | `monthly`, vaikeväärtus `monthly`), `resetTime` (`HH:MM`), `enabled` (vaikeväärtus `true`). `GET` vastused täiendavad igat piirmäära väljadega `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` ja `nextResetAt`. Tegemist on haldusklassi lõpp-punktiga (autentimist jõustatakse tsentraalselt authz pipeline'i poolt).
## Päringu töötlemine
1. Klient saadab päringu aadressile `/v1/*`
2. Route handler kutsub välja `handleChat`, `handleEmbedding`, `handleAudioTranscription` või `handleImageGeneration`
3. Mudel lahendatakse (otsene provider/mudel või alias/kombo)
4. Mandaadid valitakse kohalikust andmebaasist, filtreerides konto kättesaadavuse alusel
5. Vestluse puhul: `handleChatCore` kontrollib semantilist/signatuuri vahemälu ja lahendab kombo tihendusseaded
6. Proaktiivne tihendamine käivitub enne provider'i translatsiooni, kui see on lubatud (`lite`, Caveman, RTK või kihilisena)
7. Provider executor saadab päringu edasi (upstream)
8. Vastus tõlgitakse tagasi kliendi formaati (vestluse puhul) või tagastatakse muutmata kujul (embeddings/pildid/audio)
9. Kasutus, tihendamise analüütika ja päringute logid salvestatakse
10. Vigade korral rakendub kombo reeglite kohane fallback
Täielik arhitektuuri viide: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)
---
## Kombode haldus
Kõrgema tasandi ruuting kombod (juba kokkuvõtlikult kirjeldatud `/api/combos*` all) saab ka üks-ühele siduda mudeli id mustriga, võimaldades OpenAI-stiilis mudeli id läbipaistvat suunamist kombole.
| Meetod | Tee | Kirjeldus |
| ------ | -------------------------------- | ------------------------------------------------------------------------ |
| GET | `/api/model-combo-mappings` | Kuva kõik mudel→kombo seosed |
| POST | `/api/model-combo-mappings` | Loo seos — body: `{pattern, comboId, priority?, enabled?, description?}` |
| GET | `/api/model-combo-mappings/[id]` | Kuva üks konkreetne seos |
| PUT | `/api/model-combo-mappings/[id]` | Uuenda olemasoleva seose välju |
| DELETE | `/api/model-combo-mappings/[id]` | Eemalda seos |
**Autentimine:** haldussessioon/API-võti (`requireManagementAuth`).
---
## Veebihaagid (Webhooks)
Väljuvad veebihaagi tellimused OmniRoute sündmuste jaoks (päringu lõpetamine, kvoodi ammendumine, võtme rotatsioon jne).
| Meetod | Tee | Kirjeldus |
| ------ | ------------------------- | ----------------------------------------------------------------------- |
| GET | `/api/webhooks` | Loetleb veebihaagid (saladused on maskeeritud kujule `<prefix>...`) |
| POST | `/api/webhooks` | Loob veebihaagi — keha: `{url, events?: ["*"], secret?, description?}` |
| GET | `/api/webhooks/[id]` | Toob veebihaagi |
| PUT | `/api/webhooks/[id]` | Uuendab url/events/secret/description |
| DELETE | `/api/webhooks/[id]` | Eemaldab veebihaagi |
| POST | `/api/webhooks/[id]/test` | Saadab testandmed veebihaagi URL-ile ja tagastab kättetoimetamise oleku |
**Autentimine:** haldussessioon/API võti (`requireManagementAuth`).
---
## Registreeritud võtmed (automaatne haldus)
Kasutatakse automaatse võtmehalduse alamsüsteemi poolt, et väljastada ja rotaatida API võtmeid vastu teenusepakkuja/konto, koos päevaste/tunniste kvootidega.
| Meetod | Tee | Kirjeldus |
| ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/registered-keys` | Loetleb registreeritud võtmed (näidatakse ainult maskeeritud eesliidet) |
| POST | `/api/v1/registered-keys` | Väljastab uue registreeritud võtme — keha: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Tagastab tooreid andmeid sisaldava võtme **ühe korra**. Tagastab `429` kvoodi keeldumisel. |
| GET | `/api/v1/registered-keys/[id]` | Toob registreeritud võtme metaandmed (toorandmeid ei näidata) |
| DELETE | `/api/v1/registered-keys/[id]` | Tühistab registreeritud võtme |
| POST | `/api/v1/registered-keys/[id]/revoke` | Selgesõnaline tühistamise otspunkt (samaväärne DELETE-ga) |
**Autentimine:** Bearer API võti (`isAuthenticated`). Vaata ka `/v1/quotas/check` ja `/v1/issues/report`.
---
## Agentide protokoll
Pilveagentide ülesanded (Claude Code, Codex Cloud, OpenHands jt), mis käivitatakse kaugjuhtimisega OmniRoute'i kasutajate nimel.
| Metood | Tee | Kirjeldus |
| ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/agents/tasks` | Ülesannete loend — valikulised `?provider=`, `?status=`, `?limit=` (1–500, vaikimisi 50) |
| POST | `/api/v1/agents/tasks` | Ülesande loomine — päring valideeritakse skeemiga `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Tagastab `201` koos ülesande andmepaketiga |
| DELETE | `/api/v1/agents/tasks?id=...` | Ülesande kustutamine |
| GET | `/api/v1/agents/tasks/[id]` | Ülesande lugemine — värskendab sünkroonselt olekut ülemvoolu pilveagendist, kui `external_id` on määratud |
| POST | `/api/v1/agents/tasks/[id]` | Diskrimineeriv tegevus: `{action: "approve"}`, `{action: "message", message}` või `{action: "cancel"}` |
| DELETE | `/api/v1/agents/tasks/[id]` | Konkreetse ülesande kustutamine id järgi |
> **Autentimine:** haldusautentimine on nõutav kõigi meetodite puhul (`requireCloudAgentManagementAuth`). Enne versiooni v3.8.0 olid need autentimata — vaata muudatust commitis `588a0333`.
```bash
# Loo Claude Code pilveülesanne
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":"..."}}'
```
---
## Haldusproksid
Väljuvad HTTP(S)/SOCKS proksid, mida saab määrata pakkujatele, kontodele või globaalselt.
| Metood | Tee | Kirjeldus |
| ------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/v1/management/proxies` | Proksite loend (koos `?id=` tagastab ühe; koos `?id=&where_used=1` tagastab määramiste graafi) |
| POST | `/api/v1/management/proxies` | Proksi loomine — päring valideeritakse skeemiga `createProxyRegistrySchema` |
| PATCH | `/api/v1/management/proxies` | Proksi uuendamine — päring valideeritakse skeemiga `updateProxyRegistrySchema` (vajab `id`) |
| DELETE | `/api/v1/management/proxies?id=...&force=1` | Proksi kustutamine (kasuta `force=1`, et eraldada määramised) |
| GET | `/api/v1/management/proxies/assignments` | Määramiste loend — filtreeritav `proxy_id`, `scope`, `scope_id` järgi; edasta `resolve_connection_id=<id>`, et lahendada ühenduse aktiivne proks |
| PUT | `/api/v1/management/proxies/assignments` | Määramine — päring valideeritakse skeemiga `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Tühjendab dispetšeri vahemälu |
| PUT | `/api/v1/management/proxies/bulk-assign` | Hulgimääramine — päring valideeritakse skeemiga `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) |
| GET | `/api/v1/management/proxies/health?hours=24` | Proksite koondtervis (õnnestumiste/ebaõnnestumiste arv, latentsus) antud ajavahemikus |
**Autentimine:** haldusseanss/API-võti on nõutav kõigi teede puhul (`requireManagementAuth`).
> Ülesande kirjelduses mainitud `POST /api/v1/management/proxies/[id]/assignments` ja `POST /api/v1/management/proxies/[id]/health` teenindatakse tegelikult ülalpool näidatud lamedate `/assignments` ja `/health` teede kaudu — koodibaasis puuduvad id-põhised alamteed.
---
## Vastupidavus (laiendatud)
OmniRoute pakub kolme sõltumatut ajutise rikke mehhanismi; allolevad haldusotspunktid võimaldavad operaatoritel neid lugeda ja üle kirjutada:
| Ulatus | Oleku salvestus | Lugemine | Lähtestamine / tühjendamine |
| ----------------------------------- | -------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------ |
| Teenusepakkuja katkestaja (breaker) | `domain_circuit_breakers` + mälusisene | `/api/monitoring/health` | `POST /api/resilience/reset` |
| Ühenduse jahutusaeg | `rateLimitedUntil` teenusepakkuja ühendustel | `/api/rate-limits`, `/api/providers/[id]` | (taasaktiveerub laisalt; tühjenda teenusepakkuja PUT-i abil) |
| Mudeli lukustus | Mälusisene mudeli saadavuse register | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` |
`PATCH /api/resilience` võtab vastu teenusepakkuja katkestaja (breaker) ülekirjutusi `providerBreaker.oauth` ja `providerBreaker.apikey` alt. Igas profiilis on toetatud `degradationThreshold`, `failureThreshold` ja `resetTimeoutMs`; samad väljad on kättesaadavad ka Dashboard → Settings → Resilience jaotises.
```bash
# Tühjenda üksik mudeli lukustus
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"}'
# Kustuta kõik lukustused
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
```
Täielik kontseptuaalne viide ja katkestaja (breaker) vaikeväärtused: vaata [`CLAUDE.md`](../../CLAUDE.md) → "Resilience Runtime State".
---
## Oskused (Skills)
Oskuste raamistik OmniRoute laiendamiseks kohandatud käivitatavate handleritega, samuti turuplatsi integratsioonid.
| Meetod | Tee | Kirjeldus |
| ------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/skills` | Loetleb installitud oskused — filtreeritavad `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local` järgi, lehekülgede kaupa |
| GET | `/api/skills/[id]` | Ühe oskuse pärimine |
| PUT | `/api/skills/[id]` | Oskuse uuendamine (nimi, kirjeldus, režiim, skeem, handler, sildid) |
| DELETE | `/api/skills/[id]` | Oskuse eemaldamine |
| POST | `/api/skills/install` | Oskuse installimine toormanifestist — sisu: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
| GET | `/api/skills/executions` | Loetleb viimased oskuste käivitused (auditijälg sisendite/väljundite/kestusega) |
| GET | `/api/skills/marketplace?q=...` | Otsing/populaarsuse loend SkillsMP turuplatsilt (vajab `skillsmpApiKey` seadistust) |
| POST | `/api/skills/marketplace/install` | Oskuse installimine ID järgi SkillsMP-st |
| GET | `/api/skills/skillssh?q=&limit=` | Otsing skills.sh registrist |
| POST | `/api/skills/skillssh/install` | Oskuse installimine ID järgi skills.sh-ist |
**Autentimine:** haldussessioon/API-võti. Turuplatsi otsingu otspunktid aktsepteerivad kas haldusautentimist või Bearer API-võtit (`isAuthenticated`).
---
## Mälu
Püsiv vestlus-/faktimälu hoidla, ulatusega API võtme / seansi kaupa.
| Meetod | Tee | Kirjeldus |
| ------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/memory` | Mälukirjete loend — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, koos `offset/limit` või `page/limit` leheküljestusega |
| POST | `/api/memory` | Mälukirje loomine — keha valideeritakse Zod-iga: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET | `/api/memory/[id]` | Ühe mälukirje päring |
| DELETE | `/api/memory/[id]` | Mälukirje kustutamine |
| GET | `/api/memory/health` | Mälu alamsüsteemi tervis (andmebaasi ühenduvus, manustuste taustasüsteem, vektorindeksi olek) |
**Autentimine:** haldusseanss/API võti (`requireManagementAuth`). `type` väärtused: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (vt `MemoryType` failis `src/lib/memory/types.ts`).
---
## MCP server
OmniRoute pakub sisseehitatud Model Context Protocol serverit kolme transpordiga (stdio, SSE, streamable-http) ja piiratud ulatusega tööriistadega. Allolevad juhtpaneeli lõpp-punktid loevad oleku-/auditandmeid ja vahendavad HTTP transporte.
| Meetod | Tee | Kirjeldus |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Südamelöök, transport, võrgus olek, viimane kõne, populaarseimad tööriistad, 24h edukuse määr |
| GET | `/api/mcp/tools` | MCP tööriistade loend väljadega `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
| GET | `/api/mcp/sse` | Ava SSE voog SSE transpordile (tagastab `503`, kui MCP on välja lülitatud või transport ei sobi) |
| POST | `/api/mcp/sse` | Saada JSON-RPC kaader SSE transpordile |
| GET | `/api/mcp/stream` | Ava Streamable HTTP transpordi SSE poolt (serveri algatatud sõnumid) |
| POST | `/api/mcp/stream` | Saada JSON-RPC kaader Streamable HTTP transpordile |
| DELETE | `/api/mcp/stream` | Lõpeta Streamable HTTP seanss |
| GET | `/api/mcp/audit` | Päri auditilogi — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | Koondstatistika auditist (kogusummad, edukuse määr, keskmine kestus, populaarseimad tööriistad) |
**Autentimine:** transpordid `sse`/`stream` austavad MCP-spetsiifilist autentimispinda (Bearer API võti ulatusega `mcp`); `status`/`tools`/`audit*` lõpp-punktid on juhtpaneelilt loetavad (täiendavat autentimist ei vajata, kui juhtpaneeli hosti on juba juurde pääsetud).
> Mõlemad HTTP transpordid sõltuvad seadetest `settings.mcpEnabled` ja `settings.mcpTransport` — transpordi mittevastavus tagastab `400`, MCP väljalülitatud oleku puhul tagastatakse `503`.
---
## A2A server
OmniRoute pakub A2A (Agent-to-Agent) JSON-RPC 2.0 lõpp-punkti ja REST-i ümbrist, mida saab kasutada inspekteerimiseks/juhtpaneelil.
### JSON-RPC
```bash
POST /a2a
Authorization: Bearer your-api-key # valikuline, välja arvatud kui OMNIROUTE_API_KEY on määratud
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "message/send",
"params": {
"skill": "smart-routing",
"messages": [{"role": "user", "content": "Route this coding task"}]
}
}
```
Toetatud meetodid (kõik sõltuvad `settings.a2aEnabled` seadest):
| Meetod | Kirjeldus |
| ---------------- | --------------------------------------------------------------------- |
| `message/send` | Sünkroonne oskuse käivitamine; tagastab `{task, artifacts, metadata}` |
| `message/stream` | Sama oskuste komplekti voogesitusega (SSE) käivitamine |
| `tasks/get` | Ülesande hankimine `taskId` järgi |
| `tasks/cancel` | Ülesande tühistamine `taskId` järgi |
Sisseehitatud oskused: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.
### Agendikaart
```bash
GET /.well-known/agent.json
```
Tagastab avaliku A2A agendikaardi (nimi, kirjeldus, võimalused, oskuste kataloog, autentimisskeem) — vahemällu salvestatud avalikult 1 tunniks. Autentimist ei vajata.
### REST-i abifunktsioonid
| Meetod | Tee | Kirjeldus |
| ------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/a2a/status` | A2A lubatud + ülesannete statistika + vahemällu salvestatud agendikaardi kokkuvõte |
| GET | `/api/a2a/tasks` | Ülesannete loend — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST | `/api/a2a/tasks` | (Ei ole rakendatud REST-i abifunktsioonina — loo JSON-RPC `message/send` kaudu) |
| GET | `/api/a2a/tasks/[id]` | Ühe ülesande hankimine |
| POST | `/api/a2a/tasks/[id]/cancel` | Ülesande tühistamine |
**Autentimine:** REST-i abifunktsioonid töötavad ilma haldusautentimiseta (juhtpaneelilt loetavad); JSON-RPC `/a2a` tee kasutab Bearer `OMNIROUTE_API_KEY` väärtust, kui see on konfigureeritud.
---
## Cloud, Evals ja Assess
| Meetod | Tee | Kirjeldus |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Kontrollib Bearer võtit ja tagastab maskeeritud pakkuja ühendused + mudelite aliased pilve sünkroonimise klientidele |
| POST | `/api/cloud/credentials/update` | Uuendab krüpteeritud volikirju pilves sünkroonitud pakkuja jaoks |
| POST | `/api/cloud/model/resolve` | Lahendab loogilise mudeli ID konkreetseks pakkujaks/mudeliks, kasutades kohalikku ruutimistabelit |
| GET | `/api/cloud/models/alias` | Loetleb mudelite aliased, mis on pilvesünkroonimisele nähtavad |
| GET | `/api/assess` | Loeb viimased hindamise kategoriseeringud (pakkuja/mudeli kaupa) |
| POST | `/api/assess` | Käivitab hindamise — päis: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Loetleb sisseehitatud hindamiskomplektid + viimased käivitused |
| POST | `/api/evals` | Käivitab hindamise |
| POST | `/api/evals/suites` | Loob kohandatud hindamiskomplekti — päis valideeritakse `evalSuiteSaveSchema` kaudu |
| GET | `/api/evals/suites/[id]` | Hangib kohandatud hindamiskomplekti |
**Autentimine:** `/api/cloud/auth` valideerib Bearer võtme otse; teised `/api/cloud/*`, `/api/evals/*` ja `/api/assess` teed vajavad haldussessiooni/API-võtit. `/api/assess` POST kasutab `validateBody` funktsiooni koos diskrimineeritud liidu (union) skeemiga.
---
## ACP (Agent Client Protocol) haldus
lapsprotsessidena. Need lõpp-punktid haldavad ACP agentide tuvastamist ja
kohandatud agentide registreerimist.
| Metood | Tee | Kirjeldus |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/acp/agents` | Loetleb kõik teadaolevad CLI agendid (sisseehitatud + kohandatud) koos paigaldusoleku, versiooni ja binaarfailiga |
| POST | `/api/acp/agents` | Registreerib kohandatud ACP agendi või uuendab vahemälu — sisu: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` või `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Eemaldab kohandatud ACP agendi — päringuparameeter: `?id=<agentId>` |
**Vastuse näide** (`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
}
```
**Autentimine:** Vajalik on haldussessioon (dashboardi `auth_token` küpsis) või
haldusõigustega API võti.
Täpsema info saamiseks vaata [ACP raamistik](../frameworks/ACP.md).
---
## Analüütika ja jälgitavus
Reaalajas analüütika lõpp-punktid ruutimise, tihendamise ja pakkujate
mitmekesisuse jälgimiseks. Need toetavad `/dashboard/analytics/*` lehti.
### Automaatse ruutimise analüütika
| Metood | Tee | Kirjeldus |
| ------ | ------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/auto-routing` | Koondstatistika automaatse ruutimise kohta: kõnede koguarv, strateegiate jaotus, tasemete jaotus, top pakkujad |
| GET | `/api/analytics/auto-routing?days=7` | Ajavahemikuga piiratud statistika (vaikimisi 24h) |
**Vastuse näide**:
```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 }
]
}
```
### Tihendamise analüütika
| Metood | Tee | Kirjeldus |
| ------ | ---------------------------- | -------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/compression` | Koondstatistika tihendamise kohta: säästetud tokenid, sääst %, režiimide jaotus, mootorite kasutus |
**Vastuse näide**:
```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
}
}
```
### Pakkujate mitmekesisuse jälgimine
| Metood | Tee | Kirjeldus |
| ------ | -------------------------- | ----------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/diversity` | Shannoni entroopial põhinev mitmekesisuse jälgimine: vältib üksikuid rikkepunkte, mõõtes pakkujate hajuvust |
**Vastuse näide**:
```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 moodustab 40% liiklusest — kaaluge mitmekesistamist"]
}
```
**Autentimine:** Vajalik on haldussessioon või haldusõigustega API võti.
---
## Administraatori toimingud
Ainult administraatoritele mõeldud lõpp-punktid operatiivseks haldamiseks.
| Meetod | Tee | Kirjeldus |
| ------ | ------------------------ | --------------------------------------------------------------------------------------------------- |
| GET | `/api/admin/concurrency` | Praeguste samaaegsuse piirangute lugemine (globaalsed + pakkuja kohta) |
| POST | `/api/admin/concurrency` | Samaaegsuse piirangute uuendamine — body: `{global?: number, perProvider?: Record<string, number>}` |
**Autentimine:** Vajalik administraatoriõigustega haldusseanss.
---
## CLI-tööriistade haldamine
Halda CLI-tööriistu, mis integreeruvad OmniRoute-iga (antigravity, chipotle, commandCode,
devin-cli jne). Täieliku loendi leiad siit: [Pakkujate viide](./PROVIDER_REFERENCE.md).
| Meetod | Tee | Kirjeldus |
| ------ | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cli-tools/all-statuses` | Kõigi CLI-tööriistade olek (paigaldatud, versioon, viimati nähtud) |
| GET | `/api/cli-tools/status` | Ühe CLI-tööriista oleku üksikasjad (`?tool=` päring) |
| POST | `/api/cli-tools/apply` | Kirjuta tööriista genereeritud konfiguratsioon (`dryRun` teeb eelvaate; `422` + `containerEphemeralTarget` konteineriseerituse korral; `migration` viitab vanapärasele Codex YAML-ile) |
| GET | `/api/cli-tools/backups` | CLI-tööriistade konfiguratsioonide varukoopiate loend |
| POST | `/api/cli-tools/backups` | Loo varukoopia kõigist CLI-tööriistade konfiguratsioonidest |
| POST | `/api/cli-tools/backups` | Taasta: sama lõpp-punkt, kuid kehas `{tool, backupId}` taastab vastava varukoopia |
| GET | `/api/cli-tools/antigravity-mitm` | Antigravity MITM-vahendusserveri olek ("antigravity-mitm" CLI-tööriist) |
| POST | `/api/cli-tools/antigravity-mitm/alias` | Antigravity-mitm aliaste konfigureerimine |
**Autentimine:** Vajalik haldusseanss.
---
## Agendi oskused
Halda AI agentide oskusi (sarnaselt OpenAI kohandatud GPT-dele, kuid agentide jaoks).
| Meetod | Tee | Kirjeldus |
| ------ | ---------------------------- | -------------------------------------------------------------------------------------------- |
| GET | `/api/agent-skills` | Kõigi agendi oskuste loend (sisseehitatud + kohandatud) |
| GET | `/api/agent-skills/[id]` | Konkreetse agendi oskuse hankimine |
| POST | `/api/agent-skills` | Kohandatud agendi oskuse loomine — body: `{name, description, prompt, model?, temperature?}` |
| PUT | `/api/agent-skills/[id]` | Kohandatud agendi oskuse uuendamine |
| DELETE | `/api/agent-skills/[id]` | Kohandatud agendi oskuse kustutamine |
| GET | `/api/agent-skills/[id]/raw` | Töötlemata prompti ja metaandmete hankimine (ilma käivitamata) |
| POST | `/api/agent-skills/generate` | AI genereerib uue oskuse loomuliku keele kirjelduse põhjal |
**Autentimine:** Vajalik haldusseanss või haldusõigustega API-võti.
---
## Vahemälu haldus
Semantilise vahemälu ja arutlusvahemälu haldamine.
| Meetod | Tee | Kirjeldus |
| ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cache` | Vahemälu ülevaade: kirjete koguarv, tabamuste määr, kettal olev suurus |
| GET | `/api/cache/entries` | Vahemälus olevate kirjete loend (koos leheküljestamisega) |
| DELETE | `/api/cache/entries` | Vahemälu kirjete kustutamine (filtreerimine päringuparameetrite alusel) |
| GET | `/api/cache/stats` | Detailne vahemälu statistika (pakkuja ja mudeli kaupa) |
| GET | `/api/cache/reasoning` | Arutlusvahemälu olek (arutluse taasesituseks) |
| DELETE | `/api/cache/reasoning` | Arutlusvahemälu tühjendamine — päringuparameetrid: `?toolCallId=<id>` (üksik) või `?provider=<p>` või ilma parameetriteta (kõik) |
**Autentimine:** Vajalik haldusseanss.
---
## Mäluüsteem
Püsimälu haldamine (FTS5 + vektor-embeddingud).
| Meetod | Tee | Kirjeldus |
| ------ | ------------------ | -------------------------------------------------------------------------- |
| GET | `/api/memory` | Mäluüksuste loend (filtreerimine ulatuse, tüübi või otsingupäringu alusel) |
| POST | `/api/memory` | Uue mäluüksuse loomine — päring: `{scope, type, content, metadata?}` |
| GET | `/api/memory/[id]` | Konkreetse mäluüksuse hankimine |
| PUT | `/api/memory/[id]` | Mäluüksuse värskendamine |
| DELETE | `/api/memory/[id]` | Mäluüksuse kustutamine |
| GET | `/api/memory?q=` | Mälust otsimine (FTS5 + vektor) — statistika sisaldub samas vastuses |
**Autentimine:** Vajalik haldusseanss või haldusõigustega API-võti.
---
## Veebihaagid (Webhooks)
Sündmuste jaoks veebihaakide tellimuste haldamine.
| Meetod | Tee | Kirjeldus |
| ------ | ------------------------------- | -------------------------------------------------------------------------- |
| GET | `/api/webhooks` | Kõikide veebihaagi tellimuste loend |
| POST | `/api/webhooks` | Veebihaagi tellimuse loomine — päring: `{url, events[], secret?, active?}` |
| GET | `/api/webhooks/[id]` | Konkreetse veebihaagi tellimuse hankimine |
| PUT | `/api/webhooks/[id]` | Veebihaagi tellimuse värskendamine |
| DELETE | `/api/webhooks/[id]` | Veebihaagi tellimuse kustutamine |
| GET | `/api/webhooks/[id]/deliveries` | Veebihaagi edastuste ajaloo loend (õnnestumiste/nurjumiste logi) |
| POST | `/api/webhooks/[id]/test` | Testsündmuse saatmine veebihaagile |
**Autentimine:** Vajalik haldusseanss.
Täieliku sündmuste tüüpide loetelu leiate: [Webhooks Framework](../frameworks/WEBHOOKS.md).
---
## Skills raamistik
Skillide (agentse laienduste raamistiku) haldamine.
| Meetod | Tee | Kirjeldus |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------- |
| GET | `/api/skills` | Kõigi installitud skillide loend (sisseehitatud + kohandatud) |
| POST | `/api/skills/install` | Skilli installimine kohalikust asukohast või URL-ilt |
| DELETE | `/api/skills/[id]` | Skilli desinstallimine |
| PUT | `/api/skills/[id]` | Skilli lubamine või keelamine — sisu: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST | `/api/skills/executions` | Skilli täitmine — sisu: `{skillName, apiKeyId, input?, sessionId?}` |
| GET | `/api/skills/executions` | Kõigi skillide täitmisajaloo loend (filtreeri `?apiKeyId=` järgi) |
**Autentimine:** Vajalik on halduse sessioon või haldusõigustega API-võti.
Täieliku ülevaate saamiseks vaata [Skillide raamistik](../frameworks/SKILLS.md).
---
## Pluginad
OmniRoute pluginate (kolmandate osapoolte laienduste) haldamine.
| Meetod | Tee | Kirjeldus |
| ------ | ---------------------------------- | -------------------------------------- |
| GET | `/api/plugins` | Installitud pluginate loend |
| POST | `/api/plugins/marketplace/install` | Plugina installimine turuplatsilt |
| DELETE | `/api/plugins/[name]` | Plugina desinstallimine |
| POST | `/api/plugins/[name]/activate` | Plugina aktiveerimine |
| POST | `/api/plugins/[name]/deactivate` | Plugina deaktiveerimine |
| GET | `/api/plugins/[name]/config` | Plugina konfiguratsiooni pärimine |
| PUT | `/api/plugins/[name]/config` | Plugina konfiguratsiooni värskendamine |
**Autentimine:** Vajalik on halduse sessioon.
Täieliku ülevaate saamiseks vaata [Pluginate raamistik](../frameworks/PLUGIN_SDK.md).
---
## Shadow ruutimine
Pakkujate shadow / A-B võrdlus **ei ole eraldiseisev REST-liides** — see konfigureeritakse combo ruutimise kaudu (vaata [Auto-Combo](../routing/AUTO-COMBO.md)). Combo-kohaseid võrdlusmõõdikuid pakub `GET /api/combos/metrics`.
---
## Guardrails (kaitsemehhanismid)
Käitusaegsete kaitsemehhanismide (PII tuvastus, prompt-süstimise tuvastus, visuaalne sildumine) ülevaatamine. Kaitsemehhanismid töötavad iga päringu puhul; päringupõhine loobumine toimub `x-omniroute-disabled-guardrails` päringu päise kaudu — püsivat lubamise/keelamise liidest ei ole.
| Meetod | Path | Kirjeldus |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------- |
| GET | `/api/guardrails` | Registreeritud kaitsemehhanismide ja nende oleku loend (nimi / lubatud / prioriteet) |
| POST | `/api/guardrails/test` | Enne-kõnet toimuva töövoo katsekäivitus näidissisendi peal — sisu: `{input, disabledGuardrails?}` |
**Autentimine:** Vajalik on halduse sessioon.
Täieliku ülevaate saamiseks vaata [Turvalisus > Guardrails](../security/GUARDRAILS.md).
---
---
## Autentimine
Vaadake [Halduse autentimine](../guides/MANAGEMENT-AUTH.md), kus kirjeldatakse
nelja mandaadipere (armatuurlaua seanss, kohalik CLI-märgis, `oma_live_…`
juurdepääsuluba, manage-õigustega API-võti) ja seda, kuidas need erinevad
järelduse (inference) võtmetest.
- Armatuurlaua marsruudid (`/dashboard/*`) kasutavad `auth_token` küpsist
- Sisselogimine kasutab salvestatud parooli räsi; varuvariandiks on `INITIAL_PASSWORD`
- `requireLogin` on lülitatav `/api/settings/require-login` kaudu
- `/v1/*` marsruudid vajavad valikuliselt Bearer API-võtit, kui `REQUIRE_API_KEY=true`
- selles viitedokumendis tähendab "halduse märgis" / "manage-õigustega API-võti" ühte nimetatud juhendi peredest — mitte määratlemata täiendavat salajase teabe tüüpi
> **Ühilduvust rikkuv muudatus (v3.8.0)** — `/api/v1/agents/tasks/*` ja jahutusaja (cooldown) halduse otspunktid vajavad nüüd **halduse autentimist** (armatuurlaua `auth_token` küpsist või manage-õigustega API-võtit). Kliendid, kes varem kutsusid need marsruudid välja autentimata, saavad nüüd vastuseks `401 Unauthorized`. Vaadake commit'i `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).
Reference in New Issue View Git Blame Copy Permalink