pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-17 12:22:34 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
76b037c2e7c3cc015f3cc03451f08d6252ddc2df
OmniRoute/docs/i18n/ga/docs/reference/API_REFERENCE.md
Diego Rodrigues de Sa e Souza 58f88a83e4 feat(i18n): 7 new locales — Hausa, Yoruba, Igbo, Amharic, Uzbek, Georgian, Armenian (66 locales) (#13727) 
Batch 3 (last) of the locale-expansion plan: ha, yo, ig, am, uz, ka, hy on every surface — dashboard catalog, docs mirror (22-file core + llm.txt + CHANGELOG), CLI catalog, README flag block, locale tables and 🌐 language bars. Also closes the key gap the batch-1 (43 keys) and batch-2 (10 keys) catalogs carried since their base merges, fixes the Igbo "Model" copy and allowlists the Uzbek cognate. Translation-ratio baseline covers 65 locales.

⚠️ base-red inherited: #12732
2026-09-15 09:50:01 -03:00

1717 lines
122 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 (Gaeilge)
🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/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)
---
---
title: "Tagairt API"
version: 3.8.51
lastUpdated: 2026-08-31
---
# Tagairt API
🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/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)
Príomhthagairt don API OmniRoute. Cuimsíonn sé an dromchla poiblí `/v1` agus na pointí bainistíochta is mó a úsáidtear; [`docs/openapi.yaml`](../openapi.yaml) léite le meaisín agus an crann ródanna faoi `src/app/api/` is iad na foinsí iomlána.
---
## Clár Ábhair
- [Comhlánúcháin Comhrá](#chat-completions)
- [Cúnaimh Seisiúin Eisiacha Bainistithe](#exclusive-managed-session-leases)
- [Leabúcháin](#embeddings)
- [Giniúint Íomhá](#image-generation)
- [OCR Cáipéisí](#document-ocr)
- [Liostáil Samhlacha](#list-models)
- [Manifead Soláthraí Plugin](#provider-plugin-manifest)
- [Deireanna Comhoiriúnachta](#compatibility-endpoints)
- [Comhaid API](#files-api)
- [Batchanna API](#batches-api)
- [API Taiscéil](#search-api)
- [Straoisiú WebSocket](#websocket-streaming)
- [Quótaí & Tuairisciú Saincheisteanna](#quotas--issues-reporting)
- [Taisce Séimeantach](#semantic-cache)
- [Painéal & Bainistíocht](#dashboard--management)
- [Bainistíocht Combo](#combo-management)
- [Gréasáin Hookála](#webhooks)
- [Eochracha Cláraithe (Bainistíocht Uathoibríoch)](#registered-keys-auto-management)
- Prótacal gníomhaireanna (agents protocol)
- Bróicéirí Bainistíochta (management proxies)
- [Dul-as-áite (leathnaithe)](#resilience-extended)
- [Scileanna](#skills)
- [Cuimhne](#memory)
- Freastalaí MCP (mcp server)
- Freastalaí A2A (a2a server)
- [Scamall, Meastóireachta & Luacháil](#cloud-evals--assess)
- Próiseáil Iarratais (request processing)
- [Fíordheimhniú](#authentication)
---
## Comhlánúcháin Comhrá
```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
}
```
### Príobháideachtaí Saincheaptha
| Príobháideacht | Treoshuíomh | Cur Síos |
| ------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache` | Iarratas | Socraigh go `true` chun taisce a sheachaint |
| `x-omniroute-no-memory` | Iarratas | Socraigh go `true` chun cuimhne + insteáil scileanna a scipeáil don iarratas seo (macallaí le no-cache; seachaineann sé costas comharthaíochta/costais in aghaidh an ghairm) |
| `X-OmniRoute-Progress` | Iarratas | Socraigh go `true` le haghaidh teagmhais dul chun cinn |
| `X-Session-Id` | Iarratas | Eochair seisiúin greamaitheach don bhfuaimniú seisiúin seachtrach |
| `x_session_id` | Iarratas | Malartach foirmne leictreonach freisin (HTTP díreach) |
| `X-OmniRoute-Session-Id` | Iarratas | Clib seisiúin/comhrá soláthraithe ag an gcaoineoir (soláthraíonn sé freisin cuimhne). Nuair a bheidh sé i láthair, coinnítear mar atá i `call_logs.session_tag` le haghaidh leithscriú costais in aghaidh an tseisiúin (#8249) — ní dhéantar é a shintéisú nuair nach bhfuil sé i láthair |
| `Idempotency-Key` | Iarratas | Eochair dídhíolaimh (fuinneog 5s) |
| `X-Request-Id` | Iarratas | Eochair dídhíolaimh malartach |
| `X-OmniRoute-Cache` | Freagra | `HIT` nó `MISS` (neamh-ghruthaíoch) |
| `X-OmniRoute-Idempotent` | Freagra | `true` má tá sé dídhílithe |
| `X-OmniRoute-Progress` | Freagra | `enabled` má tá rianú dul chun cinn ann |
| `X-OmniRoute-Session-Id` | Freagra | Aitheantas seisiúin éifeachtach a úsáideann OmniRoute |
| `X-OmniRoute-Request-Id` | Freagra | Aitheantas comhghaoil an iarratais (nuair a bhfuil sé ar eolas) |
| `X-OmniRoute-Version` | Freagra | Leagan tógála OmniRoute (i gcónaí i láthair) |
| `X-OmniRoute-Cost-Saved` | Freagra | USD a sheachain an taisce ar HIT (buanna taisce amháin) |
| `X-OmniRoute-Decision` | Freagra | Rianú ródaithe: `strategy=<ainm>; provider=<ailias>; latency_ms=<n>` (`<ainm>` é an straitéis combo, nó `single` d'iarratas neamh-combo) — i gcónaí i láthair ar fhreagairt críochnaithe |
> Nóta Nginx: má braitheann tú ar cheannteidil le foirmne leictreonach (mar shampla `x_session_id`), cumasaigh `underscores_in_headers on;`.
> **Ceannteidil teileaméadrachta costais:** cuirtear tacar `X-OmniRoute-*` teileaméadrachta costais le freagairt rathúil neamh-ghruthaíoch freisin — `X-OmniRoute-Response-Cost` (USD, deich n-uimhir dheicigiúil seasta; `0.0000000000` dathaorí/nár phraghsáladh), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit`, agus `X-OmniRoute-Fallback-Attempts` (amháin nuair a bhíonn > 0), móide `X-OmniRoute-Request-Id` agus `X-OmniRoute-Version`. Fuaimeann iad seo le comhlánúcháin comhrá, `/v1/responses`, `/v1/messages**, agus **na deireanna meán** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`, agus `/v1/moderations`(costas i gcónaí`0`). Ríomhann costas meán de réir modality (in aghaidh na híomhá, in aghaidh an tsoicind, in aghaidh an charachtair, in aghaidh an aonaid taiscéil) nuair a bhíonn praghsáil ar fáil, seachas sin `0` (teip oscailte).
> **Samhlacha costas buanna taisce:** ar buanna taisce séimeantach (`X-OmniRoute-Catch-Hit: true`) ní dhéantar glao ar ais, mar sin is `0.0000000000` é `X-OmniRoute-Response-Cost` (an costas **fhorlíontach** a sheirbheálann an buanna). Tugtar tuairisc ar an bhunchoiste/bheadh-fosta costas ar leithligh i `X-OmniRoute-Cost-Saved`. Ba cheart do thomhaltóirí billíochta `X-OmniRoute-Response-Cost` a shuim (ní chosnaíonn buanna taisce aon ní); is féidir le taisce-anailísíocht `X-OmniRoute-Cost-Saved` a chomhoibriú.
## Cúraimí Sesiúin Eisiach Aistrithe
Is éard atá i gceist le cíosú suíochán aistrithe eisiach ná conradh ródála roghnach neodrúil an chliaint: sealbhóir gníomhach amháin
seasann ceann amháin de cheangal bailí OmniRoute. Níl sé ag cíosú samhail, ní éilíonn sé OAuth, ní aithníonn sé
cliant ar leith, níl sé ag teastáil ó sholáthraí ar leith.
Caithfidh an eochair API fíordheimhnithe an raon `lease:exclusive` a bheith aici agus liosta ceart
`allowedConnections` neamhfholamh. Dearann an teorainn athrúchán bunachar sonraí an dá réimse le chéile nuair a
cruthaítear eochair agus i nglanbhfuascailt páirteach.
```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"}
```
Taispeánann freagraí éadáil, athnuaite agus scaoilte rathúla stampsa ama, `state`, agus an dearfach beacht
`generation`, ach ní dhéanann siad riamh ceangal roghnaithe nó ainmhíniú teagmhála. Soláthraíonn athnú agus scaoileadh an
giniúint sa corp JSON:
```json
{ "action": "renew", "generation": 1 }
```
```json
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
```
Is féidir le sealbhóir suíochán gníomhach iarratas a dhéanamh go soiléir ar mheitadaita taispeána sábháilte príobháideachais a bhfuil a cheangal reatha aige:
```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": "Príomhchódacs",
"provider": "codex"
}
}
```
Cuirtear an stádas roghnach seo i bhfeidhm ag an sealbhóir dorchadais, an eochair API aistrithe dearbhaithe, agus an
giniúint gníomhach beacht in aon idirbheart bunachar sonraí amháin. Níl `displayName` ach an t-ainm ceangail cumraithe
gearrtha; is é `null` é nuair nach bhfuil ainm sábháilte cumraithe ann. Ní déanann OmniRoute riamh ríomhphost nó
aitheantas cuntas ginte a athchur. Is é an luach soláthraí lipéad taispeána neamh-thollsmaoine agus ní
aitheantas soláthraí comhoiriúnach ginte riamh. Earraí teagmhála, teibhiní, fianáin, IDanna ceangail nó API amh,
hashes sealbhóra, rúin fhaing, agus sonraí ródála inmheánacha fágtar amach.
Filleann gach amharc cearr-eochair, cearr-sealbhóir, giniúint sean-aimsir, in easnamh, as dáta, scaoilte, agus neamhbhailí ar an
bhfeall céanna `409 LEASE_FENCE_STALE` gan mheitadaita ceangail. Níl aon cheangal gníomhach ag claint a fuair an freagra
feithimh acmhainne le scrúdú. Nuair a thrasnaíonn an ródáil suíochán gníomhach, fanann an giniúint céanna bailí agus
fillfidh an stádas go hataimice ar an gceangal nua, ní ar an sean-cheangal amháin. Fanann na cliaint atá ann gan athrú toisc
go gcoinneoidh freagraí éadáil, athnuna, scaoilte agus feithimh a n-cruthanna roimhe seo.
Ní athraíonn an conradh freastalaí seo stádas Codex OpenAI gnáth `/status`. Tuarascálann Codex gnáth anois a
sholáthraí samhail agus stádas dearbhaithe/chuntas ionsuite ach ní dhéanann sé mheitadaita cuntais sholáthraí saincheaptha
ar bithe a rindreáil; caithfidh comhtháthú cliant ina dhiaidh sin glao a dhéanamh ar an ngníomh seo agus cinneadh a dhéanamh conas
`connection.displayName` a thaispeáint.
Ansin soláthraíonn gach iarratas tomhaillte aistrithe an dá cheann rialaithe:
```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```
Dearadh an sealbhóir beacht, an giniúint, an ceangal gníomhach, agus an eochair API dearbhaithe díreach roimh
gach iarracht suas-chreasa tacaíochta. Ní theipeann an t-sealbhóir agus an giniúint a atreorú le heochair eile fiú
nuair a cheadaíonn an eochair sin an ceangal céanna. Ní stóráiltear, ní logáiltear, ní choimeádtear i mbunachar
snaidhm iarratais, ná ní sheoltar úinéirí amh thart.
Fillean troid shealadach le HTTP `429` le `Retry-After` agus:
```json
{
"state": "WAITING_FOR_CAPACITY",
"error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
"reason": "NO_FREE_ELIGIBLE_CONNECTION",
"retryAfter": 30
}
```
Ciallaíonn an freagra seo ach go raibh an tacar gníomhach gnáth go heisiach agus go raibh gach iarrthóir saor
ag coinneáil ag suíochán coigríche gníomhach. Coinníonn samhlacha/soláthraithe gan tacaíocht, mímhaitheas polasaí, fuarú,
ciste, sláinte, agus teipthe eisiúcháin gnáth a bhfreagairtí OmniRoute reatha.
### `x-omniroute-compression`
Forbhreathnú ríomhaireachta in aghaidh an iarratais ar an bplean comhbhrú. Imeallacht is airde — buann sé an ródáil-chomhcheangal
forbhreathnú, an próifíl gníomhach, tuarascáil auto, agus an Réamhshocrú Pána. Luachanna:
| Luach | Éifeacht |
| ------------- | --------------------------------------------------------------------------------- |
| `off` | Gan comhbhrú don iarratas seo. |
| `default` | An Réamhshocrú próifíl pána (neamhaird ar an bpróifíl gníomhach). |
| `engine:<id>` | Inneall amháin nuair atá cumasaithe, mar shampla `engine:rtk`. |
| `<combo>` | Comhcheangal ainmnithe, meaitseáilte le hainm (gan cás i dtosach), ansin le h-id. |
Nótaí:
- Déantar neamhshuim ar luachanna anaithnide (ní dhiúltaitar an t-arratas riamh); tarlaíonn an t-aimsriúchán
tríd an tosaíocht oibríora gnáth.
- Má roinntear ainmanna ag iliomad comhcheangal, seol an t-ainm **id** le haghaidh meaitseála dearfa.
- Ní féidir comhcheangal a roghnú le hainm `off` nó `default` (tugtar ar na príomhfhocail sin i dtosach);
déan tagairt don chomhcheangal sin le a h-id.
- Is geata crua é an tswitch comhbhrú máistir: nuair a dhíchumasútear comhbhrú ar fud an chórais,
ní féidir an ceann seo cumasú.
Filleann an plean i bhfeidhm sa cheann freagra:
```
X-OmniRoute-Compression: <mode>; source=<source>
```
áit a bhfuil `<source>` ceann de `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, nó `off`.
---
## Leabú
```bash
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "nebius/Qwen/Qwen3-Embedding-8B",
"input": "The food was delicious"
}
```
Soláthraithe ar fáil: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.
Na haitheantóirí catalogh iad `provider/model` (m.sh: `jina-ai/jina-embeddings-v5-omni-small`). Tugann modhanna Jina amháin a chuaigh sa chlár (m.sh `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) freisin. Úsáideann modhanna Jina embed/rerank/classify/segment dheimhniúil stiúrthóireacht `jina-ai` ar dtús; is é `JINA_AI_API_KEY` an rogha eile amháin nuair nach bhfuil eochair stiúrthóireachta ar fáil. Ní chuireann an chárta `jina-reader` ach Reader / `r.jina.ai` amháin (`POST /v1/web/fetch`) agus ní sheirbheálann sé leabú nó athraingearadh riamh.
Glacann samhlacha chlárlainne a chuireann tacaíacht ilmhódach i bhfeidhm le suas le 32 mír struchtúrtha neodrach soláthraí freisin. Is iad na cineálacha míreanna meáin `text`, `image`, `audio`, `video`, agus `document`. Tá an `source` meáin acu nó `{"type":"url","url":"https://..."}` nó
`{"type":"base64","data":"...","media_type":"..."}`.
Glacann Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`,
agus an ailias teaghlaigh `jina-ai/jina-embeddings-v5-omni` → omni-small) freisin doiciméid
Native EmbeddingsV5Request Jina agus **seolann sé iad slán** go `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,..." }]
}
]
}
```
Is féidir na luachanna `{ image | audio | video | pdf }` native a bheith ina n-URL HTTPS poiblí, ina `data:` URI, nó ina raw base64. Ní dhéanann OmniRoute na haitheanna sin a shníomh nó ní tharraingíonn sé URLanna bunúsacha íomhá — déanann Jina an meáin poiblí a aimsiú féin. Seoltar na breisshuimeanna Jina (`task`, `normalized`, `truncate`, `embedding_type`). Ní dhéanann SKUanna Jina téacs amháin ach cáipéisí neamh-théacs a dhearcadh.
Teorainneacha slándála agus iompair:
- Ní mór URLanna meáin cianda a bheith ina n-HTTPS poiblí. Faightear míreanna canonical `{type,source:url}` ar an taobh freastalaí (athfhíorú aistriúcháin, teorainn ama, teorainneacha méide, DNS poiblí, pining ceangail) agus cuirtear isteach iad roimh an gairm soláthraí. Seoltar míreanna native `{image:"https://..."}` Jina díreach mar atá iad tar éis an tseiceáil HTTPS poiblí céanna; déanann Jina an URL a aimsiú.
- Tá meáin base64 inlíne teoranta go 8 MiB díchódaithe in aghaidh an mhír agus 16 MiB díchódaithe ar fud an iarratais.
Aistriúchán soláthraí (nach seoltar míreanna canonical gan athrú riamh):
- Samhlacha ilmhódacha Jina: éiríonn gach mír barrleibhéal ina haitheann eochair-mhódach amháin
(`text` / `image` / `audio` / `video` / `pdf`) ag úsáid URIanna sonraí don meáin inlíne; aon veicteoir in aghaidh
mír barrleibhéal.
- Teaghlach Gemini Embedding 2: éiríonn iarratais barrleibhéal amháin ina n-iarratais native amháin
`models/{model}:embedContent` le `content.parts` (`text` nó `inline_data`).
- Samhlacha anaithnid/dinimiciúla gan meiteashonraí módach soiléir dearcann ionchur struchtúrtha le HTTP 400.
```json
{
"model": "jina-ai/jina-embeddings-v5-omni-small",
"input": [
{ "type": "text", "text": "A red bicycle" },
{
"type": "image",
"source": { "type": "url", "url": "https://example.com/bicycle.png" }
}
],
"dimensions": 512,
"encoding_format": "float"
}
```
Ní dhéanann comhcheangail mhúnla/mód neamhthacaíochta HTTP 400 a thabhairt ar ais in ionad an mhír a choimeád. Leanann réimsí síneadh neamh-ionchur ar iarratais téacs/téacs comharthaí gan athrú.
```bash
# Liostáil gach samhail leabú
GET /v1/embeddings
```
---
## Gineadh Íomhá
```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"
}
```
Soláthraithe ar fáil: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (local), ComfyUI (local).
```bash
# Liostaigh gach samhail íomhá
GET /v1/images/generations
```
---
## OCR Cáipéisí
```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"
}
}
```
Roghnaíonn `model` an soláthraí OCR trí réimír `soláthraí/samhail`; réitítear aitheantas samhail lom (m.sh. `mistral-ocr-latest`) leis an soláthraí cláraithe, agus más fágtha gan `model` úsáidtear Mistral (`mistral-ocr-latest`) de réir réamhshocraithe. Soláthraithe cláraithe (`open-sse/config/ocrRegistry.ts`):
| Aitheantas an tsoláthraí | Aitheantas na samhail | Luach `model` | Nótaí |
| ----------------------------- | --------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (nó `mistral-ocr-latest` lom) | Comhuaineach — filleann an freagra díreach ón aon ghlao upstream amháin. |
| `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Asuaineach upstream (`analyze` + suirbhé) — féach thíos. |
| `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Comhuaineach, trí chrioscomhrá pháirtnéara `openapi/chat/completions` Vertex AI — féach thíos maidir le húdarás/URL. |
Filleann na trí sholáthraí go léir sa choirp Mistral-chruthaithe céanna:
```json
{
"pages": [{ "index": 0, "markdown": "# Extracted text..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
```
### Sreabhadh suirbhé Azure Document Intelligence
Tá API `analyze` Azure Document Intelligence asuaineach: fillteann an t-iarratas tosaigh le ceanntacs `Operation-Location` in ionad choirp, agus ní mór an toradh a shuirbhéil. Déanann an láimhseálaí (`open-sse/handlers/ocr.ts`) suirbhé ar an URL sin gach soicind ar feadh suas le 30 iarracht, teipeann go gasta (ní leanann sé ag suirbhéil) má fhilleann freagra suirbhé neamh-`ok` nó stádas `"failed"`, agus filleann sé `504` má tá an oibríocht fós ag rith tar éis an bhuiséid iarrachta a bheith críochnaithe. Normalaítear an freagra deiridh Azure sa chruth `pages`/`markdown` céanna a úsáideann Mistral roimh é a sheoladh ar ais don ghlaonnaí, ionas nach gá do chód cliant cás speisialta a dhéanamh don soláthraí.
### Údarás agus réiteach críochphointe Vertex AI DeepSeek OCR
Athúsáideann `vertex-deepseek-ocr` an t-údarás Vertex AI céanna a thacaíonn OmniRoute cheana féin le haghaidh tráfaic comhrá/íomhá (`open-sse/executors/vertex.ts`): nó is eochair API an cheangail comhartha seirbhíse JSON (malartaithe le haghaidh comhartha rochtana OAuth gearrthéarma trí shreabhadh JWT-bearer) nó nó comhartha rochtana OAuth atá déanta cheana féin agus úsáidte mar atá é. Is é críochphointe upstream URL críochphointe páirtnéara ginearálta Vertex `openapi/chat/completions`, tógtha ón tionscadal agus an réigiún a bhaineann leis an gceangal — buann sonraí sonracha an tsoláthraí `providerSpecificData.project`/`providerSpecificData.region` i gcónaí; murach sin, díorthaítear an tionscadal ó `project_id` na comhartha seirbhíse JSON agus glacann an réigiún `us-central1` de réir réamhshocraithe. Tarlaítear an dá réiteach i `open-sse/handlers/ocr.ts` (`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), a úsáidtear ag `src/app/api/v1/ocr/route.ts` sula seoltar ar ais go `handleOcr`.
---
## Liostáil Samhlacha
```bash
GET /v1/models
Authorization: Bearer your-api-key
→ Filleann sé gach samhail comhrá, leabú, agus íomhá + teaglaim i bhformáid OpenAI
```
### Réimigh samhla (`?prefix=`)
I ndáiríre, fógraítear formhór na samhlacha faoi **réimh soláthraí**. Cuirtear ar chumas an réimh a fhaightear leis an gclithead `MODELS_CATALOG_PREFIX_MODE`, agus is féidir é a shárú **de réir iarratais** le paraiméadar fiafraí — úsáideach do chliant ar mian leo liostáil ghlan gan athrú ar shocrú an fhreastalaí do gach eile:
```bash
GET /v1/models?prefix=alias # aon aitheantas amháin le gach samhail — an réimh ailias gearr
GET /v1/models?prefix=dual # an dá fhoirm (réamhshocrú an fhreastalaí)
GET /v1/models?prefix=canonical # réimh iomlán an aitheantais soláthraí amháin
```
| Mód | Eisíonn | Nótaí |
| ----------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual` | `cc/claude-sonnet-4-6` **agus** `claude/claude-sonnet-4-6` | **Réamhshocrú.** Téann an dá aitheantas go dtí an tsamhail chéanna; coinnítear iad ionas go n-oibríonn cumraíochtaí cliant a cruthaíodh le ceachtar acu. Méadaítear an catalóg beagnach dhá uair. |
| `alias` | `cc/claude-sonnet-4-6` | Aon iontráil amháin le gach samhail. Ní chailleann soláthraithe gan ailias soaitéireacht a n-iontráil a sheoladh, mar sin ní chailltear aon rud. |
| `canonical` | `claude/claude-sonnet-4-6` | Aon iontráil amháin le gach samhail faoin réimh iomlán aitheantais soláthraí. Ní chailleann soláthraithe gan ailias soaitéireacht (m.sh. `antigravity/…`, `agy/…`) an t-aon aitheantas amháin a sheoladh anseo, mar sin ní cailltear aon rud. |
Is féidir aitheantas a bhaineann le modh `dual` a aithint gan an paraiméadar fiafraí: tugann sé réimse `parent` a thaispeánann an príomh-aitheantas.
Ba cheart do chliant a thaispeánann roghnóir samhlacha iarratas a dhéanamh ar `?prefix=alias` — seo a dhéanann an síneadh [OmniCopilot VS Code](../guides/VSCODE-COPILOT.md).
### Samhlacha gan smaoineamh
Do shamhlacha Claude atá in ann smaoineamh, fógraíonn `/v1/models` freisin leagan **gan smaoineamh** a bhfuil a aitheantas réimhaithe le `claude-3-omniroute-no-thinking/`:
```
claude-3-omniroute-no-thinking/<soláthraí>/<samhail>
```
Trí an t-aitheantas seo a roghnú (m.sh. i gcumraíocht Claude Code a chuireann bloic `thinking` i gcónaí leis) réitíonn sé ar ais go dtí an fíor `<soláthraí>/<samhail>` le réasúnú curtha ar ceal — `thinking:{type:"disabled"}` ar an gcosán `/v1/messages`, nó na réimsí `reasoning`/`reasoning_effort` curtha ar ceal ar an gcosán `/v1/chat/completions`. Ní liostaítear an leagan ach do shamhlacha teaghlach Claude a thacaíonn le smaoineamh **agus** a urramaíonn `disabled` (mar sin, m.sh. samhlacha inoiriúnaithe amháin a dhiúltaíonn `disabled` cuirtear as an áireamh). Is féidir le hoibreoirí an leagan a chur i bhfeidhm nó as as de réir samhail trí `ModelSpec.noThinkingAlias`.
---
## Straitéis Paráidithe Soláthraí
```bash
GET /api/v1/provider-plugin-manifest
```
Filleann sé an manifest paráidithe soláthraí atá sábháilte ó JSON a úsáideann Bifrost, CLIProxyAPI, agus róutóirí sidecar amach anseo. Gineadh an freagra ó chlárúchán soláthraithe TypeScript agus fágann sé amach díreach rúndachtacha cliant OAuth, réiteach timpeallachta rithiúil, feidhmeanna rithithe, ceannteidil iarratais, agus sonraí cuntas.
Bain úsáid as an bhfeidhmchlár seo nuair a rithíonn sidecar lasmuigh den phróiseas agus nach féidir leis `open-sse/config/providerPluginManifestRegistry.ts` a allmhairiú go díreach.
---
## Feidhmeanna Comhoiriúnachta
| Modh | Cosán | Formáid |
| ---- | ----------------------------------------- | ------------------------------------- |
| 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 (edit/inpaint) |
| POST | `/v1/videos/generations` | Gineadh físeán ar stíl OpenAI |
| POST | `/v1/music/generations` | Gineadh ceol ar stíl OpenAI |
| POST | `/v1/audio/transcriptions` | OpenAI Audio (STT) |
| POST | `/v1/audio/speech` | OpenAI TTS (fillfidh corp fuaime) |
| POST | `/v1/rerank` | Athrangement ar stíl Cohere/Voyage |
| POST | `/v1/classify` | Aicmigh Jina (`api.jina.ai`) |
| POST | `/v1/segment` | Deighilteoir Jina (`segment.jina.ai`) |
| POST | `/v1/moderations` | Modhnuithe OpenAI |
| GET | `/v1/models` | OpenAI |
| POST | `/v1/messages/count_tokens` | Anthropic |
| GET | `/v1beta/models` | Gemini |
| POST | `/v1beta/models/{...path}` | Gemini generateContent |
| POST | `/v1/api/chat` | Ollama |
| GET | `/api/v1/vscode/{token}/` | Ailias catalóige OpenAI |
| GET | `/api/v1/vscode/{token}/models` | Ailias múnlaí OpenAI |
| POST | `/api/v1/vscode/{token}/chat/completions` | Ailias tógála OpenAI |
| POST | `/api/v1/vscode/{token}/responses` | Ailias tógála OpenAI Responses |
| POST | `/api/v1/vscode/{token}/api/chat` | Ailias tógála Ollama |
| GET | `/api/v1/vscode/{token}/api/tags` | Ailias tógála clibeanna Ollama |
Leanann gach cosán POST an chéanna: `Bearer your-api-key` + corp JSON atá bailíochta ag Zod (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, srl., féach `src/shared/validation/schemas.ts`). Filleann 4xx ar theip scéime.
Do chliaint nach féidir leo `Authorization: Bearer ...` a cheangal, glactha le eochracha API freisin i URL trí áiseanna comhoiriúnachta sreangfhiarróta (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) nó na feidhmeanna speisialta `/api/v1/vscode/{token}/...` atá dhoiciméadaithe thíos.
```bash
# Athrangement
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Aicmigh Jina (Cúigí Aiceanáise)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Deighilteoir Jina
POST /v1/segment { "content": "...", "return_chunks": true }
# Cuardach Jina (s.jina.ai; ainmneacha soláthraithe: jina-search, jina-ai, jina)
POST /v1/search { "query": "...", "provider": "jina-search" }
# Modhnuithe
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
# TTS — fillfidh corp audio/mpeg (nó formáid iarrata)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# Eagarthóir íomhá (ilpháirt)
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
# Gineadh físeáin/ceoil (ID múnla le réimír soláthraithe)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." }
```
### Cosáin Soláthraithe Speisialta
```bash
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
```
Cuirtear réimír an tsoláthraigh leis go huathoibríoch más gá. Filleann múnlaí mímhaithe `400`.
---
## Comhaid API
Deireadh pointí comhoiriúnach le haghaidh comhaid OpenAI le haghaidh isteach/méideanna buana agus uaslódálacha cuspóir comhaid.
| Modh | Conair | Cur Síos |
| ------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/files` | Uaslódáil comhad (ilchuidiúil: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — 512 MiB uasta |
| GET | `/v1/files` | Liostaigh comhaid le haghaidh eochair API deimhnithe |
| GET | `/v1/files/[id]` | Faigh amach meiteashonraí comhaid |
| DELETE | `/v1/files/[id]` | Scrios comhad |
| GET | `/v1/files/[id]/content` | Sruth-amharc comhad amh i dteachtaireacht ais |
**Fíordheimhniú:** Eochair API Bearer — tá comhaid scóipeáilte in aghaidh na heochr API trí `getApiKeyRequestScope`.
---
## Easbatches API
Próiseáil easbatches comhoiriúnach le haghaidh OpenAI.
| Modh | Conair | Cur Síos |
| ------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/batches` | Cruthaigh easbatch — déantar bailíocht ar an gcomhlacht ag `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
| GET | `/v1/batches` | Liostaigh easbatches |
| GET | `/v1/batches/[id]` | Faigh amach stádas easbatch + `request_counts` |
| DELETE | `/v1/batches/[id]` | Scrios easbatch críochnaithe/teipthe |
| POST | `/v1/batches/[id]/cancel` | Cealaigh easbatch atá ar siúl |
**Fíordheimhniú:** Eochair API Bearer. Tá easbatches scóipeáilte in aghaidh na heochr API.
---
## API Tafas
Absatracht soláthraí faoiseamh/gréasáin (Tavily, Brave, Exa, Serper, srl.).
| Modh | Conair | Cur Síos |
| ---- | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| GET | `/v1/search` | Liostaigh soláthraithe taifeadta agus cumais |
| POST | `/v1/search` | Rith iarratas tafas — déantar bailíocht ar an gcomhlacht ag `v1SearchSchema`, tacaíocht le cuimhneadh/coimeád |
| GET | `/v1/search/analytics` | Staidreamh buamtha/loighne/cuimhne in aghaidh an soláthraí |
**Fíordheimhniú:** Eochair API Bearer (`extractApiKey` + `isValidApiKey`). Cuireann polasaí tafas i bhfeidhm trí `enforceApiKeyPolicy`.
---
## API Craoladh Gréasáin
Bain teachtaireacht as URL trí sholáthraí craoladh gréasáin cumraithe (Firecrawl, Léitheoir Jina, Tavily Extract, TinyFish Fetch, Nimble Extract).
| Modh | Cosán | Cur Síos |
| ---- | --------------- | ------------------------------------------------------ |
| POST | `/v1/web/fetch` | Craol/doirt URL — baill-validate le `v1WebFetchSchema` |
**Údarú:** Eochair API Béar (`extractApiKey` + `isValidApiKey`). Forchur beartais trí `enforceApiKeyPolicy`.
**Aisghabháil fhiosrach um quota (#8297):** nuair nach dtugtar `provider` sainráite, siúlaidh an linne
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) i
dtosaíocht shocraithe (lanú ar dtús) — déantar seachbhó ar sholáthraí atá teoranta i ráta ach atá cumraithe seachas gearrthréigean an iarratais, agus titeann teip in-athshéanta/quota barrshraithe
(HTTP 429 i gcónaí; 402/403 le haghaidh leibhéal saor in aisce stíl quota Firecrawl/Tavily/TinyFish —
ní le haghaidh Léitheoir Jina, agus riamh le haghaidh 400 droch-iarratais simplí) tríd go dtí an chéad
sholáthraí creidiúnaithe eile gan triail ag am an iarratais. Nuair ata gach soláthraí sa
linne tuirseach, freagraíonn an críochfoirt aon `429` (le ceanntásc `Retry-After`)
seachas an `400` ginearálta roimhe seo. Nuarr iarrtar `provider` sainráite,
**níl aon aisghabháil thostach** — tarraingíonn soláthraí sainráite teoranta i ráta nó theip
a earráid féin (`429` má tá sé teoranta i ráta, seachas stádas barrshraithe).
---
## Sruthú WebSocket
```bash
GET /v1/ws?handshake=1
404 Not Found
```
Bailíonn sé idir-lámhach uasghrádaithe WebSocket agus filleann sé na teachtaireachtaí samplacha phrótacail sreafa (`request`, `cancel`). Déileálann na frámaí WS iarbhír leis an bhfreastalaí WS sanbhailithe lasmuigh de thábla ródha Next.js.
**Údarú:** Eochair API Béar le linn idir-lámhach.
### Freagairt API thar WebSocket (codex amháin)
```bash
# An t-aochchlár chéanna leis an API HTTP (réamhshocrú 20128); uasghrádaigh an ceangal:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (nó: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
# NÍ mór an chéad fhráma a bheith response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```
Tásealbhóir Responses-API-over-WebSocket ceangailte **go heisiach le `codex`** (cúlra
ChatGPT). Éistann sé ar an port céanna leis an API/deais ar na cosáin `/v1/responses`,
`/responses`, agus `/api/v1/responses`. Ar an chéad fhráma `response.create` sé
a dhéanann fíordheimhniú + ullmhú trí an droichead inmheánach `codex-resues-ws`, roghnaíonn sé
ceangal codex OAuth, agus pasálann sé go `wss://chatgpt.com/backend-api/codex/responses`
trí iompar `wreq-js`. **Diúltaítear múnlaí neamh-chodex** (`codex_ws_provider_required`).
Le haghaidh ródha cnáib quota úsáid `model: "qtSd/<group>/codex/<model>"`. Cumtha i
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.
**Údarú:** Eochair API Béar le linn idir-lámhach. Ní mór don fhreastalaí HTTP sanbhailithe (`server-ws.mjs`)
a bheith ina phointe iontrála gníomhach (mar atá sé, de réir réamhshocraithe, nuair a bhíonn `app/server-ws.mjs` ann).
#### ID múnla: úsáid an ID bare ChatGPT (gan réimír `codex/`)
Déanann **Codex CLI** OpenAI bailíochtú ar ainm an mhúnla ar thaobh an chliaint nuair a
`tacaíonn_websockets = true` agus **diúltaíonn IDanna le réimír soláthraí** cosúil le
`codex/gpt-5.5` (`Ní thacaítear leis an múnla 'codex/gpt-5.5' agus é ag úsáid Codex le
cuntas ChatGPT`). Seol an ID **bare** (m.sh. `gpt-5.5`). Tá droichead OmniRoute
codex-amháin, mar sin athshuíomhann sé ID bare mar múnla codex
(`resolveCodexWsModelInfo`) sula ndéanann sé pasáil suas go barrshraithe — fiú is go
ródhálfeadh bare `gpt-5.5` go soláthraí eile thar HTTP.
#### Cumrú Codex CLI OpenAI
Cuir an Codex CLI ar OmniRoute trí sholáthraí saincheaptha le tacaíocht WebSocket
a chur le `~/.codex/config.toml` (úsáid `CODEX_HOME ar leith chun cumraíocht atá ann cheana a sheachaint):
```toml
model = "gpt-5.5" # ID bare — NÍ "codex/gpt-5.5"
model_provider = "omniroute"
[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1" # gan(/) deiridh; déantar URL an WS a threorú (úsáid https/wss i dtáirgeadh)
wire_api = "responses" # luach amháin tacaíochta ó Feabhra 2026
supports_websockets = true # cumasaíonn an t-iompar Responses-over-WS
env_key = "OMNIROUTE_API_KEY" # coinníonn eochair API OmniRoute (Béar)
```
```bash
export OMNIROUTE_API_KEY=sk-... # eochair API OmniRoute (aon eochair má tá REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```
Uasghrádaíonn an CLI `base_url + /responses` go WebSocket agus pasálann OmniRoute é
go dtí an ceangal codex OAuth roghnaithe. Bailíodh go hiomlán i gcoinne an
fhreastaláin áitiúil: fillfidh ChatGPT `codex.rate_limits` + `response.created` agus sruthóidh sé an
críochnú.
---
## Quótaí & Tuairiscíocht Saincheisteanna
| Modh | Cosán | Cur Síos |
| ---- | ------------------- | ---------------------------------------------------------------------------------------------------- |
| GET | `/v1/quotas/check` | Réimhghlanmheasúnú quóta do `provider` + `accountId` sula seoltar eochair chláraithe |
| POST | `/v1/issues/report` | Tuairisc teipthe eochair/quóta a sheoladh chuig GitHub (teastaíonn `GITHUB_ISSUES_REPO` + comhartha) |
**Údarú:** Eochair API Bearer (`isAuthenticated`).
---
## Úsáid seirbhíse féinseirbhíse (`/api/usage/om-usage`)
Is féidir le haon eochair API **úsáid agus quótaí a dtuigtear leis féin** a léamh — gan aon údarú bainistíochta. Is é seo an tseirbhís a úsáideann cliant (CLI, painéal an OmniCopilot) chun caiteachas sealba eochair a thaispeáint d'úsáideoir eochrach.
```bash
# Foirm téacs — conradh stairiúil, téacs plain le haghaidh teirminéil
curl -H "Authorization: Bearer <your-api-key>" \
http://localhost:20128/api/usage/om-usage
# Foirm struchtúrtha — cad a itheann comhéadan úsáideora
curl -H "Authorization: Bearer <your-api-key>" \
"http://localhost:20128/api/usage/om-usage?format=json"
```
Ní mór go mbeadh **`allowUsageCommand`** cumasaithe ag an eochair (as réamhshocrú — cuirtear é ar agus as in eagarthóir eochracha an deais in aghaidh na heochrach). Gan é, freagraíonn an seirbhís `403`.
Tugann `?format=json` cruth idirdhealaitheach ar ais ionas nach léann glacadóir réimse sonraí de diúltú. Ar rathú:
```jsonc
{
"allowed": true,
// láithreach ach amháin nuair a roghnaigh an eochair teorainneacha úsáide pearsanta (laethúil/seachtainiúil USD):
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// an léarscáil quóta soláthraí roghnaithe, nó null nuair nach bhfuil aon rud i stór fós:
"provider": {
"connectionId": "…",
"provider": "claude",
"plan": "…",
"quotas": {/* … */},
},
// gach léarscáil ceangail, ionas gur féidir le comhéadan úsáideora roinnt soláthraithe a chur i bhfigiúr taobh le taobh:
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
```
Ar diúltú (`401` eochair mhícheart / `403` nach bhfuil cead agat) fillfidh an bealach céanna `{"allowed": false, "error": {"message": "…"}}` — léarscáil `personal`/`provider` atá ann ach folamh (eochair ceadaithe, níor foghlaimíodh aon rud fós) stáit éagsúil le diúltú, agus ní dhéanann ach an cruth JSON idirdhealú idir dhaoine.
**Údarú:** Eochair API Bearer pearsanta an glacadóra, bailíochtaithe le `isValidApiKey` — níl sé seo _ag an dá dhromchla_ bainistíochta (`/api/keys/…`), a bhfuil sé fós taobh thiar de `requireManagementAuth`.
---
## Taisce Sémantach
```bash
# Faigh staitisticí taisce
GET /api/cache/stats
# Glan gach taisce
DELETE /api/cache/stats
```
Sampla freagra:
```json
{
"semanticCache": {
"memorySize": 42,
"memoryMaxSize": 500,
"dbSize": 128,
"hitRate": 0.65
},
"idempotency": {
"activeKeys": 3,
"windowMs": 5000
}
}
```
### Tionchar aseolaíochta
Seirbheálann turas taisce Sémantach an freagra ón taisce **gan aon ghlao ar bharr**, mar sin tá an t-aiseolas `X-OmniRoute-Response-Latency` tuairiscithe gar don náid (is cuma cén t-am aseolaíochta bunaidh). Ba cheart do chliaint atá íogair maidir le hacléadh (bainistíocht luais, monatóireacht p50/p99) an ceannteideal freagra `X-OmniRoute-Cache-Latency` a sheiceáil:
| Luach | Ciall |
| -------------- | --------------------------------------------------------------- |
| `synthetic` | Freagra seirbheáilte ón taisce; ní ham aseolaíochta fíor-上游 é |
| _(as láthair)_ | Freagra ó ghlao fíor-上游 |
### Sheachaint taisce in aghaidh na heochrach
Is féidir le heochracha API dul as léamha taisce Sémantach trí `cacheDefaultMode`:
| Luach | Iompar |
| -------- | -------------------------------------------------------------------- |
| `legacy` | Iompar taisce gnáth (réamhshocrú) |
| `bypass` | Seachain amharc taisce go hiomlán; buailfidh sé i gcónaí le upstream |
Socraítear é ag cruthú eochrach (`POST /api/keys`) nó nuashonrú (`PATCH /api/keys/[id]`):
```json
{ "cacheDefaultMode": "bypass" }
```
### Sheachaint in aghaidh an iarratais
Is féidir le haon iarratas an taisce a sheachaint is cuma faoi shocruithe na heochrach:
```
X-OmniRoute-No-Cache: true
```
---
## Taibléad & Bainistíocht
Ní cheadaítear bealach isteach bainistíochta (`/api/*` seachas ceadanas poiblí logáil isteach) le heochracha inferences gnáthmhodh. Éighníomhartha creidmheasa, scóip, agus samplaí curl:
[Bainistíocht Ceadána](../guides/MANAGEMENT-AUTH.md).
### Fíordheimhniú
| Críochphointe | Modh | Cur síos |
| ----------------------------- | ------- | -------------------------------- |
| `/api/auth/login` | POST | Logáil isteach |
| `/api/auth/logout` | POST | Logáil amach |
| `/api/settings/require-login` | GET/PUT | Tionól logála isteach éigeantach |
### Bainistíocht Soláthraithe
| Críochphointe | Modhanna | Cur síos |
| ---------------------------- | --------------------- | -------------------------------------------------------------------------------------------------- |
| `/api/providers` | GET/POST | Liostú / cruthú soláthraithe |
| `/api/providers/[id]` | GET/PUT/DELETE | Bainistíocht soláthraí |
| `/api/providers/[id]/test` | POST | Tástáil ceangal soláthraí |
| `/api/providers/[id]/models` | GET | Liostáil samhlacha soláthraí |
| `/api/providers/validate` | POST | Bailíochtaigh cumraíocht soláthraí |
| `/api/providers/bulk` | POST | Cuir eochracha API le haghaidh AMHÁIN soláthraí le chéile |
| `/api/providers/import` | POST | Iompórtáil liosta soláthraithe éagsúla ó CSV/JSON parsáilte (#6836); torthaí páirteanna éiríomhach |
| `/api/provider-notes*` | Éagsúla | Bainistíocht nóid soláthraí |
| `/api/provider-models` | GET/POST/PATCH/DELETE | Samhlacha saincheaptha (cuir le, nuashonraigh, cuir i bhfolach/taispeáin, scrios) |
### Sreimeanna OAuth
| Críochphointe | Modhanna | Cur síos |
| -------------------------------- | -------- | ------------------------ |
| `/api/oauth/[provider]/[action]` | Éagsúla | OAuth ar leith soláthraí |
### Ródáil & Cumraíocht
| Críochphointe | Modhanna | Cur síos |
| --------------------- | -------- | ---------------------------------------- |
| `/api/models/alias` | GET/POST | Ailiasanna samhlacha |
| `/api/models/catalog` | GET | Gach samhail de réir soláthraí + cineáil |
| `/api/combos*` | Éagsúla | Bainistíocht comhcheangail |
| `/api/keys*` | Éagsúla | Bainistíocht eochracha API |
| `/api/pricing` | GET | Praghsáil samhlacha |
### Úsáid & Anailísíocht
| Críochphointe | Modhanna | Cur síos |
| -------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history` | GET | Stair úsáide |
| `/api/usage/logs` | GET | Logaí úsáide |
| `/api/usage/request-logs` | GET | Logaí ar leibhéal iarratais |
| `/api/usage/[connectionId]` | GET | Úsáid in aghaidh an cheangail |
| `/api/usage/token-limits` | GET/POST/DELETE | Teorainneacha ceadúnais comharthaí in aghaidh an eochrach API |
| `/api/usage/model-latency-stats` | GET | Buaintíochta moille soláthraí/samhail rollta (meán/p50/p99, ráta rathúlachta); scagairí: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) |
| `/api/usage/cache-health` | GET | Achoimre sláinte cuimhne-tásca ar `call_logs` — ráta scríbh/read, dáileadh méid scríbh p50/p90/p99, díriú scríbh trom, roinnt in aghaidh na samhail, agus breithmheas `healthy`/`degraded`/`thrash`/`no-data`; paraiméadar iarratais `range` (`1h`\|`24h`\|`7d`\|`30d`, réamhshocradh `24h`) agus `model` roghnach (#8827) |
### Socruithe
| Críochphointe | Modhanna | Cur síos |
| ------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings` | GET/PUT/PATCH | Socruithe ginearálta |
| `/api/settings/proxy` | GET/PUT | Cumraíocht seachfhreagraí líonra |
| `/api/settings/proxy/test` | POST | Tástáil ceangal seachfhreagraí |
| `/api/settings/ip-filter` | GET/PUT | Liosta ceadaithe/blocála IP |
| `/api/settings/thinking-budget` | GET/PUT | Mód athscríofa **iarratais** smaointeoireachta (traschéadadh / uathbhriseadh / saincheaptha / oiriúnach). Neamhspleách ar comhbhrú. Féach [Buiséad Smaointeoireachta](../guides/THINKING_BUDGET.md). |
| `/api/settings/system-prompt` | GET/PUT | Leid córais domhanda |
| `/api/settings/compression` | GET/PUT | Cumraíocht comhbhrú domhanda |
| `/api/settings/purge-request-history` | POST | Glan rithanna loga iarratais agus earraí áitiúla loga gairm |
### Comhthéacs & Comhbhrú
| Críochphointe | Modhanna | Cur síos |
| -------------------------------------- | -------------- | --------------------------------------------------------------------------------------- |
| `/api/compression/preview` | POST | Réamhamharc comhbhrú as/lite/rialach/foréigneach/ultra/RTK/stacked |
| `/api/compression/language-packs` | GET | Liostáil pacáistí teanga Caveman ar fáil |
| `/api/compression/rules` | GET | Liostáil meiteashonraí rialacha Caveman |
| `/api/context/caveman/config` | GET/PUT | Ailias socruithe sainiúla Caveman |
| `/api/context/rtk/config` | GET/PUT | Socruithe sainiúla RTK, lena n-áirítear scagairí saincheaptha agus coinneáil aschur amh |
| `/api/context/rtk/filters` | GET | Catalóg scagairí RTK agus diagnóisic scagairí saincheaptha |
| `/api/context/rtk/test` | POST | Rith réamhamhairc/tástála RTK ar ualach téacs |
| `/api/context/rtk/raw-output/[id]` | GET | Léigh aschur amh athbhactha de réir aitheantóra指针 |
| `/api/context/combos` | GET/POST | Liostú/chruthú comhcheangail comhbhrú |
| `/api/context/combos/[id]` | GET/PUT/DELETE | Mionsonraí/nuashonrú/scriosadh comhcheangail comhbhrú |
| `/api/context/combos/[id]/assignments` | GET/PUT | Sanigh comhcheangail comhbhrú le comhcheangail ródáil |
| `/api/context/analytics` | GET | Ailias anailísíochta comhbhrú |
### Monatóireacht
| Críochphointe | Modhanna | Cur síos |
| ------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions` | GET | Rianú seisiún gníomhach |
| `/api/rate-limits` | GET | Teorainneacha ráta in aghaidh an chuntais |
| `/api/monitoring/health` | GET | Seiceáil sláinte + achoimre soláthraí (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) |
| `/api/cache/stats` | GET/DELETE | Staidreamh cuimhne / glan |
| `/api/modality-bridge/stats` | GET | `attempts` i gcuimhne, rathúilta/`bridged`, teipeanna, buanna cuimhne, `totalLatencyMs`, `latencySamples`, meán-am sampláilte `averageLatencyMs`, agus am úsáide deiridh (athshocradh ar atosú; bainistíocht údaraithe) |
| `/api/modality-bridge/video/runtime` | GET | Seiceáil ciorcláin iontaofa dílis roimh údarú/bainistíocht; leagarthán FFmpeg/ffprobe agus leaganacha glanta (no-store) |
| `/api/modality-bridge/video/extract` | POST | Bróicéir octets ciorcláin iontaofa dílis inmheánach údaraithe; 50 MiB ionchur, líne cheangail teoranta/32 MiB aschur, `503` acmhainn, `499` dícheangal, `504` sprioc-am; ní API uaslódála poiblí é |
### Cúltaca & Easpórtáil/Iompórtáil
| Críochphointe | Modhanna | Cur síos |
| --------------------------- | -------- | ------------------------------------------------------------ |
| `/api/db-backups` | GET | Liostáil cúltacanna ar fáil |
| `/api/db-backups` | PUT | Cruthaigh cúltaca lámhleabhar |
| `/api/db-backups` | POST | Athchóirigh ó chúltaca áirithe |
| `/api/db-backups/export` | GET | Íoslódáil bunachar sonraí mar .sqlite |
| `/api/db-backups/import` | POST | Uaslódáil comhad .sqlite chun bunachar sonraí a athsholáthar |
| `/api/db-backups/exportAll` | GET | Íoslódáil cúltaca iomlán mar archív .tar.gz |
### Sioncrónú Scáileáin
| Críochphointe | Modhanna | Cur síos |
| ---------------------- | -------- | ----------------------------------- |
| `/api/sync/cloud` | Éagsúla | Oibríochtaí sioncrónaithe scáileáin |
| `/api/sync/initialize` | POST | Tús sioncrónaithe |
| `/api/cloud/*` | Éagsúla | Bainistíocht scáileáin |
### Túinéil
| Críochphointe | Modhanna | Cur síos |
| -------------------------- | -------- | --------------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET | Léigh status suiteála/ollsachála Túinéil Tapa Cloudflare don taibléad |
| `/api/tunnels/cloudflared` | POST | Cumasaigh nó díchumasaigh Túinéil Tapa Cloudflare (`action=enable/disable`) |
| `/api/tunnels/ngrok` | GET | Léigh stát ollsachála Túinéil ngrok don taibléad |
| `/api/tunnels/ngrok` | POST | Cumasaigh nó díchumasaigh Túinéil ngrok (`action=enable/disable`) |
### Uirlisí CLI
| Críochphointe | Modhanna | Cur síos |
| ---------------------------------- | -------- | ---------------------- |
| `/api/cli-tools/claude-settings` | GET | Stádas CLI Claude |
| `/api/cli-tools/codex-settings` | GET | Stádas CLI Codex |
| `/api/cli-tools/droid-settings` | GET | Stádas CLI Droid |
| `/api/cli-tools/openclaw-settings` | GET | Stádas CLI OpenClaw |
| `/api/cli-tools/runtime/[toolId]` | GET | Rith am CLI ginearálta |
Áiríonn freagraí CLI: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
### Uachtaráin ACP
| Críochphointe | Modhanna | Cur síos |
| ----------------- | -------- | ---------------------------------------------------------------------------- |
| `/api/acp/agents` | GET | Liostáil na huachtaráin go léir a braith (ionsuite + saincheaptha) le stádas |
| `/api/acp/agents` | POST | Cuir uachtarán saincheaptha leis nó athnuaigh taisce braite |
| `/api/acp/agents` | DELETE | Bain uachtarán saincheaptha le `id` paraiméadar iarratais |
Áiríonn freagra GET `agents[]` (id, ainm, dhénártha, leagan, suiteáilte, prótacal, isCustom) agus `summary` (iomlán, suiteáilte, gan aimsiú, ionsuite, saincheaptha).
### Lánún & Teorainneacha Ráta
| Críochphointe | Modhanna | Cur síos |
| --------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------- |
| `/api/resilience` | GET/PATCH | Faigh/nuashonraigh líne iarratais, fuaraithe ceangail, briseoir soláthraí, agus socruithe fanachta |
| `/api/resilience/reset` | POST | Athshocrigh briseoirí sléibhe soláthraithe |
| `/api/resilience/model-cooldowns` | GET | Liostáil na glasáil in-ghníomhacha in aghaidh an (soláthraí, ceangal, samhail), sórtáilte de réir am atá fágtha |
| `/api/resilience/model-cooldowns` | DELETE | Glan glasáil samhail — bod `{provider, model}` nó `{all: true}` chun gach rud a scriosadh |
| `/api/rate-limits` | GET | Stádas teorainneacha ráta in aghaidh an chuntais |
| `/api/rate-limit` | GET | Cumraíocht teorainneacha ráta domhanda |
> Éilíonn na ceithre bhealach isteach `/api/resilience/*` go léir **údarú bainistíochta** (`requireManagementAuth`). Féach [Lánúin (extended)](#resilience-extended) le haghaidh mionphlé iomlán ar briseoir soláthraí vs fuarú ceangail vs glasáil samhail.
### Luachmhairí
| Críochphointe | Modhanna | Cur síos |
| ------------- | -------- | ---------------------------------------------- |
| `/api/evals` | GET/POST | Liostáil sraith luachmhairí / rith luachmhairí |
### Polasaithe
| Críochphointe | Modhanna | Cur síos |
| --------------- | --------------- | ---------------------------- |
| `/api/policies` | GET/POST/DELETE | Bainistigh polasaithe ródála |
### Comhlíonadh
| Críochphointe | Modhanna | Cur síos |
| --------------------------- | -------- | ------------------------------------- |
| `/api/compliance/audit-log` | GET | Loga iniúchta comhlíonadh (N deiridh) |
### v1beta (Comhoiriúnach le Gemini)
| Críochphointe | Modhanna | Cur síos |
| -------------------------- | -------- | -------------------------------------- |
| `/v1beta/models` | GET | Liostáil samhlacha i bhformáid Gemini |
| `/v1beta/models/{...path}` | POST | Críochphointe `generateContent` Gemini |
Scáileáil na críochphointí seo formáid API Gemini do chliaint a bhfuil súil acu le comhoiriúnacht SDK Gemini dhúchasach.
### APIanna Inmheánacha / Córais
| Críochphointe | Modhanna | Cur síos |
| ------------------------ | -------- | ------------------------------------------------------------ |
| `/api/init` | GET | Seiceáil tús iarratais应用程序 (úsáidte an chéad uair) |
| `/api/tags` | GET | Clibanna samhail comhoiriúnach le Ollama (do chliant Ollama) |
| `/api/restart` | POST | Tús athshosa réidh freastalaí |
| `/api/shutdown` | POST | Tús múchadh réidh freastalaí |
| `/api/system/env/repair` | POST | Deisigh athrógacha timpeallachta OAuth soláthraí |
> **Nóta:** Úsáidtear na críochphointí seo go hinmheánach ag an gcóras nó le haghaidh comhoiriúnachta cliant Ollama. Ní ghlaoitear orthu de ghnáth ag úsáideoirí deiridh.
### Athchóiriú Timpeallachta OAuth _(v3.6.1+)_
```bash
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
```
Deisíonn sé athrógacha timpeallachta OAuth atá in easnamh nó truaillithe do sholáthraí áirithe. Tuairisceáin:
```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"
}
```
---
## Athscríbhinn Fuaime
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```
Cuir comhaid fuaime in iúl ag baint úsáide as aon soláthraí STT cumraithe. Roghnaíonn an chéad alt cosáin an soláthraí dúchais (`openai/…`, `deepgram/…`). Úsáideann geataí a onnmhaireann samhail dhílse soláthraí eile aitheantas incháilithe (`openrouter/deepgram/nova-3`).
**Iarratas:**
```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"
```
**Freagra:**
```json
{
"text": "Dia duit, seo é ábhar na fuaime a tiontaíodh.",
"task": "transcribe",
"language": "en",
"duration": 12.5
}
```
**Samplaí aitheantas samhail:** `openai/whisper-1` (éilíonn sé eochair OpenAI),
`openrouter/deepgram/nova-3` (éilíonn sé eochair OpenRouter),
`deepgram/nova-3` (éilíonn sé eochair dhúchasach Deepgram). Ní úsáideann iarratas `deepgram/nova-3` lom **osnádúrtha** OpenRouter.
**Formáidí tacaíochta:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
---
## Comhoiriúnacht Ollama
Do chliaint a úsáideann formáid API Ollama:
```bash
# Críochphointe comhrá (formáid Ollama)
POST /v1/api/chat
# Liostú samhlacha (formáid Ollama)
GET /api/tags
```
Aistrítear iarratais go huathoibríoch idir formáidí Ollama agus inmheánacha.
## Ailiasanna VS Code / Gan Ceanntásc le Comharthaí Mona
Úsáid na hainmneacha seo nuair nach féidir le comhtháthú ceanntásc `Authorization` a instealladh agus teastaíonn an eochair API leabaithe sa bhun-chomhartha URL.
```bash
# Ailias eolaire ar stíl OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# Ailiasanna comhrá ar stíl OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Ailiasanna ar stíl Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```
Sampla:
```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"}]}'
```
Nótaí:
- Athúsáidtear na hainmneacha le comharthaí mona na láimhseálaithe céanna le haghaidh `/v1/*` agus `/api/tags`; fanann cruthanna na bhfreagraí mar an gcéanna.
- Is fearr `Authorization: Bearer ...` a úsáid i gcónaí nuair a thacaíonn an cliant le ceanntáscanna saincheaptha.
- D'fhéadfadh comharthaí atá bunaithe ar URL teacht i dtaifeadtaí freasúra droim ar ais, stair brabhsálaí, agus teileamheadrachta taobh amuigh de OmniRoute. Déileáil leo mar rogha comhoiriúnachta, ní mar mhodh réamhshocraithe fíordheimhnithe.
---
## Teileamheadrachta
```bash
# Faigh achoimre ar theileamheadrachta moill (p50/p95/p99 in aghaidh an tsoláthraí)
GET /api/telemetry/summary
```
**Freagra:**
```json
{
"providers": {
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
}
}
```
---
## Buget
```bash
# Faigh stádas buget do gach eochair API
GET /api/usage/budget
# Socraigh nó nuashonraigh buget
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"
}
```
> **Nótaí scéime** (`setBudgetSchema`): éilítear `apiKeyId`; ní mór go mbeadh ar a laghad amháin de `dailyLimitUsd`, `weeklyLimitUsd`, nó `monthlyLimitUsd` níos mó ná náid. Réimsí roghnach: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Filleann an sean-chruth `{keyId, limit, period}` `400 Bad Request`.
## Teorainneacha comharthaí
Buiséid **comharthaí** in aghaidh an eochair API (éagsúil leis an mbuiséim bunaithe ar USD thuas). Fóraítear iad ar an mbealach iarratais: nuair a shroicheann úsáid reatha fuinneoige eochair a theorainn, diúltaítear iarratais le `429 Too Many Requests`. Is féidir teorainneacha a scóipeáil go sonrach ar `model`, ar `provider`, nó a chur i bhfeidhm `global`ly trasna na heochrach; nuair a mheaitseann roinnt teorainneacha le hiarratas, buann an ceann is sriantaí.
```bash
# Liostaigh teorainneacha comharthaí eochrach (agus úsáid fhuinneoige beo ann)
GET /api/usage/token-limits?apiKeyId=key-123
# Cruthaigh nó nuashonraigh teorainn comharthaí
POST /api/usage/token-limits
Content-Type: application/json
{
"apiKeyId": "key-123",
"scopeType": "model",
"scopeValue": "openai/gpt-4o",
"tokenLimit": 1000000,
"resetInterval": "monthly",
"enabled": true
}
# Scrios teorainn comharthaí de réir id
DELETE /api/usage/token-limits?id=tl-abc
```
> **Nótaí scéime** (`setTokenLimitSchema`): tá `apiKeyId` agus `scopeType` (`model` | `provider` | `global`) riachtanach. Tá `scopeValue` riachtanach mura bhfuil `scopeType` ina `global` (m.sh. aitheantas samhail le haghaidh scóipe `model`, aitheantas soláthraí le haghaidh scóipe `provider`). Ní mór go mbeadh `tokenLimit` ina shlánuimhir dhearfach (comhshóite ó shreang). Roghnach: `id` (fág thar lear le cruthú, soláthar le nuashonrú), `resetInterval` (`daily` | `weekly` | `monthly`, réamhshocrú `monthly`), `resetTime` (`HH:MM`), `enabled` (réamhshocrú `true`). Saibhríonn freagraí `GET` gach teorainn le `tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, agus `nextResetAt`. Is é seo críochfoirt bainistíochta (fóirceannadh dearbhaithe go hintleachtúil ag an phíobáin údaraithe).
## Próiseáil Iarratais
1. Seolann an cliant iarratas go `/v1/*`
2. Glaoann an láimhseálaí ródaithe ar `handleChat`, `handleEmbedding`, `handleAudioTranscription`, nó `handleImageGeneration`
3. Réitítear an tsamhail (soláthraí/samhail díreach nó alás/comhoibriú)
4. Roghnaítear creidiúnaithe ó bhunachar sonraí logánta le scagadh infhaighteachta cuntais
5. I gcás comhrá: seiceálann `handleChatCore` taisce shéimeantach/sínithe agus réitíonn socruithe comhbhrú comhoibriú
6. Rithann comhbhrú proachtach roimh aistriú soláthraí nuair a bheidh sé cumasaithe (`lite`, Caveman, RTK, nó carntha)
7. Seolann an feidhmiúchán soláthraí iarratas in aghaidh an tsréidh
8. Aistrítear an freagra ar ais go formáid an chliant (comhrá) nó fíorann tuairiscítear mar atá (leabharshuanna/íomhánna/fuaime)
9. Taifeadtar úsáid, anailísíocht comhbhrú, agus logaí iarratais
10. Cuirtear i bhfeidhm teacht ar ais ar earráidí de réir rialacha comhoibriú
Tagairt chun iomlán na hailtireachta: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)
---
## Bainistíocht Comhoibriú
Is féidir comhoibrithe ródaithe ardleibhéil (cur síos cheana féin faoi `/api/combos*`) a chur mapáil 1:1 freisin ó bpatrún aitheanta samhail, rud a ligeann athsheoladh trédhearcach aitheanta samhail ar stíl OpenAI go comhoibriú.
| Modh | Conair | Cur síos |
| ------ | -------------------------------- | -------------------------------------------------------------------------------- |
| GET | `/api/model-combo-mappings` | Liostaigh gach mapáil samhail→comhoibriú |
| POST | `/api/model-combo-mappings` | Cruthaigh mapáil — corp: `{pattern, comboId, priority?, enabled?, description?}` |
| GET | `/api/model-combo-mappings/[id]` | Faigh amach mapáil shingil |
| PUT | `/api/model-combo-mappings/[id]` | Nuashonraigh réimsí de mapáil atá ann cheana |
| DELETE | `/api/model-combo-mappings/[id]` | Bain mapáil |
**Údarú:** seisiún bainistíochta/eochair API (`requireManagementAuth`).
## Webhooks
Sreathsheoltaí amach webhook d’imeachtaí OmniRoute (críochchur iarratais, tuirse ceadanna, casadh eochrach, srl.).
| Modh | Conair | Cur síos |
| ------ | ------------------------- | ----------------------------------------------------------------------------- |
| GET | `/api/webhooks` | Liostaigh webhooks (folaítear na rúin i `<prefix>...`) |
| POST | `/api/webhooks` | Cruthaigh webhook — ball: `{url, events?: ["*"], secret?, description?}` |
| GET | `/api/webhooks/[id]` | Faigh webhook |
| PUT | `/api/webhooks/[id]` | Nuashonraigh url/events/secret/description |
| DELETE | `/api/webhooks/[id]` | Bain webhook |
| POST | `/api/webhooks/[id]/test` | Seol pacáiste tástála go dtí an URL webhook agus seol stádas seachadta ar ais |
**Údarú:** Seisiún bainistíochta/eochair API (`requireManagementAuth`).
---
## Eochracha Cláraithe (Uath-Bhainistíocht)
Úsáidte ag an forbhreathnóir eochracha uathoibriú chun eochracha API a eisiúint agus a chasadh i gcoinne soláthraí/cuntais chúltaca, le ceadanna laethúla/hourly.
| Modh | Conair | Cur síos |
| ------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/registered-keys` | Liostaigh eochracha cláraithe (roinn marcáilte amháin) |
| POST | `/api/v1/registered-keys` | Eisigh eochair chláraithe nua — ball: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Seol an eochair amh **uair amháin**. Seol `429` ar diúltú ceadanna. |
| GET | `/api/v1/registered-keys/[id]` | Faigh meiteashonraí eochrach cláraithe (gan amhábhar amh) |
| DELETE | `/api/v1/registered-keys/[id]` | Cuir eochair chláraithe ar ceal |
| POST | `/api/v1/registered-keys/[id]/revoke` | Críochphointe cealta sainráite (éifeacht chéanna le DELETE) |
**Údarú:** Eochair API Bearer (`isAuthenticated`). Féach freisin `/v1/quotas/check` agus `/v1/issues/report`.
## Prótacal na nGníomhairí
Tascanna ghníomhairí scálaíomhá (Claude Code, Codex Cloud, OpenHands, srl.) a chomhlíonann i bhfíor-am thar ceann úsáideoirí OmniRoute.
| Modh | Conair | Cur síos |
| ------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/agents/tasks` | Liosta tascanna — roghnach `?provider=`, `?status=`, `?limit=` (1–500, réamhshocruth 50) |
| POST | `/api/v1/agents/tasks` | Cruthaigh tasc — dearbhú corp le `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Filleann `201` le表皮lascana tasc |
| DELETE | `/api/v1/agents/tasks?id=...` | Scrios tasc |
| GET | `/api/v1/agents/tasks/[id]` | Léigh tasc — athnuaigh stádas go comhuaineach ón ghníomhaí scálaíomhá uachtaraigh nuair a shocrútear `external_id` |
| POST | `/api/v1/agents/tasks/[id]` | Gníomh a dhiscríobh: `{action: "approve"}`, `{action: "message", message}`, nó `{action: "cancel"}` |
| DELETE | `/api/v1/agents/tasks/[id]` | Scrios tasc ar leith de réir an aitheantas |
> **Údarú:** éilítear údarú bainistíochta ar gach modh (`requireCloudAgentManagementAuth`). Roimh v3.8.0 bhí siad gan údarú — féach coilíneacht `588a0333` le haghaidh an athraithe tábhachtach.
```bash
# Cruthaigh tasc scálaíomhá Claude Code
curl -X POST http://localhost:20128/api/v1/agents/tasks \
-H "Authorization: Bearer your-management-key" \
-H "Content-Type: application/json" \
-d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'
```
---
## Seachmhóirí Bainistíochta
Seachmhóirí HTTP(S)/SOCKS amach is féidir a shannadh do sholáthraithe, cuntais, nó go huilíoch.
| Modh | Conair | Cur síos |
| ------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/management/proxies` | Liosta seachmhóirí (le `?id=` filleann ceann amháin; le `?id=&where_used=1` filleann an graf sannadh) |
| POST | `/api/v1/management/proxies` | Cruthaigh seachmhóir — dearbhú corp le `createProxyRegistrySchema` |
| PATCH | `/api/v1/management/proxies` | Nuashonraigh seachmhóir — dearbhú corp le `updateProxyRegistrySchema` (éilítear `id`) |
| DELETE | `/api/v1/management/proxies?id=...&force=1` | Scrios seachmhóir (úsáid `force=1` le sannadh a dhícheangal) |
| GET | `/api/v1/management/proxies/assignments` | Liosta sannadh — inscortha le `proxy_id`, `scope`, `scope_id`; seol `resolve_connection_id=<id>` le seachmhóir gníomhach a réiteach do cheangal |
| PUT | `/api/v1/management/proxies/assignments` | Sann — dearbhú corp le `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Glanann taisce an dáileoir |
| PUT | `/api/v1/management/proxies/bulk-assign` | Sannadh t괄m — dearbhú corp le `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) |
| GET | `/api/v1/management/proxies/health?hours=24` | Sláinte seachmhóir comhiomlán (líonanna rathúil/téip, fuirm) thar fhuinneog |
**Údarú:** seisiún/eochair API bainistíochta ar gach conair (`requireManagementAuth`).
> Seirbhísí le `POST /api/v1/management/proxies/[id]/assignments` agus `POST /api/v1/management/proxies/[id]/health` sa chur síos tasc ag na conairí réidh `/assignments` agus `/health` a thaispeántar thuas — níl aon fhochonairí de réir id san bhunachar-cód.
## Seasmhacht (leathnaithe)
Nochtann OmniRoute trí shéimhchóras neamhspleácha ar theip shealadach; ligeann na críochphoist bainistíochta thíos d'oibritheoirí iad a léamh agus a shárú:
| Scóp | Stóráil stáit | Léamh | Athshocrú / glan |
| -------------------- | ----------------------------------------- | ----------------------------------------- | ------------------------------------------------ |
| Briseadh soláthraí | `domain_circuit_breakers` + i-gcuimhne | `/api/monitoring/health` | `POST /api/resilience/reset` |
| Fuar-chrios ceangail | `rateLimitedUntil` ar naisc soláthraí | `/api/rate-limits`, `/api/providers/[id]` | (athlasann go dtíomlach; glan via PUT soláthraí) |
| Glasáil samhail | Clárlann ar fáilteacht samhail i-gcuimhne | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` |
Glacann `PATCH /api/resilience` sárúcháin briseadh soláthraí faoi `providerBreaker.oauth` agus `providerBreaker.apikey`. Gach próifíl tacaíochta `degradationThreshold`, `failureThreshold`, agus `resetTimeoutMs`; nochtar na réimsí céanna i Dashboard → Settings → Resilience.
```bash
# Glan glasáil amháin samhail
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"}'
# Scrios gach glasáil
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
```
Tagairt choincheapúil iomlán agus réamhshocruithe briseadh: féach [`CLAUDE.md`](../../CLAUDE.md) → "Stáit Rith Seasmhachta".
---
## Scileanna
Frámaíocht scileanna le haghaidh síneadh OmniRoute le láimhseálaithe inrite saincheaptha, móide idirthábháil margaidh.
| Modh | Cosán | Cur Síos |
| ------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/skills` | Liostaigh scileanna suiteáilte — ináscartach le `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, leathanach |
| GET | `/api/skills/[id]` | Faigh scile amháin |
| PUT | `/api/skills/[id]` | Nuashonraigh scile (ainm, cur síos, mód, scéime, láimhseálaí, clibeanna) |
| DELETE | `/api/skills/[id]` | Díshuiteáil scile |
| POST | `/api/skills/install` | Suiteáil scile ó dearbhúchán amh: corp: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
| GET | `/api/skills/executions` | Liostaigh rithanna scile le déanáil (cosán iniúchta le hionchuir/aschuir/ath) |
| GET | `/api/skills/marketplace?q=...` | Cuardaigh/popúlach liosta ómhargadh SkillsMP (éilíonn suíomh `skillsmpApiKey`) |
| POST | `/api/skills/marketplace/install` | Suiteáil scile le haghaidh id ó SkillsMP |
| GET | `/api/skills/skillssh?q=&limit=` | Cuardaigh clárlann skills.sh |
| POST | `/api/skills/skillssh/install` | Suiteáil scile le haghaidh id ó skills.sh |
**Údarú:** seisiún bainistíochta/eochair API. Glacann cosáin cuardaigh margaidh údarú bainistíochta nó eochair API Bearer (`isAuthenticated`).
## Cuimhne
Stóráil cuimhne chomhrá/sléite seasta, scóipithe in aghaidh an eochair-API / seisiún.
| Modh | Cosán | Cur Síos |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/memory` | Liostáil cuimhní — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, le paiteantóireacht `offset/limit` nó `page/limit` |
| POST | `/api/memory` | Cruthaigh cuimhne — bailíonn an corp le Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET | `/api/memory/[id]` | Taispeáin cuimhne amháin |
| DELETE | `/api/memory/[id]` | Scrios cuimhne |
| GET | `/api/memory/health` | Sláinte forbhreathnú cuimhne (nascadh DB, innéacs veicteora, stádas an chúlra leabú) |
**Údarú:** Seisiún bainistíochta/eochair-API (`requireManagementAuth`). Ainmchlár `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (féach `MemoryType` in `src/lib/memory/types.ts`).
---
## Freastalaí MCP
Seolann OmniRoute freastalaí Prótacail Comhthéacs Mhúnla leabaithe le 3 iompar (stdio, SSE, streamable-http) agus uirlisí scóipithe. Léann na deiridhanna an stiúrthóra stádas/ sonraacha iniúchta agus ionadaíonn na heasnáin HTTP.
| Modh | Cosán | Cur Síos |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Cárta croí, iompar, stádas ar líne, glao deireanach, uirlisí barr, ráta rathúcháin 24h |
| GET | `/api/mcp/tools` | Liosta uirlisí MCP le `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
| GET | `/api/mcp/sse` | Oscail sruth SSE le haghaidh an iompair SSE (tuairiscíonn `503` mura bhfuil MCP cumasaithe nó míshreangú iompair) |
| POST | `/api/mcp/sse` | Seol fráma JSON-RPC ar an iompar SSE |
| GET | `/api/mcp/stream` | Oscail taobh SSE an Iompair HTTP In-sruthaithe (teachtaíonn an freastalaí) |
| POST | `/api/mcp/stream` | Seol fráma JSON-RPC ar an iompar HTTP In-sruthaithe |
| DELETE | `/api/mcp/stream` | Cruthaigh seisiún HTTP In-sruthaithe |
| GET | `/api/mcp/audit` | Iarratas loga iniúchta — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | Staitisticí iniúchta comhiomlán (ian, ráta rathúcháin, meán fad, uirlisí barr) |
**Údarú:** measann an t-iompar `sse`/`stream` an dromchla údaraithe speisialta MCP (eochair-API Bearer le scóip `mcp`); is féidir na bealaí `status`/`tools`/`audit*` a léamh ón stiúrthóir (ní theastaíonn údarú breise seachas an óstach stiúrthóra a shroichint).
> Tá an dá iompar HTTP faoi ghlas ag `settings.mcpEnabled` agus `settings.mcpTransport` — freagraíonn míshreangú iompar le `400`, freagraíonn stádas MCP díchumasaithe le `503`.
## Freastalaí A2A
Nochtann OmniRoute críochphointe JSON-RPC 2.0 A2A (Ailceimeadóir-go-Ailceimeadóir) chomh maith le casúr REST le haghaidh iniúchta/anoiaill.
### JSON-RPC
```bash
POST /a2a
Authorization: Bearer your-api-key # roghnach mura bhfuil OMNIROUTE_API_KEY socraithe
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "message/send",
"params": {
"skill": "smart-routing",
"messages": [{"role": "user", "content": "Route this coding task"}]
}
}
```
Modhanna tacaíochta (go léir faoin ngníomhachtú `settings.a2aEnabled`):
| Modh | Cur síos |
| ---------------- | ------------------------------------------------------------------ |
| `message/send` | Rith scile comhshochronach; filltean `{task, artifacts, metadata}` |
| `message/stream` | Rith SSE sruthú an tacar scileanna céanna |
| `tasks/get` | Faighte tasc le `taskId` |
| `tasks/cancel` | Cealaigh tasc le `taskId` |
Scileanna ionsuite: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.
### Cárta Ailceimeadóra
```bash
GET /.well-known/agent.json
```
Filltean cárta poiblí A2A an ailceimeadóra (ainm, cur síos, cumais, catalóg scileanna, scéim údaráitheadh) — cuirte i stóras poiblí ar feadh 1 uair. Ní gá údarás.
### Cúntóirí REST
| Modh | Conair | Cur síos |
| ---- | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/a2a/status` | A2A cumasaithe + staitisticí tasc + achoimre cárta ailceimeadóra stóráilte |
| GET | `/api/a2a/tasks` | Liosta tascanna — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST | `/api/a2a/tasks` | (Ní churtha i bhfeidhm mar chúntóir REST — cruthaigh le JSON-RPC `message/send`) |
| GET | `/api/a2a/tasks/[id]` | Faigh tasc amháin |
| POST | `/api/a2a/tasks/[id]/cancel` | Cealaigh tasc |
**Údarás:** ritheann na cúntóirí REST gan údarás bainistíochta (inisithe ag an deais); úsáideann an bealach JSON-RPC `/a2a` Bearer `OMNIROUTE_API_KEY` más rud é atá cumraithe.
---
## Scáláil, Meastóireachtaí & Measúnuithe
| Modh | Conair | Cur síos |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Bailigh eochair Bearer agus fillte nasc soláthraithe mascáilte + ailiasanna samhail le haghaidh cliant sioncronú scála |
| POST | `/api/cloud/credentials/update` | Nuashonraigh creadinchreidmheacha criptithe le haghaidh soláthraí sioncronaithe scála |
| POST | `/api/cloud/model/resolve` | Réitigh aitheantas samhail loighciúil go samhail/soláthraí cruinn le tábla ródaithe áitiúil |
| GET | `/api/cloud/models/alias` | Liosta ailiasanna samhail mar a nochtar don sioncronú scála |
| GET | `/api/assess` | Léigh na catagóirithe meastóireachta is déanaí (in aghaidh an tsoláthraí/samhail) |
| POST | `/api/assess` | Rith measúnú — corp: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Liosta na sraithanna meastóireachta ionsuite + na rithanna is déanaí |
| POST | `/api/evals` | Tosaigh rith meastóireachta |
| POST | `/api/evals/suites` | Cruthaigh sraith meastóireachta saincheaptha — corp bailíochtaithe ag `evalSuiteSaveSchema` |
| GET | `/api/evals/suites/[id]` | Faigh sraith meastóireachta saincheaptha |
**Údarás:** baineann `/api/cloud/auth` eochair Bearer le bailíochtú díreach; éilíonn bealaigh eile `/api/cloud/*`, `/api/evals/*`, agus `/api/assess` seisiún bainistíochta/eochair API. Úsáideann POST `/api/assess` `validateBody` le scéim scóip comhthiomsaithe dhíghrúpaithe.
---
## Bainistíocht ACP (Prótacal Ailtireachta Comhla)
mar phróisis leanúna. Na críochphointí seo bainistíonn siad braiteadh na n-aonad ACP agus clárú saincheaptha aonad.
| Modh | Conair | Cur Síos |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/acp/agents` | Liostaigh gach CLI aonad ar eolas (inneabhraithe + saincheaptha) le státs suiteáil, leagan, dénártha |
| POST | `/api/acp/agents` | Cláraigh aonad ACP saincheaptha nó athnua an taisce — corp: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` nó `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Bain aonad ACP saincheaptha — paraiméadar fiafraí: `?id=<agentId>` |
**Sampla freagra** (`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
}
```
**Údarú:** Éilíonn sé seisiún bainistíochta (fianán `auth_token` deasc) nó eochair API scóipe bainistíochta.
Féach [Fráma ACP](../frameworks/ACP.md) le haghaidh sonraí iomlán.
---
## Anailísíocht & Inghníomhachtacht
Críochphointí anailísíochta fíor-ama le haghaidh monatóireachta ar roptá, comhbhrú, agus éagsúlacht soláthraithe. Cumhdaíonn siad na leathanaigh `/dashboard/analytics/*`.
### Anailísíocht uathrioptá
| Modh | Conair | Cur Síos |
| ---- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/auto-routing` | Staitisticí uathrioptá beachtaithe: iomlán glaonna, dáileadh straitéisí, dáileadh céimeanna, príomhsholáthraithe |
| GET | `/api/analytics/auto-routing?days=7` | Staitisticí fuinneoige ama (réamhshocrú 24u) |
**Sampla freagra**:
```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 }
]
}
```
### Anailísíocht comhbhrú
| Modh | Conair | Cur Síos |
| ---- | ---------------------------- | ------------------------------------------------------------------------------------------------------ |
| GET | `/api/analytics/compression` | Staitisticí comhbhrú beachtaithe: comharthaí shábháilte, coigilteas %, dáileadh modhanna, úsáid innill |
**Sampla freagra**:
```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
}
}
```
### Rianú éagsúlachta soláthraithe
| Modh | Conair | Cur Síos |
| ---- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/analytics/diversity` | Rianú éagsúlachta atá bunaithe ar entropó Shannon: cuireann sé cosc ar phointí teipe aonair trí mheasúnú ar leathadh na soláthraithe |
**Sampla freagra**:
```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": ["Cuireann OpenAI 40% den trácheáil ar fáil — smaoinigh ar éagsúlacht a mhéadú"]
}
```
**Údarú:** Éilíonn sé seisiún bainistíochta nó eochair API scóipe bainistíochta.
---
## Oibríochtaí Riarachána
Deireannaí ar nósanna riarachána amháin le haghaidh bainistíochta oibríochtaí.
| Modh | Conair | Cur Síos |
| ---- | ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| GET | `/api/admin/concurrency` | Léigh teorainneacha comhthráchta reatha (comhshó + in aghaidh an soláthraí) |
| POST | `/api/admin/concurrency` | Nuashonraigh teorainneacha comhthráchta — comhlacht: `{global?: number, perProvider?: Record<string, number>}` |
**Údarú:** Éilíonn sé seisiún bainistíochta le raon riarachána.
---
## Bainistíocht Uirlisí CLI
Bainistigh uirlisí CLI a chomhtháthaíonn le OmniRoute (antigravity, chiplete, commandCode, devin-cli, srl.). Féach [Tagairt Soláthraí](./PROVIDER_REFERENCE.md) le haghaidh an liosta iomlán.
| Modh | Conair | Cur Síos |
| ---- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cli-tools/all-statuses` | Stádas gach uirlisí CLI (suiteáilte, leagan, feicthe go deireanach) |
| GET | `/api/cli-tools/status` | Mionsonraí stádais d'uirlis CLI amháin (iarratais `?tool=`) |
| POST | `/api/cli-tools/apply` | Scríobh cumraíocht ghinmheánach uirlis (`dryRun` réamhamharcanna; `422` + `containerEphemeralTarget` nuair atá i gcoimeádán; `migration` nótaíonn sé YAML Codex sean-nós) |
| GET | `/api/cli-tools/backups` | Liosta cúltacaí cumraíochta uirlisí CLI |
| POST | `/api/cli-tools/backups` | Cruthaigh cúltaca de gach cumraíocht uirlisí CLI |
| POST | `/api/cli-tools/backups` | Athchóirigh: an chéanna le pointe deiridh agus `{tool, backupId}` sa chomhlacht athchóiríonn an cúltaca sin |
| GET | `/api/cli-tools/antigravity-mitm` | Stádas seachbhreithe MITM antigravity (uirlis CLI "antigravity-mitm") |
| POST | `/api/cli-tools/antigravity-mitm/alias` | Cumraigh ailiasanna antigravity-mitm |
**Údarú:** Éilíonn sé seisiún bainistíochta.
---
## Scileanna gníomhaire
Bainistigh scileanna gníomhaire AI (cosúil le GPTs saincheaptha OpenAI ach do ghníomhairí).
| Modh | Conair | Cur Síos |
| ------ | ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| GET | `/api/agent-skills` | Liostaigh gach scil gníomhaire (ionsuite + saincheaptha) |
| GET | `/api/agent-skills/[id]` | Faigh scil gníomhaire ar leith |
| POST | `/api/agent-skills` | Cruthaigh scil gníomhaire saincheaptha — comhlacht: `{name, description, prompt, model?, temperature?}` |
| PUT | `/api/agent-skills/[id]` | Nuashonraigh scil gníomhaire saincheaptha |
| DELETE | `/api/agent-skills/[id]` | Scrios scil gníomhaire saincheaptha |
| GET | `/api/agent-skills/[id]/raw` | Faigh prompt amh + meiteashonraí (gan rith) |
| POST | `/api/agent-skills/generate` | Gintear scil nua le AI ó chur síos teanga nádúrtha |
**Údarú:** Éilíonn sé seisiún bainistíochta nó eochair API raon bainistíochta.
---
## Bainistíocht Taisce
Bainistiú na taisce chiallchreidmheach agus na taisce tuairimíochta.
| Modh | Cosán | Cur Síos |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| FAIGH | `/api/cache` | Forbhreathnú taisce: iontrálacha iomlán, ráta buailte, méid ar diosca |
| FAIGH | `/api/cache/entries` | Liosta na n-iontrálacha atá i stór (le leathanachnascadh) |
| SCRÍOS | `/api/cache/entries` | Scrios iontrálacha taisce (scag de réir na bparaiméadar fiafraí) |
| FAIGH | `/api/cache/stats` | Staitisticí taisce mionsonraithe (de réir soláthraí, de réir samhail) |
| FAIGH | `/api/cache/reasoning` | Stádas na taisce tuairimíochta (do athsheirm tuairimíochta) |
| SCRÍOS | `/api/cache/reasoning` | Glan an fharraimh tuairimíochta — paraiméadair fiafraí: `?toolCallId=<id>` (aonair) nó `?provider=<p>` nó gan paraméadair (go léir) |
**Údarú:** Éilíon seisiún bainistíochta.
---
## Córas Cuimhne
Bainistiú cuimhne buan (FTS5 + leabú veicteoirí).
| Modh | Cosán | Cur Síos |
| ------ | ------------------ | --------------------------------------------------------------------------------------------- |
| FAIGH | `/api/memory` | Liosta na n-iontrálacha cuimhne (scag de réir scóip, cineáil, fiafraí cuardaigh) |
| POST | `/api/memory` | Cruthaigh iontráil cuimhne nua — comhlacht: `{scope, type, content, metadata?}` |
| FAIGH | `/api/memory/[id]` | Faigh iontráil cuimhne ar leith |
| CUIR | `/api/memory/[id]` | Nuashonraigh iontráil cuimhne |
| SCRÍOS | `/api/memory/[id]` | Scrios iontráil cuimhne |
| FAIGH | `/api/memory?q=` | Cuardaigh cuimhne (FTS5 + veicteoir) — cuirtear staitisticí san áireamh sa fhreagairt chéanna |
**Údarú:** Éilíon seisiún bainistíochta nó eochair API scóipe bainistíochta.
---
## Webhooks
Bainistiú síntíní webhook d'imeachtaí.
| Modh | Cosán | Cur Síos |
| ------ | ------------------------------- | ------------------------------------------------------------------------- |
| FAIGH | `/api/webhooks` | Liosta na síntíní webhook go léir |
| POST | `/api/webhooks` | Cruthaigh síntín webhook — comhlacht: `{url, events[], secret?, active?}` |
| FAIGH | `/api/webhooks/[id]` | Faigh síntín webhook ar leith |
| CUIR | `/api/webhooks/[id]` | Nuashonraigh síntín webhook |
| SCRÍOS | `/api/webhooks/[id]` | Scrios síntín webhook |
| FAIGH | `/api/webhooks/[id]/deliveries` | Liosta stair na seachadadh do webhook (logáil rathúlacht/teip) |
| POST | `/api/webhooks/[id]/test` | Seol imeacht tástála chuig webhook |
**Údarú:** Éilíon seisiún bainistíochta.
Féach [Creat Webhooks](../frameworks/WEBHOOKS.md) le haghaidh na n-imeachtaí iomlán.
## Fráma Scileanna
Bainistigh Scileanna (an fráma síntí gníomhaireacha).
| Method | Path | Description |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------- |
| GET | `/api/skills` | Liostaigh na scileanna go léir atá suiteáilte (ionsuite + saincheaptha) |
| POST | `/api/skills/install` | Suiteáil scil ó chonair áitiúil nó ó URL |
| DELETE | `/api/skills/[id]` | Díshuiteáil scil |
| PUT | `/api/skills/[id]` | Cumasaigh nó díchumasaigh scil — comhlacht: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST | `/api/skills/executions` | Rith scil — comhlacht: `{skillName, apiKeyId, input?, sessionId?}` |
| GET | `/api/skills/executions` | Liostaigh stair forghníomhaithe do na scileanna go léir (scag de réir `?apiKeyId=`) |
**Údarú:** Éilíonn seisiún bainistíochta nó eochair API le raon feidhme bainistíochta.
Féach [Fráma Scileanna](../frameworks/SKILLS.md) le haghaidh sonraí iomlána.
---
## Breiseáin
Bainistigh breiseáin OmniRoute (síntí tríú páirtí).
| Method | Path | Description |
| ------ | ---------------------------------- | ------------------------------------- |
| GET | `/api/plugins` | Liostaigh na breiseáin atá suiteáilte |
| POST | `/api/plugins/marketplace/install` | Suiteáil breiseán ón margadh |
| DELETE | `/api/plugins/[name]` | Díshuiteáil breiseán |
| POST | `/api/plugins/[name]/activate` | Gníomhachtaigh breiseán |
| POST | `/api/plugins/[name]/deactivate` | Díghníomhachtaigh breiseán |
| GET | `/api/plugins/[name]/config` | Faigh cumraíocht an bhreiseáin |
| PUT | `/api/plugins/[name]/config` | Nuashonraigh cumraíocht an bhreiseáin |
**Údarú:** Éilíonn seisiún bainistíochta.
Féach [Fráma Breiseán](../frameworks/PLUGIN_SDK.md) le haghaidh sonraí iomlána.
---
## Ródú Scátha
Ní dromchla REST neamhspleách é comparáid scátha / A-B de sholáthraithe — cumraítear é trí ródú comhcheangail (féach [Auto-Combo](../routing/AUTO-COMBO.md)). Freastalaíonn `GET /api/combos/metrics` ar mhéadracht chomparáide in aghaidh an chomhcheangail.
---
## Ráillí Cosanta
Déan iniúchadh ar na ráillí cosanta ag am rite (braite PII, braite insteallta pras, nascacht fís). Ritheann ráillí cosanta ar gach iarratas; is trí cheanntásc iarrata `x-omniroute-disabled-guardrails` a dhéantar rogha an fhágáil amach in aghaidh an ghlao — níl aon dromchla cumasaithe/díchumaisithe buan ann.
| Method | Path | Description |
| ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------- |
| GET | `/api/guardrails` | Liostaigh na ráillí cosanta cláraithe agus a stádas (ainm / cumasaithe / tosaíocht) |
| POST | `/api/guardrails/test` | Rith triail thirim ar an bpíblíne réamhghlao thar ionchur samplach — comhlacht: `{input, disabledGuardrails?}` |
**Údarú:** Éilíonn seisiún bainistíochta.
Féach [Slándáil > Ráillí Cosanta](../security/GUARDRAILS.md) le haghaidh sonraí iomlána.
---
## Fíordheimhniú
Féach ar [Bainistíocht Fíordheimhnithe](../guides/MANAGEMENT-AUTH.md) le haghaidh na ceithre theaghlach creidiúna (seisiún an deais, teaghlach CLI logchomhartha, Rochtain Token `oma_live_…`, agus eochair API scóip bainistíochta) agus conas a mbaineann siad le heochracha tomhais.
- Úsáideann bealaí an Deais (`/dashboard/*`) an fógra `auth_token`
- Úsáidtear an t-aitriamh pasfhocail shábháilte le haghaidh logála isteach; tá súil ar `INITIAL_PASSWORD`
- Is féidir `requireLogin` a scoránaigh trí `/api/settings/require-login`
- Éilíonn bealaí `/v1/*` Eochair API Bearer go roghnach nuair a bhíonn `REQUIRE_API_KEY=true`
- Tagann "tacar bainistíochta" / "eochair API scóip bainistíochta" i dtacaigh seo le ceann de na teaghlaigh san treoir sin — ní le cineál rúndachta breise neamhshainithe.
> **Athrú briseadh (v3.8.0)** — Éilíonn bealaí `/api/v1/agents/tasks/*` agus na pointí deiridh bainistíochta comhdhálaithe **fíordheimhniú bainistíochta** anois (fógra `auth_token` an deais nó eochair API scóip bainistíochta). Gheobhaidh cliaint a ghlaonna ar na bealaí seo gan fíordheimhniú roimhe seo `401 Unauthorized`. Féach ar tiomanta `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).
Reference in New Issue View Git Blame Copy Permalink