# API Reference (Հայերեն)

🌐 **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) · 🇧🇦 [bs](../../../bs/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) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇮🇩 [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)

---

🌐 **Լեզուներ:** 🇺🇸 [English](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇧🇦 [Bosanski](../i18n/bs/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md)

OmniRoute API-ի հիմնական տեղեկատուն։ Այն ընդգրկում է հանրային `/v1` մակերեսը և կառավարման ամենաշատ օգտագործվող վերջնակետերը։ Մեքենայաընթեռնելի [`docs/openapi.yaml`](../openapi.yaml) ֆայլը և `src/app/api/`-ի ներքո գտնվող երթուղիների ծառը ամբողջական աղբյուրներն են։

OpenAI-ին համատեղելի արձանագրության և մատակարարների հնարավորությունների կենտրոնացված մատրիցի համար տես
[`OPENAI_COMPATIBILITY.md`](./OPENAI_COMPATIBILITY.md)։

Յուրաքանչյուր տեղակայում սպասարկում է սպեցիֆիկացիայի իր պատճենը՝ `/openapi.yaml` հասցեում, որը կառուցման ընթացքում ստեղծվում է `docs/openapi.yaml`-ից։ Այն պարունակում է կառուցման տարբերակը և հարաբերական սերվերի URL՝ (`./`), ուստի հարցումները մնում են այն հոսթում, որը սպասարկել է փաստաթուղթը։ Ներբեռնված ֆայլը ներմուծող գործիքը նման հոսթ չունի և բազային URL-ը պետք է սահմանվի ձեռքով։

---

## Բովանդակության ցանկ

- [Զրույցի լրացումներ](#chat-completions)
- [Բացառիկ կառավարվող սեսիայի վարձակալություններ](#exclusive-managed-session-leases)
- [Ներդրումներ](#embeddings)
- [Պատկերների ստեղծում](#image-generation)
- [Փաստաթղթերի OCR](#document-ocr)
- [Մոդելների ցանկ](#list-models)
- [Մատակարարի պլագինի մանիֆեստ](#provider-plugin-manifest)
- [Համատեղելիության վերջնակետեր](#compatibility-endpoints)
- [Files API](#files-api)
- [Batches API](#batches-api)
- [Search API](#search-api)
- [WebSocket հոսքային փոխանցում](#websocket-streaming)
- [Քվոտաներ և խնդիրների հաղորդում](#quotas--issues-reporting)
- [Իմաստային քեշ](#semantic-cache)
- [CLIProxyAPI-ի կառավարման համատեղելիություն](#cliproxyapi-management-compatibility)
- [Վահանակ և կառավարում](#dashboard--management)
- [Կոմբոյի կառավարում](#combo-management)
- [Վեբհուքներ](#webhooks)
- [Գրանցված բանալիներ (ավտոմատ կառավարում)](#registered-keys-auto-management)
- [Գործակալների արձանագրություն](#agents-protocol)
- [Կառավարման պրոքսիներ](#management-proxies)
- [Դիմակայունություն (ընդլայնված)](#resilience-extended)
- [Հմտություններ](#skills)
- [Հիշողություն](#memory)
- [MCP սերվեր](#mcp-server)
- [A2A սերվեր](#a2a-server)
- [Cloud, Evals և Assess](#cloud-evals--assess)
- [Հարցումների մշակում](#request-processing)
- [Նույնականացում](#authentication)

---

## Զրույցի լրացումներ

```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
}
```

### Հատուկ վերնագրեր

| Header                   | Direction | Description                                                                                                                                                                                                                                                     |
| ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache`   | Հարցում   | Սահմանեք `true`, որպեսզի շրջանցեք քեշը                                                                                                                                                                                                                          |
| `x-omniroute-no-memory`  | Հարցում   | Սահմանեք `true`, որպեսզի այս հարցման համար բաց թողնեք հիշողության + հմտությունների ներարկումը (նման է no-cache-ին․ խուսափում է յուրաքանչյուր կանչի նշանների/արժեքի ծախսից)                                                                                      |
| `X-OmniRoute-Progress`   | Հարցում   | Սահմանեք `true`՝ առաջընթացի իրադարձությունների համար                                                                                                                                                                                                            |
| `X-Session-Id`           | Հարցում   | Կպչուն սեսիայի բանալի արտաքին սեսիայի կապակցման համար                                                                                                                                                                                                           |
| `x_session_id`           | Հարցում   | Ընդունվում է նաև ընդգծումով տարբերակը (ուղիղ HTTP)                                                                                                                                                                                                              |
| `X-OmniRoute-Session-Id` | Հարցում   | Կանչողի կողմից տրամադրված սեսիայի/երկխոսության պիտակ (նաև փոխանցվում է հիշողությանը)։ Ներկայության դեպքում բառացիորեն պահպանվում է `call_logs.session_tag`-ում՝ ըստ սեսիայի արժեքի վերագրում կատարելու համար (#8249) — բացակայության դեպքում երբեք չի ստեղծվում |
| `Idempotency-Key`        | Հարցում   | Կրկնօրինակման կանխման բանալի (5 վայրկյանի պատուհան)                                                                                                                                                                                                             |
| `X-Request-Id`           | Հարցում   | Կրկնօրինակման կանխման այլընտրանքային բանալի                                                                                                                                                                                                                     |
| `x-omniroute-connection` | Հարցում   | Մեկ մոդելով հարցումը կապում է մատակարարի մեկ կապի (հաշվի) հետ՝ ըստ նույնացուցիչի — տես [Հարցման համար հաշվի կապակցում](#account-pinning-per-request)                                                                                                            |
| `X-OmniRoute-Cache`      | Պատասխան  | `HIT` կամ `MISS` (ոչ հոսքային)                                                                                                                                                                                                                                  |
| `X-OmniRoute-Idempotent` | Պատասխան  | `true`, եթե կրկնօրինակումը կանխվել է                                                                                                                                                                                                                            |
| `X-OmniRoute-Progress`   | Պատասխան  | `enabled`, եթե առաջընթացի հետևումն ակտիվ է                                                                                                                                                                                                                      |
| `X-OmniRoute-Session-Id` | Պատասխան  | OmniRoute-ի կողմից օգտագործված արդյունավետ սեսիայի ID                                                                                                                                                                                                           |
| `X-OmniRoute-Request-Id` | Պատասխան  | Հարցման փոխկապակցման ID (երբ հայտնի է)                                                                                                                                                                                                                          |
| `X-OmniRoute-Version`    | Պատասխան  | OmniRoute-ի հավաքածուի տարբերակը (միշտ առկա է)                                                                                                                                                                                                                  |
| `X-OmniRoute-Cost-Saved` | Պատասխան  | ԱՄՆ դոլարով գումարը, որը քեշը խնայել է HIT-ի դեպքում (միայն քեշի հարվածների դեպքում)                                                                                                                                                                            |
| `X-OmniRoute-Decision`   | Պատասխան  | Ուղղորդման հետագիծ՝ `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>`-ը համակցված ռազմավարությունն է, կամ `single`՝ ոչ համակցված հարցման դեպքում) — ավարտի պատասխաններում միշտ առկա է                                                               |

> Nginx-ի նշում․ եթե հիմնվում եք ընդգծում պարունակող վերնագրերի վրա (օրինակ՝ `x_session_id`), միացրեք `underscores_in_headers on;`։

#### Հարցման համար հաշվի կապակցում

Երբ մատակարարն ունի մի քանի կապ (հաշիվներ կամ բանալիներ), OmniRoute-ը սովորաբար ընտրում է դրանցից մեկը
իր հաշվի ընտրության ռազմավարության միջոցով։ Փոխարենը հարցումը կարող է կապվել մեկ կոնկրետ կապի հետ
`x-omniroute-connection` վերնագրի միջոցով՝

```bash
curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer <your OmniRoute API key>" \
  -H "Content-Type: application/json" \
  -H "x-omniroute-connection: <connection id>" \
  -d '{"model": "codex/gpt-5.5", "messages": [{"role": "user", "content": "hi"}]}'
```

- **Որտեղ գտնել id-ն։** Բացեք մատակարարի էջը վահանակում
  (**Dashboard → Providers → <provider>**) և միացման տողում սեղմեք `xxxxxxxx…` id-ի չիպը․
  այն պատճենում է միացման ամբողջական id-ն։
- **Որ հարցումներն են հաշվի առնում այն։** Մեկ մոդելի հարցումները (`provider/model`)՝
  `/v1/chat/completions`, `/v1/messages` և `/v1/responses` հասցեներում։ Կոմբինացիաներն անտեսում են վերնագիրը․
  յուրաքանչյուր կոմբինացիայի քայլի համար հաշիվը ամրակցեք հենց այդ քայլի սեփական միացման միջոցով։
- **Ամրակցումը խիստ է, ոչ թե նախապատվություն։** Ամրակցված միացումն օգտագործվում է բացառապես։
  Հարցման ընթացքում տեղի ունեցած խափանումը գրանցում է հաշվի սառեցման ժամանակահատվածը, բայց
  չի անցնում նույն մատակարարի մեկ այլ հաշվի։
- **Սառեցումն ու քվոտան ազատում են ամրակցումը։** Քանի դեռ ամրակցված միացումը սառեցված է,
  քվոտան սպառված է կամ քվոտայի քաղաքականությամբ արգելափակված է, հետագա հարցումները անցնում են
  մատակարարի մյուս միացումներին՝ ճիշտ այնպես, ինչպես չամրակցված տրաֆիկը։
- **Անհայտ կամ անջատված id-ները ձախողվում են։** Եթե id-ն մատակարարի ակտիվ խմբում չկա (ջնջված է,
  ապաակտիվացված է կամ պատկանում է մեկ այլ մատակարարի), համապատասխան հաշիվ չի մնում, ուստի
  հարցումը ձախողվում է՝ այլ տեղ անաղմուկ ուղղորդվելու փոխարեն։

Claude Code-ը հատուկ վերնագրերն ուղարկում է `ANTHROPIC_CUSTOM_HEADERS`-ի միջոցով։ Այն տեղադրեք
`~/.claude/settings.json`-ի `env` բլոկում կամ նախագծի մակարդակի `.claude/settings.json`-ում՝ յուրաքանչյուր նախագծի համար մեկ այլ հաշիվ ամրակցելու նպատակով․

```jsonc
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
    "ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: <connection id>",
  },
}
```

Աղբյուր՝ `src/sse/handlers/chat.ts` (վերնագրի ընթերցում), `src/sse/services/auth.ts` և
`src/sse/services/sessionAffinityPin.ts` (ամրակցման ազատում և խմբում բացակայության ստուգում)։

> **Ծախսերի հեռաչափության վերնագրեր․** հոսք չօգտագործող հաջող պատասխանները նույնպես ներառում են `X-OmniRoute-*` ծախսերի հեռաչափության հավաքածուն՝ `X-OmniRoute-Response-Cost` (ԱՄՆ դոլար, հաստատուն 10 տասնորդական նիշ․ անվճար/չգնահատվածի համար՝ `0.0000000000`), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit` և `X-OmniRoute-Fallback-Attempts` (միայն երբ > 0), ինչպես նաև `X-OmniRoute-Request-Id` և `X-OmniRoute-Version`։ Դրանք ուղարկվում են chat completions-ի, `/v1/responses`, `/v1/messages` **և մեդիայի վերջնակետերի** միջոցով՝ `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` և `/v1/moderations` (միշտ՝ `0` ծախսով)։ Մեդիայի ծախսը հաշվարկվում է ըստ համապատասխան մեդիայի տեսակի (ըստ պատկերի, ըստ վայրկյանի, ըստ նիշի, ըստ որոնման միավորի), երբ գնագոյացումը հասանելի է, իսկ հակառակ դեպքում՝ `0` (fail-open)։

> **Քեշի հարվածի ծախսի իմաստը․** իմաստային քեշի HIT-ի դեպքում (`X-OmniRoute-Cache-Hit: true`) վերին հոսքի հարցում չի կատարվում, ուստի `X-OmniRoute-Response-Cost`-ը `0.0000000000` է (հարվածի սպասարկման **աճողական** ծախսը)։ Սկզբնական/ակնկալվող ծախսը առանձին հաղորդվում է `X-OmniRoute-Cost-Saved`-ում։ Գանձման համակարգի սպառողները պետք է գումարեն `X-OmniRoute-Response-Cost`-ը (հարվածներն անվճար են), իսկ քեշի վերլուծությունը կարող է միավորել `X-OmniRoute-Cost-Saved`-ը։

## Բացառիկ կառավարվող սեսիայի վարձակալություններ

Բացառիկ կառավարվող սեսիայի վարձակալությունը միացման ընտրովի, հաճախորդից անկախ երթուղավորման պայմանագիր է․ մեկ ակտիվ սեփականատերը պահում է մեկ համապատասխան OmniRoute միացում։ Այն չի վարձակալում մոդել, չի պահանջում OAuth, չի նույնականացնում որևէ կոնկրետ հաճախորդ և չի պահանջում որևէ կոնկրետ մատակարար։

Նույնականացումն իրականացնող API բանալին պետք է ունենա `lease:exclusive` scope և բացահայտ, ոչ դատարկ
`allowedConnections` ցուցակ։ Տվյալների բազայի փոփոխության սահմանը բանալու ստեղծման և մասնակի թարմացումների ժամանակ պարտադրում է երկու դաշտերի համատեղ առկայությունը։

```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"}
```

Հաջող `acquire`, `renew` և `release` պատասխանները տրամադրում են ժամանակային դրոշմներ, `state` և ճշգրիտ դրական
`generation`, սակայն երբեք չեն բացահայտում ընտրված միացումը կամ հավատարմագրերը։ `renew` և `release` գործողությունները
`generation`-ը տրամադրում են JSON մարմնում․

```json
{ "action": "renew", "generation": 1 }
```

```json
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
```

Ակտիվ վարձակալության սեփականատերը կարող է բացահայտորեն պահանջել գաղտնիությունը պահպանող ցուցադրման մետատվյալներ իր ընթացիկ կապակցման համար․

```json
{ "action": "status", "generation": 1 }
```

```json
{
  "state": "ACTIVE",
  "generation": 1,
  "acquiredAt": "2026-08-28T12:00:00.000Z",
  "renewedAt": "2026-08-28T12:00:30.000Z",
  "expiresAt": "2026-08-28T12:02:30.000Z",
  "connection": {
    "displayName": "Primary Codex",
    "provider": "codex"
  }
}
```

Այս ընտրովի status գործողությունը մեկ տվյալների բազայի գործարքում սահմանափակվում է անթափանց սեփականատիրոջ, նույնականացված կառավարվող API բանալու և ճշգրիտ ակտիվ սերնդի միջոցով։ `displayName`-ը միայն կարգավորված միացման անունն է՝ կտրատված բացատներից․ այն `null` է, երբ անվտանգ կարգավորված անուն գոյություն չունի։ OmniRoute-ը երբեք չի փոխարինում այն էլփոստով կամ գեներացված հաշվի նույնականացմամբ։ Մատակարարի արժեքը ոչ զգայուն ցուցադրման պիտակ է և երբեք չի հանդիսանում համատեղելի մատակարարի գեներացված նույնացուցիչ։ Հավատարմագրերը, թոքենները, cookie-ները, միացման կամ API բանալու չմշակված նույնացուցիչները, սեփականատերերի հեշերը, սահմանափակման գաղտնիքները և ներքին երթուղավորման տվյալները բացառվում են։

Սխալ բանալու, սխալ սեփականատիրոջ, հնացած սերնդի, բացակայող, ժամկետանց, ազատված և անվավերացված որոնումները բոլորը վերադարձնում են նույն
`409 LEASE_FENCE_STALE` սխալը՝ առանց միացման մետատվյալների։ Տարողության սպասման պատասխանը ստացած հաճախորդը չունի ստուգման ենթակա ակտիվ կապակցում։ Երբ երթուղավորումը փոխում է ակտիվ վարձակալությունը, նույն սերունդը մնում է վավեր, իսկ status-ը ատոմիկորեն վերադարձնում է նոր կապակցումը՝ երբեք ոչ հինը։ Գոյություն ունեցող հաճախորդները չեն փոխվում, քանի որ acquire, renew, release և սպասման պատասխանները պահպանում են իրենց նախկին ձևերը։

Այս սերվերային պայմանագիրը չի փոխում ստանդարտ OpenAI Codex `/status`-ը։ Ստանդարտ Codex-ը ներկայում հայտնում է իր մոդելի մատակարարին և ներկառուցված նույնականացման/հաշվի վիճակը, սակայն չի ցուցադրում կամայական մատակարարի հաշվի մետատվյալներ․ հետագա հաճախորդային ինտեգրումը պետք է կանչի այս գործողությունը և որոշի, թե ինչպես ցուցադրել `connection.displayName`-ը։

Յուրաքանչյուր կառավարվող inference հարցում այնուհետև տրամադրում է կառավարման երկու վերնագրերը՝

```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```

Յուրաքանչյուր աջակցվող upstream փորձից անմիջապես առաջ ստուգվում են ճշգրիտ սեփականատերը, սերունդը, ակտիվ միացումը և նույնականացված API բանալին։ Սեփականատիրոջն ու սերունդը մեկ այլ բանալիով կրկնելը ձախողվում է, նույնիսկ եթե այդ բանալին թույլ է տալիս օգտագործել նույն միացումը։ Չմշակված սեփականատերերը չեն պահպանվում, չեն գրանցվում, չեն պահվում հարցման snapshot-ում և չեն փոխանցվում upstream։

Ժամանակավոր մրցակցությունը վերադարձնում է HTTP `429`՝ `Retry-After`-ով և՝

```json
{
  "state": "WAITING_FOR_CAPACITY",
  "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
  "reason": "NO_FREE_ELIGIBLE_CONNECTION",
  "retryAfter": 30
}
```

Այս պատասխանը միայն նշանակում է, որ սովորական համապատասխան բազմությունը դատարկ չէր, և յուրաքանչյուր ազատ թեկնածու զբաղեցված էր օտար ակտիվ վարձակալությամբ։ Չաջակցվող մոդելները/մատակարարները, քաղաքականության անհամապատասխանությունը, cooldown-ը, քվոտան, առողջական վիճակը և սովորական համապատասխանության այլ ձախողումները պահպանում են իրենց գոյություն ունեցող OmniRoute պատասխանները։

### `x-omniroute-compression`

Յուրաքանչյուր հարցման համար սեղմման պլանի վերասահմանում։ Ամենաբարձր առաջնահերթությունն ունի՝ գերազանցում է երթուղավորման համակցության վերասահմանմանը, ակտիվ պրոֆիլին, ավտոմատ գործարկմանը և վահանակի Default-ին։ Արժեքները՝

| Արժեք         | Գործողություն                                                                                            |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| `off`         | Այս հարցման համար սեղմում չկա։                                                                           |
| `default`     | Վահանակից ստացված Default պրոֆիլը (անտեսում է ակտիվ պրոֆիլը)։ Կորուստներով շարժիչները մնում են անջատված։ |
| `safe`        | Միայն կրկնությունների հեռացում և բացատների համախմբում։                                                   |
| `allow-lossy` | Այս հարցման համար պահպանում է օպերատորի պլանը՝ ներառյալ ամփոփումները և ոճային վերաշարադրումները։         |
| `engine:<id>` | Մեկ շարժիչ, երբ միացված է, օրինակ՝ `engine:rtk`։ Այդ շարժիչի համար հարցման մակարդակով միացում։           |
| `<combo>`     | Անվանված համակցություն, որը նախ համեմատվում է անունով (առանց մեծատառերի տարբերակման), ապա՝ id-ով։        |

Նշումներ․

- Անհայտ արժեքներն անտեսվում են (հարցումը երբեք չի մերժվում)․ լուծումը անցնում է օպերատորի սովորական առաջնահերթության հաջորդ փուլ։
- Եթե մի քանի համակցություններ ունեն նույն անունը, որոշակի համապատասխանության համար փոխանցեք համակցության **id**-ն։
- Այն համակցությունը, որի անունը `off` կամ `default` է, չի կարող ընտրվել անունով (այդ հիմնաբառերը մեկնաբանվում են նախ)․ նման համակցությանը հղվեք դրա id-ով։
- Սեղմման գլխավոր անջատիչը կոշտ սահմանափակում է․ երբ սեղմումը գլոբալ անջատված է, այս վերնագիրը չի կարող այն միացնել։

Կիրառված պլանը վերադարձվում է պատասխանի վերնագրում՝

```
X-OmniRoute-Compression: <mode>; source=<source>
```

որտեղ `<source>`-ը հետևյալներից մեկն է՝ `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` կամ `off`։

---

## Էմբեդինգներ

```bash
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "nebius/Qwen/Qwen3-Embedding-8B",
  "input": "The food was delicious"
}
```

Հասանելի մատակարարներ՝ Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI։

Կատալոգի id-ներն ունեն `provider/model` ձևաչափ (օրինակ՝ `jina-ai/jina-embeddings-v5-omni-small`)։ Ռեեստրում առկա Jina-ի մոդելների առանց նախածանցի id-ները (օրինակ՝ `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) նույնպես resolve են լինում։ Jina embed/rerank/classify/segment ծառայությունները նախ օգտագործում են dashboard-ի `jina-ai` հավատարմագրերը․ `JINA_AI_API_KEY`-ը օգտագործվում է որպես fallback միայն այն դեպքում, երբ dashboard-ում բանալի չկա։ `jina-reader` քարտը նախատեսված է միայն Reader / `r.jina.ai`-ի համար (`POST /v1/web/fetch`) և երբեք չի սպասարկում embeddings կամ rerank։

Ռեեստրի այն մոդելները, որոնք հայտարարում են multimodal աջակցություն, ընդունում են նաև մինչև 32 provider-neutral կառուցվածքային
տարրեր։ Media տարրերի տեսակներն են՝ `text`, `image`, `audio`, `video` և `document`։ Նրանց media `source`-ը
կամ `{"type":"url","url":"https://..."}` է, կամ
`{"type":"base64","data":"...","media_type":"..."}`։

Jina v5 Omni-ը (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`,
և ընտանիքի alias-ը՝ `jina-ai/jina-embeddings-v5-omni` → omni-small) նույնպես ընդունում է Jina-ի բնիկ
EmbeddingsV5Request docs-ը և **դրանք անփոփոխ փոխանցում է** `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,..." }] }
  ]
}
```

Բնիկ `{ image | audio | video | pdf }` արժեքները կարող են լինել հանրային HTTPS URL, `data:` URI կամ
հում base64։ OmniRoute-ը չի վերածում այդ օբյեկտները տողերի և չի բեռնում բնիկ image URL-ները․ Jina-ն
ինքն է ստանում հանրային media-ն։

Փոխանցվում են Jina-ի լրացուցիչ դաշտերը (`task`, `normalized`, `truncate`, `embedding_type`)։ Միայն տեքստի համար նախատեսված Jina SKU-ները դեռևս մերժում են ոչ տեքստային փաստաթղթերը։

Անվտանգության և փոխանցման սահմանափակումներ․

- Հեռակա media URL-ները պետք է լինեն հանրային HTTPS։ Կանոնական `{type,source:url}` տարրերը ստացվում են
  server-side եղանակով (redirect-ի վավերացում, timeout, չափի սահմանափակումներ, հանրային DNS,
  կապի pinning) և provider-ի կանչից առաջ ներառվում են հարցման մեջ։ Jina-native `{image:"https://..."}` տարրերը
  նույն հանրային HTTPS ստուգումից հետո փոխանցվում են 그대로․ URL-ը ստանում է Jina-ն։
- Ներկառուցված base64 media-ն սահմանափակված է յուրաքանչյուր տարրի համար 8 MiB ապակոդավորված և ամբողջ հարցման
  համար՝ 16 MiB ապակոդավորված չափով։

Provider-ի փոխակերպում (կանոնական տարրերը երբեք չեն փոխանցվում անփոփոխ)․

- Jina-ի multimodal մոդելներ․ վերին մակարդակի յուրաքանչյուր տարր դառնում է modality-ին համապատասխանող մեկ օբյեկտ
  (`text` / `image` / `audio` / `video` / `pdf`)՝ ներկառուցված media-ի համար օգտագործելով data URI-ներ․ վերին
  մակարդակի յուրաքանչյուր տարրի համար ստեղծվում է մեկ վեկտոր։
- Gemini Embedding 2 ընտանիք․ վերին մակարդակի մեկ զանգվածը դառնում է մեկ բնիկ
  `models/{model}:embedContent` հարցում՝ `content.parts`-ով (`text` կամ `inline_data`)։
- llama.cpp (`llama-cpp/<model>`, ցանկացած մոդել, որը տեղական սերվերը բեռնել է)․ կանոնական `text` տարրերը
  դառնում են պարզ տողեր, իսկ `image` / `audio` / `video` տարրերից յուրաքանչյուրը դառնում է մեկ
  `{"content": [part]}` օբյեկտ՝ օգտագործելով llama-server-ի chat content parts-ը (`image_url`,
  `input_audio`՝ `wav` / `mp3` / `flac` ձևաչափերով, `input_video`) և ներկառուցված տվյալներ․ վերին մակարդակի
  յուրաքանչյուր տարրի համար ստեղծվում է մեկ վեկտոր։ Սերվերը պետք է գործարկվի `--embedding --mmproj …` դրոշներով․
  առանց projector-ի այն ինքն է մերժում media-ն։ `document`-ը չի աջակցվում։
- Առանց բացահայտ modality metadata-ի անհայտ/դինամիկ մոդելները մերժում են կառուցվածքային մուտքը 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"
}
```

Չաջակցվող մոդել/մոդալություն համակցությունները վերադարձնում են HTTP 400, այլ ոչ թե փոխակերպում տարրը։ Ժառանգական string/token հարցումների՝ input-ին չվերաբերող ընդլայնման դաշտերը շարունակում են փոխանցվել անփոփոխ։

```bash
# Ցուցադրել embedding-ի բոլոր մոդելները
GET /v1/embeddings
```

---

## Image Generation

```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"
}
```

Հասանելի մատակարարները ներառում են OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana,**OpenRouter** ,**ZenMux** , SD WebUI (տեղական), ComfyUI (տեղական)։

`n` վերադարձնում է `n` պատկերները `data[]` ում: Պրովայդերները, որոնց վերին հոսանքում API մեկ զանգի համար վերադարձնում է մեկ պատկեր (Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik, NVIDIA NIM, Cloudflare Workers AI), ստանում են `n` առանձին զանգեր վերևից՝ առավելագույնը 4 թռիչքի ժամանակ: Ֆիքսված `seed` փոխհատուցվում է զանգի ինդեքսով (`seed`, `seed + 1`,…), այնպես որ պատկերները տարբերվում են, բայց մնում են վերարտադրելի: `n` սահմանափակված է 10-ով: Հարցումն ամբողջությամբ ձախողվում է, եթե որևէ զանգ ձախողվի: Fan-out ձևաչափերի ցանկը `SINGLE_IMAGE_FANOUT_FORMATS` է `open-sse/handlers/imageGeneration/fanOut.ts` ում:

ZenMux նորից օգտագործում է գոյություն ունեցող API-բանալին կապը և ընդունում `zenmux/` կամ `zm/` նախածանցները.

- `zenmux/openai/gpt-image-2` օգտագործում է ZenMux ի OpenAI Պատկերները API: Տարբերակները ներառում են `size`, `quality`, `n`, `output_format`, `output_compression`, `background` և `response_format`:
- Այլ հրատարակիչներ, ինչպիսիք են `zm/meta/muse-image-1.0`, օգտագործում են ZenMux ի Vertex AI `:predict` վերջնակետը: `n` քարտեզներ `sampleCount`, `aspect_ratio` to `aspectRatio`, իսկ `image_size` (`1K`, `2K`, `4K`) `sampleImageSize`: Pixel `size` ապահովում է միայն կողմի հարաբերակցությունը, ոչ երաշխավորված պիքսելների չափսերը: Աջակցվող գործակիցները, լուծումները և հաշվարկները տարբերվում են ըստ մոդելի:
- `zm/inclusionai/ming-image-0.1-design` ընտրում է իր չափերը: Բաց թողնել `size`, `aspect_ratio` և `image_size`; բացահայտ արժեքները վերադարձնում են HTTP 400: PNG, JPEG և WebP կարող են պահանջվել `output_format` ով:

Այս ինտեգրումն աջակցում է տեքստի պատկերի ստեղծմանը, այլ ոչ թե հղում-պատկերի խմբագրմանը: Vertex ելքը նորմալացված է `data[].b64_json`; `response_format: "url"` վերադարձնում է HTTPS URL կամ base64 տվյալների URL երբ հասանելի են միայն պատկերի բայթերը: Empty/filtered ելքերը վերադարձնում են ոչ թե դատարկ հաջողություն, այլ սխալ: Մոդելի հասանելիությունը կախված է ZenMux հաշվից: Տես [ZenMux ի Vertex API](https://docs.zenmux.ai/api/vertexai/generate-images) և [OpenAI Պատկերները API](https://docs.zenmux.ai/api/openai/generate-an-image) :

Microsoft 365 Copilot մուտքի կապը ծառայում է `copilot-m365-web/m365-copilot-image` Copilot ի ներկառուցված պատկերային գործիքի միջոցով՝ մեկ Copilot պտույտ յուրաքանչյուր պատկերի համար (`n` 1–4), `size` ուղղորդում է միայն կողմնորոշումը և պատկերները վերադարձվում են ներկառուցված (`b64_json` կամ URL տվյալների `response_format: "url"` համար): Տես [Microsoft 365 Copilot](../providers/COPILOT-M365.md#image-generation).

```bash
# List all image models
GET /v1/images/generations
```

---

## Փաստաթղթերի OCR

```bash
POST /v1/ocr
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "mistral/mistral-ocr-latest",
  "document": {
    "type": "document_url",
    "document_url": "https://example.com/invoice.pdf"
  }
}
```

`model`-ը ընտրում է OCR մատակարարին `provider/model` նախածանցի միջոցով․ առանց նախածանցի մոդելի նույնացուցիչը (օրինակ՝
`mistral-ocr-latest`) համապատասխանեցվում է դրա գրանցված մատակարարին, իսկ բաց թողնված `model`-ի դեպքում կանխադրվածը
Mistral-ն է (`mistral-ocr-latest`)։ Գրանցված մատակարարները (`open-sse/config/ocrRegistry.ts`)՝

| Մատակարարի id                 | Մոդելի id            | `model` արժեք                                                           | Նշումներ                                                                                                                                  |
| ----------------------------- | -------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `mistral`                     | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (կամ առանց նախածանցի `mistral-ocr-latest`) | Սինխրոն — պատասխանը վերադարձվում է անմիջապես վերադասի միակ կանչից։                                                                        |
| `azure-document-intelligence` | `prebuilt-read`      | `azure-document-intelligence/prebuilt-read`                             | Ասինխրոն վերադաս գործողություն (`analyze` + հարցում) — տես ստորև։                                                                         |
| `vertex-deepseek-ocr`         | `deepseek-ocr-maas`  | `vertex-deepseek-ocr/deepseek-ocr-maas`                                 | Սինխրոն՝ Vertex AI-ի `openapi/chat/completions` գործընկերային վերջնակետի միջոցով — նույնականացման և URL-ի վերաբերյալ մանրամասները՝ ստորև։ |

Բոլոր երեք մատակարարները պատասխանում են նույն՝ Mistral-ի ձևին համապատասխան մարմնով․

```json
{
  "pages": [{ "index": 0, "markdown": "# Extracted text..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}
```

### Azure Document Intelligence-ի հարցումների ընթացք

Azure Document Intelligence-ի `analyze` API-ն ասինխրոն է․ սկզբնական հարցումը մարմնի փոխարեն վերադարձնում է
`Operation-Location` վերնագիր, և արդյունքի համար պետք է հարցումներ կատարել։ Մշակիչը
(`open-sse/handlers/ocr.ts`) յուրաքանչյուր վայրկյանը մեկ հարցում է կատարում այդ URL-ին՝ առավելագույնը 30 փորձի
ընթացքում, անմիջապես ձախողվում է (այլևս հարցումներ չի կատարում) ոչ `ok` հարցման պատասխանի կամ `"failed"` կարգավիճակի
դեպքում, և վերադարձնում է `504`, եթե փորձերի բյուջեն սպառվելուց հետո գործողությունը դեռ ընթացքի մեջ է։ Azure-ի
վերջնական պատասխանը նորմալացվում է նույն `pages`/`markdown` կառուցվածքին, որն օգտագործում է Mistral-ը, նախքան
այն կանչողին վերադարձնելը, ուստի հաճախորդի կոդը կարիք չունի մատակարարի համար հատուկ բացառություններ մշակելու։

### Vertex AI DeepSeek OCR-ի նույնականացում և վերջնակետի որոշում

`vertex-deepseek-ocr`-ը կրկին օգտագործում է Vertex AI-ի նույն նույնականացումը, որն OmniRoute-ն արդեն աջակցում է
չաթի/պատկերների համար (`open-sse/executors/vertex.ts`)․ միացման API բանալին կա՛մ Service Account JSON հավատարմագիր
է (JWT-bearer հոսքի միջոցով փոխանակվում է կարճաժամկետ OAuth հասանելիության նշանով), կա՛մ արդեն ստեղծված OAuth
հասանելիության նշան, որն օգտագործվում է 그대로։ Վերադասի վերջնակետի URL-ը Vertex-ի ընդհանուր
`openapi/chat/completions` գործընկերային վերջնակետն է, որը կազմվում է միացման նախագծից և տարածաշրջանից․ բացահայտ
`providerSpecificData.project`/`providerSpecificData.region` արժեքները միշտ գերակայում են, իսկ հակառակ դեպքում
նախագիծը ստացվում է Service Account JSON-ի `project_id`-ից, իսկ տարածաշրջանի կանխադրված արժեքն է
`us-central1`։ Երկու որոշումներն էլ կատարվում են `open-sse/handlers/ocr.ts`-ում
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`) և օգտագործվում են
`src/app/api/v1/ocr/route.ts`-ում՝ նախքան `handleOcr`-ին փոխանցելը։

---

## Մոդելների ցանկ

```bash
GET /v1/models
Authorization: Bearer your-api-key

→ Վերադարձնում է chat, embedding և image բոլոր մոդելները + կոմբինացիաները OpenAI ձևաչափով
```

### Մոդելի գներ (`pricing`)

Մուտքը պարունակում է `pricing` օբյեկտ, երբ OmniRoute-ը գիտի մոդելի գինը։ Գինը ստացվում է
գնագոյացման աղյուսակից, որն օգտագործվում է ծախսերի հաշվառման համար՝ ներկառուցված լռելյայն արժեքներից, համաժամեցված գներից և
`/api/pricing`-ի միջոցով սահմանված վերասահմանումներից։ Սրանք ցուցակային գներ են, ուստի բաժանորդագրային մատակարարների համար նույնպես ցուցադրվում է մեկ տոկենի գինը։

```json
"pricing": {
  "prompt": "0.000005",
  "completion": "0.000025",
  "input_cache_read": "0.0000005",
  "input_cache_write": "0.00000625",
  "input": 5,
  "output": 25,
  "cached": 0.5,
  "cache_creation": 6.25
}
```

| Fields                                                          | Unit                          | Notes                                                                                                                                                                                          |
| --------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`, `completion`, `input_cache_read`, `input_cache_write` | USD per token, decimal string | Համատեղելի է OpenRouter-ի հետ, երբեք չի օգտագործում ցուցչային գրառում։ Քեշի երկու դաշտերը հայտնվում են միայն քեշի գնի առկայության դեպքում։                                                     |
| `input`, `output`, `cached`, `cache_creation`                   | USD per 1M tokens, number     | Նախկին կատալոգի տարբերակներից մնացած դաշտեր, որոնք պահպանվել են առկա հաճախորդների համար։ `reasoning` և `long_context` դաշտերը նույնպես հայտնվում են, երբ գնագոյացման տողը դրանք պարունակում է։ |

- **Կոմբինացիաները** կրում են իրենց առաջին տեսանելի թիրախի գինը։ Ներկառուցված `auto/*` կոմբինացիաները թիրախն ընտրում են հարցման պահին, ուստի `pricing` չունեն։
- **Անվճար մոդելները** ցուցադրում են `"0"` (և `0`), երբ դրանց գինը զրո է։ Գնագոյացման տող չունեցող մոդելը նույնպես ցուցադրում է `"0"`, երբ կատալոգը այն նշում է որպես անվճար (`free: true`) կամ այն ներառված է ներկառուցված անվճար մոդելների կատալոգում։
- **Անհայտ գին․** մուտքը չունի `pricing` բանալի։
- **Վարկով հաշվարկվող մատակարարները** (օրինակ՝ Kiro) գանձում են ըստ հարցումների, այլ ոչ թե ըստ տոկենների։ Նրանց մուտքերը պահպանում են նախկինում ունեցած մեկ միլիոն տոկենի համար նախատեսված թվային դաշտերը և չեն պարունակում մեկ տոկենի համար նախատեսված տողային դաշտեր։
- **Տարբերակները** (reasoning-effort նույնացուցիչներ, no-thinking այլանուններ, discovery և gateway հայելիներ) պատճենում են այն մոդելի գինը, որին ուղղորդում են։
- Դաշտերը պարունակում են միայն բազային դրույքաչափերը։ Երկար կոնտեքստի մակարդակները (թվային `long_context` դաշտը) և ծառայության մակարդակի բազմապատկիչները (օրինակ՝ Codex fast կամ flex) չեն փոխում `prompt`-ը կամ `completion`-ը։
- Օբյեկտը նույնն է նույնականացման բոլոր ոճերի համար, ներառյալ Anthropic-ի ոճով հարցումը՝ `x-api-key` և `anthropic-version` վերնագրերով (պատասխանը մնում է `{ "object": "list", "data": [...] }`)։ Իրականացում՝ `src/app/api/v1/models/catalogPricing.ts`։

### Մոդելի id նախածանցներ (`?prefix=`)

Մոդելների մեծ մասը հրապարակվում է **մատակարարի նախածանցով**։ Թե որ նախածանցը կստանաք, վերահսկվում է
`MODELS_CATALOG_PREFIX_MODE` ֆունկցիոնալ դրոշով և կարող է վերասահմանվել **յուրաքանչյուր հարցման համար** հարցման պարամետրով․ սա օգտակար է այն հաճախորդի համար, որը ցանկանում է մաքուր ցանկ՝ առանց մյուսների համար ամբողջ սերվերի կարգավորումը փոխելու։

```bash
GET /v1/models?prefix=alias        # յուրաքանչյուր մոդելի համար մեկ id — կարճ alias նախածանցը
GET /v1/models?prefix=dual         # երկու ձևերը (սերվերի լռելյայն արժեքը)
GET /v1/models?prefix=canonical    # միայն ամբողջական provider-id նախածանցը
```

| Mode        | Emits                                                   | Notes                                                                                                                                                                                                                        |
| ----------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual`      | `cc/claude-sonnet-4-6` **և** `claude/claude-sonnet-4-6` | **Լռելյայն։** Երկու id-ներն էլ ուղղորդում են դեպի նույն մոդելը․ պահպանվել են, որպեսզի հաճախորդի այն konfigurացիաները, որոնք կոդավորել էին ձևերից որևէ մեկը, շարունակեն աշխատել։ Կատալոգի ծավալը մոտավորապես կրկնապատկվում է։ |
| `alias`     | `cc/claude-sonnet-4-6`                                  | Յուրաքանչյուր մոդելի համար մեկ մուտք։ Առանձին alias չունեցող մատակարարները նույնպես հրապարակում են իրենց մուտքը, այնպես որ ոչինչ չի կորչում։                                                                                 |
| `canonical` | `claude/claude-sonnet-4-6`                              | Յուրաքանչյուր մոդելի համար մեկ մուտք՝ ամբողջական provider-id նախածանցով։ Առանձին alias չունեցող մատակարարները (օրինակ՝ `antigravity/…`, `agy/…`) նույնպես այստեղ հրապարակում են իրենց միակ id-ն, այնպես որ ոչինչ չի կորչում։ |

`dual` ռեժիմի հայելին կարելի է ճանաչել նաև առանց հարցման պարամետրի․ այն պարունակում է `parent`
դաշտ, որը մատնանշում է հիմնական id-ն։

Մոդելների ընտրացանկ ցուցադրող հաճախորդները պետք է հարցնեն `?prefix=alias` — հենց դա է անում
[OmniCopilot VS Code ընդլայնումը](../guides/VSCODE-COPILOT.md)։

### Discovery զտիչներ (`?capability=`, `?min_context=`, `?kind=`, `?q=`)

`GET /v1/models`-ը ընդունում է discovery-ի միացման ենթակա զտիչներ։ Դրանցից որևէ մեկի բացակայության դեպքում պատասխանը
չի փոխվում։ Դրանք սահմանափակում են կատալոգը, որն արդեն տեսնում է կանչողը (API-բանալու թույլտվությունները կիրառվում են նախ),
և գործարկվում են նախքան OpenAI-ի ոճի `limit` / `after` էջավորումը։

```bash
GET /v1/models?capability=vision&capability=tool_calling   # թվարկված բոլոր capability-ները պետք է լինեն true
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding                              # կատալոգի `type`; առանց դրա տողերը `chat` են
GET /v1/models?q=sonnet&limit=10                           # id-ի կամ անվան վրա առանց մեծատառերի տարբերակման համընկնում
```

| Պարամետր      | Արժեքներ                                                                                            |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `capability`  | `attachment`, `reasoning`, `structured_output`, `temperature`, `thinking`, `tool_calling`, `vision` |
| `min_context` | ոչ բացասական ամբողջ թիվ, համեմատվում է `context_length`-ի հետ                                       |
| `kind`        | `chat`, `audio`, `embedding`, `image`, `moderation`, `music`, `rerank`, `video`                     |
| `q`           | 1–200 նիշ                                                                                           |

Անհայտ արժեքը կամ ոչ բացասական ամբողջ թիվ չհանդիսացող `min_context`-ը (օրինակ՝ `1.5`) վերադարձնում է HTTP `400`, և հաղորդագրությունը թվարկում է վավեր արժեքները։ Իրականացումը՝
`src/app/api/v1/models/catalogFilters.ts`։

### Մոդելների կարճ ցուցակ (`POST /v1/models/query`)

`POST /v1/models/query`-ը նույն կատալոգից վերադարձնում է կարճ, դետերմինացված ցուցակ՝ նույն
նույնականացմամբ և ըստ բանալու տեսանելիությամբ, ինչ `GET /v1/models`-ը։

```bash
POST /v1/models/query
Authorization: Bearer your-api-key
Content-Type: application/json

{ "capabilities": ["vision", "tool_calling"], "min_context": 128000, "max_output": 16000,
  "kind": "chat", "q": "gpt", "owned_by": "openai", "exclude": ["openai/gpt-4o"], "limit": 5 }

→ { "object": "list", "data": [ ...models ] }
```

Յուրաքանչյուր դաշտ ընտրովի է։ `capabilities`-ը և `exclude`-ը ընդունում են զանգված կամ ստորակետերով
բաժանված տող, իսկ `max_output`-ը համեմատվում է `max_output_tokens`-ի հետ։ Արդյունքները դասավորվում են
ըստ `owned_by`-ի, ապա՝ ըստ `id`-ի։ `limit`-ի լռելյայն արժեքը `20` է, իսկ `100`-ից մեծ արժեքները
սահմանափակվում են `100`-ով։ Անվավեր JSON-ը, անհայտ դաշտը կամ անվավեր արժեքը վերադարձնում է HTTP `400`։

### Առանձին թաքցված չաթի մոդելներ

Մատակարարի էջում **Թաքնված** նշված մոդելը բացառվում է կատալոգից և բացահայտ հարցման դեպքում
մերժվում է HTTP `404` / `model_not_found`-ով։ Ստուգումն օգտագործում է լուծված մատակարարն ու մոդելը՝
ներառյալ մատակարարի այլանունները, համատեղելի մատակարարի հանգույցների նախածանցները և կապի
լռելյայն արժեքները։ Կոմբոն բաց է թողնում թաքցված թիրախները և կարող է օգտագործել տեսանելի
հարակից մոդել։ Երբ այլևս գործարկելի թիրախ չի մնում, այն վերադարձնում է նույն սխալի կոդը։
Թաքցումը հանելու փոփոխությունն ուժի մեջ է մտնում հաջորդ հարցման ժամանակ։ Միայն պատկերների
տեսանելիության վերասահմանումները չեն թաքցնում նույն ID-ով չաթի մոդելը։

Այս առանձին մոդելի կարգավորումը տարբեր է
[մոդելների ցուցադրման թույլատրման/արգելման ցուցակներից](../routing/MODEL_EXPOSURE_LIST.md), որոնք զտում են կատալոգում
գովազդումը և ավտոմատ երթուղավորման թեկնածուներին՝ միաժամանակ պահպանելով բացահայտ ուղղորդումը։
API բանալու մոդելի թույլտվությունները շարունակում են կիրառվել անկախ կերպով։ Կատալոգի նախածանցի
լռելյայն ռեժիմը շարունակում է մնալ `dual`։

### Առանց մտածողության մոդելի տարբերակներ

Մտածողության հնարավորություն ունեցող Claude մոդելների համար `/v1/models`-ը նաև հայտարարում է
**առանց մտածողության** տարբերակ, որի ID-ն ունի `claude-3-omniroute-no-thinking/` նախածանցը՝

```
claude-3-omniroute-no-thinking/<provider>/<model>
```

Այս ID-ի ընտրությունը (օրինակ՝ Claude Code-ի կազմաձևում, որը միշտ կցում է `thinking` բլոկ)
լուծվում է դեպի իրական `<provider>/<model>`՝ ճնշված տրամաբանմամբ՝ `/v1/messages` ուղու վրա
`thinking:{type:"disabled"}` կամ `/v1/chat/completions` ուղու վրա `reasoning`/`reasoning_effort`
դաշտերը հեռացվում են։ Տարբերակը ցուցակագրվում է միայն մտածողությանն աջակցող **և**
`disabled`-ը ընդունող Claude ընտանիքի մոդելների համար (այսինքն՝ օրինակ միայն հարմարվող մոդելները,
որոնք մերժում են `disabled`-ը, բացառվում են)։ Օպերատորները կարող են յուրաքանչյուր մոդելի համար
ստիպողաբար միացնել կամ անջատել տարբերակը `ModelSpec.noThinkingAlias`-ի միջոցով։

---

## Provider Plugin Manifest

```bash
GET /api/v1/provider-plugin-manifest
```

Վերադարձնում է Bifrost-ի, CLIProxyAPI-ի և ապագա sidecar երթուղիչների կողմից օգտագործվող JSON-անվտանգ provider plugin manifest-ը։ Պատասխանը գեներացվում է TypeScript provider registry-ից և միտումնավոր չի ներառում OAuth client secrets-ը, runtime environment resolution-ը, executor functions-ը, request headers-ը և account data-ն։

Օգտագործեք այս endpoint-ը, երբ sidecar-ն աշխատում է առանձին գործընթացում և չի կարող ուղղակիորեն ներմուծել
`open-sse/config/providerPluginManifestRegistry.ts`-ը։

---

## ElevenLabs աուդիոյի գեներացում

Կարգավորեք `elevenlabs` provider connection-ը OmniRoute-ում՝ ձեր ElevenLabs API key-ով։
Հաճախորդները նույնականացվում են իրենց **OmniRoute** key-ով (`Authorization: Bearer $OMNIROUTE_API_KEY`);
gateway-ը պահված provider key-ը փոխանցում է որպես `xi-api-key`։ Երբեք ElevenLabs key-ը մի ուղարկեք որպես gateway bearer token։

| Մեթոդ | Ուղի                        | Պատասխան                                    | API key endpoint category |
| ----- | --------------------------- | ------------------------------------------- | ------------------------- |
| POST  | `/v1/sound-generation`      | Native աուդիո բայթեր                        | `elevenlabs`              |
| POST  | `/v1/music`                 | Native աուդիո բայթեր                        | `music`                   |
| POST  | `/v1/music/stream`          | Հոսքային աուդիո բայթեր                      | `music`                   |
| POST  | `/v1/music/detailed`        | Native multipart աուդիո և կոմպոզիցիայի պլան | `music`                   |
| POST  | `/v1/music/detailed/stream` | Native SSE մետատվյալներ և աուդիո հատվածներ  | `music`                   |
| POST  | `/v1/music/plan`            | JSON կոմպոզիցիայի պլան                      | `music`                   |

Այս endpoint-ները լրացնում են առկա `/v1/audio/speech`, `/v1/audio/transcriptions`,
`/v1/voices`, `/v1/text-to-speech/{voiceId}` և `/v1/speech-to-text` երթուղիները։ Native JSON դաշտերը
և query պարամետրերը, օրինակ՝ `output_format`-ը և `enable_logging`-ը, պահպանվում են։
`/v1/music/detailed`-ի պատասխանները պահպանում են իրենց multipart սահմանազատիչները․ վերլուծեք դրանք որպես multipart։
`/v1/music/detailed/stream`-ը վերադարձնում է `text/event-stream`՝ SSE իրադարձություններում կոմպոզիցիայի մետատվյալներով
և base64 աուդիո հատվածներով։ Բոլոր վեց երթուղիներն աջակցում են CORS preflight-ին։

```bash
export OMNIROUTE_BASE_URL="http://localhost:20128"
export OMNIROUTE_API_KEY="your-omniroute-api-key"

# Կարճ ձայնային էֆեկտ։ Տևողությունը՝ 0.5-ից 30 վայրկյան։
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/sound-generation?output_format=mp3_44100_128" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"A single soft bell chime","duration_seconds":1,"model_id":"eleven_text_to_sound_v2"}' \
  --output effect.mp3

# Երաժշտության տևողությունն արտահայտվում է միլիվայրկյաններով՝ 3000-ից 600000։
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music?output_format=mp3_44100_128" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Gentle instrumental piano","music_length_ms":10000,"force_instrumental":true,"model_id":"music_v1"}' \
  --output music.mp3
```

Օգտագործեք `/v1/music/stream`-ը նույն JSON body-ով՝ աուդիոն աստիճանաբար փոխանցելու համար։ Կոմպոզիցիան ընդունում է
ճիշտ մեկ տարբերակ՝ `prompt` կամ `composition_plan`․ `/v1/music/plan`-ը պահանջում է `prompt`
և ըստ ցանկության ընդունում է `source_composition_plan`։ Native սխեմաները պահպանում են լրացուցիչ
provider դաշտերը, որպեսզի կոմպոզիցիայի պլանի տարբերակներն ու fine-tuning-ի ընտրանքները հասնեն ElevenLabs-ին։

Միավորված `/v1/music/generations` endpoint-ը նույնպես ընդունում է
`elevenlabs/music_v1`, `elevenlabs/music_v2` և `elevenlabs/music_v2_5`։ Ակտիվ ElevenLabs connection-ի դեպքում
այս մոդելները հասանելի են music catalog-ում։ Այս endpoint-ը վերադարձնում է
`{"created":...,"data":[{"b64_json":"...","format":"mp3"}]}`։ Դրա `duration` դաշտը վայրկյաններով է
և համապատասխանեցվում է `music_length_ms`-ին․ բացահայտ նշված `music_length_ms`-ը գերակայում է։
`instrumental`-ը համապատասխանեցվում է `force_instrumental`-ին, իսկ native դաշտը գերակայում է։
Հոսքային փոխանցման համար օգտագործեք native streaming endpoint-ները, իսկ միայն composition plan-ով
կառավարվող հարցումների համար՝ native composition endpoint-ը։

```bash
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music/generations" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs/music_v1","prompt":"Gentle instrumental piano","duration":10,"instrumental":true}'
```

Endpoint-ի, մոդելի, բյուջեի և connection-ի սահմանափակումները կիրառվում են նախքան upstream call-ը։
Native երթուղիները վերադարձնում են upstream-ի status code-երն ու error body-ները անփոփոխ, ներառյալ
`402`-ը՝ plan restriction-ի, և `429`-ը՝ quota limit-ի դեպքում։ `character-cost`, `song-id`, `request-id` և `retry-after`
header-ները պահպանվում են, երբ առկա են։ Անվճար credit balance-ը չի երաշխավորում հասանելիություն յուրաքանչյուր
music model-ի, output format-ի կամ API feature-ի համար․ ElevenLabs-ը յուրաքանչյուր հարցման համար որոշում է entitlement-ը։
Միավորված endpoint-ը պահպանում է error status code-երը OmniRoute-ի normalized error envelope-ում։

Upstream contracts՝ [sound effects](https://elevenlabs.io/docs/api-reference/text-to-sound-effects/convert),
[music composition](https://elevenlabs.io/docs/api-reference/music/compose) և
[streaming music details](https://elevenlabs.io/docs/api-reference/music/compose-detailed-stream)։

---

## Համատեղելիության վերջնակետեր

| Մեթոդ | Ուղի                                      | Ձևաչափ                                       |
| ----- | ----------------------------------------- | -------------------------------------------- |
| 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 (խմբագրում/inpaint)            |
| POST  | `/v1/videos/generations`                  | OpenAI-ի ոճով տեսանյութերի գեներացում        |
| POST  | `/v1/music/generations`                   | OpenAI-ի ոճով երաժշտության գեներացում        |
| POST  | `/v1/audio/transcriptions`                | OpenAI Audio (STT)                           |
| POST  | `/v1/audio/speech`                        | OpenAI TTS (վերադարձնում է աուդիոյի մարմինը) |
| POST  | `/v1/rerank`                              | Cohere/Voyage-ի ոճով վերադասավորում          |
| POST  | `/v1/classify`                            | Jina-ի դասակարգում (`api.jina.ai`)           |
| POST  | `/v1/segment`                             | Jina-ի սեգմենտավորիչ (`segment.jina.ai`)     |
| POST  | `/v1/moderations`                         | OpenAI Moderations                           |
| GET   | `/v1/models`                              | OpenAI                                       |
| POST  | `/v1/models/query`                        | Զտված մոդելների կարճ ցուցակ                  |
| POST  | `/v1/messages/count_tokens`               | Anthropic                                    |
| GET   | `/v1beta/models`                          | Gemini                                       |
| POST  | `/v1beta/models/{...path}`                | Gemini generateContent                       |
| POST  | `/v1/api/chat`                            | Ollama                                       |
| GET   | `/api/v1/vscode/{token}/`                 | OpenAI-ի կատալոգի այլանուն                   |
| GET   | `/api/v1/vscode/{token}/models`           | OpenAI-ի մոդելների այլանուն                  |
| POST  | `/api/v1/vscode/{token}/chat/completions` | OpenAI-ի թոքենիզացված այլանուն               |
| POST  | `/api/v1/vscode/{token}/responses`        | OpenAI Responses-ի թոքենիզացված այլանուն     |
| POST  | `/api/v1/vscode/{token}/api/chat`         | Ollama-ի թոքենիզացված այլանուն               |
| GET   | `/api/v1/vscode/{token}/api/tags`         | Ollama-ի թոքենիզացված թեգերի այլանուն        |

Բոլոր POST երթուղիները հետևում են նույն կառուցվածքին՝ `Bearer your-api-key` + Zod-ով վավերացված JSON մարմին (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` և այլն, տես `src/shared/validation/schemas.ts`)։ Սխեմայի ձախողման դեպքում վերադարձվում է 4xx։

Այն հաճախորդների համար, որոնք չեն կարող կցել `Authorization: Bearer ...`, OmniRoute-ը նաև ընդունում է API բանալիներ URL-ում՝ կամ հարցման տողի համատեղելիության միջոցով (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`), կամ ստորև փաստագրված հատուկ `/api/v1/vscode/{token}/...` վերջնակետերի միջոցով։

```bash
# Վերադասավորում (ամպային ռեեստրի մատակարար կամ OpenAI-ի հետ համատեղելի մատակարարի հանգույց՝ որպես "<prefix>/<model>")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina-ի դասակարգում (Foundation API-ի հավատարմագրեր)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina-ի սեգմենտավորիչ
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina-ի որոնում (s.jina.ai, մատակարարների այլանուններ՝ jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Մոդերացիաներ
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — վերադարձնում է audio/mpeg (կամ պահանջված ձևաչափի) մարմին
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Soniox TTS-ի համար պահանջվում են լեզու և ձայն. `language`-ի լռելյայն արժեքը "en" է. բացակայող
# ձայնը կամ OpenAI-ի ստանդարտ ձայնի անունը (alloy, nova, …) դառնում է "Adrian"
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }

# Պատկերի խմբագրում (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Տեսանյութերի / երաժշտության գեներացում (մատակարարի նախածանցով մոդելի նույնացուցիչ)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }
```

> **Վերադասակարգման մատակարարի հանգույցներ․** `POST /v1/rerank`-ը նաև ուղղորդվում է OpenAI-ին համատեղելի մատակարարի հանգույցներին
> (oMLX, vLLM, Infinity, TEI՝ gateway-ի հետևում, …), որոնց հասցեները տրված են `<node-prefix>/<model>` ձևաչափով։ Loopback
> հանգույցները (`localhost`, `127.0.0.1`, `172.16.0.0/12`) միշտ թույլատրելի են, ինչպես նաև այն հոսթանունները, որոնք
> օպերատորը նշում է `OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS`-ում (օրինակ՝ Docker/Compose ծառայության անունը, ինչպես
> `http://reranker:8080/v1`․ այս հանգույցներին դիմում է անմիջականորեն՝ երբեք ոչ `HTTP(S)_PROXY`-ի, ոչ էլ
> միացման ամրակցված պրոքսիի միջոցով)։ Ցանկացած այլ
> հոսթում գտնվող հանգույցները՝ LAN-ի համակարգիչ կամ Tailscale-ի գործընկեր, թույլատրելի են միայն այն դեպքում, երբ օպերատորը միացնում է
> `RERANK_REMOTE_PROVIDER_NODES` ֆունկցիայի դրոշը **և** հանգույցի բազային URL-ը անցնում է մատակարարի ելքային URL-ի քաղաքականությունը
> (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`)։ Հիշողության շարժիչի վերադասակարգման
> քայլը այս երթուղին կանչում է loopback-ի միջոցով, ուստի նույն կանոնը կիրառվում է Memory-ի կարգավորումներում գտնվող
> `rerankProviderModel`-ի նկատմամբ։
>
> **Տեղական սերվերի ձևաչափեր․** հանգույցը կանչվում է `<base>/v1/rerank` հասցեով, իսկ 404-ի դեպքում՝ `<base>/rerank`
> հասցեով (Infinity, TEI)։ Upstream-ի մարմինը պարունակում է ինչպես Cohere/OpenAI-ի ձևակերպումները
> (`documents`, `return_documents`), այնպես էլ TEI-ի ձևակերպումները (`texts`, `return_text`), իսկ upstream-ի պատասխանը
> նորմալացվում է Cohere-ի envelope-ի՝ TEI-ի առանց լրացուցիչ փաթեթավորման `[{index, score, text}]`, բարակ gateway-ներից ստացվող
> `{results: [{index, score}]}` և Voyage-ի ոճի `{data: [...]}` պատասխանները հաճախորդին վերադարձվում են որպես
> `{results: [{index, relevance_score, document?}]}`՝ դասավորված ըստ գնահատականի և սահմանափակված `top_n`-ով։

> **Մատակարարի հանգույցների հայտնաբերում․** OpenAI-ին համատեղելի մատակարարի հանգույցի մոդելները հայտնվում են `GET /v1/models`-ում՝
> հանգույցի նախածանցի ներքո։ Endpoint-ի մետատվյալներ չպարունակող տողերը (ինչը բնորոշ է տեղական `/v1/models` ցուցակներին)
> ժառանգում են հանգույցի `apiType`-ը, ուստի `embeddings` հանգույցի մոդելներն ունեն `type: "embedding"`, իսկ
> `rerank` հանգույցի մոդելները՝ `type: "rerank"`, այլ ոչ թե լռելյայն ստանում են chat տեսակը․ սակայն համաժամեցված կամ ձեռքով ավելացված
> տողի բացահայտ `supportedEndpoints`-ը շարունակում է գերակայել։

### Նվիրված մատակարարի երթուղիներ

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

Մատակարարի նախածանցը ավտոմատ ավելացվում է, եթե բացակայում է։ Չհամապատասխանող մոդելները վերադարձնում են `400`։

---

## Ֆայլերի API

OpenAI-ի հետ համատեղելի ֆայլերի վերջնակետ՝ փաթեթային մուտքի/ելքի և ֆայլի նպատակի համար վերբեռնումների համար։

| Մեթոդ  | Ճանապարհ                 | Նկարագրություն                                                                                                           |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| POST   | `/v1/files`              | Վերբեռնել ֆայլ (multipart՝ `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — առավելագույնը 512 MiB |
| GET    | `/v1/files`              | Ցուցադրել նույնականացված API բանալու համար նախատեսված ֆայլերը                                                            |
| GET    | `/v1/files/[id]`         | Ստանալ ֆայլի մետատվյալները                                                                                               |
| DELETE | `/v1/files/[id]`         | Ջնջել ֆայլը                                                                                                              |
| GET    | `/v1/files/[id]/content` | Հոսքով վերադարձնել ֆայլի սկզբնական բովանդակությունը                                                                      |

**Նույնականացում․** Bearer API բանալի — ֆայլերը սահմանափակվում են ըստ API բանալու՝ `getApiKeyRequestScope`-ի միջոցով։ Բանալին
տեսնում, ներբեռնում և ջնջում է միայն իր սեփական ֆայլերը, իսկ առանց բանալու dashboard-ի նիստը կարդում է
ամբողջ օրինակը։ Սեփականատեր չունեցող ֆայլը (անանուն կամ dashboard-ի նիստի միջոցով վերբեռնված) մերժվում է
նիստ չօգտագործող յուրաքանչյուր կանչողին։ `GET /v1/files`-ը անանուն կանչողին, ինչպես նաև ներկայացված բանալուն, որը
չի հաջողվում նույնականացնել, վերադարձնում է `401`, նույնիսկ երբ `REQUIRE_API_KEY=false` է՝ բոլոր վարձակալների
ֆայլերը ցուցադրելու փոխարեն (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523)։

---

## Փաթեթների API

OpenAI-ի հետ համատեղելի փաթեթային մշակում։

| Մեթոդ  | Ճանապարհ                  | Նկարագրություն                                                                                                           |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| POST   | `/v1/batches`             | Ստեղծել փաթեթ — մարմինը վավերացվում է `v1BatchCreateSchema`-ի միջոցով (`input_file_id`, `endpoint`, `completion_window`) |
| GET    | `/v1/batches`             | Ցուցադրել փաթեթները                                                                                                      |
| GET    | `/v1/batches/[id]`        | Ստանալ փաթեթի կարգավիճակը և `request_counts`-ը                                                                           |
| DELETE | `/v1/batches/[id]`        | Ջնջել ավարտված/ձախողված փաթեթը                                                                                           |
| POST   | `/v1/batches/[id]/cancel` | Չեղարկել ընթացքի մեջ գտնվող փաթեթը                                                                                       |

**Նույնականացում․** Bearer API բանալի։ Փաթեթները սահմանափակվում են ըստ API բանալու՝ ֆայլերի համար կիրառվող նույն երեքակողմ կանոնի համաձայն․ միայն սեփական բանալին, dashboard-ի նիստը՝ ամբողջ օրինակի մակարդակով, իսկ սեփականատեր չունեցող գրառումները մերժվում են նիստ չօգտագործող յուրաքանչյուր կանչողին (ստացման, ջնջման, չեղարկման և ստեղծման ժամանակ `input_file_id`-ի ստուգման դեպքում)։
`GET /v1/batches`-ը անանուն կանչողին վերադարձնում է `401`, նույնիսկ երբ `REQUIRE_API_KEY=false` է։

---

## Որոնել API

Web/search մատակարարի աբստրակցիա (Tavily, Brave, Exa, Serper և այլն):

| Մեթոդ | Ճանապարհ               | Նկարագրություն                                                                                        |
| ----- | ---------------------- | ----------------------------------------------------------------------------------------------------- |
| GET   | `/v1/search`           | Ցուցակեք կազմաձևված որոնման մատակարարների + հնարավորությունները                                       |
| POST  | `/v1/search`           | Գործարկեք որոնման հարցում — մարմինը վավերացված `v1SearchSchema` կողմից, աջակցում է caching/coalescing |
| GET   | `/v1/search/analytics` | Յուրաքանչյուր մատակարարի hit/latency/cache վիճակագրություն                                            |

**Auth:** Կրող API բանալի (`extractApiKey` + `isValidApiKey`). Որոնման քաղաքականությունն իրականացվում է `enforceApiKeyPolicy` միջոցով:

**Ավտոմատ ընտրություն.** առանց `provider`, սկզբում աշխատում է կազմաձևված կապով ամենաէժան մատակարարը, իսկ հաջորդ ամենաէժանը ձախողումն է: Անվճար վերջին միջոցի մատակարարները (`duckduckgo-free`) օգտագործվում են միայն այն դեպքում, երբ այլ բան կազմաձևված չէ: Ինքնահոսթավորված SearXNG հաշվվում է որպես կազմաձև, երբ նրա կապը պահում է իրական `baseUrl` (ոչ թե կատալոգի լռելյայն `http://localhost:8888/search` `baseUrl` : այն այնուհետև դասվում է որպես $0 պրովայդեր ստեղնավորվածներից առաջ, իսկ ամենաէժան ստեղնավորված մատակարարը որպես ձախողում, ներառյալ, երբ SearXNG պատասխանում է 400, 401, 403 կամ 401 `http(s)` URL : ամպային մետատվյալների հասցեն չի հաշվվում: SearXNG կապը, որը պահում է նշան, դասվում է այս կերպ միայն `https://` կամ loopback `http://` վրա: Հեռավոր պարզ `http://` միջոցով այն երբեք ձախողում է և մնում է որպես վերջին միջոց, որն օգտագործվում է միայն այն ժամանակ, երբ որևէ այլ մատակարար չկա կազմաձևված կամ երբ պահանջվում է անունով, ուստի այն ուղարկում է նշանը հստակ տեքստով այդ երկու դեպքերում:

### Exa եւ Tavily `provider_options`

Exa-ն և Tavily-ը կարդում են մատակարարի համար նախատեսված դաշտերը անունների տարածության պայուսակից՝ `provider_options.exa` (կամ `provider_options["exa-search"]`) և `provider_options.tavily` (կամ `provider_options["tavily-search"]`): Միայն ստորև նշված ստեղները փոխանցվում են: Յուրաքանչյուրը ստուգվում է `open-sse/handlers/search/providerOptionsPassthrough.ts` ում իր սեփական Zod սխեմայի համեմատ, և սխալ տիպով բանալին բաց է թողնվում: Ցանկացած այլ բանալի անտեսվում է, այդ թվում՝ auth, base URL, `stream` և `outputSchema`: Այլ պրովայդերների կողմից օգտագործվող հարթ ստեղները (`cx`, `depth`, ...) աշխատում են ինչպես նախկինում:

| Մատակարար | Բարձր մակարդակի դաշտեր                                                                                                                                                                                                                                                                                                                                                    | Բնադրված                                                                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Exa       | `type`, `category`, `userLocation`, `moderation`, `additionalQueries`, `objective`, `systemPrompt`, `compliance` (հարթ պարզունակներ), `startPublishedDate`, `endPublishedDate`                                                                                                                                                                                            | `contents.{text, highlights, summary, extras, livecrawlTimeout, maxAgeHours}` միավորվել է լռելյայն `{ text: true, highlights: true }` վրա |
| Թավիլի    | `search_depth`, `chunks_per_source`, `time_range`, `start_date`, `end_date`, `include_published_date`, `filter_by_published_date`, `include_answer`, `include_raw_content`, `include_images`, `include_image_descriptions`, `include_favicon`, `include_domains_mode`, `language`, `filter_by_language`, `auto_parameters`, `exact_match`, `include_usage`, `safe_search` | —                                                                                                                                         |

Միշտ հաղթում են ընդհանուր դաշտերը՝ `query`, `max_results`, `filters` (տիրույթներ), `country` և `search_type` ից ստացված թեման։ Exa-ում `search_type: "news"` պահպանում է `category: "news"`: Տավիլը նույնպես ընդունում է `search_type: "finance"` (`topic: "finance"`)։

Firecrawl որոնման արժեքը գրանցվում է 10 վերադարձված արդյունքների մեկնարկած բլոկի համար՝ $0,002 (2 վարկ) մեկ բլոկ և առնվազն մեկ բլոկ մեկ զանգի համար ( [Firecrawl billing](https://docs.firecrawl.dev/billing) ): 11 արդյունք արժե $0,004:

Ընդհանուր `time_range` այժմ հասնում է երկու մատակարարներին. Exa-ն ստանում է `startPublishedDate` (ISO ժամադրոշմ) և Tavily-ն ստանում է `start_date` (`YYYY-MM-DD`): `provider_options` ում հստակ ամսաթիվը գերակայում է քարտեզագրվածին:

Exa արդյունքները պահպանում են `id`, `highlights` (յուրաքանչյուր կարևոր կետ, ոչ միայն առաջինը, որն օգտագործվում է որպես `snippet`), `highlight_scores`, `summary`, `subpages`, `entities` և `extras` `provider_raw` ում: Tavily արդյունքները պահպանում են `images` և `favicon`:

Linkup որոնման արժեքը գրանցվում է $0,005 `depth` `fast` և `standard` համար և $0,05-ի համար `deep` համար ( [Linkup pricing](https://docs.linkup.so/pages/documentation/development/pricing) ), անկախ նրանից `depth` գալիս է `provider_options` ից կամ կապի կարգավորումներից:

Exa `type: "lite"` (Exa 3.0) ընդունում է դաշտերի ավելի փոքր շարք և մերժում է ամբողջ հարցումը, երբ որևէ այլ դաշտ է սահմանված: Lite-ի համար `additionalQueries`, `systemPrompt` և բոլոր `contents` ստեղները, բացի `text` և `highlights` հանվում են զանգից առաջ: Հնացած `subpages`, `subpageTarget`, `highlights.numSentences` և `highlights.highlightsPerUrl` այլևս չեն փոխանցվում:

Ծախսերի հաշվառումը `costPerQuery` հարթ գրանցամատյանն `instant`, բացառությամբ Exa- `auto`, որը հետևում `fast` `lite` ի սեփական գնին. $0,001 յուրաքանչյուր հետագա արդյունքի համար; և $0,001 մեկ վերադարձված արդյունքի համար, երբ `contents.summary` սահմանվում է: Tavily-ն գրանցվում է 1 կրեդիտով ($0,008) `search_depth` `basic`, `fast` և `ultra-fast` համար, իսկ 2 վարկ (0,016$) `advanced` համար ( [Tavily API վարկեր](https://docs.tavily.com/documentation/api-credits) ): `auto_parameters: true` ով զանգը, որը Tavily-ն թարմացնում է առաջադեմի, դեռ գրանցվում է 1 կրեդիտով:

---

## Web Fetch API

URL-ից բովանդակություն է հանում կարգավորված վեբ-հայտնման մատակարարի միջոցով (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract)։

Parallel Extract-ը (`parallel-search`, նույն API key-ով, ինչ Parallel Search-ը) վերադարձնում է միայն Markdown
— ցանկացած այլ `format` արժեք հանգեցնում է `400`-ի — և բովանդակությունը սահմանափակում է 100,000 նիշով։ Երբ
թիրախային էջն ինքնին հնարավոր չէ հանել, upstream-ը դա հաղորդում է HTTP 200-ի ներսում․ OmniRoute-ը դա
մակերես է հանում որպես `422`՝ ֆիքսված հաղորդագրությամբ։

| Method | Path            | Description                                                                  |
| ------ | --------------- | ---------------------------------------------------------------------------- |
| POST   | `/v1/web/fetch` | URL-ի ստացում/սկրեյփինգ — մարմինը վավերացվում է `v1WebFetchSchema`-ի միջոցով |

**Auth:** Bearer API key (`extractApiKey` + `isValidApiKey`)։ Քաղաքականությունը կիրառվում է `enforceApiKeyPolicy`-ի միջոցով։

**Quota-aware fallback (#8297):** երբ բացահայտ `provider` նշված չէ, pool-ը
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search` →
`parallel-search`) շրջանցվում է հաստատուն առաջնահերթության կարգով (fill-first) — rate limit-ով, բայց
կարգավորված մատակարարը բաց է թողնվում՝ հարցումը կարճ միացնելու փոխարեն, իսկ կրկնափորձելի/quota upstream
խափանումը (HTTP 429-ը միշտ, Firecrawl/Tavily/TinyFish quota-անման անվճար մակարդակների համար՝ 402/403 —
ոչ Jina Reader-ի համար, և երբեք՝ սովորական 400 սխալ հարցման համար) հարցման պահին փոխանցվում է հաջորդ՝
դեռ չփորձված, հավատարմագրված մատակարարին։ Երբ pool-ի բոլոր մատակարարները սպառված են, endpoint-ը նախորդ
ընդհանուր `400`-ի փոխարեն վերադարձնում է մեկ `429`՝ `Retry-After` վերնագրով։ Երբ բացահայտ `provider` է
պահանջվում, լուռ fallback **չկա** — rate limit-ով կամ ձախողված բացահայտ մատակարարն արտածում է իր սեփական
սխալը (`429`, եթե rate limit է, հակառակ դեպքում՝ upstream կարգավիճակը)։

---

## WebSocket Streaming

```bash
GET /v1/ws?handshake=1
```

Վավերացնում է WebSocket upgrade handshake-ը և վերադարձնում wire protocol-ի օրինակային հաղորդագրությունները (`request`, `cancel`)։ Փաստացի WS frame-երը մշակվում են ներառված WS server-ի կողմից՝ Next.js route table-ից դուրս։

**Auth:** Bearer API key handshake-ի ընթացքում։

### Responses API over WebSocket (միայն codex)

```bash
# Նույն host:port-ը, ինչ HTTP API-ի համար (կանխադրված՝ 20128)․ թարմացրեք կապը՝
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (կամ՝ -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Առաջին frame-ը ՊԱՐՏԱԴԻՐ պետք է լինի response.create-ը՝
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```

Responses-API-over-WebSocket proxy-ն միացված է **բացառապես `codex`-ին** (ChatGPT backend)։ Այն լսում է API-ի/dashboard-ի նույն port-ի վրա՝ `/v1/responses`, `/responses` և `/api/v1/responses` ուղիներով։ Առաջին `response.create` frame-ի ժամանակ այն վավերացնում և նախապատրաստում է կապը ներքին `codex-responses-ws` bridge-ի միջոցով, ընտրում է codex OAuth կապ և `wreq-js` transport-ի միջոցով թունելավորում դեպի `wss://chatgpt.com/backend-api/codex/responses`։ **Ոչ codex մոդելները մերժվում են** (`codex_ws_provider_required`)։ Quota-share routing-ի համար օգտագործեք `model: "qtSd/<group>/codex/<model>"`։ Իրականացված է `app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`-ում։

**Auth:** Bearer API key handshake-ի ընթացքում։ Ներառված HTTP server-ը (`server-ws.mjs`) պետք է լինի ակտիվ entrypoint-ը (կանխադրված՝ այդպես է, երբ `app/server-ws.mjs`-ը գոյություն ունի)։

#### Model id: օգտագործեք ChatGPT-ի մերկ id-ն (առանց `codex/` prefix-ի)

OpenAI-ի **Codex CLI**-ն client-side վավերացնում է մոդելի անունը, երբ
`supports_websockets = true`, և մերժում է provider-prefixed id-երը, օրինակ՝
`codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`)։ Ուղարկեք **մերկ** id-ն (օրինակ՝ `gpt-5.5`)։ OmniRoute-ի bridge-ը միայն
codex-ի համար է, ուստի թունելավորումից առաջ մերկ id-ն կրկին լուծում է որպես codex մոդել
(`resolveCodexWsModelInfo`) — չնայած նրան, որ մերկ `gpt-5.5`-ը HTTP-ի միջոցով այլապես
կուղղորդվեր մեկ այլ մատակարարի։

#### OpenAI Codex CLI-ի կարգավորում

Codex CLI-ն ուղղեք OmniRoute-ին՝ `~/.codex/config.toml`-ում WebSocket
աջակցությամբ custom provider ավելացնելով (օգտագործեք առանձին `CODEX_HOME`, որպեսզի առկա կարգավորումները չփոփոխվեն)։

```toml
model = "gpt-5.5"                 # մերկ id — ՈՉ "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # առանց վերջում slash-ի․ WS URL-ը ստացվում է սրանից (production-ում օգտագործեք https/wss)
wire_api = "responses"                    # միակ աջակցվող արժեքը 2026 թվականի փետրվարից
supports_websockets = true                # միացնում է Responses-over-WS transport-ը
env_key = "OMNIROUTE_API_KEY"             # պարունակում է OmniRoute API key-ը (Bearer)
```

```bash
export OMNIROUTE_API_KEY=sk-...           # OmniRoute API key (ցանկացած key, եթե REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```

CLI-ն `base_url + /responses`-ը թարմացնում է WebSocket-ի և OmniRoute-ը այն թունելավորում է դեպի
ընտրված codex OAuth կապը։ End-to-end վավերացվել է տեղային server-ի դեմ․ ChatGPT-ը վերադարձնում է
`codex.rate_limits` + `response.created` և հոսքային կերպով փոխանցում ավարտը։

---

## Քվոտաների և խնդիրների հաղորդում

| Method | Path                | Description                                                                                               |
| ------ | ------------------- | --------------------------------------------------------------------------------------------------------- |
| GET    | `/v1/quotas/check`  | Նախապես վավերացնել քվոտան `provider` + `accountId` զույգի համար՝ նախքան գրանցված բանալի տրամադրելը        |
| POST   | `/v1/issues/report` | Քվոտայի/բանալիի տրամադրման ձախողման մասին հաղորդել GitHub-ին (պահանջվում են `GITHUB_ISSUES_REPO` + token) |

**Auth:** Bearer API key (`isAuthenticated`)։

### Քվոտայի սեսիայի վերականգնում (միացման դեպքում)

Չհոսքային `POST /v1/chat/completions` կամ `POST /v1/responses` հարցումը, որը ձախողվում է
վերջնական քվոտայի սխալով (`402`/`429`/`503`, որի մարմինը նշում է, որ քվոտան կամ կրեդիտները սպառվել են),
կարող է պահվել և հետագայում կրկին կատարվել՝ սխալը վերադարձնելու փոխարեն։ Կանչողը միացնում է այս
հնարավորությունը յուրաքանչյուր հարցման համար՝ երեք վերնագրերով.

| Header                       | Value                                          |
| ---------------------------- | ---------------------------------------------- |
| `x-omniroute-quota-recovery` | `auto`                                         |
| `x-omniroute-session`        | սեսիայի ID, `[A-Za-z0-9._:-]{1,128}`           |
| `x-omniroute-recovery-turn`  | սեսիայի ներսում եզակի շրջանի ID (նույն կանոնը) |

Միայն `stream: false` շրջադարձերն են իրավասու, եթե չկան գործիքներ, գործիքների պատմություն կամ
`previous_response_id`, և չկա `x-omniroute-connection` կապում, իսկ `STORAGE_ENCRYPTION_KEY`-ը պետք է
սահմանված լինի (հարցումը պահվում է կոդավորված վիճակում մինչև 24 ժամ)։ Այնուհետև պատասխանը լինում է
`202`՝ `recovery.poll`-ով։ Հարցումը ստուգեք `GET /v1/quota-recoveries/{id}`-ով (`202`՝ քանի դեռ
ընթացքի մեջ է, `200`՝ ավարտվելուց հետո վերականգնված մարմնով) կամ չեղարկեք `DELETE`-ով։ Տոմսերը
տեսանելի են միայն դրանք ստեղծած API բանալուն։ Եթե կրկնակի կատարման արդյունքն անորոշ է, այն ավարտվում է
`needs_confirmation` վիճակով՝ նույն հարցումը երկու անգամ չուղարկելու փոխարեն։ Աղբյուրը՝
`src/lib/quota/quotaSessionRecovery.ts`։

---

## Ինքնասպասարկման օգտագործում (`/api/usage/om-usage`)

Ցանկացած API ստեղն կարող է կարդալ** իր սեփականը** օգտագործման և քվոտաների — ոչ կառավարման հեղինակություն. Սա այն վերջնակետն է, որն օգտագործում է հաճախորդը (CLI, OmniCopilot վահանակ)՝ բանալիատիրոջը ցույց տալու իրենց ծախսերը:

```bash
# Text form (the historical contract — plain text for a terminal)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Structured form — what a UI consumes
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"
```

Բանալին պետք է ունենա**`allowUsageCommand`** միացված է (կանխադրաբար անջատված է — վահանակի API-ստեղների կառավարիչը փոխում է այն յուրաքանչյուր բանալիով): Առանց դրա վերջնակետը պատասխանում է `403`:

`?format=json` վերադարձնում է խտրական ձև, այնպես որ զանգահարողը երբեք չի կարդում տվյալների դաշտը մերժումից հետո: Հաջողության մասին.

```jsonc
{
  "allowed": true,
  // present only when the key opted into per-key usage limits (daily/weekly/5-hour USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // the selected provider quota snapshot, or null when nothing is cached yet:
  "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */} },
  // every connection's snapshot, so a UI can render several providers side by side:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}
```

Մերժման դեպքում (`401` վատ ստեղնը / `403` չի թույլատրվում) նույն երթուղին վերադարձնում է `{ "allowed": false, "error": { "message": "…" } }` — ներկա, բայց դատարկ `personal`/`provider` (բանալին թույլատրված է, դեռ ոչինչ չի սովորել) տարբերվում է մերժումից, և միայն JSON ձևն է տարբերակում դրանք:

**Auth:** զանգահարողի սեփական կրող API ստեղնը, վավերացված `isValidApiKey` — ով, սա _ոչ_ կառավարման մակերեսն է (`/api/keys/…`), որը մնում է `requireManagementAuth` հետևում:

### Հումք ընդդեմ Cutoff- ճշգրտված քվոտայի տոկոսների

`/api/usage/om-usage` օգտագործելիս զանգահարողները պետք է ուշադրություն դարձնեն այն տոկոսների միջև, որոնք ներկայացված են** պարզ տեքստային ելք** և կառուցվածքային**JSON ելք** :

| Ասպեկտ               | Պարզ տեքստի ձևաչափ (`/api/usage/om-usage` / `@@om-usage`)                                                    | JSON ձևաչափ (`?format=json`)                                                |
| :------------------- | :----------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- |
| **Արդյունք դաշտ**    | `NN% left` (օրինակ, `20% left`)                                                                              | `provider.quotas` / `providers[].quotas`                                    |
| **Չափում**           | **Կտրված-ճշգրտված օգտագործելի նպաստ** : մնացորդային հզորությունը սահմանային շեմից բարձր                      | **Հումքի վերին քվոտա** Չճշգրտված մատակարարի չափում                          |
| **Cutoff scaling**   | Սանդղակավորվել է `effectiveRemainingPercent()` միջոցով, որպեսզի պաշտպանված արգելոցը կարդացվի որպես `0% left` | Ոչ մեկը (չմշակված պատկերի արժեքները, ինչպես հաղորդում է մատակարարը)         |
| **Շեմային տվյալներ** | Ներառված է ցուցադրվող տոկոսի մեջ                                                                             | Պահվում է `quotaWindowThresholds` ում մեկ կապի համար (կամ սերվերի լռելյայն) |
| **Առաջնային սպառող** | Ինտերակտիվ CLIs, տերմինալի հուշումներ, մարդկային օպերատորներ                                                 | Ծրագրային ինտեգրումներ, վահանակներ, վերլուծություններ, վճարումների հետքեր   |

#### The Cutoff Adjustment Formula

OmniRoute աջակցում է ակտիվ քվոտաների կրճատումներ՝ կանխելու վերին հոսանքի հյուծումը (կազմաձևված է `quotaWindowThresholds` կապի, մատակարարի լռելյայն կամ գլոբալ ճկունության կարգավորումների միջոցով): Երբ սահմանային շեմը (օրինակ՝ `cutoff = 25%`) ակտիվ է քվոտայի պատուհանում, տեքստի մատուցողը հաշվարկում է մնացորդը հետևյալ կերպ.

- Եթե `remaining <= cutoff`. վերադարձնում է `0%`:
- Եթե `remaining > cutoff`. վերադարձնում է `((remaining - cutoff) / (100 - cutoff)) * 100`:

Ձևաչափված տեքստի ելքը կլորացնում է սա մինչև մոտակա ամբողջ թիվը (`Math.round(...)`):

#### Պատկերավոր օրինակ

Դիտարկենք մատակարարի պատուհանը** 60% հումքի օգտագործում** (հետևաբար** 40% հումքի մնացորդային քվոտա** ) և կազմաձևված** 25% մնացյալ քվոտայի կրճատում** շեմը:

| Ներկայացուցչություն            | Հաշվարկ                                            | Մնացած  |           Նշանակված Օգտագործված           |
| :----------------------------- | :------------------------------------------------- | :-----: | :---------------------------------------: |
| **Հում JSON (`?format=json`)** | Հոսանքի վերևի լուսանկար (`quotas[window]`)         | **40%** |                  **60%**                  |
| **Տեքստի ձևաչափ (`NN% left`)** | `((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100` | **20%** | **80%** (եթե `100 - remaining` հաշվում է) |

- **Ինչու տեքստը ցույց է տալիս 20% ձախ.** Հաշվի վրա մնացած 40% ֆիզիկական քվոտայից 25%-ը վերապահված է կտրման քաղաքականության կողմից: Զանգահարողին մնում է 75%-ից միայն 15%-ը, մինչև երթուղիչը կդադարեցնի երթուղին դեպի այս միացում: Scaling-ը ապահովում է կապի ազդանշանների սպառումը (`0% left`) հենց այն ժամանակ, երբ երթուղավորումը կդադարի:
- **Ինչու JSON պահպանում է հումքի արժեքները.** JSON ծանրաբեռնվածությունը վերադարձնում է մատակարարի ճշգրիտ նկարը (`UsageSnapshot`), այնպես որ արտաքին գործիքներն ունենան մուտք դեպի վերգետնյա ճշմարտություն վերին հոսքի օգտագործման և կապի մակարդակի `quotaWindowThresholds` առանց սերվերի կողմից կորուստների մասշտաբավորման:

#### Սպառողների միգրացիայի ուղեցույց

Եթե արտաքին ինտեգրումը (օրինակ՝ խմբագրի հավելվածը կամ գործակալի ընդլայնումը) նախկինում քերել է տեքստի վերջնակետը (`NN% left`) և հաշվարկել օգտագործված տոկոսը որպես `100 - NN`, միգրացիա `?format=json` նշանակում է.

- Հում JSON արժեքները կարդալը կանդրադառնա** իրական սպառումը հոսանքին հակառակ** (60% օգտագործվում է վերը նշված օրինակում):
- Եթե ինտեգրացիան ցանկանում է պահպանել տեքստի վերջնակետի օգտագործելի թույլատրելի իմաստաբանությունը, այն կարող է գնահատել հաճախորդի կողմից մնացած արդյունավետ բանաձևը, օգտագործելով `quotaWindowThresholds` կապի մակարդակի վերացման համար:

---

## Սեմանտիկ քեշ

```bash
# Ստանալ քեշի վիճակագրությունը
GET /api/cache/stats

# Մաքրել բոլոր քեշերը
DELETE /api/cache/stats
```

Պատասխանի օրինակ՝

```json
{
  "semanticCache": {
    "memorySize": 42,
    "memoryMaxSize": 500,
    "dbSize": 128,
    "hitRate": 0.65
  },
  "idempotency": {
    "activeKeys": 3,
    "windowMs": 5000
  }
}
```

### Ազդեցությունը ուշացման վրա

Սեմանտիկ քեշի HIT-ը պատասխանը մատուցում է քեշից՝ **առանց upstream
կանչի**, ուստի հաղորդվող `X-OmniRoute-Response-Latency`-ը գրեթե զրոյական է
(անկախ սկզբնական upstream ուշացումից)։ Ուշացման նկատմամբ զգայուն հաճախորդները
(բենչմարքինգ, p50/p99 մոնիթորինգ) պետք է ստուգեն
`X-OmniRoute-Cache-Latency` պատասխանի վերնագիրը՝

| Value       | Meaning                                                            |
| ----------- | ------------------------------------------------------------------ |
| `synthetic` | Պատասխանը մատուցվել է քեշից․ ուշացումը իրական upstream ժամանակը չէ |
| _(absent)_  | Պատասխանը ստացվել է իրական upstream կանչից                         |

### Քեշի շրջանցում ըստ բանալիի

API բանալիները կարող են հրաժարվել սեմանտիկ քեշից կարդալուց՝ `cacheDefaultMode`-ի միջոցով՝

| Value    | Behavior                                                       |
| -------- | -------------------------------------------------------------- |
| `legacy` | Քեշի սովորական վարքագիծ (կանխադրված)                           |
| `bypass` | Բաց թողնել քեշի որոնումն ամբողջությամբ․ միշտ դիմել upstream-ին |

Սահմանեք բանալու ստեղծման ժամանակ (`POST /api/keys`) կամ թարմացման ժամանակ (`PATCH /api/keys/[id]`)՝

```json
{ "cacheDefaultMode": "bypass" }
```

### Շրջանցում ըստ հարցման

Ցանկացած հարցում կարող է շրջանցել քեշը՝ անկախ բանալու կարգավորումներից՝

```
X-OmniRoute-No-Cache: true
```

---

## CLIProxyAPI-ի կառավարման համատեղելիություն

OmniRoute-ը պատասխանում է [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)-ի
կառավարման երեք endpoint-ներին, որոնց դիմում են օգտագործման վահանակները՝ Claude-ի և Codex-ի
բաժանորդագրության սահմանաչափերը կարդալու համար
(օրինակ՝ T3 Code-ի `cliproxy` օգտագործման սահմանաչափի աղբյուրը)։ Հաճախորդի base URL-ը ուղղեք
OmniRoute-ին և որպես կառավարման բանալի օգտագործեք `manage` scope-ով API բանալի։ Ուղիները
մատուցվում են `/v0/management/*` և `/api/v0/management/*` հասցեներով։

| Method | Path                         | Description                                                                                                                                      |
| ------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/v0/management/auth-files`  | Claude-ի և Codex-ի OAuth միացումները՝ որպես `{ files: [{ id, auth_index, provider, email, disabled, id_token }] }`։ Token-ներ չկան               |
| POST   | `/v0/management/api-call`    | Մարմին՝ `{ auth_index, method, url, header?, data? }`։ Ուղարկում է մեկ թույլատրված հարցում հաշվի token-ով և վերադարձնում `{ status_code, body }` |
| POST   | `/v0/management/reset-quota` | Մարմին՝ `{ auth_index }`։ Մաքրում է մեկ հաշվի միացման cooldown-ը, մոդելի lockout-ները և Codex-ի յուրաքանչյուր scope-ի cooldown-ները              |

- `auth_index`-ը OmniRoute-ի միացման id-ն է։ `provider`-ը `claude` կամ `codex` է (միայն OAuth
  միացումներ․ `anthropic` API բանալու provider-ը չի ցուցակագրվում)։ Codex-ի համար
  `id_token.chatgpt_account_id`-ը պահպանված workspace id-ն է, իսկ `plan_type`-ը՝ պահպանված պլանը։
- `api-call`-ը ընդհանուր նշանակության proxy չէ։ Այն ընդունում է միայն Claude-ի `GET
https://api.anthropic.com/api/oauth/usage` և Codex-ի `GET https://chatgpt.com/backend-api/wham/usage`, `GET .../wham/rate-limit-reset-credits` և
  `POST .../wham/rate-limit-reset-credits/consume` հարցումները, որոնցից յուրաքանչյուրը՝ միայն համապատասխան
  provider-ի հաշվին։ Մնացած ամեն ինչ վերադարձնում է `403`՝ առանց upstream-ին դիմելու։ Կանչողի
  `Authorization` վերնագիրը (ներառյալ `$TOKEN$` placeholder-ը) անտեսվում է․ OmniRoute-ը ներդնում է
  միացման access token-ը՝ նախ թարմացնելով այն, երբ դրա ժամկետը մոտ է լրանալուն, և փոխանցում է միայն
  թույլատրված վերնագրերը (`anthropic-beta`; `OpenAI-Beta`, `Originator`, `Chatgpt-Account-Id`;
  `Accept`, `Content-Type`)։ Բացակայող `Chatgpt-Account-Id`-ը լռելյայն ստանում է պահպանված workspace id-ի արժեքը։
  Հարցումների ժամկետը լրանում է 15 վայրկյանից հետո, և դրանք օգտագործում են միացման proxy-ն։
- `reset-quota`-ն անփոփոխ է թողնում վերջնական վիճակները (`banned`, `expired`, `credits_exhausted`)։ Անհայտ
  `auth_index`-ը վերադարձնում է `404`։

**Նույնականացում․** վահանակի սեսիա կամ `manage` scope-ով API բանալի, որը պարտադիր է նույնիսկ այն դեպքում, երբ մուտքն անջատված է
(ուղիները գտնվում են `ALWAYS_PROTECTED_API_PATHS`-ում)։ Միայն inference-ի համար նախատեսված բանալիները ստանում են `403`։ Աղբյուրը՝
`src/lib/cliproxyCompat/managementApi.ts`։

---

## Վահանակ և կառավարում

Կառավարման երթուղիները (`/api/*` բացի հանրային auth/login) են** ոչ** լիազորված սովորական եզրակացության API ստեղներով: Հավատարմագրերի ընտանիքներ, շրջանակներ և ոլորման օրինակներ. [Կառավարման վավերացում](../guides/MANAGEMENT-AUTH.md) :

### Նույնականացում

| Վերջնակետ                     | Մեթոդ    | Նկարագրություն                                                                                                                                                                                                                                                                                                  |
| ----------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/auth/login`             | POST     | Մուտք գործել                                                                                                                                                                                                                                                                                                    |
| `/api/auth/logout`            | POST     | Դուրս գալ                                                                                                                                                                                                                                                                                                       |
| `/api/settings/require-login` | GET/POST | Մուտքի կարգավիճակը (GET, հանրային): POST սահմանում է գաղտնաբառը / փոխում է մուտքը. օպերատորը միայն գաղտնաբառի առկայության դեպքում (վահանակի նիստ, տեղական CLI կամ մուտքի անջատում — API ստեղները և `oma_` նշանները ստանում են `403`); վահանակի նիստը ուղարկում է `currentPassword` գաղտնաբառը փոխարինելու համար |

### Մատակարարների կառավարում

| Վերջնակետ                               | Մեթոդ                     | Նկարագրություն                                                                                                                                       |
| --------------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/providers`                        | GET/POST                  | Ցուցակել / ստեղծել պրովայդերներ                                                                                                                      |
| `/api/providers/[id]`                   | GET/PUT/DELETE            | Կառավարեք մատակարարին                                                                                                                                |
| `/api/providers/[id]/test`              | POST                      | Փորձարկող մատակարարի միացում                                                                                                                         |
| `/api/providers/[id]/models`            | GET                       | Ցուցակեք մատակարարների մոդելները                                                                                                                     |
| `/api/providers/validate`               | POST                      | Վավերացրեք մատակարարի կազմաձևը                                                                                                                       |
| `/api/providers/bulk`                   | POST                      | Զանգվածային ավելացրեք API ստեղները ONE մատակարարի համար                                                                                              |
| `/api/providers/import`                 | POST                      | Ներմուծեք տարասեռ մատակարար LIST վերլուծված CSV/JSON ֆայլից (#6836); մեկ տողում մասնակի ձախողման արդյունքներ                                         |
| `/api/provider-nodes*`                  | Տարբեր                    | Մատակարարի հանգույցի կառավարում                                                                                                                      |
| `/api/provider-models`                  | GET/POST/PUT/PATCH/DELETE | Պատվերով մոդելներ և յուրաքանչյուր մոդելի անտեսում (ավելացնել, թարմացնել, hide/show, ջնջել)                                                           |
| `/api/provider-models/validate-and-add` | POST                      | Կառավարման կողմից վավերացված, միացնել խիստ կապի վավերացում և ատոմային հատուկ մոդելի գրանցում; տես [Մոդելի վավերացում](../guides/MODEL-VALIDATION.md) |

synced/imported մոդելների համար `PUT /api/provider-models` ընդունում է `provider`, `modelId` և `maxOutputTokenOverride`. դրական ամբողջ թիվը սահմանում է ձեռքով ելքային նշանի գլխարկը, իսկ `null` մաքրում է այն՝ կանխադրվածը վերականգնելու համար: `GET /api/provider-models?provider=<provider>` վերադարձնում է այս արժեքները `modelOutputOverrides` ով, ներառյալ մոդելներն առանց հատուկ մոդելի տողի: The override-ն օգտագործում է գործարկման ժամանակի `max_output_tokens` հնարավորությունը և գոյատևում է մոդելի վերահամաժամեցումից: OpenAI-ի հետ համատեղելի մատակարարի էջն առաջարկում է նույն edit/clear կառավարումը և նշում մոդելները՝ հստակ տեսողության աջակցությամբ:

Համատեղելի մատակարարի հանգույցում գրելու ուղիները (`POST`, `PUT`, `PATCH`, `DELETE` և `/api/provider-models/validate-and-add`) պահում են մոդելի id-ը որպես մերկ վերին հոսանքով id. նախածանցային ցուցակից տեղադրվող id-ի դեպքում հանգույցի սեփական նախածանցի որևէ առաջատար փաթեթը ծալված է, և պատասխանները կրկնում են պահված ID-ն: Կանոնական մատակարարների կտրված ID-ները (օրինակ՝ `nvidia/nemotron-…`) պահվում են բառացի: `/v1/models` երբեք չի թողարկում կուտակված `<prefix>/<prefix>/<model>` id:

Պատվերով Զրույցի ավարտման հանգույցները հարմարեցնում են բացահայտ հիմնավորումների անջատումները վերին հոսանքին հակառակ: Հաջողակ կապի փորձարկումն ավտոմատ կերպով ընտրում է զրույցի ձևանմուշների կառավարում ID ի ճշգրիտ մոդելի համար, որի `/models` մուտքն ապացուցում է `owned_by` ճանաչված արժեքը՝ `vllm`, `sglang` կամ `llamacpp`: Թափանցիկ OpenAI-ի հետ համատեղելի փաթաթանները կարող են պահպանել սկզբնական մոդելի մուտքագրումը տեղադրված `openai` օբյեկտի ներսում. հայտնաբերումը հետևում է մինչև երեք նման ծրարների: Բացակայող, անհայտ կամ հակասական սեփականություն ունեցող մոդելները պահպանում են սովորական OpenAI վարքագիծը: Հայտնաբերումը վերօգտագործում է առկա կատալոգի հարցումը, չի առաջացնում ավարտման նշաններ և անվավեր է դառնում, երբ կապի վերջնակետը փոխվում է:

Այդ մետատվյալները չբացահայտող հետին պլանի վարքագիծը ամրացնելու համար օգտագործեք գոյություն ունեցող մասնակի մատակարարի թարմացումը API.

```json
{
  "providerSpecificData": {
    "reasoningControl": "chat-template"
  }
}
```

Ուղարկեք այդ մարմինը `PUT /api/providers/<connection-id>` ով: Այդ կապակցությամբ, `none` ի բացահայտ հիմնավորումը ուղարկվում է որպես `chat_template_kwargs.thinking=false` և `chat_template_kwargs.enable_thinking=false`: Կաղապարի բացահայտ արժեքները մնում են հեղինակավոր, քանի դեռ սերվերի կողմից հիմնավորման կանոնը չի ստիպում ջանքեր գործադրել: Կարգավորումը կիրառվում է միայն այն դեպքում, երբ սովորական OpenAI-ի հետ համատեղելի կապը ուղարկում է Chat Completions մարմինը. Պատասխանների հարցումները և սովորական մատակարարները պահպանում են իրենց մայրենի հարցումների ձևը: Սահմանեք `reasoningControl` ին `openai` ՝ սովորական OpenAI `reasoning_effort` անցումը ստիպելու համար, կամ բաց թողեք it/set այն `null` ՝ ավտոմատ հայտնաբերումն օգտագործելու համար:

Claude Code-ի ավտոմատ ռեժիմի դասակարգիչը պահանջում է անջատել լռելյայն բնիկ մտածողությունը, երբ դրանք չեն պարունակում հստակ հիմնավորման վերահսկումներ: Հայտնաբերումը օգտագործում է դասակարգչի համակարգի նշիչը Claude-ի ձևաչափի հարցումներում, այլ ոչ թե մոդելների անունները կամ լրացման սահմանները: Բացահայտ մարմնի կառավարումները, աջակցվող effort/thinking վերնագրերը, երթուղային կանոնները և լուծված մոդելի ջանքերը պահպանում են իրենց առաջնահերթությունը: Դասակարգիչի երկու փուլերն էլ պահպանում են իրենց հուշումները, ավարտի սահմանները, կանգառի հաջորդականությունը և իրական վերին հոսքի թույլտվության վճիռները. Երկրորդ փուլը դեռևս կարող է արտադրել իր պահանջված տեսանելի պատճառաբանությունը որպես սովորական տեքստ:

### OAuth Հոսում է

| Վերջնակետ                        | Մեթոդ  | Նկարագրություն          |
| -------------------------------- | ------ | ----------------------- |
| `/api/oauth/[provider]/[action]` | Տարբեր | Մատակարարի հատուկ OAuth |

### Ուղղորդում և կազմաձևում

| Վերջնակետ             | Մեթոդ    | Նկարագրություն                             |
| --------------------- | -------- | ------------------------------------------ |
| `/api/models`         | GET/PUT  | Մոդելների ցուցակ / կեղծանունների թարմացում |
| `/api/models/alias`   | GET/POST | Մոդելային անուններ                         |
| `/api/models/catalog` | GET      | Բոլոր մոդելներն ըստ մատակարարի + տեսակի    |
| `/api/combos*`        | Տարբեր   | Համակցված կառավարում                       |
| `/api/keys*`          | Տարբեր   | API բանալիների կառավարում                  |
| `/api/pricing`        | GET      | Մոդելային գնագոյացում                      |

#### Մոդելի սահմանաչափի ծագումը

`GET /api/models?withLimits=1` (նաև `true`; `0`/`false` կամ դրա բացթողումը պահում է լռելյայն օգտակար բեռը անփոփոխ) յուրաքանչյուր մոդելի տողում ավելացնում է `contextWindow`, `maxInputTokens`, `maxOutputTokens` և `capsSource` օբյեկտ: `capsSource` անվանում է այն կանոնը, որն ապահովում էր յուրաքանչյուր սահմանաչափ, ուստի զարմանալի սահմանը (օրինակ՝ 128k 1M մոդելի վրա) կարելի է հետևել դրա ծագմանը: Լուծված արժեքները նույնն են, ինչ օգտագործում է երթուղիչը. դրոշը միայն դաշտեր է ավելացնում և երբեք արժեքը չի փոխում: Ցանկացած այլ `withLimits` արժեք մերժվում է `400` ով:

| `capsSource` արժեքը                          | Ծագում                                                                     |
| -------------------------------------------- | -------------------------------------------------------------------------- |
| `override:context`                           | Համատեքստ-պատուհանի շարունակական վերացում (`model_context_overrides`)      |
| `override:max_input` / `override:max_output` | Մշտական `max_input_tokens` / `max_output_tokens` կարողությունների վերացում |
| `static-authoritative:<provider>/<model>`    | Ստատիկ հեղինակավոր համատեքստ-պատուհան աղյուսակ                             |
| `synced:<provider>/<model>`                  | models.dev համաժամեցված հնարավորությունների տող                            |
| `registry:<provider>/<model>`                | Մատակարարի ռեեստրի մուտքը                                                  |
| `spec:<model>`                               | Ստատիկ մոդելի սպեկտր                                                       |
| `effort-base:` նախածանց                      | Շարքը փոխառված է ջանք-ծածանցով տարբերակի բազային մոդելից                   |
| `none`                                       | Ոչ մի աղբյուր չի հայտարարում սահմանաչափը (արժեքը `null` է)                 |

Իրականացում. `getResolvedModelCapabilitiesWithLimitSources()` `src/lib/modelCapabilities.ts` ում և գերակայության շղթաները `src/lib/modelCapabilityLimits.ts` ում:

### Օգտագործում և վերլուծություն

| Վերջնակետ                        | Մեթոդ           | Նկարագրություն                                                                                                                                                                                                                                                                                                               |
| -------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history`             | GET             | Օգտագործման պատմություն                                                                                                                                                                                                                                                                                                      |
| `/api/usage/logs`                | GET             | Օգտագործման տեղեկամատյաններ                                                                                                                                                                                                                                                                                                  |
| `/api/usage/request-logs`        | GET             | Հարցման մակարդակի տեղեկամատյաններ                                                                                                                                                                                                                                                                                            |
| `/api/usage/[connectionId]`      | GET             | Մեկ կապի օգտագործումը                                                                                                                                                                                                                                                                                                        |
| `/api/usage/token-limits`        | GET/POST/DELETE | API-բանալինների նշանային-սահմանափակ բյուջեներ                                                                                                                                                                                                                                                                                |
| `/api/usage/model-latency-stats` | GET             | Rolling per-provider/model latency ագրեգատ (avg/p50/p95/p99, հաջողության մակարդակ); զտիչներ՝ `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)                                                                                                                                                                 |
| `/api/usage/cache-health`        | GET             | Արագ քեշի առողջության ամփոփում `call_logs` — write/read հարաբերակցությամբ, p50/p90/p99 գրելու չափի բաշխում, ծանր գրելու համակենտրոնացում, յուրաքանչյուր մոդելի բաժանում և `healthy`/`degraded`/`thrash`/`no-data` դատավճիռ; հարցումը params `range` (`1h`\| `24h`\| `7d`\| `30d`, լռելյայն `24h`) և կամընտիր `model` (#8827) |

### API հիմնական թույլտվությունները

`PATCH /api/keys/{id}` թարմացնում է գոյություն ունեցող բանալու թույլտվությունները: Ինչպես յուրաքանչյուր `/api/keys*` երթուղի, այն կարիք ունի կառավարման թույլտվության (տես [Կառավարման նույնականացում](../guides/MANAGEMENT-AUTH.md) ), ոչ թե եզրակացության բանալի: Ուղարկեք միայն այն դաշտերը, որոնք ցանկանում եք փոխել; Նրանցից ոչ մեկի հետ կապված հարցումը չի մերժվում `No valid fields to update` ով: Ընդունված դաշտերը սահմանված են `updateKeyPermissionsSchema` ով `src/shared/validation/schemas/keys.ts` ում:

| Դաշտ                                        | Տեսակ                                                                 | Նշումներ                                                                                                                                                                                                                                                               |
| ------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                                      | լարային, 1-200 նիշ                                                    |                                                                                                                                                                                                                                                                        |
| `isActive`                                  | բուլյան                                                               |                                                                                                                                                                                                                                                                        |
| `isBanned`                                  | բուլյան                                                               |                                                                                                                                                                                                                                                                        |
| `expiresAt`                                 | ISO 8601 datetime կամ `null`                                          | `null` մաքրում է ժամկետը                                                                                                                                                                                                                                               |
| `modelAccessMode`                           | `all` \| `restricted`                                                 | `allowedModels` պետք է դատարկ լինի, երբ ռեժիմը `all` է                                                                                                                                                                                                                 |
| `allowedModels`, `blockedModels`            | լարերի զանգված՝ մինչև 1000                                            |                                                                                                                                                                                                                                                                        |
| `allowedCombos`                             | լարերի զանգված՝ մինչև 500                                             | Բանալին համակցող դարպասներ կարող են կանչել. ուղղակի մոդելները կառավարվում են `modelAccessMode` / `allowedModels` ով                                                                                                                                                    |
| `connectionAccessMode`                      | `all` \| `restricted`                                                 | `allowedConnections` պետք է լինի ոչ դատարկ, երբ `restricted` և դատարկ, երբ `all`                                                                                                                                                                                       |
| `allowedConnections`                        | UUIDs ի զանգված, մինչև 100                                            |                                                                                                                                                                                                                                                                        |
| `allowAutoCombos`                           | բուլյան                                                               | `false` մերժում է այս բանալիով `auto/*` մոդելների հարցումները. թույլատրվում են այն բանալիները, որոնք երբեք չեն կարգավորում                                                                                                                                             |
| `catalogScope`                              | `all` \| `combos` \| `models`                                         | Ինչ է թվարկում `GET /v1/models` այս ստեղնի համար (միայն կոմբինատներ, միայն մոդելներ կամ երկուսն էլ); այն չի փոխում, թե ինչ կարող է զանգահարել ստեղնը                                                                                                                   |
| `forcedModel`                               | լարային մինչև 300 նիշ կամ `null`                                      | Ուղարկում է զրույցի հարցումները դեպի այս model/combo, `X-Route-Model` և `body.model` վրա; բանալիների սահմանները դեռ գործում են                                                                                                                                         |
| `noLog`, `autoResolve`                      | բուլյան                                                               |                                                                                                                                                                                                                                                                        |
| `throttleDelayMs`                           | ամբողջ թիվ, 0-300000                                                  |                                                                                                                                                                                                                                                                        |
| `maxSessions`                               | ամբողջ թիվ, 0-10000                                                   |                                                                                                                                                                                                                                                                        |
| `rateLimits`                                | `{ limit, window }` (դրական ամբողջ թվեր, մինչև 50) կամ `null` զանգված | `null` մաքրում է սահմանները                                                                                                                                                                                                                                            |
| `accessSchedule`                            | ժամանակացույցի օբյեկտ կամ `null`                                      | `null` մաքրում է ժամանակացույցը                                                                                                                                                                                                                                        |
| `scopes`                                    | տողերի զանգված, մինչև 32                                              |                                                                                                                                                                                                                                                                        |
| `allowedEndpoints`                          | տողերի զանգված, մինչև 20                                              |                                                                                                                                                                                                                                                                        |
| `streamDefaultMode`                         | `legacy` \| `json`                                                    |                                                                                                                                                                                                                                                                        |
| `cacheDefaultMode`                          | `legacy` \| `bypass`                                                  | Տես [մեկ բանալի քեշի շրջանցում](#per-key-cache-bypass)                                                                                                                                                                                                                 |
| `compressionEnabled`                        | բուլյան                                                               |                                                                                                                                                                                                                                                                        |
| `codexServiceMode`                          | Codex ծառայության ռեժիմներից մեկը                                     |                                                                                                                                                                                                                                                                        |
| `disableNonPublicModels`                    | բուլյան                                                               |                                                                                                                                                                                                                                                                        |
| `allowUsageCommand`                         | բուլյան                                                               |                                                                                                                                                                                                                                                                        |
| `usageLimitEnabled`                         | բուլյան                                                               |                                                                                                                                                                                                                                                                        |
| `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | թիվը >= 0 կամ `null`                                                  |                                                                                                                                                                                                                                                                        |
| `fiveHourUsageLimitUsd`                     | թիվը >= 0 կամ `null`                                                  | Շարժվող 5-ժամյա USD բյուջեն, որը կիրառվում է օրական և շաբաթական սահմանաչափերի նման (`usageLimitEnabled`, `UNPRICED_USAGE_BUDGET_POLICY`): `retry-after` այն է, երբ պատուհանի ամենահին ծախսերը հնանում են, ինչը կարող է արգելափակված թողնել իր սահմանաչափից շատ բանալի: |
| `chaosModeEnabled`                          | բուլյան                                                               |                                                                                                                                                                                                                                                                        |

```bash
curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \
  -H "Authorization: Bearer <management-credential>" \
  -H "Content-Type: application/json" \
  -d '{ "allowAutoCombos": false, "catalogScope": "combos" }'
```

### Կարգավորումներ

| Վերջնակետ                             | Մեթոդ         | Նկարագրություն                                                                                                                                                                                                                                                                                                                  |
| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings`                       | GET/PUT/PATCH | Ընդհանուր կարգավորումներ. Անվտանգության քաղաքականության բանալիներին (`requireLogin`, `newPassword`, `oidc*`, `corsOrigins`, `bruteForceProtection`) անհրաժեշտ է `currentPassword` և օպերատորի հավատարմագիր — API ստեղները և `oma_` նշանները ստանում են `403`; յուրաքանչյուր մուտացիայի կարիք ունի `admin` մուտքի նշանի շրջանակը |
| `/api/settings/proxy`                 | GET/PUT       | Ցանցի վստահված անձի կազմաձևում                                                                                                                                                                                                                                                                                                  |
| `/api/settings/proxy/test`            | POST          | Փորձարկեք վստահված անձի կապը                                                                                                                                                                                                                                                                                                    |
| `/api/settings/ip-filter`             | GET/PUT       | IP allowlist/blocklist                                                                                                                                                                                                                                                                                                          |
| `/api/settings/thinking-budget`       | GET/PUT       | Thinking/reasoning** խնդրանք** վերագրանցման ռեժիմ (անցում / ավտոմատ ժապավեն / մաքսային / հարմարվողական): Անկախ սեղմումից: Տես [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md).                                                                                                                                               |
| `/api/settings/system-prompt`         | GET/PUT       | Համաշխարհային համակարգի հուշում                                                                                                                                                                                                                                                                                                 |
| `/api/settings/compression`           | GET/PUT       | Համաշխարհային սեղմման կոնֆիգուրացիա                                                                                                                                                                                                                                                                                             |
| `/api/settings/purge-request-history` | POST          | Մաքրել հարցումների մատյանների տողերը և տեղական զանգերի գրանցամատյանի արտեֆակտները                                                                                                                                                                                                                                               |

### Համատեքստ և սեղմում

| Վերջնակետ                              | Մեթոդ          | Նկարագրություն                                                                        |
| -------------------------------------- | -------------- | ------------------------------------------------------------------------------------- |
| `/api/compression/preview`             | POST           | Նախադիտեք off/lite/standard/aggressive/ultra/RTK/stacked սեղմումը                     |
| `/api/compression/language-packs`      | GET            | Ցուցակե՛ք Caveman լեզվի հասանելի փաթեթները                                            |
| `/api/compression/rules`               | GET            | Թվարկեք Caveman կանոնների մետատվյալները                                               |
| `/api/context/caveman/config`          | GET/PUT        | Caveman-ի հատուկ կարգավորումների կեղծանունը                                           |
| `/api/context/rtk/config`              | GET/PUT        | RTK-ին հատուկ կարգավորումներ, ներառյալ հատուկ զտիչներ և չմշակված արտադրանքի պահպանում |
| `/api/context/rtk/filters`             | GET            | RTK ֆիլտրի կատալոգ և անհատական ֆիլտրի ախտորոշում                                      |
| `/api/context/rtk/test`                | POST           | Գործարկեք RTK preview/test տեքստային ծանրաբեռնվածության դեմ                           |
| `/api/context/rtk/raw-output/[id]`     | GET            | Կարդացեք պահպանված խմբագրված չմշակված ելքը ըստ ցուցիչի ID-ի                           |
| `/api/context/combos`                  | GET/POST       | Կոմպրեսիոն կոմբինացիա list/create                                                     |
| `/api/context/combos/[id]`             | GET/PUT/DELETE | Կոմպրեսիոն կոմբինացիա detail/update/delete                                            |
| `/api/context/combos/[id]/assignments` | GET/PUT        | Վերագրեք սեղմման կոմպոզիցիաներ երթուղային կոմբինատներին                               |
| `/api/context/analytics`               | GET            | Կոմպրեսիոն վերլուծական կեղծանուն                                                      |

### Մոնիտորինգ

| Վերջնակետ                            | Մեթոդ      | Նկարագրություն                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions`                      | GET        | Ակտիվ նստաշրջանի հետևում                                                                                                                                                                                                                                                                                                                                                                              |
| `/api/rate-limits`                   | GET        | Մեկ հաշվի տոկոսադրույքի սահմանաչափեր                                                                                                                                                                                                                                                                                                                                                                  |
| `/api/monitoring/health`             | GET        | Առողջության ստուգման + մատակարարի ամփոփագիր (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`): Կառավարման տեսքը ներառում է `credentialHealth`. զոնդ-քեշի սկալերներ, `failedConnections` երբ `failed>0` և `staleDbNonOkCount` (SQLite կպչուն `test_status`, ոչ թե չափիչ): Տես [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/api/cache/stats`                   | GET/DELETE | Քեշի վիճակագրություն / մաքրել                                                                                                                                                                                                                                                                                                                                                                         |
| `/api/modality-bridge/stats`         | GET        | Հիշողության մեջ `attempts`, հաջողություններ/`bridged`, ձախողումներ, քեշի հարվածներ, `totalLatencyMs`, `latencySamples`, նմուշով նշանակված `averageLatencyMs` և վերջին օգտագործման ժամանակը (վերագործարկվելիս, կառավարման հաստատում)                                                                                                                                                                   |
| `/api/modality-bridge/video/runtime` | GET        | Խիստ վստահելի-loopback ստուգում նախքան կառավարումը auth/probe; ախտահանված FFmpeg/ffprobe առկայությունը և տարբերակները (առանց խանութի)                                                                                                                                                                                                                                                                 |
| `/api/modality-bridge/video/extract` | POST       | Ներքին վավերացված վստահելի-loopback բայթ բրոքեր; 50 MiB մուտքագրում, սահմանափակված queue/32 MiB ելք, `503` հզորություն, `499` անջատում, `504` վերջնաժամկետ; ոչ հանրային վերբեռնում API                                                                                                                                                                                                                |

### Տեսանյութի շրջանակի փորագրում

`GET /api/v1/video-bridge/drilldown` կարդում է վարձակալի վրա ամրացված անթափանց բռնակը, որը վերադարձվել է `x-omniroute-video-drilldown` ում հստակ համաձայնեցված Video Bridge հարցումից հետո: Ե՛վ ընթերցումները, և՛ `DELETE` միշտ պահանջում են վավեր API բանալի և օպերատորի անկախ `modalityBridgeVideoDrilldownRemoteEnabled` թույլտվությունը: Արտադրության պահպանումը լրացուցիչ պահանջում է `modalityBridgeVideoDrilldownEnabled` և խիստ յուրաքանչյուր մասի `drilldown: true`: Եթե բանալին ունի ոչ դատարկ վերջնակետի թույլտվության ցուցակ, այն պետք է ներառի `video` և՛ GET, և՛ DELETE համար, անկախ նրանից զանգահարողը օգտագործում է `/v1`, թե `/api/v1`:

GET հարցում՝ պահանջվում է `handle`; ընտրովի `variant` (`preview`, `standard`, `detail`), `limit` (1–8; ժառանգական `frames` ընդունված է, բայց չի կարող համակցվել `limit` հետ), զրոյական `page` և `start`/`end` վայրկյաններ: Երբ երկու ֆոկուսի սահմաններն էլ տրամադրված են, `end` պետք է ավելի մեծ լինի, քան `start`: Duplicate/unknown հարցման բանալիները մերժված են: Հաջող պատասխանները պարունակում են `derivation`, `durationSeconds`, `frames`, `hasMore`, `page`, `variant` և կամընտիր `focusWindow`; no-store JSON սահմանափակված է 32 MiB ով, ներառյալ Base64-ը: Չափազանց մեծ արդյունքը վերադարձնում է 413; պահանջել ավելի քիչ շրջանակներ:

`DELETE /api/v1/video-bridge/drilldown?handle=...` վերադարձնում է `{ "removed": 0|1 }`. Անհայտ, ժամկետանց և խաչաձեւ բանալի GETs չեն տարբերվում 404 պատասխաններից; cross-key DELETE չի կարող հեռացնել սեփականատիրոջ մուտքը: Անջատված մուտքը վերադարձնում է 403, missing/invalid վավերացում 401, անվավեր հարցումներ 400, չեղարկում 499 և ժամանակավոր սխալներ 503: Բռնակները գործընթացային են, ժամկետանց են տասը րոպեից և չեն պահպանվում վերագործարկումից հետո: Նոր բռնակներ օգտագործում են `v1.` գումարած 32 բայթ պատահական Base64URL նշան; պահպանվում են միայն նշանային հեշերը: Legacy 64-hex նշանները մնում են շարահյուսական ընթեռնելի՝ համատեղելիության համար: Համաձայնության, քվոտաների և տարբերակների ստացման մանրամասների համար տե՛ս [Video Bridge-ի պաշտպանիչ բազրիքները](../security/GUARDRAILS.md#video-bridge-videobridgets-videobridgepipelinets) :

### Կրկնօրինակում և Export/Import

| Վերջնակետ                   | Մեթոդ  | Նկարագրություն                                                                                 |
| --------------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| `/api/db-backups`           | GET    | Ցուցակեք հասանելի կրկնօրինակները                                                               |
| `/api/db-backups`           | PUT    | Ստեղծեք ձեռքով կրկնօրինակում                                                                   |
| `/api/db-backups`           | POST   | Վերականգնել հատուկ կրկնօրինակից                                                                |
| `/api/db-backups`           | PATCH  | Պահպանեք կրկնօրինակի պահպանման կարգավորումները (միայն օպերատորի համար)                         |
| `/api/db-backups`           | DELETE | Պահված պահուստները կտրեք պահպանման կարգավորումներում (միայն օպերատորի համար)                   |
| `/api/db-backups/export`    | GET    | Ներբեռնեք տվյալների բազան որպես .sqlite ֆայլ                                                   |
| `/api/db-backups/import`    | POST   | Վերբեռնեք .sqlite ֆայլը տվյալների բազան փոխարինելու համար (միայն `?dryRun=true` վավերացնում է) |
| `/api/db-backups/exportAll` | GET    | Ներբեռնեք ամբողջական կրկնօրինակը որպես .tar.gz արխիվ                                           |

`/api/db-backups/export`, `/api/db-backups/exportAll` և `/api/settings/export-json` հանձնում են յուրաքանչյուր պահված հավատարմագիրը, այնպես որ նրանք պահանջում են վահանակի նիստը կամ տեղական CLI (կամ մուտքն անջատված է): Ցանկացած ծավալի API ստեղները և `oma_` մուտքի նշանները ստանում են `403`: Վերականգնումները պահպանում են նույն սահմանը. `POST /api/db-backups/import` (ներառյալ `dryRun=true` ), `POST /api/db-backups` (վերականգնել id-ով) և `POST /api/settings/import-json` փոխարինում են կենդանի տվյալների բազան կամ կարգավորումները, այնպես որ մեքենայի հավատարմագրերն այնտեղ նույնպես ստանում են `403` : `omniroute sync import` ուղարկում է տեղական CLI հավատարմագիրը: Այդպես արեք `DELETE /api/db-backups` (կտրեք պահված կրկնօրինակները) և `PATCH /api/db-backups` (պահման կարգավորումները. պահպանվող արժեքները մղում են ավտոմատ էտումը յուրաքանչյուր կրկնօրինակումից հետո): Ցուցակումը (`GET`) և ձեռքով կրկնօրինակի ստեղծումը (`PUT`) պահպանում են սովորական կառավարման հեղինակությունը:

### Cloud Sync

| Վերջնակետ              | Մեթոդ  | Նկարագրություն                        |
| ---------------------- | ------ | ------------------------------------- |
| `/api/sync/cloud`      | Տարբեր | Ամպային համաժամացման գործողություններ |
| `/api/sync/initialize` | POST   | Նախաձեռնել համաժամացումը              |
| `/api/cloud/*`         | Տարբեր | Ամպային կառավարում                    |

### Թունելներ

| Վերջնակետ                  | Մեթոդ | Նկարագրություն                                                              |
| -------------------------- | ----- | --------------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET   | Կարդացեք Cloudflare Quick Tunnel install/runtime կարգավիճակը վահանակի համար |
| `/api/tunnels/cloudflared` | POST  | Միացնել կամ անջատել Cloudflare Quick Tunnel-ը (`action=enable/disable`)     |
| `/api/tunnels/ngrok`       | GET   | Կարդացեք ngrok Tunnel-ի գործարկման ժամանակի կարգավիճակը վահանակի համար      |
| `/api/tunnels/ngrok`       | POST  | Միացնել կամ անջատել ngrok թունելը (`action=enable/disable`)                 |

### CLI գործիքներ

| Վերջնակետ                          | Մեթոդ | Նկարագրություն                   |
| ---------------------------------- | ----- | -------------------------------- |
| `/api/cli-tools/claude-settings`   | GET   | Claude CLI կարգավիճակ            |
| `/api/cli-tools/codex-settings`    | GET   | Codex CLI կարգավիճակ             |
| `/api/cli-tools/droid-settings`    | GET   | Droid CLI կարգավիճակը            |
| `/api/cli-tools/openclaw-settings` | GET   | OpenClaw CLI կարգավիճակ          |
| `/api/cli-tools/runtime/[toolId]`  | GET   | Ընդհանուր CLI գործարկման ժամանակ |

CLI պատասխանները ներառում են՝ `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`:

### ACP Գործակալներ

| Վերջնակետ         | Մեթոդ  | Նկարագրություն                                                              |
| ----------------- | ------ | --------------------------------------------------------------------------- |
| `/api/acp/agents` | GET    | Նշեք բոլոր հայտնաբերված գործակալները (ներկառուցված + մաքսային) կարգավիճակով |
| `/api/acp/agents` | POST   | Ավելացնել հատուկ գործակալ կամ թարմացնել հայտնաբերման քեշը                   |
| `/api/acp/agents` | DELETE | Հեռացրեք մաքսային գործակալը `id` հարցման պարամի միջոցով                     |

GET պատասխանը ներառում է `agents[]` (id, անուն, երկուական, տարբերակ, տեղադրված, արձանագրություն, isCustom) և `summary` (ընդհանուր, տեղադրված, notFound, builtIn, մաքսային):

### Ճկունության և տոկոսադրույքի սահմանները

| Վերջնակետ                         | Մեթոդ     | Նկարագրություն                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/resilience`                 | GET/PATCH | Get/update հարցումների հերթ, կապի սառեցում, մատակարարի անջատիչ և սպասման կարգավորումներ                                                                                                                                                                                                                                                                                                                                                                            |
| `/api/resilience/reset`           | POST      | Վերականգնել մատակարարի անջատիչները                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `/api/resilience/model-cooldowns` | GET       | Ցուցակեք ակտիվ կողպեքները յուրաքանչյուր (մատակարար, կապ, մոդել)՝ տեսակավորված ըստ մնացած ժամանակի                                                                                                                                                                                                                                                                                                                                                                  |
| `/api/resilience/model-cooldowns` | DELETE    | Մաքրել մոդելի կողպեքը — մարմնի `{provider, model}` կամ `{all: true}` ամեն ինչ ջնջելու համար                                                                                                                                                                                                                                                                                                                                                                        |
| `/api/rate-limits`                | GET/POST  | Մեկ հաշվի տոկոսադրույքի սահմանաչափի կարգավիճակը (GET) կամ փոխարկեք տոկոսադրույքի սահմանաչափի պաշտպանությունը միացման համար (POST `{connectionId, enabled}`): Աջակցված գրելու ուղին `rateLimitProtection` համար (երբեք չի փոփոխվել `PUT /api/providers/[id]` միջոցով): Նշում. `enabled: false` անջատում է բացահայտ պաշտպանությունը, բայց չի անջատում ակտիվ API-բանալին միացումը համաշխարհային ավտոմատ միացնելու անվտանգության ցանցից (`autoEnableApiKeyProviders`): |
| `/api/rate-limit`                 | GET       | Համաշխարհային տոկոսադրույքի սահմանաչափի կազմաձևում (հնացած, `/api/rate-limits` ի կեղծանուն)                                                                                                                                                                                                                                                                                                                                                                        |

> Բոլոր չորս `/api/resilience/*` երթուղիները պահանջում են** կառավարման հեղինակություն** (`requireManagementAuth`): Տե՛ս [առաձգականություն (ընդլայնված)](#resilience-extended) ՝ մատակարարի անջատիչի ընդդեմ կապի սառեցման ընդդեմ մոդելի արգելափակման ամբողջական խզման համար:

### Էվալս

| Վերջնակետ    | Մեթոդ    | Նկարագրություն                                          |
| ------------ | -------- | ------------------------------------------------------- |
| `/api/evals` | GET/POST | Ցուցակել արժեքավոր հավաքակազմերը / գործարկել գնահատումը |

### Քաղաքականություն

| Վերջնակետ       | Մեթոդ           | Նկարագրություն                         |
| --------------- | --------------- | -------------------------------------- |
| `/api/policies` | GET/POST/DELETE | Կառավարեք երթուղային քաղաքականությունը |

### Համապատասխանություն

| Վերջնակետ                   | Մեթոդ | Նկարագրություն                               |
| --------------------------- | ----- | -------------------------------------------- |
| `/api/compliance/audit-log` | GET   | Համապատասխանության աուդիտի մատյան (վերջին N) |

### v1beta (Gemini-ի հետ համատեղելի)

| Վերջնակետ                  | Մեթոդ | Նկարագրություն                     |
| -------------------------- | ----- | ---------------------------------- |
| `/v1beta/models`           | GET   | Ցուցակեք մոդելները Gemini ձևաչափով |
| `/v1beta/models/{...path}` | POST  | Gemini `generateContent` վերջնակետ |

Այս վերջնակետերը արտացոլում են Gemini ի API ձևաչափը հաճախորդների համար, ովքեր ակնկալում են տեղական Gemini SDK համատեղելիություն:

### Ներքին / Համակարգ APIs

| Վերջնակետ                | Մեթոդ | Նկարագրություն                                                       |
| ------------------------ | ----- | -------------------------------------------------------------------- |
| `/api/init`              | GET   | Սկսել ֆոնային համաժամացման ծառայությունները (կառավարման վավերացում)  |
| `/api/tags`              | GET   | Ollama-ի հետ համատեղելի մոդելի պիտակներ ( Ollama հաճախորդների համար) |
| `/api/restart`           | POST  | Գործարկեք նրբագեղ սերվերի վերագործարկումը                            |
| `/api/shutdown`          | POST  | Գործարկեք սերվերի նրբագեղ անջատումը                                  |
| `/api/system/env/repair` | POST  | Վերանորոգեք OAuth մատակարարի միջավայրի փոփոխականները                 |
| `/api/system/version`    | GET   | Current/latest տարբերակ, թարմացման կարգավիճակ, թողարկման ալիք        |
| `/api/system/version`    | POST  | Սկսեք տեղակայման մասին տեղեկացված թարմացում վերջին տարբերակի համար   |

> **Նշում.** Այս վերջնակետերն օգտագործվում են ներքին համակարգի կողմից կամ Ollama հաճախորդի համատեղելիության համար: Նրանք սովորաբար չեն կանչվում վերջնական օգտագործողների կողմից:

### OAuth Շրջակա միջավայրի վերանորոգում _(v3.6.1 +)_

```bash
POST /api/system/env/repair
Content-Type: application/json

{
  "provider": "claude-code"
}
```

Վերականգնում է բացակայող կամ վնասված OAuth միջավայրի փոփոխականները կոնկրետ մատակարարի համար: Վերադարձնում է՝

```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"
}
```

### Տարբերակի և թողարկման ալիք

```bash
GET /api/system/version
```

Միայն Loopback-ի կառավարման երթուղին (admin auth): Վերադարձնում է գործող տարբերակը, վերջին հրապարակված տարբերակը և ավտոմատ թարմացման կարգավիճակը: `releaseChannel` և `channels` հավելյալ դաշտեր են (երկաթուղային 3.8.54); `channel` պահպանում է իր նշանակությունը — տեղակայման ռեժիմում, որն օգտագործում է վահանակի թարմացումը (`npm`, `source` կամ `docker-compose`):

```json
{
  "current": "3.8.52",
  "latest": "3.8.52",
  "updateAvailable": false,
  "channel": "npm",
  "autoUpdateSupported": true,
  "autoUpdateError": null,
  "news": null,
  "releaseChannel": "latest",
  "channels": { "latest": "3.8.52", "next": "3.8.53-rc.1" }
}
```

- `releaseChannel` — npm ալիքը գործող շինարարության համար. `nightly` `-nightly.*` տարբերակների համար, `next` այլ նախնական թողարկումների համար (`-rc.*`, `-beta.*`, `-alpha.*`), `lts` ավելի հին հիմնական տարբերակի համար, քան `channels.latest`, այլապես `latest`: Նույն կանոնները, ինչ `scripts/release/dist-tag.mjs`, որն ընտրում է npm dist-պիտակը հրապարակման պահին:
- `channels` — հրապարակել է յուրաքանչյուր dist-tag-ի գլուխը՝ `npm view omniroute dist-tags` ից (registry HTTP backback), քեշավորված նույն 10 րոպեանոց TTL ինչ `latest`: `latest` միշտ առկա է (հետ է ընկնում `latest` դաշտ, հետո `"unavailable"`); `next`, `nightly` և `lts` հայտնվում են միայն այն ժամանակ, երբ այդ dist-tag-ը գոյություն ունի: `Cache-Control: no-cache` հարցումը թարմացնում է երկու որոնումները:

Ալիքի մոդելը (`latest` = v3 մինչև 4.0 GA, `next` = rc, `nightly` = `develop` կառուցումներ, `lts` = v3 patches 4.0 GA ից հետո) նկարագրված է `docs/ops/RELEASE_STRATEGY.md` ում:

---

## Աուդիոյի տառադարձում

```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```

Տառադարձեք աուդիոֆայլերը ցանկացած կարգավորված STT մատակարարի միջոցով։ Ուղու առաջին հատվածը ընտրում է բնիկ մատակարարին (`openai/…`, `deepgram/…`)։ Այլ մատակարարի մոդելը վերաարտահանող gateway-ներն օգտագործում են որակավորված նույնացուցիչ
(`openrouter/deepgram/nova-3`)։

**Հարցում՝**

```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"
```

**Պատասխան՝**

```json
{
  "text": "Hello, this is the transcribed audio content.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}
```

**Մոդելների նույնացուցիչների օրինակներ՝** `openai/whisper-1` (պահանջում է OpenAI բանալի),
`openrouter/deepgram/nova-3` (պահանջում է OpenRouter բանալի),
`deepgram/nova-3` (պահանջում է բնիկ Deepgram բանալի)։ Առանց նախածանցի
`deepgram/nova-3` հարցումը **չի օգտագործում OpenRouter**։

**Աջակցվող ձևաչափեր՝** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`։

**Gemini Live (`gemini/gemini-3.5-transcribe-live`)․** ֆայլային ռեժիմով տառադարձում Gemini Live-ի
WebSocket-ի միջոցով (պահանջում է Gemini API բանալի)։ Վերբեռնված ֆայլը `ffmpeg`-ի միջոցով փոխարկվում է 16 kHz մոնո PCM-ի
(`ffmpeg`-ը պետք է հասանելի լինի `PATH`-ում, եթե ֆայլն արդեն 16 kHz մոնո PCM WAV չէ), փոխանցվում է
սեսիային, և վերջնականացված տեքստը վերադարձվում է որպես `{ "text": "..." }`։ Ընտրովի `language` և `prompt` ձևի դաշտերը
փոխանցվում են հետագա մշակման համար։ Սահմանափակումներ՝ 25 MiB-ից մեծ վերբեռնումները կամ 10 րոպեից երկար վերծանված աուդիոն վերադարձնում են
`413`․ 60 վայրկյանից երկար տևող փոխարկումը դադարեցվում է և վերադարձնում է `504`։ API բանալին ուղարկվում է միայն
`x-goog-api-key` վերնագրում, երբեք՝ WebSocket URL-ում։

---

## Ollama-ի համատեղելիություն

Ollama-ի API ձևաչափն օգտագործող հաճախորդների համար՝

```bash
# Chat endpoint (Ollama format)
POST /v1/api/chat

# Model listing (Ollama format)
GET /api/tags
```

Հարցումները ավտոմատ կերպով թարգմանվում են Ollama-ի և ներքին ձևաչափերի միջև։

## Token-ացված VS Code / վերնագրազուրկ alias-ներ

Օգտագործեք այս alias-ները, երբ ինտեգրումը չի կարող ներարկել `Authorization` վերնագիր և պահանջում է API բանալին ներառել հիմնական URL-ում։

```bash
# OpenAI-style catalog alias
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# OpenAI-style chat aliases
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Ollama-style aliases
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```

Օրինակ՝

```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"}]}'
```

Նշումներ՝

- Token-ացված alias-ները կրկին օգտագործում են նույն մշակիչները, ինչ `/v1/*` և `/api/tags`-ը․ պատասխանների կառուցվածքները մնում են նույնական։
- Նախընտրելի է `Authorization: Bearer ...` տարբերակը, երբ հաճախորդն աջակցում է անհատական վերնագրերին։
- URL-ի վրա հիմնված token-ները կարող են հայտնվել հակադարձ պրոքսիի մատյաններում, դիտարկիչի պատմության մեջ և OmniRoute-ից դուրս իրականացվող հեռաչափության տվյալներում։ Դրանց վերաբերվեք որպես համատեղելիության տարբերակի, ոչ թե նույնականացման լռելյայն եղանակի։

---

## Հեռաչափում

```bash
# Ստանալ ուշացման հեռաչափության ամփոփում (p50/p95/p99 յուրաքանչյուր մատակարարի համար)
GET /api/telemetry/summary
```

**Պատասխան․**

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

---

## Բյուջե

```bash
# Ստանալ բյուջեի կարգավիճակը բոլոր API բանալիների համար
GET /api/usage/budget

# Սահմանել կամ թարմացնել բյուջեն
POST /api/usage/budget
Content-Type: application/json

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

> **Սխեմայի նշումներ** (`setBudgetSchema`). `apiKeyId`-ը պարտադիր է. `dailyLimitUsd`, `weeklyLimitUsd` կամ `monthlyLimitUsd` դաշտերից առնվազն մեկը պետք է զրոյից մեծ լինի։ Ընտրովի դաշտեր՝ `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`)։ Հին `{keyId, limit, period}` ձևաչափը վերադարձնում է `400 Bad Request`։

## Տոկենների սահմանաչափեր

Յուրաքանչյուր API բանալիի համար **token** բյուջեները (տարբերվում են վերևում նշված՝ ԱՄՆ դոլարի վրա հիմնված Budget-ից)։ Սահմանաչափերը կիրառվում են հարցման ուղու վրա․ երբ բանալու ընթացիկ պատուհանի օգտագործումը հասնում է իր սահմանաչափին, հարցումները մերժվում են `429 Too Many Requests`-ով։ Սահմանաչափերը կարող են սահմանվել կոնկրետ `model`-ի, `provider`-ի համար կամ կիրառվել բանալու նկատմամբ ամբողջությամբ՝ `global` ձևով․ երբ մի քանի սահմանաչափեր համապատասխանում են հարցմանը, կիրառվում է ամենախիստը։

```bash
# Ցուցադրել բանալու տոկենների սահմանաչափերը (ներառում է ընթացիկ պատուհանի օգտագործումը)
GET /api/usage/token-limits?apiKeyId=key-123

# Ստեղծել կամ թարմացնել տոկենի սահմանաչափ
POST /api/usage/token-limits
Content-Type: application/json

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

# Ջնջել տոկենի սահմանաչափն ըստ id-ի
DELETE /api/usage/token-limits?id=tl-abc
```

> **Schema notes** (`setTokenLimitSchema`)․ `apiKeyId` և `scopeType` (`model` | `provider` | `global`) դաշտերը պարտադիր են։ `scopeValue`-ը պարտադիր է, եթե `scopeType`-ը `global` չէ (օրինակ՝ մոդելի id՝ `model` սահմանման դեպքում, մատակարարի id՝ `provider` սահմանման դեպքում)։ `tokenLimit`-ը պետք է լինի դրական ամբողջ թիվ (տողից վերածվում է թվի)։ Ընտրովի դաշտեր՝ `id` (ստեղծելիս բաց թողնել, թարմացնելիս տրամադրել), `resetInterval` (`daily` | `weekly` | `monthly`, լռելյայն՝ `monthly`), `resetTime` (`HH:MM`), `enabled` (լռելյայն՝ `true`)։ `GET` պատասխանները յուրաքանչյուր սահմանաչափը լրացնում են `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` և `nextResetAt` դաշտերով։ Սա կառավարման դասի endpoint է (նույնականացումը կենտրոնացված կերպով պարտադրվում է authz խողովակաշարի կողմից)։

## Հարցումների մշակում

1. Հաճախորդը հարցում է ուղարկում `/v1/*`
2. Երթուղու մշակիչը կանչում է `handleChat`, `handleEmbedding`, `handleAudioTranscription` կամ `handleImageGeneration`
3. Մոդելը որոշվում է (ուղղակի մատակարար/մոդել կամ alias/combo)
4. Տեղային DB-ից ընտրվում են հավատարմագրերը՝ հաշվի հասանելիության զտմամբ
5. Chat-ի համար՝ `handleChatCore`-ը ստուգում է semantic/signature cache-ը և որոշում combo-ի սեղմման կարգավորումները
6. Երբ միացված է, մատակարարին թարգմանելուց առաջ գործարկվում է պրոակտիվ սեղմումը (`lite`, Caveman, RTK կամ stacked)
7. Մատակարարի executor-ը ուղարկում է upstream հարցումը
8. Պատասխանը թարգմանվում է հաճախորդի ձևաչափով (chat-ի դեպքում) կամ վերադարձվում է անփոփոխ (embeddings/images/audio)
9. Գրանցվում են օգտագործումը, սեղմման վերլուծական տվյալները և հարցումների մատյանները
10. Սխալների դեպքում կիրառվում է fallback-ը՝ combo-ի կանոնների համաձայն

Ամբողջական ճարտարապետական հղում՝ [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)

---

## Combo-ի կառավարում

Ավելի բարձր մակարդակի երթուղման combo-ները (որոնք արդեն ամփոփված են `/api/combos*` բաժնում) նույնպես կարող են 1:1 քարտեզագրվել մոդելի id-ի օրինաչափությունից՝ թույլ տալով OpenAI-ի ոճի մոդելի id-ն անտեսանելի կերպով վերահղել combo-ի։

| Method | Path                             | Description                                                                          |
| ------ | -------------------------------- | ------------------------------------------------------------------------------------ |
| GET    | `/api/model-combo-mappings`      | Ցուցադրել model→combo բոլոր քարտեզագրումները                                         |
| POST   | `/api/model-combo-mappings`      | Ստեղծել քարտեզագրում — body՝ `{pattern, comboId, priority?, enabled?, description?}` |
| GET    | `/api/model-combo-mappings/[id]` | Ստանալ մեկ քարտեզագրում                                                              |
| PUT    | `/api/model-combo-mappings/[id]` | Թարմացնել առկա քարտեզագրման դաշտերը                                                  |
| DELETE | `/api/model-combo-mappings/[id]` | Հեռացնել քարտեզագրումը                                                               |

**Auth:** կառավարման սեսիա/API բանալի (`requireManagementAuth`)։

---

## Վեբհուքներ

OmniRoute-ի իրադարձությունների համար ելքային վեբհուքների բաժանորդագրություններ (հարցման ավարտ, քվոտայի սպառում, բանալու ռոտացիա և այլն)։

| Մեթոդ  | Ճանապարհ                  | Նկարագրություն                                                              |
| ------ | ------------------------- | --------------------------------------------------------------------------- |
| GET    | `/api/webhooks`           | Ցուցադրել վեբհուքները (գաղտնիքները քողարկված են՝ `<prefix>...`)             |
| POST   | `/api/webhooks`           | Ստեղծել վեբհուք — մարմին՝ `{url, events?: ["*"], secret?, description?}`    |
| GET    | `/api/webhooks/[id]`      | Ստանալ վեբհուքը                                                             |
| PUT    | `/api/webhooks/[id]`      | Թարմացնել url/events/secret/description                                     |
| DELETE | `/api/webhooks/[id]`      | Հեռացնել վեբհուքը                                                           |
| POST   | `/api/webhooks/[id]/test` | Ուղարկել թեստային payload վեբհուքի URL-ին և վերադարձնել առաքման կարգավիճակը |

**Նույնականացում․** կառավարման սեսիա/API բանալի (`requireManagementAuth`)։

---

## Գրանցված բանալիներ (ավտոմատ կառավարում)

Օգտագործվում է բանալիների ավտոմատ կառավարման ենթահամակարգի կողմից՝ պահուստային մատակարարի/հաշվի համար API բանալիներ տրամադրելու և ռոտացիայի ենթարկելու նպատակով՝ օրական/ժամային քվոտաներով։

| Մեթոդ  | Ճանապարհ                              | Նկարագրություն                                                                                                                                                                                                                   |
| ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/registered-keys`             | Ցուցադրել գրանցված բանալիները (միայն քողարկված նախածանցը)                                                                                                                                                                        |
| POST   | `/api/v1/registered-keys`             | Թողարկել նոր գրանցված բանալի — մարմին՝ `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`։ Հում բանալին վերադարձվում է **միայն մեկ անգամ**։ Քվոտայի մերժման դեպքում վերադարձնում է `429`։ |
| GET    | `/api/v1/registered-keys/[id]`        | Ստանալ գրանցված բանալու մետատվյալները (հում նյութ չի տրամադրվում)                                                                                                                                                                |
| DELETE | `/api/v1/registered-keys/[id]`        | Չեղարկել գրանցված բանալին                                                                                                                                                                                                        |
| POST   | `/api/v1/registered-keys/[id]/revoke` | Բացահայտ չեղարկման վերջնակետ (նույն ազդեցությունն ունի, ինչ DELETE-ը)                                                                                                                                                            |

**Նույնականացում․** կառավարման սեսիա/API բանալի (`requireManagementAuth`) — նույն պաշտպանությունն է, ինչ `/api/keys`-ի համար՝ dashboard-ի սեսիա, տեղական CLI թոքեն կամ `manage`/`admin` scope-ով API բանալի․ միայն inference-ի համար նախատեսված API բանալիները ստանում են `403`։ Տես նաև `/v1/quotas/check` և `/v1/issues/report`։

---

## Գործակալների արձանագրություն

Ամպային գործակալի առաջադրանքներ (`Claude Code`, `Codex Cloud`, `OpenHands` և այլն), որոնք հեռակա կարգով կատարվում են OmniRoute-ի օգտատերերի անունից։

| Method | Path                          | Description                                                                                                                                                                          |
| ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/v1/agents/tasks`        | Ցուցադրել առաջադրանքները — կամընտիր `?provider=`, `?status=`, `?limit=` (1–500, լռելյայն՝ 50)                                                                                        |
| POST   | `/api/v1/agents/tasks`        | Ստեղծել առաջադրանք — մարմինը վավերացվում է `CreateCloudAgentTaskSchema`-ով (`providerId`, `prompt`, `source`, `options?`)։ Վերադարձնում է առաջադրանքի envelope-ը՝ `201` կարգավիճակով |
| DELETE | `/api/v1/agents/tasks?id=...` | Ջնջել առաջադրանքը                                                                                                                                                                    |
| GET    | `/api/v1/agents/tasks/[id]`   | Կարդալ առաջադրանքը — համաժամանակորեն թարմացնում է կարգավիճակը վերին հոսքի ամպային գործակալից, երբ սահմանված է `external_id`                                                          |
| POST   | `/api/v1/agents/tasks/[id]`   | Տարբերակված գործողություն՝ `{action: "approve"}`, `{action: "message", message}` կամ `{action: "cancel"}`                                                                            |
| DELETE | `/api/v1/agents/tasks/[id]`   | Ջնջել կոնկրետ առաջադրանքն ըստ id-ի                                                                                                                                                   |

> **Նույնականացում․** կառավարման նույնականացումը պարտադիր է յուրաքանչյուր մեթոդի համար (`requireCloudAgentManagementAuth`)։ Մինչև v3.8.0-ը այս մեթոդները նույնականացում չէին պահանջում․ տես `588a0333` commit-ը՝ խախտող փոփոխության մանրամասների համար։

```bash
# Ստեղծել Claude Code ամպային առաջադրանք
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'
```

---

## Կառավարման պրոքսիներ

Ելքային HTTP(S)/SOCKS պրոքսիներ, որոնք կարող են վերագրվել պրովայդերներին, հաշիվներին կամ կիրառվել գլոբալ մակարդակում։

| Method | Path                                         | Description                                                                                                                                                     |
| ------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/management/proxies`                 | Ցուցադրել պրոքսիները (`?id=`-ի միջոցով վերադարձվում է մեկը, իսկ `?id=&where_used=1`-ի միջոցով՝ նշանակումների գրաֆիկը)                                           |
| POST   | `/api/v1/management/proxies`                 | Ստեղծել պրոքսի — մարմինը վավերացվում է `createProxyRegistrySchema`-ով                                                                                           |
| PATCH  | `/api/v1/management/proxies`                 | Թարմացնել պրոքսին — մարմինը վավերացվում է `updateProxyRegistrySchema`-ով (պահանջվում է `id`)                                                                    |
| DELETE | `/api/v1/management/proxies?id=...&force=1`  | Ջնջել պրոքսին (`force=1`-ը կիրառվում է նշանակումները անջատելու համար)                                                                                           |
| GET    | `/api/v1/management/proxies/assignments`     | Ցուցադրել նշանակումները — հնարավոր է զտել ըստ `proxy_id`, `scope`, `scope_id`-ի․ փոխանցեք `resolve_connection_id=<id>`՝ կապի համար ակտիվ պրոքսին որոշելու համար |
| PUT    | `/api/v1/management/proxies/assignments`     | Վերագրել — մարմինը վավերացվում է `proxyAssignmentSchema`-ով (`{scope, scopeId?, proxyId?}`)։ Մաքրում է dispatcher-ի քեշը                                        |
| PUT    | `/api/v1/management/proxies/bulk-assign`     | Խմբաքանակով վերագրել — մարմինը վավերացվում է `bulkProxyAssignmentSchema`-ով (`{scope, scopeIds[], proxyId?}`)                                                   |
| GET    | `/api/v1/management/proxies/health?hours=24` | Ամփոփել պրոքսիի առողջական վիճակը (հաջողությունների/ձախողումների քանակ, ուշացում) նշված ժամանակահատվածում                                                        |

**Նույնականացում․** կառավարման սեսիան/API բանալին պարտադիր է յուրաքանչյուր երթուղու համար (`requireManagementAuth`)։

> Առաջադրանքի նկարագրության մեջ նշված `POST /api/v1/management/proxies/[id]/assignments` և `POST /api/v1/management/proxies/[id]/health` հարցումները սպասարկվում են վերևում ցուցադրված հարթ `/assignments` և `/health` երթուղիներով․ կոդերի բազայում ըստ id-ի ենթաերթուղիներ չկան։

---

## Ճկունություն (ընդլայնված)

OmniRoute-ը տրամադրում է ժամանակավոր խափանումների կառավարման երեք անկախ մեխանիզմ․ ստորև ներկայացված կառավարման endpoint-ները թույլ են տալիս օպերատորներին կարդալ և վերասահմանել դրանց արժեքները։

| Տիրույթ             | Վիճակի պահպանում                                | Ընթերցում                                 | Վերականգնում / մաքրում                                              |
| ------------------- | ----------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------- |
| Մատակարարի անջատիչ  | `domain_circuit_breakers` + հիշողության մեջ     | `/api/monitoring/health`                  | `POST /api/resilience/reset`                                        |
| Միացման սառեցում    | Մատակարարի միացումների վրա `rateLimitedUntil`   | `/api/rate-limits`, `/api/providers/[id]` | (վերամիացվում է ծույլ եղանակով․ մաքրումը՝ մատակարարի PUT-ի միջոցով) |
| Մոդելի արգելափակում | Հիշողության մեջ մոդելների հասանելիության ռեեստր | `GET /api/resilience/model-cooldowns`     | `DELETE /api/resilience/model-cooldowns`                            |

`PATCH /api/resilience`-ը ընդունում է մատակարարի անջատիչի վերասահմանումներ՝ `providerBreaker.oauth` և `providerBreaker.apikey` դաշտերի ներքո։ Յուրաքանչյուր պրոֆիլ աջակցում է `degradationThreshold`, `failureThreshold` և `resetTimeoutMs` դաշտերին․ նույն դաշտերը հասանելի են նաև Կառավարման վահանակ → Կարգավորումներ → Ճկունություն բաժնում։

```bash
# Մաքրել մեկ մոդելի արգելափակումը
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o-mini"}'

# Մաքրել բոլոր արգելափակումները
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'
```

Ամբողջական հայեցակարգային տեղեկանքի և անջատիչի լռելյայն արժեքների համար տես [`CLAUDE.md`](../../CLAUDE.md) → «Resilience Runtime State» և [`docs/architecture/RESILIENCE_GUIDE.md`](../architecture/RESILIENCE_GUIDE.md)։

### Rate-Limit հերթ և ավտոմատ միացման անվտանգության մեխանիզմ

- **Գրառման աջակցվող ուղի**․ `POST /api/rate-limits`՝ `{"connectionId": "<id>", "enabled": true|false}` մարմնով, աջակցվող կառավարման endpoint-ն է՝ միացման համար rate-limit պաշտպանությունը միացնելու կամ անջատելու նպատակով։ `PUT /api/providers/[id]`-ը միտումնավոր չի փոփոխում և չի փոխում `rateLimitProtection`-ի արժեքը (#11278)։
- **`enabled: false`-ի իմաստը**․ `enabled: false` արժեքը հեռացնում է միացման բացահայտ պաշտպանությունը, սակայն **ակտիվ API-key միացումը չի հանում գլոբալ ավտոմատ միացման անվտանգության մեխանիզմից (`autoEnableApiKeyProviders = true`)**։ `reconcileEnabledConnections`-ում (`open-sse/services/rateLimitManager.ts`) `false` և `undefined` արժեքները համարժեք են․ առանց բացահայտ պաշտպանության ակտիվ API-key միացումները շարունակում են պաշտպանված մնալ ավտոմատ միացման անվտանգության մեխանիզմի ներքո։
- **Գլոբալ անջատում**․ API-key միացումները rate-limit հերթերի առանց գործարկելու համար գլոբալ անջատեք անվտանգության մեխանիզմը՝ `RATE_LIMIT_AUTO_ENABLE=false` (env) կամ `resilienceSettings.requestQueue.autoEnableApiKeyProviders = false` (Կարգավորումներ → Ճկունություն / `PATCH /api/resilience`) միջոցով։

---

## Հմտություններ

OmniRoute-ը հատուկ գործարկվող մշակիչներով ընդլայնելու հմտությունների շրջանակ, ինչպես նաև marketplace-ի ինտեգրումներ։

| Մեթոդ  | Ուղի                              | Նկարագրություն                                                                                                                   |
| ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`                     | Տեղադրված հմտությունների ցանկ — զտելի է ըստ `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, էջավորումով       |
| GET    | `/api/skills/[id]`                | Ստանալ մեկ հմտություն                                                                                                            |
| PUT    | `/api/skills/[id]`                | Թարմացնել հմտությունը (անուն, նկարագրություն, ռեժիմ, սխեմա, մշակիչ, պիտակներ)                                                    |
| DELETE | `/api/skills/[id]`                | Ապատեղադրել հմտությունը                                                                                                          |
| POST   | `/api/skills/install`             | Տեղադրել հմտություն չմշակված մանիֆեստից — մարմին՝ `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
| GET    | `/api/skills/executions`          | Ցուցադրել հմտությունների վերջին գործարկումները (աուդիտի հետք՝ մուտքերով/ելքերով/տևողությամբ)                                     |
| GET    | `/api/skills/marketplace?q=...`   | Որոնել/ցուցադրել հանրահայտ ցանկը SkillsMP marketplace-ից (`skillsmpApiKey` կարգավորումը պարտադիր է)                              |
| POST   | `/api/skills/marketplace/install` | Տեղադրել հմտություն SkillsMP-ի նույնացուցիչով                                                                                    |
| GET    | `/api/skills/skillssh?q=&limit=`  | Որոնել skills.sh ռեեստրում                                                                                                       |
| POST   | `/api/skills/skillssh/install`    | Տեղադրել հմտություն skills.sh-ի նույնացուցիչով                                                                                   |

**Նույնականացում․** կառավարման սեսիա/API key։ Marketplace-ի որոնման երթուղիներն ընդունում են կամ կառավարման նույնականացում, կամ Bearer API key (`isAuthenticated`)։

---

## Հիշողություն

Մշտական խոսակցական/փաստային հիշողության պահոց՝ API բանալիի / սեսիայի շրջանակում։

| Մեթոդ  | Ուղի                 | Նկարագրություն                                                                                                                    |
| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/memory`        | Հիշողությունների ցուցակ — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, `offset/limit` կամ `page/limit` էջավորում                 |
| POST   | `/api/memory`        | Հիշողության ստեղծում — մարմինը վավերացվում է Zod-ի միջոցով՝ `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET    | `/api/memory/[id]`   | Մեկ հիշողության ստացում                                                                                                           |
| DELETE | `/api/memory/[id]`   | Հիշողության ջնջում                                                                                                                |
| GET    | `/api/memory/health` | Հիշողության ենթահամակարգի առողջական վիճակ (ՏԲ կապակցվածություն, embedding-ների backend, վեկտորային ինդեքսի կարգավիճակ)            |

**Նույնականացում․** կառավարման սեսիա/API բանալի (`requireManagementAuth`)։ `type` enum՝ `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (տե՛ս `MemoryType`-ը՝ `src/lib/memory/types.ts`-ում)։

---

## MCP սերվեր

OmniRoute-ը ներառում է ներկառուցված Model Context Protocol սերվեր՝ 3 տրանսպորտային եղանակներով (stdio, SSE, streamable-http) և սահմանափակված գործիքներով։ Ստորև ներկայացված dashboard-ի endpoint-ները կարդում են կարգավիճակի/աուդիտի տվյալները և պրոքսավորում HTTP տրանսպորտները։

| Մեթոդ  | Ուղի                   | Նկարագրություն                                                                                                       |                      |
| ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------- | -------------------- |
| GET    | `/api/mcp/status`      | Սրտի զարկ, տրանսպորտ, առցանց վիճակ, վերջին կանչ, առաջատար գործիքներ, 24-ժամյա հաջողության մակարդակ                   |
| GET    | `/api/mcp/tools`       | MCP գործիքների ցանկ՝ `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` դաշտերով              |
| GET    | `/api/mcp/sse`         | SSE տրանսպորտի համար SSE հոսքի բացում (վերադարձնում է `503`, եթե MCP-ն անջատված է կամ տրանսպորտը չի համապատասխանում) |
| POST   | `/api/mcp/sse`         | JSON-RPC frame-ի ուղարկում SSE տրանսպորտով                                                                           |
| GET    | `/api/mcp/stream`      | Streamable HTTP տրանսպորտի SSE կողմի բացում (սերվերի կողմից նախաձեռնված հաղորդագրություններ)                         |
| POST   | `/api/mcp/stream`      | JSON-RPC frame-ի ուղարկում Streamable HTTP տրանսպորտով                                                               |
| DELETE | `/api/mcp/stream`      | Streamable HTTP սեսիայի ավարտում                                                                                     |
| GET    | `/api/mcp/audit`       | Աուդիտի մատյանի հարցում — `?limit=`, `?offset=`, `?tool=`, `?success=true                                            | false`, `?apiKeyId=` |
| GET    | `/api/mcp/audit/stats` | Աուդիտի վիճակագրության համախմբում (ընդհանուր քանակներ, հաջողության մակարդակ, միջին տևողություն, առաջատար գործիքներ)  |

**Նույնականացում․** `sse`/`stream` տրանսպորտները կիրառում են MCP-ին հատուկ նույնականացման մակերեսը (Bearer API բանալի՝ `mcp` scope-ով), իսկ `status`/`tools`/`audit*` երթուղիները հասանելի են dashboard-ից (dashboard host-ին հասանելիությունից բացի լրացուցիչ նույնականացում չի պահանջվում)։

> Երկու HTTP տրանսպորտներն էլ սահմանափակվում են `settings.mcpEnabled` և `settings.mcpTransport` կարգավորումներով — տրանսպորտի անհամապատասխանությունը վերադարձնում է `400`, իսկ MCP-ի անջատված վիճակը՝ `503`։

---

## A2A սերվեր

OmniRoute-ը տրամադրում է A2A (Agent-to-Agent) JSON-RPC 2.0 վերջնակետ, ինչպես նաև REST wrapper՝ ստուգման/վահանակի օգտագործման համար։

### JSON-RPC

```bash
POST /a2a
Authorization: Bearer your-api-key   # կամընտիր է, եթե OMNIROUTE_API_KEY սահմանված չէ
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Route this coding task"}]
  }
}
```

Աջակցվող մեթոդները (բոլորը հասանելի են միայն `settings.a2aEnabled`-ի միացված լինելու դեպքում)․

| Մեթոդ            | Նկարագրություն                                                                 |
| ---------------- | ------------------------------------------------------------------------------ |
| `message/send`   | Հմտության համաժամանակյա կատարում, վերադարձնում է `{task, artifacts, metadata}` |
| `message/stream` | Նույն հմտությունների SSE հոսքային կատարում                                     |
| `tasks/get`      | Ստանում է առաջադրանքն ըստ `taskId`                                             |
| `tasks/cancel`   | Չեղարկում է առաջադրանքն ըստ `taskId`                                           |

Ներկառուցված հմտություններ՝ `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`։

### Agent Card

```bash
GET /.well-known/agent.json
```

Վերադարձնում է հանրային A2A agent card-ը (անուն, նկարագրություն, հնարավորություններ, հմտությունների կատալոգ, նույնականացման սխեմա)․ այն հանրային կերպով պահվում է քեշում 1 ժամ։ Նույնականացում չի պահանջվում։

### REST օգնականներ

| Մեթոդ | Ուղի                         | Նկարագրություն                                                                                                           |
| ----- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| GET   | `/api/a2a/status`            | A2A-ի միացված լինելը + առաջադրանքների վիճակագրություն + քեշավորված agent card-ի ամփոփում                                 |
| GET   | `/api/a2a/tasks`             | Առաջադրանքների ցանկ — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST  | `/api/a2a/tasks`             | (Չի իրականացվում որպես REST օգնական — ստեղծեք JSON-RPC `message/send`-ի միջոցով)                                         |
| GET   | `/api/a2a/tasks/[id]`        | Ստանում է մեկ առաջադրանք                                                                                                 |
| POST  | `/api/a2a/tasks/[id]/cancel` | Չեղարկում է առաջադրանքը                                                                                                  |

**Նույնականացում․** REST օգնականներն աշխատում են առանց կառավարման նույնականացման (տեսանելի են վահանակից)․ JSON-RPC `/a2a` ուղին օգտագործում է Bearer `OMNIROUTE_API_KEY`-ը, եթե այն կազմաձևված է։

---

## Cloud, Evals և Assess

| Մեթոդ | Ուղի | Նկարագրություն |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Ստուգում է Bearer բանալին և վերադարձնում է քողարկված մատակարարների միացումները և մոդելների այլանունները՝ cloud sync հաճախորդների համար |
| POST | `/api/cloud/credentials/update` | Թարմացնում է cloud-ի հետ համաժամեցվող մատակարարի գաղտնագրված հավատարմագրերը |
| POST | `/api/cloud/model/resolve` | Տեղային երթուղման աղյուսակի միջոցով տրամաբանական մոդելի ID-ն համապատասխանեցնում է կոնկրետ մատակարարի/մոդելի |
| GET | `/api/cloud/models/alias` | Ցուցադրում է մոդելների այլանունները՝ cloud sync-ի համար բացահայտված ձևով |
| GET | `/api/assess` | Կարդում է գնահատման վերջին դասակարգումները (ըստ մատակարարի/մոդելի) |
| POST | `/api/assess` | Գործարկում է գնահատում — body՝ `{scope: {type:"all"}                                                   | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Ցուցադրում է ներկառուցված eval փաթեթները և վերջին գործարկումները |
| POST | `/api/evals` | Գործարկում է eval |
| POST | `/api/evals/suites` | Ստեղծում է անհատական eval փաթեթ — body-ն վավերացվում է `evalSuiteSaveSchema`-ի միջոցով |
| GET | `/api/evals/suites/[id]` | Ստանում է անհատական eval փաթեթ |

**Նույնականացում․** `/api/cloud/auth`-ը ուղղակիորեն վավերացնում է Bearer բանալին և յուրաքանչյուր միացման համար վերադարձնում է քողարկված բանալին ու `projectId`-ը միայն այն բանալու դեպքում, որն ունի `manage` / `admin` scope․ մյուս `/api/cloud/*`, `/api/evals/*` և `/api/assess` ուղիները պահանջում են կառավարման սեսիա/API բանալի։ `/api/assess` POST-ն օգտագործում է `validateBody`՝ scope-ի discriminated-union սխեմայով։

---

## ACP (Agent Client Protocol) կառավարում

որպես child գործընթացներ։ Այս endpoint-ները կառավարում են ACP գործակալների
հայտնաբերումն ու անհատական գործակալների գրանցումը։

| Մեթոդ  | Ճանապարհ          | Նկարագրություն                                                                                                                                               |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/acp/agents` | Ցուցադրել բոլոր հայտնի CLI գործակալները (ներկառուցված + անհատական)՝ տեղադրման կարգավիճակով, տարբերակով և երկուական ֆայլով                                    |
| POST   | `/api/acp/agents` | Գրանցել անհատական ACP գործակալ կամ թարմացնել քեշը — body՝ `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` կամ `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Հեռացնել անհատական ACP գործակալը — query param՝ `?id=<agentId>`                                                                                              |

**Պատասխանի օրինակ** (`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
}
```

**Նույնականացում:** Պահանջվում է կառավարման սեսիա (dashboard `auth_token` cookie) կամ կառավարման շրջանակով API բանալի։

Ամբողջական մանրամասների համար տե՛ս [ACP Framework](../frameworks/ACP.md)-ը։

---

## Վերլուծություն և դիտարկելիություն

Իրական ժամանակի վերլուծության endpoint-ներ՝ երթուղավորումը, սեղմումն ու մատակարարների բազմազանությունը մշտադիտարկելու համար։ Սրանք ապահովում են `/dashboard/analytics/*` էջերի աշխատանքը։

### Ավտոմատ երթուղավորման վերլուծություն

| Մեթոդ | Ճանապարհ                             | Նկարագրություն                                                                                                                                  |
| ----- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/analytics/auto-routing`        | Ավտոմատ երթուղավորման համախառն վիճակագրություն՝ կանչերի ընդհանուր թիվ, ռազմավարությունների բաշխում, մակարդակների բաշխում, առաջատար մատակարարներ |
| GET   | `/api/analytics/auto-routing?days=7` | Ժամանակային պատուհանով վիճակագրություն (կանխադրվածը՝ 24 ժամ)                                                                                    |

**Պատասխանի օրինակ**:

```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 }
  ]
}
```

### Սեղմման վերլուծություն

| Մեթոդ | Ճանապարհ                     | Նկարագրություն                                                                                                |
| ----- | ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/analytics/compression` | Սեղմման համախառն վիճակագրություն՝ խնայված թոքեններ, խնայողության %, ռեժիմների բաշխում, շարժիչների օգտագործում |

**Պատասխանի օրինակ**:

```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
  }
}
```

### Մատակարարների բազմազանության մշտադիտարկում

| Մեթոդ | Ճանապարհ                   | Նկարագրություն                                                                                                                       |
| ----- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| GET   | `/api/analytics/diversity` | Շանոնի էնտրոպիայի վրա հիմնված բազմազանության մշտադիտարկում․ կանխում է խափանման առանձին կետերը՝ չափելով մատակարարների բաշխվածությունը |

**Պատասխանի օրինակ**:

```json
{
  "window": "24h",
  "shannonEntropy": 2.45,
  "maxEntropy": 3.17,
  "diversityRatio": 0.77,
  "providerUsage": {
    "openai": 0.4,
    "anthropic": 0.25,
    "google": 0.2,
    "kiro": 0.15
  },
  "warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"]
}
```

**Նույնականացում:** Պահանջվում է կառավարման սեսիա կամ կառավարման շրջանակով API բանալի։

---

## Ադմինիստրատիվ գործողություններ

Միայն ադմինիստրատորների համար նախատեսված վերջնակետեր՝ գործառնական կառավարման նպատակով։

| Մեթոդ | Ճանապարհ                 | Նկարագրություն                                                                                                |
| ----- | ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/admin/concurrency` | Կարդալ համաժամանակության ընթացիկ սահմանաչափերը (գլոբալ + յուրաքանչյուր մատակարարի համար)                      |
| POST  | `/api/admin/concurrency` | Թարմացնել համաժամանակության սահմանաչափերը — մարմին՝ `{global?: number, perProvider?: Record<string, number>}` |

**Նույնականացում․** Պահանջվում է ադմինիստրատորի տիրույթով կառավարման սեսիա։

---

## CLI գործիքների կառավարում

Կառավարել OmniRoute-ի հետ ինտեգրվող CLI գործիքները (antigravity, commandCode,
devin-cli և այլն)։ Ամբողջական ցանկի համար տե՛ս [Մատակարարների տեղեկատու](./PROVIDER_REFERENCE.md)։

| Մեթոդ | Ճանապարհ                                | Նկարագրություն                                                                                                                                                                        |
| ----- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/cli-tools/all-statuses`           | Բոլոր CLI գործիքների կարգավիճակը (տեղադրված լինելը, տարբերակը, վերջին հայտնվելը)                                                                                                      |
| GET   | `/api/cli-tools/status`                 | Մեկ CLI գործիքի կարգավիճակի մանրամասները (`?tool=` հարցման պարամետր)                                                                                                                  |
| POST  | `/api/cli-tools/apply`                  | Գրել գործիքի գեներացված կազմաձևը (`dryRun`-ը նախադիտում է ցուցադրում, կոնտեյներացված լինելու դեպքում՝ `422` + `containerEphemeralTarget`, իսկ `migration`-ը նշում է հին Codex YAML-ը) |
| GET   | `/api/cli-tools/backups`                | Ցուցադրել CLI գործիքների կազմաձևերի պահուստային պատճենները                                                                                                                            |
| POST  | `/api/cli-tools/backups`                | Ստեղծել բոլոր CLI գործիքների կազմաձևերի պահուստային պատճենը                                                                                                                           |
| POST  | `/api/cli-tools/backups`                | Վերականգնել․ նույն վերջնակետը՝ մարմնում `{tool, backupId}` պարամետրերով, վերականգնում է տվյալ պահուստային պատճենը                                                                     |
| GET   | `/api/cli-tools/antigravity-mitm`       | Antigravity MITM պրոքսիի կարգավիճակը («antigravity-mitm» CLI գործիքը)                                                                                                                 |
| POST  | `/api/cli-tools/antigravity-mitm/alias` | Կազմաձևել antigravity-mitm կեղծանունները                                                                                                                                              |

**Նույնականացում․** Պահանջվում է կառավարման սեսիա։

---

## Agent հմտություններ

Կառավարել AI agent-ների հմտությունները (նման են OpenAI-ի custom GPT-ներին, բայց նախատեսված են agent-ների համար)։

| Մեթոդ  | Ճանապարհ                     | Նկարագրություն                                                                                  |
| ------ | ---------------------------- | ----------------------------------------------------------------------------------------------- |
| GET    | `/api/agent-skills`          | Ցուցադրել agent-ների բոլոր հմտությունները (ներկառուցված + custom)                               |
| GET    | `/api/agent-skills/[id]`     | Ստանալ կոնկրետ agent-ի հմտությունը                                                              |
| POST   | `/api/agent-skills`          | Ստեղծել custom agent-ի հմտություն — մարմին՝ `{name, description, prompt, model?, temperature?}` |
| PUT    | `/api/agent-skills/[id]`     | Թարմացնել custom agent-ի հմտությունը                                                            |
| DELETE | `/api/agent-skills/[id]`     | Ջնջել custom agent-ի հմտությունը                                                                |
| GET    | `/api/agent-skills/[id]/raw` | Ստանալ չմշակված prompt-ը + մետատվյալները (առանց կատարման)                                       |
| POST   | `/api/agent-skills/generate` | Բնական լեզվով նկարագրությունից AI-ի միջոցով ստեղծել նոր հմտություն                              |

**Նույնականացում․** Պահանջվում է կառավարման սեսիա կամ կառավարման ընդգրկմամբ API բանալի։

---

## Քեշի կառավարում

Կառավարեք իմաստային քեշը և տրամաբանության քեշը։

| Մեթոդ  | Ճանապարհ               | Նկարագրություն                                                                                                             |
| ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cache`           | Քեշի ընդհանուր պատկերը՝ գրառումների ընդհանուր քանակը, հարվածների հաճախականությունը, սկավառակի վրա զբաղեցրած չափը           |
| GET    | `/api/cache/entries`   | Քեշավորված գրառումների ցանկ (էջավորումով)                                                                                  |
| DELETE | `/api/cache/entries`   | Քեշի գրառումների ջնջում (զտում հարցման պարամետրերով)                                                                       |
| GET    | `/api/cache/stats`     | Քեշի մանրամասն վիճակագրություն (ըստ մատակարարի և մոդելի)                                                                   |
| GET    | `/api/cache/reasoning` | Տրամաբանության քեշի կարգավիճակ (տրամաբանության վերարտադրման համար)                                                         |
| DELETE | `/api/cache/reasoning` | Մաքրել տրամաբանության քեշը — հարցման պարամետրեր՝ `?toolCallId=<id>` (մեկը), `?provider=<p>` կամ առանց պարամետրերի (բոլորը) |

**Նույնականացում․** Պահանջվում է կառավարման սեսիա։

---

## Հիշողության համակարգ

Կառավարեք պահպանվող հիշողությունը (FTS5 + վեկտորային ներդրումներ)։

| Մեթոդ  | Ճանապարհ           | Նկարագրություն                                                                                     |
| ------ | ------------------ | -------------------------------------------------------------------------------------------------- |
| GET    | `/api/memory`      | Հիշողության գրառումների ցանկ (զտում ըստ տիրույթի, տեսակի, որոնման հարցման)                         |
| POST   | `/api/memory`      | Ստեղծել հիշողության նոր գրառում — մարմին՝ `{scope, type, content, metadata?}`                      |
| GET    | `/api/memory/[id]` | Ստանալ հիշողության որոշակի գրառում                                                                 |
| PUT    | `/api/memory/[id]` | Թարմացնել հիշողության գրառումը                                                                     |
| DELETE | `/api/memory/[id]` | Ջնջել հիշողության գրառումը                                                                         |
| GET    | `/api/memory?q=`   | Որոնել հիշողության մեջ (FTS5 + վեկտորային որոնում) — վիճակագրությունը ներառված է նույն պատասխանում |

**Նույնականացում․** Պահանջվում է կառավարման սեսիա կամ կառավարման տիրույթով API բանալի։

---

## Վեբհուքներ

Կառավարեք իրադարձությունների համար վեբհուքի բաժանորդագրությունները։

| Մեթոդ  | Ճանապարհ                        | Նկարագրություն                                                                    |
| ------ | ------------------------------- | --------------------------------------------------------------------------------- |
| GET    | `/api/webhooks`                 | Վեբհուքի բոլոր բաժանորդագրությունների ցանկ                                        |
| POST   | `/api/webhooks`                 | Ստեղծել վեբհուքի բաժանորդագրություն — մարմին՝ `{url, events[], secret?, active?}` |
| GET    | `/api/webhooks/[id]`            | Ստանալ վեբհուքի որոշակի բաժանորդագրություն                                        |
| PUT    | `/api/webhooks/[id]`            | Թարմացնել վեբհուքի բաժանորդագրությունը                                            |
| DELETE | `/api/webhooks/[id]`            | Ջնջել վեբհուքի բաժանորդագրությունը                                                |
| GET    | `/api/webhooks/[id]/deliveries` | Վեբհուքի առաքումների պատմության ցանկ (հաջողության/ձախողման մատյան)                |
| POST   | `/api/webhooks/[id]/test`       | Ուղարկել թեստային իրադարձություն վեբհուքին                                        |

**Նույնականացում․** Պահանջվում է կառավարման սեսիա։

Ամբողջական իրադարձությունների տեսակների համար տե՛ս [Վեբհուքերի շրջանակ](../frameworks/WEBHOOKS.md)։

---

## Հմտությունների շրջանակ

Կառավարեք հմտությունները (գործակալական ընդլայնումների շրջանակը)։

| Method | Path                     | Description                                                                                  |
| ------ | ------------------------ | -------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`            | Տեղադրված բոլոր հմտությունների ցանկ (ներկառուցված + հատուկ)                                  |
| POST   | `/api/skills/install`    | Հմտության տեղադրում տեղական ուղուց կամ URL-ից                                                |
| DELETE | `/api/skills/[id]`       | Հմտության ապատեղադրում                                                                       |
| PUT    | `/api/skills/[id]`       | Հմտության միացում կամ անջատում — body: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST   | `/api/skills/executions` | Հմտության գործարկում — body: `{skillName, apiKeyId, input?, sessionId?}`                     |
| GET    | `/api/skills/executions` | Բոլոր հմտությունների գործարկումների պատմության ցանկ (`?apiKeyId=`-ով զտում)                  |

**Նույնականացում:** Պահանջվում է կառավարման սեսիա կամ կառավարման ընդգրկման API բանալի։

Լրիվ մանրամասների համար տե՛ս [Հմտությունների շրջանակը](../frameworks/SKILLS.md)։

---

## Պլագիններ

Կառավարեք OmniRoute-ի պլագինները (երրորդ կողմի ընդլայնումներ)։

| Method | Path                               | Description                  |
| ------ | ---------------------------------- | ---------------------------- |
| GET    | `/api/plugins`                     | Տեղադրված պլագինների ցանկ    |
| POST   | `/api/plugins/marketplace/install` | Պլագինի տեղադրում շուկայից   |
| DELETE | `/api/plugins/[name]`              | Պլագինի ապատեղադրում         |
| POST   | `/api/plugins/[name]/activate`     | Պլագինի ակտիվացում           |
| POST   | `/api/plugins/[name]/deactivate`   | Պլագինի ապաակտիվացում        |
| GET    | `/api/plugins/[name]/config`       | Պլագինի կազմաձևման ստացում   |
| PUT    | `/api/plugins/[name]/config`       | Պլագինի կազմաձևման թարմացում |

**Նույնականացում:** Պահանջվում է կառավարման սեսիա։

Լրիվ մանրամասների համար տե՛ս [Պլագինների շրջանակը](../frameworks/PLUGIN_SDK.md)։

---

## Shadow երթուղավորում

Մատակարարների Shadow / A-B համեմատությունը **ինքնուրույն REST մակերես չէ** — այն կազմաձևվում է combo երթուղավորման միջոցով (տե՛ս [Auto-Combo](../routing/AUTO-COMBO.md))։ Յուրաքանչյուր combo-ի համեմատական չափորոշիչները տրամադրվում են `GET /api/combos/metrics`-ի միջոցով։

---

## Պաշտպանական մեխանիզմներ

Ստուգեք գործարկման ժամանակի պաշտպանական մեխանիզմները (PII-ի հայտնաբերում, prompt injection-ի հայտնաբերում, տեսողության կամրջում)։ Պաշտպանական մեխանիզմներն աշխատում են յուրաքանչյուր հարցման ժամանակ․ յուրաքանչյուր կանչի համար դրանք անջատելու հնարավորությունը տրամադրվում է `x-omniroute-disabled-guardrails` հարցման վերնագրի միջոցով — պահպանվող միացման/անջատման մակերես չկա։

| Method | Path                   | Description                                                                                                   |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/guardrails`      | Գրանցված պաշտպանական մեխանիզմների և դրանց կարգավիճակի ցանկ (անուն / միացված / առաջնահերթություն)              |
| POST   | `/api/guardrails/test` | Նախնական կանչի խողովակաշարի փորձնական գործարկում օրինակային մուտքի վրա — body: `{input, disabledGuardrails?}` |

**Նույնականացում:** Պահանջվում է կառավարման սեսիա։

Լրիվ մանրամասների համար տե՛ս [Անվտանգություն > Պաշտպանական մեխանիզմներ](../security/GUARDRAILS.md)։

---

---

## Նույնականացում

Տե՛ս [Կառավարման նույնականացում](../guides/MANAGEMENT-AUTH.md)՝ հավատարմագրերի չորս
ընտանիքների (վահանակի սեսիա, տեղային CLI տոկեն, `oma_live_…` Access Token, manage-ի շրջանակով API բանալի) և դրանց՝ inference բանալիներից տարբերությունների մասին։

- Վահանակի երթուղիները (`/dashboard/*`) օգտագործում են `auth_token` cookie
- Մուտքն օգտագործում է պահպանված գաղտնաբառի hash-ը, իսկ պահուստային տարբերակը՝ `INITIAL_PASSWORD`
- `requireLogin`-ը կարելի է փոխարկել `/api/settings/require-login`-ի միջոցով
- `/v1/*` երթուղիները կարող են պահանջել Bearer API բանալի, երբ `REQUIRE_API_KEY=true`
- «կառավարման տոկեն» / «կառավարման շրջանակով API բանալի» այս հղման մեջ նշանակում է այդ ուղեցույցում նկարագրված ընտանիքներից մեկը, ոչ թե չսահմանված գաղտնիքի լրացուցիչ տեսակ

> **Խախտող փոփոխություն (v3.8.0)** — `/api/v1/agents/tasks/*` և cooldown-ի կառավարման վերջնակետերն այժմ պահանջում են **կառավարման նույնականացում** (վահանակի `auth_token` cookie կամ կառավարման շրջանակով API բանալի)։ Հաճախորդները, որոնք նախկինում այս երթուղիները կանչում էին առանց նույնականացման, կստանան `401 Unauthorized`։ Տե՛ս commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`)։