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

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

1753 lines
202 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API Reference (မြန်မာ)
🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇳🇵 [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) | 🇨🇿 [Č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` မျက်နှာပြင်နှင့် အသုံးအများဆုံး စီမံခန့်ခွဲမှု endpoint များကို ဖော်ပြထားသည်။ စက်ဖြင့်ဖတ်ရှုနိုင်သော [`docs/openapi.yaml`](../openapi.yaml) နှင့် `src/app/api/` အောက်ရှိ route tree တို့သည် အပြည့်အစုံပါဝင်သော ကိုးကားရင်းမြစ်များဖြစ်သည်။
---
## မာတိကာ
- [ချတ် အပြီးသတ်ချက်များ](#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)
- [ဒက်ရှ်ဘုတ်နှင့် စီမံခန့်ခွဲမှု](#dashboard--management)
- [ပေါင်းစပ်မှု စီမံခန့်ခွဲခြင်း](#combo-management)
- [Webhooks](#webhooks)
- [မှတ်ပုံတင်ထားသော ကီးများ (အလိုအလျောက် စီမံခန့်ခွဲမှု)](#registered-keys-auto-management)
- [Agents ပရိုတိုကော](#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 များ
| Header | ဦးတည်ချက် | ဖော်ပြချက် |
| ------------------------ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache` | တောင်းဆိုချက် | ကက်ရှ်ကို ကျော်လွှားရန် `true` ဟု သတ်မှတ်ပါ |
| `x-omniroute-no-memory` | တောင်းဆိုချက် | ဤတောင်းဆိုချက်အတွက် မှတ်ဉာဏ်နှင့် ကျွမ်းကျင်မှုများ ထည့်သွင်းခြင်းကို ကျော်ရန် `true` ဟု သတ်မှတ်ပါ (ကက်ရှ်မသုံးခြင်းနှင့် အလားတူပြီး ခေါ်ဆိုမှုတစ်ခုချင်းစီ၏ တိုကင်/ကုန်ကျစရိတ် အပိုဝန်ကို ရှောင်ရှားပေးသည်) |
| `X-OmniRoute-Progress` | တောင်းဆိုချက် | တိုးတက်မှု အဖြစ်အပျက်များအတွက် `true` ဟု သတ်မှတ်ပါ |
| `X-Session-Id` | တောင်းဆိုချက် | ပြင်ပဆက်ရှင် ဆက်နွယ်မှုအတွက် မပြောင်းလဲသော ဆက်ရှင်ကီး |
| `x_session_id` | တောင်းဆိုချက် | အောက်မျဉ်းပါ မူကွဲကိုလည်း လက်ခံသည် (တိုက်ရိုက် HTTP) |
| `X-OmniRoute-Session-Id` | တောင်းဆိုချက် | ခေါ်ဆိုသူက ပေးထားသော ဆက်ရှင်/စကားဝိုင်း တဂ် (မှတ်ဉာဏ်သို့လည်း ဖြည့်သွင်းသည်)။ ပါရှိသည့်အခါ ဆက်ရှင်တစ်ခုချင်းစီအလိုက် ကုန်ကျစရိတ် ခွဲဝေတွက်ချက်နိုင်ရန် `call_logs.session_tag` သို့ မူရင်းအတိုင်း သိမ်းဆည်းသည် (#8249) — မပါရှိသည့်အခါ မည်သည့်အခါမျှ အလိုအလျောက် မဖန်တီးပါ |
| `Idempotency-Key` | တောင်းဆိုချက် | ထပ်နေမှုဖယ်ရှားရေး ကီး (5s အချိန်ကာလ) |
| `X-Request-Id` | တောင်းဆိုချက် | အခြားရွေးချယ်နိုင်သော ထပ်နေမှုဖယ်ရှားရေး ကီး |
| `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 ဖြစ်သည့်အခါ ကက်ရှ်ကြောင့် ရှောင်ရှားနိုင်ခဲ့သော USD ကုန်ကျစရိတ် (ကက်ရှ် hit များအတွက်သာ) |
| `X-OmniRoute-Decision` | တုံ့ပြန်ချက် | လမ်းကြောင်းရွေးချယ်မှု ခြေရာခံချက်- `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` သည် ပေါင်းစပ်မှု မဟာဗျူဟာဖြစ်ပြီး ပေါင်းစပ်မှုမဟုတ်သော တောင်းဆိုချက်အတွက် `single` ဖြစ်သည်) — အပြီးသတ် တုံ့ပြန်ချက်များတွင် အမြဲပါရှိသည် |
> Nginx မှတ်ချက်- အောက်မျဉ်းပါ Header များကို အသုံးပြုထားပါက (ဥပမာ `x_session_id`) `underscores_in_headers on;` ကို ဖွင့်ထားပါ။
> **ကုန်ကျစရိတ် တယ်လီမက်ထရီ ခေါင်းစီးများ:** streaming မဟုတ်သော အောင်မြင်သည့် တုံ့ပြန်မှုများတွင် `X-OmniRoute-*` ကုန်ကျစရိတ် တယ်လီမက်ထရီအစုလည်း ပါဝင်သည် — `X-OmniRoute-Response-Cost` (USD၊ ဒဿမ 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` နှင့် **မီဒီယာ endpoint များအားလုံး** — `/v1/embeddings`၊ `/v1/images/generations`၊ `/v1/audio/speech`၊ `/v1/audio/transcriptions`၊ `/v1/rerank`၊ `/v1/videos/generations`၊ `/v1/music/generations` နှင့် `/v1/moderations` (ကုန်ကျစရိတ်သည် အမြဲတမ်း `0`) — မှ ထုတ်ပေးသည်။ ဈေးနှုန်းအချက်အလက် ရရှိနိုင်သည့်အခါ မီဒီယာကုန်ကျစရိတ်ကို modality တစ်မျိုးချင်းအလိုက် (ပုံတစ်ပုံလျှင်၊ တစ်စက္ကန့်လျှင်၊ စာလုံးတစ်လုံးလျှင်၊ ရှာဖွေမှုယူနစ်တစ်ခုလျှင်) တွက်ချက်ပြီး၊ မရရှိနိုင်ပါက `0` အဖြစ် သတ်မှတ်သည် (fail-open)။
> **Cache-hit ကုန်ကျစရိတ် အဓိပ္ပာယ်သတ်မှတ်ချက်:** semantic-cache HIT (`X-OmniRoute-Cache-Hit: true`) ဖြစ်သည့်အခါ upstream ခေါ်ဆိုမှု မပြုလုပ်သောကြောင့် `X-OmniRoute-Response-Cost` သည် `0.0000000000` ဖြစ်သည် (hit ကို ဝန်ဆောင်မှုပေးရန် ကုန်ကျသည့် **ထပ်တိုး** ကုန်ကျစရိတ်)။ မူလကုန်ကျစရိတ်/ဖြစ်လာနိုင်ခဲ့သည့် ကုန်ကျစရိတ်ကို `X-OmniRoute-Cost-Saved` တွင် သီးခြားဖော်ပြသည်။ ငွေတောင်းခံမှုကို အသုံးပြုသည့်စနစ်များသည် `X-OmniRoute-Response-Cost` ကို စုစုပေါင်းတွက်ချက်သင့်သည် (hit များအတွက် ကုန်ကျစရိတ်မရှိပါ)။ cache ခွဲခြမ်းစိတ်ဖြာမှုများတွင် `X-OmniRoute-Cost-Saved` ကို စုစည်းတွက်ချက်နိုင်သည်။
## သီးသန့် စီမံခန့်ခွဲထားသော Session Lease များ
သီးသန့် စီမံခန့်ခွဲထားသော session leasing သည် ရွေးချယ်အသုံးပြုနိုင်ပြီး client နှင့် မသက်ဆိုင်သည့် routing contract တစ်ခုဖြစ်သည်။ လက်ရှိ owner တစ်ဦးသည် သတ်မှတ်ချက်နှင့် ကိုက်ညီသော OmniRoute connection တစ်ခုကို ထိန်းသိမ်းထားသည်။ ၎င်းသည် model တစ်ခုကို lease လုပ်ခြင်းမဟုတ်သကဲ့သို့ OAuth ကိုလည်း မလိုအပ်ပါ၊ သီးခြား client တစ်ခုကိုလည်း ဖော်ထုတ်သတ်မှတ်ခြင်းမရှိသလို သီးခြား provider တစ်ခုကိုလည်း မလိုအပ်ပါ။
အထောက်အထားစိစစ်ရန် အသုံးပြုသော API key တွင် scope `lease:exclusive` နှင့် အလွတ်မဟုတ်ကြောင်း အတိအလင်း သတ်မှတ်ထားသော `allowedConnections` စာရင်း ရှိရမည်။ Database mutation boundary သည် key ဖန်တီးမှုနှင့် တစ်စိတ်တစ်ပိုင်း update များတွင် field နှစ်ခုစလုံးကို တွဲဖက်၍ မဖြစ်မနေ သတ်မှတ်ထားစေသည်။
```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 response များသည် timestamp များ၊ `state` နှင့် အတိအကျ အပေါင်းတန်ဖိုးရှိသော `generation` ကို ဖော်ပြပေးသော်လည်း ရွေးချယ်ထားသည့် connection သို့မဟုတ် credential များကို မည်သည့်အခါမျှ မဖော်ပြပါ။ Renew နှင့် release တို့သည် generation ကို JSON body ထဲတွင် ပေးပို့သည်-
```json
{ "action": "renew", "generation": 1 }
```
```json
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
```
လက်ရှိ lease owner သည် ၎င်း၏ လက်ရှိ binding အတွက် privacy-safe display metadata ကို အတိအလင်း တောင်းဆိုနိုင်သည်-
```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 action ကို database transaction တစ်ခုတည်းအတွင်း opaque owner၊ အထောက်အထားစိစစ်ပြီးသော managed API key နှင့် အတိအကျ လက်ရှိအသုံးပြုနေသော generation တို့ဖြင့် fence လုပ်ထားသည်။ `displayName` သည် အစနှင့်အဆုံး whitespace များကို ဖြတ်တောက်ထားသော configured connection name သာဖြစ်ပြီး လုံခြုံစွာ အသုံးပြုနိုင်သည့် configured name မရှိသောအခါ `null` ဖြစ်သည်။ OmniRoute သည် email သို့မဟုတ် ထုတ်လုပ်ဖန်တီးထားသော account identity ကို မည်သည့်အခါမျှ အစားထိုးအသုံးမပြုပါ။ Provider value သည် sensitive မဖြစ်သော display label တစ်ခုဖြစ်ပြီး ထုတ်လုပ်ဖန်တီးထားသော compatible-provider identifier မဟုတ်ပါ။ Credential များ၊ token များ၊ cookie များ၊ မူရင်း connection သို့မဟုတ် API key id များ၊ owner hash များ၊ fencing secret များနှင့် internal routing data များကို ထည့်သွင်းမထားပါ။
မှားယွင်းသော key၊ မှားယွင်းသော owner၊ သက်တမ်းနောက်ကျနေသော generation၊ မရှိတော့သော၊ သက်တမ်းကုန်ဆုံးသော၊ release လုပ်ထားသောနှင့် invalidate လုပ်ထားသော lookup များအားလုံးသည် connection metadata မပါဘဲ တူညီသော `409 LEASE_FENCE_STALE` error ကို ပြန်ပေးသည်။ Capacity-wait response ကို ရရှိထားသော client တွင် စစ်ဆေးကြည့်ရှုနိုင်သည့် လက်ရှိ binding မရှိပါ။ Routing က လက်ရှိ lease တစ်ခုကို ပြောင်းလဲသောအခါ တူညီသော generation သည် ဆက်လက်အကျုံးဝင်ပြီး status က binding အသစ်ကို atomically ပြန်ပေးကာ အဟောင်းကို မည်သည့်အခါမျှ ပြန်မပေးပါ။ Acquire၊ renew၊ release နှင့် waiting response များသည် ၎င်းတို့၏ ယခင်ပုံစံများကို ဆက်လက်ထိန်းသိမ်းထားသောကြောင့် ရှိပြီးသား client များမှာ မပြောင်းလဲပါ။
ဤ server contract သည် မူရင်း OpenAI Codex `/status` ကို မပြောင်းလဲပါ။ လက်ရှိ မူရင်း Codex သည် ၎င်း၏ model provider နှင့် ထည့်သွင်းပေးထားသော authentication/account state ကို အစီရင်ခံသော်လည်း မည်သည့် arbitrary custom provider account metadata ကိုမဆို ပြသပေးခြင်းမရှိပါ။ နောင် client integration တစ်ခုသည် ဤ action ကို ခေါ်ယူပြီး `connection.displayName` ကို မည်သို့ပြသရမည်ကို ဆုံးဖြတ်ရမည်။
ထို့နောက် managed inference request တိုင်းသည် control header နှစ်ခုလုံးကို ပေးပို့သည်-
```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```
အတိအကျ owner၊ generation၊ လက်ရှိ connection နှင့် အထောက်အထားစိစစ်ပြီးသော API key တို့ကို ပံ့ပိုးထားသည့် upstream attempt တစ်ခုစီမတိုင်မီ ချက်ချင်း fence လုပ်သည်။ အခြား key က တူညီသော connection ကို ခွင့်ပြုထားသည့်တိုင် ထို key ဖြင့် owner နှင့် generation ကို ပြန်လည်အသုံးပြုခြင်းသည် မအောင်မြင်ပါ။ မူရင်း owner များကို အမြဲတမ်းသိမ်းဆည်းခြင်း၊ log မှတ်တမ်းတင်ခြင်း၊ request 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
}
```
ဤ response သည် ပုံမှန် သတ်မှတ်ချက်နှင့်ကိုက်ညီသော set သည် အလွတ်မဟုတ်ခဲ့ပြီး လွတ်နေသော candidate တိုင်းကို အခြား active lease တစ်ခုက ထိန်းသိမ်းထားသည်ဟုသာ ဆိုလိုသည်။ ပံ့ပိုးမထားသော model/provider များ၊ policy မကိုက်ညီမှု၊ cooldown၊ quota၊ health နှင့် အခြားပုံမှန် eligibility failure များသည် ၎င်းတို့၏ ရှိပြီးသား OmniRoute response များကို ဆက်လက်ထိန်းသိမ်းထားသည်။
### `x-omniroute-compression`
Request တစ်ခုချင်းစီအလိုက် compression plan ကို override လုပ်ခြင်းဖြစ်သည်။ ဦးစားပေးမှု အမြင့်ဆုံးဖြစ်ပြီး routing-combo override၊ active profile၊ auto-trigger နှင့် panel Default တို့ထက် ဦးစားပေးသည်။ Value များ-
| Value | အကျိုးသက်ရောက်မှု |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `off` | ဤ request အတွက် compression မပြုပါ။ |
| `default` | Panel မှ ဆင်းသက်လာသော Default profile ဖြစ်သည် (active profile ကို လျစ်လျူရှုသည်)။ |
| `engine:<id>` | ဖွင့်ထားသောအခါ engine တစ်ခုတည်း၊ ဥပမာ `engine:rtk`။ |
| `<combo>` | အမည်ပေးထားသော combo တစ်ခုဖြစ်ပြီး ပထမဦးစွာ name ဖြင့် (စာလုံးအကြီးအသေးမခွဲဘဲ) တိုက်ဆိုင်စစ်ဆေးကာ ထို့နောက် id ဖြင့် စစ်ဆေးသည်။ |
မှတ်ချက်များ-
- မသိသော value များကို လျစ်လျူရှုသည် (request ကို မည်သည့်အခါမျှ ပယ်ချမည်မဟုတ်ပါ)။ Resolution သည် ပုံမှန် operator precedence သို့ ဆက်လက်ကျသွားသည်။
- Combo အများအပြားသည် တူညီသော name ကို မျှဝေထားပါက တိကျသေချာစွာ တိုက်ဆိုင်မှုရရှိရန် combo **id** ကို ပေးပို့ပါ။
- Name က `off` သို့မဟုတ် `default` ဖြစ်သော combo ကို name ဖြင့် ရွေးချယ်၍မရပါ (ထို keyword များကို ပထမဦးစွာ အဓိပ္ပာယ်ဖော်သည်)။ ထိုသို့သော combo ကို ၎င်း၏ id ဖြင့် ကိုးကားပါ။
- Master compression switch သည် မဖြစ်မနေဖြတ်သန်းရသော gate ဖြစ်သည်။ Compression ကို global အဆင့်တွင် ပိတ်ထားပါက ဤ header က ၎င်းကို ဖွင့်၍မရပါ။
အသုံးပြုထားသော plan ကို response header တွင် ပြန်လည်ဖော်ပြသည်-
```
X-OmniRoute-Compression: <mode>; source=<source>
```
ဤနေရာတွင် `<source>` သည် `request-header`၊ `routing-override`၊ `active-profile`၊ `auto-trigger`၊ `default` သို့မဟုတ် `off` တို့ထဲမှ တစ်ခုဖြစ်သည်။
---
## Embedding များ
```bash
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "nebius/Qwen/Qwen3-Embedding-8B",
"input": "The food was delicious"
}
```
ရရှိနိုင်သော provider များ- Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI။
Catalog id များသည် `provider/model` ပုံစံဖြစ်သည် (ဥပမာ- `jina-ai/jina-embeddings-v5-omni-small`)။ Registry ထဲတွင် ပါရှိသော Jina model id အပြည့်မဟုတ်သည့် id များ (ဥပမာ `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) ကိုလည်း ဖြေရှင်းပေးနိုင်သည်။ Jina embed/rerank/classify/segment သည် dashboard ရှိ `jina-ai` အထောက်အထားများကို ဦးစွာအသုံးပြုသည်။ Dashboard key မရှိသည့်အခါမှသာ `JINA_AI_API_KEY` ကို အရန်အဖြစ် အသုံးပြုသည်။ `jina-reader` card သည် Reader / `r.jina.ai` အတွက်သာဖြစ်ပြီး (`POST /v1/web/fetch`) embeddings သို့မဟုတ် rerank ကို မည်သည့်အခါမျှ မပေးဆောင်ပါ။
Multimodal ပံ့ပိုးမှုရှိကြောင်း ဖော်ပြထားသည့် registry model များသည် provider နှင့် မသက်ဆိုင်သော ဖွဲ့စည်းပုံပါ
item ၃၂ ခုအထိကိုလည်း လက်ခံသည်။ Media item အမျိုးအစားများမှာ `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`
နှင့် family alias `jina-ai/jina-embeddings-v5-omni` → omni-small) သည် Jina ၏ မူရင်း
EmbeddingsV5Request doc များကိုလည်း လက်ခံပြီး `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 }` value များသည် အများပြည်သူအသုံးပြုနိုင်သော HTTPS URL၊ `data:` URI သို့မဟုတ် raw
base64 ဖြစ်နိုင်သည်။ OmniRoute သည် အဆိုပါ object များကို string အဖြစ် မပြောင်းသကဲ့သို့ မူရင်း image URL များကိုလည်း မရယူပါ — Jina က
အများပြည်သူအသုံးပြုနိုင်သော media ကို ကိုယ်တိုင်ရယူသည်။ အပို Jina field များဖြစ်သည့် (`task`, `normalized`, `truncate`, `embedding_type`) ကို
တိုက်ရိုက်ပေးပို့သည်။ Text-only Jina SKU များသည် text မဟုတ်သော doc များကို ဆက်လက်ငြင်းပယ်သည်။
လုံခြုံရေးနှင့် ပို့ဆောင်ရေး ကန့်သတ်ချက်များ-
- Remote media URL များသည် အများပြည်သူအသုံးပြုနိုင်သော HTTPS ဖြစ်ရမည်။ Canonical `{type,source:url}` item များကို
server ဘက်တွင် ရယူပြီး (redirect ပြန်လည်စစ်ဆေးခြင်း၊ timeout၊ အရွယ်အစားကန့်သတ်ချက်၊ public DNS၊ connection pinning)
provider ကို ခေါ်ဆိုခြင်းမပြုမီ inline အဖြစ် ထည့်သွင်းသည်။ Jina မူရင်း `{image:"https://..."}` item များကို
အလားတူ public-HTTPS စစ်ဆေးမှု ပြုလုပ်ပြီးနောက် မပြောင်းလဲဘဲ တိုက်ရိုက်ပေးပို့သည်။ Jina က URL ကို ရယူသည်။
- Inline base64 media ကို item တစ်ခုလျှင် decode လုပ်ပြီးသား 8 MiB နှင့် request တစ်ခုလုံးတွင် decode လုပ်ပြီးသား 16 MiB အထိ ကန့်သတ်ထားသည်။
Provider အလိုက် ပြောင်းလဲခြင်း (canonical item များကို မပြောင်းလဲဘဲ မည်သည့်အခါမျှ တိုက်ရိုက်မပေးပို့ပါ)-
- Jina multimodal model များ- ထိပ်တန်းအဆင့် item တစ်ခုစီသည် modality key ပါသော object တစ်ခု
(`text` / `image` / `audio` / `video` / `pdf`) ဖြစ်လာပြီး inline media အတွက် data URI များကို အသုံးပြုသည်။ ထိပ်တန်းအဆင့်
item တစ်ခုလျှင် vector တစ်ခု ရရှိသည်။
- Gemini Embedding 2 family- ထိပ်တန်းအဆင့် array တစ်ခုကို `content.parts` (`text` သို့မဟုတ် `inline_data`) ပါသည့် မူရင်း
`models/{model}:embedContent` request တစ်ခုတည်းအဖြစ် ပြောင်းလဲသည်။
- တိကျစွာ သတ်မှတ်ထားသော modality metadata မရှိသည့် အမည်မသိ/dynamic model များသည် ဖွဲ့စည်းပုံပါ input ကို 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"
}
```
ပံ့ပိုးမထားသော model/modality ပေါင်းစပ်မှုများသည် item ကို အတင်းအကျပ်ပြောင်းလဲမည့်အစား HTTP 400 ကို ပြန်ပေးသည်။ အစဉ်အလာ string/token request များရှိ input မဟုတ်သော
extension field များကို မပြောင်းလဲဘဲ ဆက်လက်တိုက်ရိုက်ပေးပို့သည်။
```bash
# Embedding model အားလုံးကို စာရင်းပြုစုရန်
GET /v1/embeddings
```
---
## ပုံဖန်တီးခြင်း
```bash
POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "openai/gpt-image-2",
"prompt": "တောင်တန်းများပေါ်မှ လှပသော နေဝင်ချိန်",
"size": "1024x1024"
}
```
ရရှိနိုင်သော ဝန်ဆောင်မှုပေးသူများ- OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (စက်တွင်း), ComfyUI (စက်တွင်း)။
```bash
# ပုံမော်ဒယ်အားလုံးကို စာရင်းပြုစုရန်
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` သည် `provider/model` ရှေ့ဆက်စာလုံးကို အသုံးပြု၍ OCR ဝန်ဆောင်မှုပေးသူကို ရွေးချယ်သည်။ ဝန်ဆောင်မှုပေးသူ မပါသော မော်ဒယ် id (ဥပမာ
`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` သီးသန့်) | တစ်ပြိုင်တည်းလုပ်ဆောင်သည် — တစ်ကြိမ်တည်းသော upstream ခေါ်ဆိုမှုမှ တုံ့ပြန်ချက်ကို တိုက်ရိုက်ပြန်ပေးသည်။ |
| `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | တစ်ပြိုင်တည်းမဟုတ်သော upstream (`analyze` + poll) — အောက်တွင် ကြည့်ပါ။ |
| `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Vertex AI ၏ `openapi/chat/completions` မိတ်ဖက် endpoint မှတစ်ဆင့် တစ်ပြိုင်တည်းလုပ်ဆောင်သည် — အထောက်အထားစိစစ်ခြင်း/URL အတွက် အောက်တွင် ကြည့်ပါ။ |
ဝန်ဆောင်မှုပေးသူ သုံးခုလုံးသည် တူညီသော Mistral ပုံစံ body ဖြင့် တုံ့ပြန်သည်-
```json
{
"pages": [{ "index": 0, "markdown": "# ထုတ်ယူထားသော စာသား..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
```
### Azure Document Intelligence poll လုပ်ငန်းစဉ်
Azure Document Intelligence ၏ `analyze` API သည် တစ်ပြိုင်တည်းမဟုတ်ဘဲ လုပ်ဆောင်သည်။ ကနဦးတောင်းဆိုမှုသည် body အစား
`Operation-Location` header ကို ပြန်ပေးပြီး ရလဒ်ရရှိရန် poll လုပ်ရသည်။ Handler
(`open-sse/handlers/ocr.ts`) သည် ထို URL ကို တစ်စက္ကန့်လျှင်တစ်ကြိမ်၊ အများဆုံး 30 ကြိမ်အထိ poll လုပ်သည်။ `ok` မဟုတ်သော poll တုံ့ပြန်ချက် သို့မဟုတ် `"failed"` အခြေအနေ ဖြစ်ပေါ်ပါက ချက်ချင်းပျက်ကွက်ပြီး (ဆက်လက်
poll မလုပ်တော့ပါ)၊ ကြိုးပမ်းနိုင်သည့် အကြိမ်ရေ ကုန်ဆုံးပြီးနောက် လုပ်ဆောင်ချက်သည် ဆက်လက်လည်ပတ်နေသေးပါက `504` ကို ပြန်ပေးသည်။ နောက်ဆုံး Azure တုံ့ပြန်ချက်ကို ခေါ်ဆိုသူထံ မပြန်ပေးမီ Mistral အသုံးပြုသည့် တူညီသော `pages`/`markdown` ပုံစံသို့
စံပြုပြောင်းလဲပေးသောကြောင့် client code သည် ဝန်ဆောင်မှုပေးသူအလိုက် သီးခြားကိုင်တွယ်ရန် မလိုအပ်ပါ။
### Vertex AI DeepSeek OCR အထောက်အထားစိစစ်ခြင်းနှင့် endpoint သတ်မှတ်ခြင်း
`vertex-deepseek-ocr` သည် chat/image အသွားအလာအတွက် OmniRoute က ပံ့ပိုးထားပြီးဖြစ်သော တူညီသည့် Vertex AI အထောက်အထားစိစစ်ခြင်း
(`open-sse/executors/vertex.ts`) ကို ပြန်လည်အသုံးပြုသည်။ ချိတ်ဆက်မှု၏ API key သည် Service Account JSON အထောက်အထားဖြစ်ပြီး (JWT-bearer
လုပ်ငန်းစဉ်မှတစ်ဆင့် သက်တမ်းတို OAuth access token အဖြစ် လဲလှယ်သည်) သို့မဟုတ် ဖန်တီးပြီးသား OAuth access token ကို မူရင်းအတိုင်း အသုံးပြုသည်။ Upstream endpoint URL သည် Vertex ၏ ယေဘုယျ
`openapi/chat/completions` မိတ်ဖက် endpoint ဖြစ်ပြီး ချိတ်ဆက်မှု၏ project နှင့်
region တို့မှ တည်ဆောက်သည် — `providerSpecificData.project`/`providerSpecificData.region` ကို အတိအလင်း သတ်မှတ်ထားပါက ၎င်းတို့ကို အမြဲဦးစားပေးသည်။
မဟုတ်ပါက project ကို Service Account JSON ၏ `project_id` မှ ရယူပြီး region
၏ ပုံသေတန်ဖိုးမှာ `us-central1` ဖြစ်သည်။ သတ်မှတ်ခြင်းနှစ်ခုလုံးကို `open-sse/handlers/ocr.ts`
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`) တွင် လုပ်ဆောင်ပြီး `handleOcr` သို့ မပို့မီ
`src/app/api/v1/ocr/route.ts` က အသုံးပြုသည်။
---
## မော်ဒယ်များကို စာရင်းပြုစုခြင်း
```bash
GET /v1/models
Authorization: Bearer your-api-key
→ OpenAI ဖော်မတ်ဖြင့် chat၊ embedding နှင့် image မော်ဒယ်များအားလုံး + ပေါင်းစပ်မှုများကို ပြန်ပေးသည်
```
### မော်ဒယ် id ရှေ့ဆက်များ (`?prefix=`)
မော်ဒယ်အများစုကို **provider prefix** အောက်တွင် ဖော်ပြထားသည်။ သင်ရရှိမည့် ရှေ့ဆက်ကို
`MODELS_CATALOG_PREFIX_MODE` feature flag က ထိန်းချုပ်ပြီး query parameter ဖြင့် **တောင်းဆိုမှုတစ်ခုချင်းစီအလိုက်**
ထပ်မံသတ်မှတ်နိုင်သည် — အခြားသူအားလုံးအတွက် server တစ်ခုလုံးဆိုင်ရာ ဆက်တင်ကို မပြောင်းလဲဘဲ
ရှင်းလင်းသောစာရင်းကို ရယူလိုသည့် client အတွက် အသုံးဝင်သည်-
```bash
GET /v1/models?prefix=alias # မော်ဒယ်တစ်ခုလျှင် id တစ်ခု — alias ရှေ့ဆက်အတို
GET /v1/models?prefix=dual # ပုံစံနှစ်မျိုးလုံး (server မူလသတ်မှတ်ချက်)
GET /v1/models?prefix=canonical # provider-id ရှေ့ဆက်အပြည့်အစုံသာ
```
| မုဒ် | ထုတ်ပေးသည့်အရာ | မှတ်ချက်များ |
| ----------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual` | `cc/claude-sonnet-4-6` **နှင့်** `claude/claude-sonnet-4-6` | **မူလသတ်မှတ်ချက်။** id နှစ်ခုလုံးသည် တူညီသောမော်ဒယ်သို့ လမ်းကြောင်းပို့သည်။ ပုံစံတစ်မျိုးမျိုးကို အသေသတ်မှတ်ထားသော client config များ ဆက်လက်အလုပ်လုပ်စေရန် ထိန်းသိမ်းထားခြင်းဖြစ်သည်။ catalog အရွယ်အစားကို နှစ်ဆခန့်ဖြစ်စေသည်။ |
| `alias` | `cc/claude-sonnet-4-6` | မော်ဒယ်တစ်ခုလျှင် entry တစ်ခု။ သီးခြား alias မရှိသော provider များလည်း ၎င်းတို့၏ entry ကို ထုတ်ပေးဆဲဖြစ်သောကြောင့် မည်သည့်အရာမျှ ဆုံးရှုံးခြင်းမရှိပါ။ |
| `canonical` | `claude/claude-sonnet-4-6` | provider-id ရှေ့ဆက်အပြည့်အစုံအောက်တွင် မော်ဒယ်တစ်ခုလျှင် entry တစ်ခု။ သီးခြား alias မရှိသော provider များ (ဥပမာ `antigravity/…`၊ `agy/…`) လည်း ၎င်းတို့၏ တစ်ခုတည်းသော id ကို ဤနေရာတွင် ထုတ်ပေးသောကြောင့် မည်သည့်အရာမျှ ဆုံးရှုံးခြင်းမရှိပါ။ |
`dual` မုဒ် mirror ကို query parameter မပါဘဲလည်း သိရှိနိုင်သည်- ၎င်းတွင် ပင်မ id ကို ညွှန်းထားသည့် `parent`
field ပါရှိသည်။
မော်ဒယ်ရွေးချယ်သည့် picker ကို ပြသသော client များသည် `?prefix=alias` ကို တောင်းဆိုသင့်သည် —
[OmniCopilot VS Code extension](../guides/VSCODE-COPILOT.md) ကလည်း ဤပုံစံအတိုင်း လုပ်ဆောင်သည်။
### စဉ်းစားမှုမပါသော မော်ဒယ်မျိုးကွဲများ
စဉ်းစားနိုင်စွမ်းရှိသော Claude မော်ဒယ်များအတွက် `/v1/models` သည် id ရှေ့တွင် `claude-3-omniroute-no-thinking/` ထည့်ထားသည့် **စဉ်းစားမှုမပါသော** မျိုးကွဲကိုလည်း ဖော်ပြပေးသည်-
```
claude-3-omniroute-no-thinking/<provider>/<model>
```
ဤ id ကို ရွေးချယ်ခြင်း (ဥပမာ `thinking` block ကို အမြဲပူးတွဲပေးသည့် Claude Code config တစ်ခုတွင်) သည် reasoning ကို ပိတ်ထားလျက် အမှန်တကယ် ` <provider>/<model>` သို့ ပြန်လည်ဖြေရှင်းပေးသည် — `/v1/messages` path တွင် `thinking:{type:"disabled"}` သို့မဟုတ် `/v1/chat/completions` path တွင် `reasoning`/`reasoning_effort` field များကို ဖယ်ရှားပေးခြင်းဖြစ်သည်။ ဤမျိုးကွဲကို စဉ်းစားနိုင်စွမ်းကို ပံ့ပိုးပြီး `disabled` ကိုလည်း လိုက်နာသော Claude-family မော်ဒယ်များအတွက်သာ စာရင်းသွင်းသည် (**နှင့်** `disabled` ကို ငြင်းပယ်သော adaptive-only မော်ဒယ်များကဲ့သို့သော မော်ဒယ်များကို ချန်လှပ်ထားသည်)။ Operator များသည် `ModelSpec.noThinkingAlias` မှတစ်ဆင့် မော်ဒယ်တစ်ခုချင်းစီအလိုက် ဤမျိုးကွဲကို အတင်းဖွင့် သို့မဟုတ် ပိတ်နိုင်သည်။
---
## Provider Plugin Manifest
```bash
GET /api/v1/provider-plugin-manifest
```
Bifrost၊ CLIProxyAPI နှင့် အနာဂတ် sidecar router များက အသုံးပြုသော JSON နှင့် ဘေးကင်းစွာ တွဲဖက်အသုံးပြုနိုင်သည့် provider plugin manifest ကို ပြန်ပေးသည်။ Response ကို TypeScript provider registry မှ ဖန်တီးထားပြီး OAuth client secret များ၊ runtime environment resolution၊ executor function များ၊ request header များနှင့် account data များကို ရည်ရွယ်ချက်ရှိရှိ ဖယ်ထုတ်ထားသည်။
Sidecar တစ်ခုသည် out-of-process အနေဖြင့် လည်ပတ်ပြီး
`open-sse/config/providerPluginManifestRegistry.ts` ကို တိုက်ရိုက် import မလုပ်နိုင်သည့်အခါ ဤ endpoint ကို အသုံးပြုပါ။
---
## လိုက်ဖက်ညီမှု Endpoint များ
| နည်းလမ်း | လမ်းကြောင်း | ဖော်မတ် |
| -------- | ----------------------------------------- | ------------------------------------------- |
| 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 (audio body ကို ပြန်ပေးသည်) |
| POST | `/v1/rerank` | Cohere/Voyage ပုံစံ ပြန်လည်အစီအစဉ်ချခြင်း |
| POST | `/v1/classify` | Jina အမျိုးအစားခွဲခြားခြင်း (`api.jina.ai`) |
| POST | `/v1/segment` | Jina segmenter (`segment.jina.ai`) |
| POST | `/v1/moderations` | OpenAI Moderations |
| GET | `/v1/models` | OpenAI |
| POST | `/v1/messages/count_tokens` | Anthropic |
| GET | `/v1beta/models` | Gemini |
| POST | `/v1beta/models/{...path}` | Gemini generateContent |
| POST | `/v1/api/chat` | Ollama |
| GET | `/api/v1/vscode/{token}/` | OpenAI catalog alias |
| GET | `/api/v1/vscode/{token}/models` | OpenAI models alias |
| POST | `/api/v1/vscode/{token}/chat/completions` | OpenAI tokenized alias |
| POST | `/api/v1/vscode/{token}/responses` | OpenAI Responses tokenized alias |
| POST | `/api/v1/vscode/{token}/api/chat` | Ollama tokenized alias |
| GET | `/api/v1/vscode/{token}/api/tags` | Ollama tags tokenized alias |
POST route အားလုံးသည် တူညီသော ပုံစံကို လိုက်နာသည်- `Bearer your-api-key` + Zod ဖြင့် စစ်ဆေးအတည်ပြုထားသော JSON body (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` စသည်တို့၊ `src/shared/validation/schemas.ts` ကို ကြည့်ပါ)။ Schema စစ်ဆေးမှု မအောင်မြင်ပါက 4xx ကို ပြန်ပေးသည်။
`Authorization: Bearer ...` ကို ပူးတွဲမပေးပို့နိုင်သော client များအတွက် OmniRoute သည် query-string compatibility (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) သို့မဟုတ် အောက်တွင် မှတ်တမ်းတင်ထားသော သီးသန့် `/api/v1/vscode/{token}/...` endpoint များမှတစ်ဆင့် URL အတွင်းရှိ API key များကိုလည်း လက်ခံသည်။
```bash
# ပြန်လည်အစီအစဉ်ချခြင်း
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 segmenter
POST /v1/segment { "content": "...", "return_chunks": true }
# Jina ရှာဖွေမှု (s.jina.ai; provider alias များ- jina-search, jina-ai, jina)
POST /v1/search { "query": "...", "provider": "jina-search" }
# Moderation များ
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
# TTS — audio/mpeg (သို့မဟုတ် တောင်းဆိုထားသော ဖော်မတ်) body ကို ပြန်ပေးသည်
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# ပုံတည်းဖြတ်ခြင်း (multipart)
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
# ဗီဒီယို/တေးဂီတ ဖန်တီးခြင်း (provider prefix ပါသော model id)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." }
```
### သီးသန့် Provider Route များ
```bash
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
```
Provider prefix မရှိပါက အလိုအလျောက် ထည့်ပေးသည်။ မကိုက်ညီသော model များအတွက် `400` ကို ပြန်ပေးသည်။
---
## Files API
အစုလိုက် ထည့်သွင်းမှု/ထုတ်ယူမှုနှင့် ဖိုင်ရည်ရွယ်ချက်အလိုက် အပ်လုဒ်များအတွက် OpenAI နှင့် ကိုက်ညီသော files endpoint ဖြစ်သည်။
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| -------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/files` | ဖိုင်တစ်ခုကို အပ်လုဒ်လုပ်ရန် (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — အများဆုံး 512 MiB |
| GET | `/v1/files` | အထောက်အထားစိစစ်ထားသော API key အတွက် ဖိုင်များကို စာရင်းပြုစုရန် |
| GET | `/v1/files/[id]` | ဖိုင်တစ်ခု၏ မက်တာဒေတာကို ရယူရန် |
| DELETE | `/v1/files/[id]` | ဖိုင်တစ်ခုကို ဖျက်ရန် |
| GET | `/v1/files/[id]/content` | မူရင်းဖိုင်အကြောင်းအရာကို stream ဖြင့် ပြန်လည်ပေးပို့ရန် |
**အထောက်အထားစိစစ်ခြင်း:** Bearer API key — ဖိုင်များကို `getApiKeyRequestScope` မှတစ်ဆင့် API key တစ်ခုချင်းစီအလိုက် ကန့်သတ်ထားသည်။ Key တစ်ခုသည်
၎င်း၏ကိုယ်ပိုင်ဖိုင်များကိုသာ မြင်နိုင်၊ ဒေါင်းလုဒ်လုပ်နိုင်ပြီး ဖျက်နိုင်သည်။ Key မပါသော dashboard session တစ်ခုသည်
instance တစ်ခုလုံးကို ဖတ်နိုင်သည်။ ပိုင်ရှင်မရှိသော ဖိုင်တစ်ခု (အမည်မသိ သို့မဟုတ် dashboard-session မှ အပ်လုဒ်လုပ်ထားသောဖိုင်) ကို session မဟုတ်သော
ခေါ်ဆိုသူတိုင်းအား ဝင်ရောက်ခွင့်ငြင်းပယ်သည်။ `GET /v1/files` သည် အမည်မသိ ခေါ်ဆိုသူနှင့်
ဖြေရှင်း၍မရသော တင်ပြထားသည့် key ကို `REQUIRE_API_KEY=false` ဖြစ်နေသည့်အခါ၌ပင် tenant အားလုံး၏
ဖိုင်များကို စာရင်းပြုစုမည့်အစား `401` ဖြင့် ငြင်းပယ်သည် (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).
---
## Batches API
OpenAI နှင့် ကိုက်ညီသော batch processing။
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| -------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/batches` | batch ဖန်တီးခြင်း — body ကို `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) ဖြင့် စစ်ဆေးအတည်ပြုသည် |
| GET | `/v1/batches` | batch များကို စာရင်းပြုစုခြင်း |
| GET | `/v1/batches/[id]` | batch အခြေအနေ + `request_counts` ကို ရယူခြင်း |
| DELETE | `/v1/batches/[id]` | ပြီးဆုံးသွားသော/မအောင်မြင်သော batch ကို ဖျက်ခြင်း |
| POST | `/v1/batches/[id]/cancel` | လုပ်ဆောင်နေဆဲ batch ကို ပယ်ဖျက်ခြင်း |
**အထောက်အထားစစ်ဆေးခြင်း:** Bearer API key။ Batch များကို ဖိုင်များနှင့် တူညီသော စည်းမျဉ်းသုံးမျိုးအရ API key တစ်ခုချင်းစီအလိုက် ကန့်သတ်ထားသည်-
ကိုယ်ပိုင် key ဖြင့်သာ အသုံးပြုနိုင်ခြင်း၊ dashboard session မှ instance တစ်ခုလုံးကို အသုံးပြုနိုင်ခြင်း၊ ပိုင်ရှင်မရှိသော record များကို
session မဟုတ်သည့် ခေါ်ဆိုသူအားလုံးအတွက် ငြင်းပယ်ခြင်း (ရယူခြင်း၊ ဖျက်ခြင်း၊ ပယ်ဖျက်ခြင်းနှင့် ဖန်တီးရာရှိ `input_file_id` စစ်ဆေးမှု)။
`REQUIRE_API_KEY=false` ဖြစ်နေချိန်တွင်ပင် `GET /v1/batches` သည် အမည်မသိ ခေါ်ဆိုသူကို `401` ဖြင့် ငြင်းပယ်သည်။
---
## Search API
Web/search provider abstraction (Tavily၊ Brave၊ Exa၊ Serper စသည်) ဖြစ်သည်။
| Method | Path | Description |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
| GET | `/v1/search` | သတ်မှတ်ပြင်ဆင်ထားသော search provider များ + လုပ်ဆောင်နိုင်စွမ်းများကို စာရင်းပြုစုရန် |
| POST | `/v1/search` | Search query တစ်ခုကို လုပ်ဆောင်ရန် — body ကို `v1SearchSchema` ဖြင့် အတည်ပြုပြီး caching/coalescing ကို ပံ့ပိုးသည် |
| GET | `/v1/search/analytics` | Provider တစ်ခုချင်းအလိုက် hit/latency/cache ကိန်းဂဏန်းများ |
**Auth:** Bearer API key (`extractApiKey` + `isValidApiKey`)။ Search policy ကို `enforceApiKeyPolicy` မှတစ်ဆင့် မဖြစ်မနေလိုက်နာစေသည်။
---
## Web Fetch API
ပြင်ဆင်သတ်မှတ်ထားသော web-fetch provider (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract) မှတစ်ဆင့် URL တစ်ခုမှ အကြောင်းအရာကို ထုတ်ယူပါ။
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| -------- | --------------- | ------------------------------------------------------------------------- |
| POST | `/v1/web/fetch` | URL တစ်ခုကို ရယူ/ခြစ်ယူသည် — body ကို `v1WebFetchSchema` ဖြင့် အတည်ပြုသည် |
**Auth:** Bearer API key (`extractApiKey` + `isValidApiKey`)။ မူဝါဒကို `enforceApiKeyPolicy` မှတစ်ဆင့် အတည်ပြုကျင့်သုံးသည်။
**Quota ကို ထည့်သွင်းစဉ်းစားသော fallback (#8297):** `provider` ကို အတိအလင်း မပေးထားသောအခါ pool
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) ကို
သတ်မှတ်ထားသော ဦးစားပေးအစဉ် (fill-first) အတိုင်း
ဖြတ်သန်းသည် — rate limit ဖြစ်နေသော်လည်း configure လုပ်ထားသော provider ကို request ကို ချက်ချင်းရပ်တန့်မည့်အစား ကျော်သွားပြီး၊ ပြန်လည်ကြိုးစားနိုင်သော/quota ဆိုင်ရာ upstream failure
(HTTP 429 အမြဲတမ်း၊ Firecrawl/Tavily/TinyFish ၏ quota ပုံစံ free tier များအတွက် 402/403 —
Jina Reader အတွက် မဟုတ်သကဲ့သို့ သာမန် 400 bad request အတွက်လည်း ဘယ်တော့မှ မဟုတ်ပါ) ဖြစ်ပါက request ပြုလုပ်ချိန်တွင်
မစမ်းရသေးသော credential ပါရှိသည့် နောက် provider သို့ ဆက်သွားသည်။ pool ထဲရှိ provider အားလုံး
ကုန်ဆုံးသွားသောအခါ endpoint သည် ယခင် generic `400` အစား `429` တစ်ခုတည်းကို (`Retry-After`
header နှင့်အတူ) ပြန်ပေးသည်။ `provider` ကို အတိအလင်း တောင်းဆိုထားပါက တိတ်တဆိတ် fallback လုပ်ခြင်း
**မရှိပါ** — rate limit ဖြစ်နေသော သို့မဟုတ် အလုပ်မလုပ်သော အတိအလင်းရွေးထားသည့်
provider သည် ၎င်း၏ကိုယ်ပိုင် error (`429` သည် rate limit ဖြစ်သည့်အခါ၊ မဟုတ်ပါက upstream
status) ကို တိုက်ရိုက်ဖော်ပြသည်။
---
## WebSocket Streaming
```bash
GET /v1/ws?handshake=1
```
WebSocket upgrade handshake ကို အတည်ပြုပြီး wire protocol နမူနာ message များ (`request`, `cancel`) ကို ပြန်ပေးသည်။ အမှန်တကယ် WS frame များကို Next.js route table အပြင်ဘက်ရှိ ပူးတွဲပါ WS server က ကိုင်တွယ်သည်။
**Auth:** handshake ပြုလုပ်စဉ် Bearer API key။
### WebSocket မှတစ်ဆင့် Responses API (codex အတွက်သာ)
```bash
# HTTP API နှင့် host:port တူညီသည် (မူလသတ်မှတ်ချက် 20128)၊ connection ကို upgrade လုပ်ပါ:
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 တွင်
internal `codex-responses-ws` bridge မှတစ်ဆင့် authentication ပြုလုပ်ပြီး ပြင်ဆင်ခြင်း၊
codex OAuth connection တစ်ခုကို ရွေးချယ်ခြင်းနှင့် `wreq-js` transport မှတစ်ဆင့်
`wss://chatgpt.com/backend-api/codex/responses` သို့ tunnel ပြုလုပ်ခြင်းတို့ကို ဆောင်ရွက်သည်။
**codex မဟုတ်သော model များကို ပယ်ချသည်** (`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:** handshake ပြုလုပ်စဉ် Bearer API key။ ပူးတွဲပါ HTTP server (`server-ws.mjs`)
သည် လက်ရှိအသုံးပြုနေသော entrypoint ဖြစ်ရမည် (`app/server-ws.mjs` ရှိပါက မူလသတ်မှတ်ချက်အရ ၎င်းကို အသုံးပြုထားသည်)။
#### Model id: ChatGPT id အစစ်ကို အသုံးပြုပါ (`codex/` prefix မထည့်ပါနှင့်)
OpenAI **Codex CLI** သည်
`supports_websockets = true` ဖြစ်သောအခါ client-side တွင် model name ကို အတည်ပြုစစ်ဆေးပြီး
`codex/gpt-5.5` ကဲ့သို့သော **provider prefix ပါသည့် id များကို ပယ်ချသည်**
(`ChatGPT account ဖြင့် Codex ကို အသုံးပြုသည့်အခါ 'codex/gpt-5.5' model ကို မပံ့ပိုးပါ`)။
**prefix မပါသော** id (ဥပမာ `gpt-5.5`) ကို ပို့ပါ။ OmniRoute ၏ bridge သည်
codex အတွက်သာဖြစ်သောကြောင့် upstream သို့ tunnel မပြုလုပ်မီ prefix မပါသော id ကို
codex model အဖြစ် (`resolveCodexWsModelInfo`) ပြန်လည်သတ်မှတ်သည် — prefix မပါသော
`gpt-5.5` သည် HTTP မှတစ်ဆင့်ဆိုပါက အခြား provider တစ်ခုသို့ route လုပ်မည်ဖြစ်သော်လည်း ဖြစ်သည်။
#### OpenAI Codex CLI ကို ပြင်ဆင်သတ်မှတ်ခြင်း
WebSocket ပံ့ပိုးမှုပါသော custom provider တစ်ခုကို `~/.codex/config.toml` ထဲသို့ ထည့်ခြင်းဖြင့် Codex CLI ကို OmniRoute သို့ ညွှန်ပါ (ရှိပြီးသား config ကို မထိခိုက်စေရန် သီးခြား `CODEX_HOME` ကို အသုံးပြုပါ)။
```toml
model = "gpt-5.5" # prefix မပါသော 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" # Feb 2026 မှစ၍ ပံ့ပိုးသည့် တစ်ခုတည်းသော value
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 တစ်ခု (REQUIRE_API_KEY=false ဖြစ်ပါက မည်သည့် key မဆို)
codex exec "Responda apenas: PONG"
```
CLI သည် `base_url + /responses` ကို WebSocket အဖြစ် upgrade လုပ်ပြီး OmniRoute က ၎င်းကို
ရွေးချယ်ထားသော codex OAuth connection သို့ tunnel ပြုလုပ်သည်။ local
server နှင့် အစမှအဆုံး အတည်ပြုစမ်းသပ်ပြီးဖြစ်သည်။ ChatGPT သည် `codex.rate_limits` + `response.created` ကို ပြန်ပေးပြီး completion ကို
stream လုပ်သည်။
---
## ခွဲတမ်းများနှင့် ပြဿနာတင်ပြခြင်း
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| -------- | ------------------- | ----------------------------------------------------------------------------------------------------------- |
| GET | `/v1/quotas/check` | မှတ်ပုံတင်ထားသော key တစ်ခုကို ထုတ်ပေးခြင်းမပြုမီ `provider` + `accountId` အတွက် ခွဲတမ်းကို ကြိုတင်စစ်ဆေးရန် |
| POST | `/v1/issues/report` | ခွဲတမ်း/key ထုတ်ပေးမှု မအောင်မြင်ခြင်းကို GitHub သို့ တင်ပြရန် (`GITHUB_ISSUES_REPO` + token လိုအပ်သည်) |
**အထောက်အထားစိစစ်မှု:** Bearer API key (`isAuthenticated`)။
---
## ကိုယ်တိုင်ဝန်ဆောင်မှု အသုံးပြုမှု (`/api/usage/om-usage`)
မည်သည့် API key မဆို စီမံခန့်ခွဲမှု အထောက်အထားစိစစ်ခြင်းမလိုဘဲ **၎င်း၏ကိုယ်ပိုင်** အသုံးပြုမှုနှင့် ခွဲတမ်းများကို ဖတ်ရှုနိုင်သည်။ ဤ endpoint ကို
client (CLI၊ OmniCopilot panel) က key ကိုင်ဆောင်သူအား ၎င်း၏အသုံးစရိတ်ကို ပြသရန် အသုံးပြုသည်။
```bash
# စာသားပုံစံ (မူလသတ်မှတ်ချက် — terminal အတွက် ရိုးရိုးစာသား)
curl -H "Authorization: Bearer <your-api-key>" \
http://localhost:20128/api/usage/om-usage
# ဖွဲ့စည်းထားသောပုံစံ — UI က အသုံးပြုသည့်ပုံစံ
curl -H "Authorization: Bearer <your-api-key>" \
"http://localhost:20128/api/usage/om-usage?format=json"
```
Key တွင် **`allowUsageCommand`** ကို ဖွင့်ထားရမည် (မူလအားဖြင့် ပိတ်ထားသည် — dashboard ၏ API-key
manager က key တစ်ခုချင်းစီအလိုက် ဖွင့်/ပိတ် ပြုလုပ်ပေးသည်)။ ၎င်းမရှိပါက endpoint က `403` ဖြင့် တုံ့ပြန်သည်။
`?format=json` သည် ငြင်းပယ်ထားမှုတစ်ခုမှ data field ကို ခေါ်ယူသူက မည်သည့်အခါမျှ မဖတ်မိစေရန် ခွဲခြားသတ်မှတ်ထားသော ဖွဲ့စည်းပုံကို ပြန်ပေးသည်။
အောင်မြင်သည့်အခါ-
```jsonc
{
"allowed": true,
// key က key တစ်ခုချင်းစီအလိုက် အသုံးပြုမှုကန့်သတ်ချက်များ (နေ့စဉ်/အပတ်စဉ် USD) ကို သတ်မှတ်ထားသည့်အခါမှသာ ပါဝင်သည်-
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// ရွေးချယ်ထားသော provider ၏ ခွဲတမ်း snapshot၊ သို့မဟုတ် လက်ရှိအချိန်အထိ cache ထားသည့်အရာမရှိပါက null-
"provider": {
"connectionId": "…",
"provider": "claude",
"plan": "…",
"quotas": {/* … */},
},
// UI က provider အများအပြားကို ဘေးချင်းယှဉ် ဖော်ပြနိုင်ရန် connection တစ်ခုစီ၏ snapshot-
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
```
ငြင်းပယ်သည့်အခါ (`401` မမှန်ကန်သော key / `403` ခွင့်မပြုထားခြင်း) တူညီသော route က
`{ "allowed": false, "error": { "message": "…" } }` ကို ပြန်ပေးသည် — ပါဝင်သော်လည်း ဗလာဖြစ်နေသော `personal`/`provider`
(key ကို ခွင့်ပြုထားသော်လည်း အချက်အလက် မရရှိသေးခြင်း) သည် ငြင်းပယ်ခြင်းနှင့် ကွဲပြားသည့်အခြေအနေဖြစ်ပြီး JSON ပုံစံတစ်ခုတည်းကသာ
၎င်းတို့ကို ခွဲခြားပေးသည်။
**အထောက်အထားစိစစ်မှု:** ခေါ်ယူသူ၏ ကိုယ်ပိုင် Bearer API key ကို `isValidApiKey` ဖြင့် အတည်ပြုစစ်ဆေးသည် — ၎င်းသည်
`requireManagementAuth` ၏ နောက်ကွယ်တွင် ဆက်လက်ရှိနေသည့် စီမံခန့်ခွဲမှုဆိုင်ရာ မျက်နှာပြင် (`/api/keys/…`) _မဟုတ်ပါ_။
---
## Semantic Cache
```bash
# Cache စာရင်းအင်းများ ရယူရန်
GET /api/cache/stats
# Cache အားလုံး ရှင်းလင်းရန်
DELETE /api/cache/stats
```
တုံ့ပြန်ချက် ဥပမာ-
```json
{
"semanticCache": {
"memorySize": 42,
"memoryMaxSize": 500,
"dbSize": 128,
"hitRate": 0.65
},
"idempotency": {
"activeKeys": 3,
"windowMs": 5000
}
}
```
### ကြာချိန်အပေါ် သက်ရောက်မှု
Semantic cache HIT တစ်ခုသည် **upstream ခေါ်ဆိုမှုမရှိဘဲ** cache မှ တုံ့ပြန်ချက်ကို ပေးပို့သောကြောင့်
တင်ပြထားသော `X-OmniRoute-Response-Latency` သည် မူလ upstream ကြာချိန်နှင့် မသက်ဆိုင်ဘဲ
သုညနီးပါး ဖြစ်သည်။ ကြာချိန်အပေါ် အထူးအာရုံစိုက်သော client များ
(စွမ်းဆောင်ရည်စမ်းသပ်ခြင်း၊ p50/p99 စောင့်ကြည့်ခြင်း) သည်
`X-OmniRoute-Cache-Latency` တုံ့ပြန်ချက် header ကို စစ်ဆေးသင့်သည်-
| တန်ဖိုး | အဓိပ္ပာယ် |
| ----------- | ------------------------------------------------------------------------------------- |
| `synthetic` | တုံ့ပြန်ချက်ကို cache မှ ပေးပို့ထားသည်၊ ကြာချိန်သည် အမှန်တကယ် upstream အချိန် မဟုတ်ပါ |
| _(မပါရှိ)_ | အမှန်တကယ် upstream ခေါ်ဆိုမှုမှ တုံ့ပြန်ချက် ဖြစ်သည် |
### Key တစ်ခုချင်းစီအလိုက် cache ကျော်သွားခြင်း
API key များသည် `cacheDefaultMode` မှတစ်ဆင့် semantic cache ဖတ်ရှုမှုများကို မသုံးရန် ရွေးချယ်နိုင်သည်-
| တန်ဖိုး | လုပ်ဆောင်ပုံ |
| -------- | ----------------------------------------------------------------- |
| `legacy` | ပုံမှန် cache လုပ်ဆောင်ပုံ (မူလသတ်မှတ်ချက်) |
| `bypass` | Cache ရှာဖွေမှုကို လုံးဝကျော်သွားပြီး upstream ကို အမြဲခေါ်ဆိုသည် |
Key ဖန်တီးချိန်တွင် သတ်မှတ်ပါ (`POST /api/keys`) သို့မဟုတ် အပ်ဒိတ်လုပ်ပါ (`PATCH /api/keys/[id]`)-
```json
{ "cacheDefaultMode": "bypass" }
```
### Request တစ်ခုချင်းစီအလိုက် ကျော်သွားခြင်း
မည်သည့် request မဆို key ဆက်တင်များနှင့် မသက်ဆိုင်ဘဲ cache ကို ကျော်သွားနိုင်သည်-
```
X-OmniRoute-No-Cache: true
```
---
## ဒက်ရှ်ဘုတ်နှင့် စီမံခန့်ခွဲမှု
စီမံခန့်ခွဲမှု route များ (`/api/*`၊ အများသုံး auth/login မှအပ) ကို
သာမန် inference API key များဖြင့် ခွင့်ပြုထားခြင်း **မရှိပါ**။ Credential အမျိုးအစားများ၊ scope များနှင့် curl နမူနာများ-
[စီမံခန့်ခွဲမှုဆိုင်ရာ အထောက်အထားစိစစ်ခြင်း](../guides/MANAGEMENT-AUTH.md)။
### အထောက်အထားစိစစ်ခြင်း
| Endpoint | Method | ဖော်ပြချက် |
| ----------------------------- | ------- | ------------------------------------- |
| `/api/auth/login` | POST | အကောင့်ဝင်ရန် |
| `/api/auth/logout` | POST | အကောင့်ထွက်ရန် |
| `/api/settings/require-login` | GET/PUT | အကောင့်ဝင်ရန် လိုအပ်မှုကို ပြောင်းရန် |
### Provider စီမံခန့်ခွဲမှု
| Endpoint | Method | ဖော်ပြချက် |
| ---------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/providers` | GET/POST | Provider များကို စာရင်းပြုစုရန် / ဖန်တီးရန် |
| `/api/providers/[id]` | GET/PUT/DELETE | Provider တစ်ခုကို စီမံခန့်ခွဲရန် |
| `/api/providers/[id]/test` | POST | Provider ချိတ်ဆက်မှုကို စမ်းသပ်ရန် |
| `/api/providers/[id]/models` | GET | Provider ၏ model များကို စာရင်းပြုစုရန် |
| `/api/providers/validate` | POST | Provider config ကို အတည်ပြုစစ်ဆေးရန် |
| `/api/providers/bulk` | POST | Provider တစ်ခုတည်းအတွက် API key များကို အစုလိုက်ထည့်ရန် |
| `/api/providers/import` | POST | Parse လုပ်ထားသော CSV/JSON ဖိုင်မှ မတူညီသည့် provider စာရင်းကို import လုပ်ရန် (#6836)၊ row တစ်ခုချင်းစီအလိုက် တစ်စိတ်တစ်ပိုင်း မအောင်မြင်မှုရလဒ်များ |
| `/api/provider-nodes*` | အမျိုးမျိုး | Provider node စီမံခန့်ခွဲမှု |
| `/api/provider-models` | GET/POST/PATCH/DELETE | စိတ်ကြိုက် model များ (ထည့်ရန်၊ အပ်ဒိတ်လုပ်ရန်၊ ဖျောက်ရန်/ပြရန်၊ ဖျက်ရန်) |
### OAuth လုပ်ငန်းစဉ်များ
| Endpoint | Method | ဖော်ပြချက် |
| -------------------------------- | ----------- | ----------------------------- |
| `/api/oauth/[provider]/[action]` | အမျိုးမျိုး | Provider အလိုက် သီးခြား OAuth |
### Routing နှင့် Config
| Endpoint | Method | ဖော်ပြချက် |
| --------------------- | ----------- | --------------------------------------------- |
| `/api/models/alias` | GET/POST | Model alias များ |
| `/api/models/catalog` | GET | Provider နှင့် အမျိုးအစားအလိုက် model အားလုံး |
| `/api/combos*` | အမျိုးမျိုး | Combo စီမံခန့်ခွဲမှု |
| `/api/keys*` | အမျိုးမျိုး | API key စီမံခန့်ခွဲမှု |
| `/api/pricing` | GET | Model စျေးနှုန်းများ |
### အသုံးပြုမှုနှင့် ပိုင်းခြားစိတ်ဖြာမှု
| Endpoint | Method | Description |
| -------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/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 key တစ်ခုချင်းစီအလိုက် token ကန့်သတ်ချက် ဘတ်ဂျက်များ |
| `/api/usage/model-latency-stats` | GET | Provider/model တစ်ခုချင်းစီအလိုက် ရွေ့လျား latency စုစည်းကိန်းများ (ပျမ်းမျှ/p50/p95/p99၊ အောင်မြင်မှုနှုန်း)၊ စစ်ထုတ်မှုများ- `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) |
| `/api/usage/cache-health` | GET | `call_logs` အပေါ်အခြေခံသည့် prompt-cache အခြေအနေ အနှစ်ချုပ် — ရေးသားမှု/ဖတ်ရှုမှု အချိုး၊ p50/p90/p99 ရေးသားမှုအရွယ်အစား ဖြန့်ဝေမှု၊ ကြီးမားသောရေးသားမှု စုစည်းနေမှု၊ model တစ်ခုချင်းစီအလိုက် ခွဲခြားမှုနှင့် `healthy`/`degraded`/`thrash`/`no-data` အကဲဖြတ်ချက်၊ query parameter များမှာ `range` (`1h`\|`24h`\|`7d`\|`30d`၊ မူလတန်ဖိုး `24h`) နှင့် ရွေးချယ်နိုင်သော `model` (#8827) |
### ဆက်တင်များ
| Endpoint | Method | Description |
| ------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings` | GET/PUT/PATCH | အထွေထွေ ဆက်တင်များ |
| `/api/settings/proxy` | GET/PUT | ကွန်ရက် proxy ဖွဲ့စည်းမှု |
| `/api/settings/proxy/test` | POST | Proxy ချိတ်ဆက်မှုကို စမ်းသပ်ရန် |
| `/api/settings/ip-filter` | GET/PUT | IP ခွင့်ပြုစာရင်း/ပိတ်ပင်စာရင်း |
| `/api/settings/thinking-budget` | GET/PUT | တွေးခေါ်မှု/ဆင်ခြင်မှု **တောင်းဆိုချက်** ပြန်လည်ရေးသားသည့် mode (passthrough / auto-strip / custom / adaptive)။ Compression နှင့် သီးခြားဖြစ်သည်။ [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md) ကို ကြည့်ပါ။ |
| `/api/settings/system-prompt` | GET/PUT | ကမ္ဘာလုံးဆိုင်ရာ system prompt |
| `/api/settings/compression` | GET/PUT | ကမ္ဘာလုံးဆိုင်ရာ compression ဖွဲ့စည်းမှု |
| `/api/settings/purge-request-history` | POST | တောင်းဆိုမှုမှတ်တမ်း row များနှင့် စက်တွင်း call-log artifact များကို ရှင်းလင်းရန် |
### Context နှင့် Compression
| အဆုံးမှတ် | နည်းလမ်း | ဖော်ပြချက် |
| -------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
| `/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 | စာသား payload တစ်ခုအပေါ် RTK အစမ်းကြည့်ရှုမှု/စမ်းသပ်မှုကို လုပ်ဆောင်ရန် |
| `/api/context/rtk/raw-output/[id]` | GET | pointer id ဖြင့် ထိန်းသိမ်းထားသော ဖုံးကွယ်ပြင်ဆင်ပြီး အကြမ်းထုတ်ပေးချက်ကို ဖတ်ရန် |
| `/api/context/combos` | GET/POST | ချုံ့ခြင်း combo စာရင်း/ဖန်တီးမှု |
| `/api/context/combos/[id]` | GET/PUT/DELETE | ချုံ့ခြင်း combo အသေးစိတ်/အပ်ဒိတ်/ဖျက်ခြင်း |
| `/api/context/combos/[id]/assignments` | GET/PUT | routing combo များသို့ ချုံ့ခြင်း combo များ သတ်မှတ်ရန် |
| `/api/context/analytics` | GET | ချုံ့ခြင်း ဆန်းစစ်ချက် အမည်လွှဲ |
### စောင့်ကြည့်ခြင်း
| အဆုံးမှတ် | နည်းလမ်း | ဖော်ပြချက် |
| ------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions` | GET | လက်ရှိအသုံးပြုနေသော session များကို ခြေရာခံခြင်း |
| `/api/rate-limits` | GET | အကောင့်တစ်ခုချင်းစီအလိုက် rate limit များ |
| `/api/monitoring/health` | GET | ကျန်းမာရေးစစ်ဆေးမှု + provider အကျဉ်းချုပ် (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`)။ စီမံခန့်ခွဲမှုမြင်ကွင်းတွင် `credentialHealth` ပါဝင်သည်- probe-cache scalar များ၊ `failed>0` ဖြစ်သည့်အခါ `failedConnections` နှင့် `staleDbNonOkCount` (gauge မဟုတ်ဘဲ SQLite တွင် ကပ်လျက်ရှိနေသော `test_status`)။ [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status) ကို ကြည့်ပါ။ |
| `/api/cache/stats` | GET/DELETE | Cache ကိန်းဂဏန်းများ / ရှင်းလင်းခြင်း |
| `/api/modality-bridge/stats` | GET | Memory အတွင်းရှိ `attempts`၊ အောင်မြင်မှုများ/`bridged`၊ ကျရှုံးမှုများ၊ cache hit များ၊ `totalLatencyMs`၊ `latencySamples`၊ sample အရေအတွက်ကို ပိုင်းခြေအဖြစ် သုံးထားသော `averageLatencyMs` နှင့် နောက်ဆုံးအသုံးပြုချိန် (ပြန်လည်စတင်ချိန်တွင် reset ဖြစ်သည်၊ စီမံခန့်ခွဲမှု authentication လိုအပ်သည်) |
| `/api/modality-bridge/video/runtime` | GET | စီမံခန့်ခွဲမှု authentication/probe မတိုင်မီ တင်းကျပ်သော ယုံကြည်ရသည့် loopback စစ်ဆေးမှု၊ သန့်စင်ထားသော FFmpeg/ffprobe ရရှိနိုင်မှုနှင့် version များ (no-store) |
| `/api/modality-bridge/video/extract` | POST | အတွင်းပိုင်း authentication ပြုလုပ်ထားသော ယုံကြည်ရသည့် loopback byte broker၊ 50 MiB input၊ ကန့်သတ်ထားသော queue/32 MiB output၊ capacity အတွက် `503`၊ ချိတ်ဆက်မှုပြတ်တောက်မှုအတွက် `499`၊ deadline အတွက် `504`၊ အများပြည်သူသုံး upload API မဟုတ်ပါ |
### အရန်သိမ်းခြင်းနှင့် Export/Import
| Endpoint | Method | Description |
| --------------------------- | ------ | --------------------------------------------------------------------- |
| `/api/db-backups` | GET | ရရှိနိုင်သော အရန်သိမ်းဆည်းမှုများကို စာရင်းပြုစုရန် |
| `/api/db-backups` | PUT | အရန်သိမ်းဆည်းမှုကို ကိုယ်တိုင်ဖန်တီးရန် |
| `/api/db-backups` | POST | သတ်မှတ်ထားသော အရန်သိမ်းဆည်းမှုတစ်ခုမှ ပြန်လည်ရယူရန် |
| `/api/db-backups/export` | GET | ဒေတာဘေ့စ်ကို .sqlite ဖိုင်အဖြစ် ဒေါင်းလုဒ်လုပ်ရန် |
| `/api/db-backups/import` | POST | ဒေတာဘေ့စ်ကို အစားထိုးရန် .sqlite ဖိုင်ကို အပ်လုဒ်လုပ်ရန် |
| `/api/db-backups/exportAll` | GET | အရန်သိမ်းဆည်းမှုအပြည့်အစုံကို .tar.gz archive အဖြစ် ဒေါင်းလုဒ်လုပ်ရန် |
### Cloud Sync
| Endpoint | Method | Description |
| ---------------------- | ----------- | ---------------------------- |
| `/api/sync/cloud` | အမျိုးမျိုး | Cloud sync လုပ်ဆောင်ချက်များ |
| `/api/sync/initialize` | POST | Sync ကို စတင်သတ်မှတ်ရန် |
| `/api/cloud/*` | အမျိုးမျိုး | Cloud စီမံခန့်ခွဲမှု |
### Tunnels
| Endpoint | Method | Description |
| -------------------------- | ------ | -------------------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET | Dashboard အတွက် Cloudflare Quick Tunnel ၏ ထည့်သွင်းမှု/runtime အခြေအနေကို ဖတ်ရန် |
| `/api/tunnels/cloudflared` | POST | Cloudflare Quick Tunnel ကို ဖွင့်ရန် သို့မဟုတ် ပိတ်ရန် (`action=enable/disable`) |
| `/api/tunnels/ngrok` | GET | Dashboard အတွက် ngrok Tunnel ၏ runtime အခြေအနေကို ဖတ်ရန် |
| `/api/tunnels/ngrok` | POST | ngrok Tunnel ကို ဖွင့်ရန် သို့မဟုတ် ပိတ်ရန် (`action=enable/disable`) |
### CLI Tools
| Endpoint | Method | Description |
| ---------------------------------- | ------ | -------------------- |
| `/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 runtime |
CLI တုံ့ပြန်ချက်များတွင် `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason` တို့ ပါဝင်သည်။
### ACP Agents
| Endpoint | Method | Description |
| ----------------- | ------ | --------------------------------------------------------------------------------------- |
| `/api/acp/agents` | GET | ရှာဖွေတွေ့ရှိထားသော agent အားလုံးကို အခြေအနေနှင့်တကွ စာရင်းပြုစုရန် (built-in + custom) |
| `/api/acp/agents` | POST | စိတ်ကြိုက် agent ထည့်ရန် သို့မဟုတ် ရှာဖွေမှု cache ကို ပြန်လည်စတင်ရန် |
| `/api/acp/agents` | DELETE | `id` query param ဖြင့် စိတ်ကြိုက် agent တစ်ခုကို ဖယ်ရှားရန် |
GET တုံ့ပြန်ချက်တွင် `agents[]` (id, name, binary, version, installed, protocol, isCustom) နှင့် `summary` (total, installed, notFound, builtIn, custom) တို့ ပါဝင်သည်။
### ချို့ယွင်းမှုခံနိုင်ရည်နှင့် Rate Limits
| Endpoint | Method | Description |
| --------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `/api/resilience` | GET/PATCH | တောင်းဆိုမှု queue၊ ချိတ်ဆက်မှု cooldown၊ provider breaker နှင့် စောင့်ဆိုင်းမှုဆိုင်ရာ သတ်မှတ်ချက်များကို ရယူရန်/အပ်ဒိတ်လုပ်ရန် |
| `/api/resilience/reset` | POST | Provider circuit breaker များကို ပြန်လည်သတ်မှတ်ရန် |
| `/api/resilience/model-cooldowns` | GET | လက်ရှိအသက်ဝင်နေသော (provider, connection, model) တစ်ခုချင်းအလိုက် lockout များကို ကျန်ရှိချိန်အလိုက် စီပြီး စာရင်းပြုစုရန် |
| `/api/resilience/model-cooldowns` | DELETE | Model lockout တစ်ခုကို ရှင်းလင်းရန် — body `{provider, model}` သို့မဟုတ် အားလုံးကို ဖျက်ရန် `{all: true}` |
| `/api/rate-limits` | GET | Account တစ်ခုချင်းအလိုက် rate limit အခြေအနေ |
| `/api/rate-limit` | GET | Global rate limit configuration |
> `/api/resilience/*` route လေးခုစလုံးတွင် **စီမံခန့်ခွဲမှု authentication** (`requireManagementAuth`) လိုအပ်သည်။ Provider breaker၊ connection cooldown နှင့် model lockout တို့၏ အပြည့်အစုံ ခွဲခြားရှင်းလင်းချက်အတွက် [ချို့ယွင်းမှုခံနိုင်ရည် (အသေးစိတ်)](#resilience-extended) ကို ကြည့်ပါ။
### Evals
| Endpoint | Method | Description |
| ------------ | -------- | -------------------------------------------------------------- |
| `/api/evals` | GET/POST | Eval suite များကို စာရင်းပြုစုရန် / အကဲဖြတ်မှုကို လုပ်ဆောင်ရန် |
### မူဝါဒများ
| Endpoint | Method | Description |
| --------------- | --------------- | ----------------------------------- |
| `/api/policies` | GET/POST/DELETE | Routing မူဝါဒများကို စီမံခန့်ခွဲရန် |
### စည်းမျဉ်းလိုက်နာမှု
| Endpoint | Method | Description |
| --------------------------- | ------ | ----------------------------------------------------- |
| `/api/compliance/audit-log` | GET | စည်းမျဉ်းလိုက်နာမှုဆိုင်ရာ audit log (နောက်ဆုံး N ခု) |
### v1beta (Gemini နှင့် ကိုက်ညီသော)
| Endpoint | Method | Description |
| -------------------------- | ------ | ------------------------------------------------ |
| `/v1beta/models` | GET | Model များကို Gemini format ဖြင့် စာရင်းပြုစုရန် |
| `/v1beta/models/{...path}` | POST | Gemini `generateContent` endpoint |
ဤ endpoint များသည် မူရင်း Gemini SDK နှင့် ကိုက်ညီမှုကို မျှော်လင့်သည့် client များအတွက် Gemini ၏ API format ကို ထင်ဟပ်ပေးသည်။
### အတွင်းပိုင်း / System API များ
| Endpoint | Method | ဖော်ပြချက် |
| ------------------------ | ------ | ----------------------------------------------------------------------------- |
| `/api/init` | GET | အပလီကေးရှင်း စတင်ခြင်း စစ်ဆေးမှု (ပထမဆုံး အသုံးပြုချိန်တွင် အသုံးပြုသည်) |
| `/api/tags` | GET | Ollama နှင့် တွဲဖက်အသုံးပြုနိုင်သော မော်ဒယ် တဂ်များ (Ollama client များအတွက်) |
| `/api/restart` | POST | ဆာဗာကို ချောမွေ့စွာ ပြန်လည်စတင်ရန် လုပ်ဆောင်သည် |
| `/api/shutdown` | POST | ဆာဗာကို ချောမွေ့စွာ ပိတ်ရန် လုပ်ဆောင်သည် |
| `/api/system/env/repair` | POST | OAuth provider ပတ်ဝန်းကျင် variable များကို ပြုပြင်သည် |
> **မှတ်ချက်:** ဤ endpoint များကို စနစ်အတွင်းပိုင်း၌ သို့မဟုတ် Ollama client နှင့် တွဲဖက်အသုံးပြုနိုင်ရန် အသုံးပြုသည်။ ပုံမှန်အားဖြင့် နောက်ဆုံးအသုံးပြုသူများက ၎င်းတို့ကို ခေါ်ယူအသုံးပြုခြင်း မရှိပါ။
### OAuth ပတ်ဝန်းကျင် ပြုပြင်ခြင်း _(v3.6.1+)_
```bash
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
```
သတ်မှတ်ထားသော provider တစ်ခုအတွက် ပျောက်ဆုံးနေသော သို့မဟုတ် ပျက်စီးနေသော OAuth ပတ်ဝန်းကျင် variable များကို ပြုပြင်သည်။ အောက်ပါတို့ကို ပြန်ပေးသည်-
```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
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```
ပြင်ဆင်သတ်မှတ်ထားသော မည်သည့် STT provider ကိုမဆို အသုံးပြု၍ အသံဖိုင်များကို စာသားအဖြစ် ကူးပြောင်းပါ။ ပထမဆုံး path
segment သည် မူရင်း provider (`openai/…`, `deepgram/…`) ကို ရွေးချယ်ပေးသည်။ အခြား vendor ၏ model ကို
ပြန်လည်ထုတ်ပေးသည့် gateway များတွင် အပြည့်အစုံသတ်မှတ်ထားသော id
(`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
}
```
**နမူနာ model id များ:** `openai/whisper-1` (OpenAI key တစ်ခု လိုအပ်သည်),
`openrouter/deepgram/nova-3` (OpenRouter key တစ်ခု လိုအပ်သည်),
`deepgram/nova-3` (မူရင်း Deepgram key တစ်ခု လိုအပ်သည်)။ `deepgram/nova-3` ဟုသာ
တောင်းဆိုခြင်းသည် OpenRouter ကို **အသုံးမပြုပါ**။
**ပံ့ပိုးထားသော format များ:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`။
---
## Ollama နှင့် ကိုက်ညီမှု
Ollama ၏ API format ကို အသုံးပြုသော client များအတွက်:
```bash
# Chat endpoint (Ollama format)
POST /v1/api/chat
# Model စာရင်း (Ollama format)
GET /api/tags
```
တောင်းဆိုချက်များကို Ollama format နှင့် internal format များကြား အလိုအလျောက် ပြောင်းလဲပေးသည်။
## Token ပါသော VS Code / Header မလိုသည့် Alias များ
Integration တစ်ခုက `Authorization` header ကို ထည့်သွင်းမပေးနိုင်ဘဲ API key ကို base URL အတွင်း ထည့်သွင်းရန် လိုအပ်သည့်အခါ ဤ alias များကို အသုံးပြုပါ။
```bash
# OpenAI ပုံစံ catalog alias
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# OpenAI ပုံစံ chat alias များ
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Ollama ပုံစံ alias များ
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` တို့ကဲ့သို့ handler များကိုပင် ပြန်လည်အသုံးပြုသောကြောင့် တုံ့ပြန်ချက်ပုံစံများသည် တူညီနေမည်ဖြစ်သည်။
- Client က custom header များကို ပံ့ပိုးသည့်အခါတိုင်း `Authorization: Bearer ...` ကို ဦးစားပေးအသုံးပြုပါ။
- URL အခြေပြု token များသည် reverse-proxy log များ၊ browser history နှင့် OmniRoute ပြင်ပရှိ telemetry များတွင် ပေါ်လာနိုင်သည်။ ၎င်းတို့ကို မူလ authentication mode အဖြစ်မဟုတ်ဘဲ ကိုက်ညီမှုအတွက် ရွေးချယ်စရာတစ်ခုအဖြစ် သတ်မှတ်ပါ။
---
## Telemetry
```bash
# Latency telemetry အနှစ်ချုပ်ကို ရယူရန် (provider တစ်ခုစီအတွက် 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 key အားလုံးအတွက် အသုံးစရိတ်ကန့်သတ်ချက် အခြေအနေကို ရယူရန်
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"
}
```
> **Schema မှတ်ချက်များ** (`setBudgetSchema`): `apiKeyId` ကို မဖြစ်မနေ ထည့်သွင်းရမည်ဖြစ်ပြီး `dailyLimitUsd`, `weeklyLimitUsd` သို့မဟုတ် `monthlyLimitUsd` တို့အနက် အနည်းဆုံးတစ်ခုသည် သုညထက် ကြီးရမည်။ ထည့်သွင်းရန် မဖြစ်မနေမလိုသော field များမှာ `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`) တို့ဖြစ်သည်။ ယခင် `{keyId, limit, period}` ပုံစံသည် `400 Bad Request` ကို ပြန်ပေးသည်။
## တိုကင် ကန့်သတ်ချက်များ
API key တစ်ခုချင်းစီအလိုက် **တိုကင်** ဘတ်ဂျက်များ (အထက်ပါ USD အခြေပြု ဘတ်ဂျက်နှင့် သီးခြားဖြစ်သည်)။ တောင်းဆိုမှု လမ်းကြောင်းပေါ်တွင် တိုက်ရိုက် သက်ရောက်စေသည်။ key တစ်ခု၏ လက်ရှိအချိန်ကာလအတွင်း အသုံးပြုမှုပမာဏသည် ၎င်း၏ ကန့်သတ်ချက်သို့ ရောက်ရှိသွားသောအခါ တောင်းဆိုမှုများကို `429 Too Many Requests` ဖြင့် ငြင်းပယ်သည်။ ကန့်သတ်ချက်များကို သတ်မှတ်ထားသော `model` တစ်ခု၊ `provider` တစ်ခုအတွက် နယ်ပယ်သတ်မှတ်နိုင်သည် သို့မဟုတ် key တစ်ခုလုံးအနှံ့ `global` အဖြစ် အသုံးချနိုင်သည်။ တောင်းဆိုမှုတစ်ခုနှင့် ကိုက်ညီသော ကန့်သတ်ချက်များစွာရှိပါက အတင်းကျပ်ဆုံး ကန့်သတ်ချက်ကို အသုံးပြုသည်။
```bash
# Key တစ်ခု၏ တိုကင်ကန့်သတ်ချက်များကို စာရင်းပြုစုရန် (တိုက်ရိုက် အချိန်ကာလ အသုံးပြုမှု ပါဝင်သည်)
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 မှတ်ချက်များ** (`setTokenLimitSchema`)၊ `apiKeyId` နှင့် `scopeType` (`model` | `provider` | `global`) တို့သည် မဖြစ်မနေ လိုအပ်သည်။ `scopeType` သည် `global` မဟုတ်လျှင် `scopeValue` လိုအပ်သည် (ဥပမာ `model` နယ်ပယ်အတွက် model id၊ `provider` နယ်ပယ်အတွက် provider id)။ `tokenLimit` သည် အပေါင်းကိန်းပြည့် ဖြစ်ရမည် (string မှ အလိုအလျောက် ပြောင်းလဲပေးသည်)။ ရွေးချယ်နိုင်သည်များမှာ `id` (အသစ်ဖန်တီးရန် မထည့်ပါနှင့်၊ အပ်ဒိတ်လုပ်ရန် ထည့်ပါ)၊ `resetInterval` (`daily` | `weekly` | `monthly`၊ မူလသတ်မှတ်ချက် `monthly`)၊ `resetTime` (`HH:MM`)၊ `enabled` (မူလသတ်မှတ်ချက် `true`) တို့ဖြစ်သည်။ `GET` တုံ့ပြန်မှုများတွင် ကန့်သတ်ချက်တစ်ခုချင်းစီကို `tokensUsed`၊ `remaining`၊ `windowStart`၊ `periodStartAt` နှင့် `nextResetAt` တို့ဖြင့် ထပ်မံဖြည့်စွက်ပေးသည်။ ၎င်းသည် စီမံခန့်ခွဲမှုအဆင့် endpoint တစ်ခုဖြစ်သည် (authz pipeline က ဗဟိုမှ auth ကို သက်ရောက်စေသည်)။
## တောင်းဆိုမှု လုပ်ဆောင်ပုံ
1. Client က တောင်းဆိုမှုကို `/v1/*` သို့ ပေးပို့သည်
2. Route handler က `handleChat`၊ `handleEmbedding`၊ `handleAudioTranscription` သို့မဟုတ် `handleImageGeneration` ကို ခေါ်သည်
3. Model ကို ဖြေရှင်းသတ်မှတ်သည် (တိုက်ရိုက် provider/model သို့မဟုတ် alias/combo)
4. Account ရရှိနိုင်မှု စစ်ထုတ်ခြင်းဖြင့် local DB မှ credentials များကို ရွေးချယ်သည်
5. Chat အတွက် `handleChatCore` က semantic/signature cache ကို စစ်ဆေးပြီး combo compression ဆက်တင်များကို ဖြေရှင်းသတ်မှတ်သည်
6. ဖွင့်ထားသည့်အခါ provider ဘာသာပြန်ပြောင်းလဲမှုမတိုင်မီ proactive compression ကို လုပ်ဆောင်သည် (`lite`၊ Caveman၊ RTK သို့မဟုတ် stacked)
7. Provider executor က upstream တောင်းဆိုမှုကို ပေးပို့သည်
8. တုံ့ပြန်မှုကို client format သို့ ပြန်လည်ဘာသာပြန်ပြောင်းလဲသည် (chat) သို့မဟုတ် မူလအတိုင်း ပြန်ပေးသည် (embeddings/images/audio)
9. အသုံးပြုမှု၊ compression analytics နှင့် တောင်းဆိုမှု မှတ်တမ်းများကို မှတ်တမ်းတင်သည်
10. Combo စည်းမျဉ်းများအရ အမှားများ ဖြစ်ပေါ်သည့်အခါ fallback ကို အသုံးပြုသည်
ဗိသုကာဖွဲ့စည်းပုံ အပြည့်အစုံ ကိုးကားချက်၊ [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)
---
## Combo စီမံခန့်ခွဲမှု
အဆင့်မြင့် routing combo များ (`/api/combos*` အောက်တွင် အနှစ်ချုပ်ထားပြီးဖြစ်သည်) ကို model id pattern တစ်ခုမှ 1:1 အချိုးဖြင့်လည်း ချိတ်ဆက်သတ်မှတ်နိုင်ပြီး OpenAI ပုံစံ model id တစ်ခုကို combo တစ်ခုဆီ ပွင့်လင်းမြင်သာစွာ လမ်းကြောင်းပြောင်းပေးနိုင်သည်။
| Method | Path | ဖော်ပြချက် |
| ------ | -------------------------------- | ------------------------------------------------------------------------------------- |
| 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]` | ရှိပြီးသား ချိတ်ဆက်မှုတစ်ခု၏ field များကို အပ်ဒိတ်လုပ်ရန် |
| DELETE | `/api/model-combo-mappings/[id]` | ချိတ်ဆက်မှုတစ်ခုကို ဖယ်ရှားရန် |
**Auth:** စီမံခန့်ခွဲမှု session/API key (`requireManagementAuth`)။
---
## Webhooks
OmniRoute ဖြစ်ရပ်များ (တောင်းဆိုမှု ပြီးဆုံးခြင်း၊ quota ကုန်ဆုံးခြင်း၊ key လဲလှယ်ခြင်း စသည်တို့) အတွက် အပြင်ဘက်သို့ ပေးပို့သည့် webhook စာရင်းသွင်းမှုများ။
| Method | Path | ဖော်ပြချက် |
| ------ | ------------------------- | ---------------------------------------------------------------------------------------------- |
| GET | `/api/webhooks` | Webhook များကို စာရင်းပြုစုသည် (လျှို့ဝှက်ချက်များကို `<prefix>...` ပုံစံဖြင့် ဖုံးကွယ်ထားသည်) |
| POST | `/api/webhooks` | Webhook ဖန်တီးသည် — body: `{url, events?: ["*"], secret?, description?}` |
| GET | `/api/webhooks/[id]` | Webhook တစ်ခုကို ရယူသည် |
| PUT | `/api/webhooks/[id]` | url/events/secret/description ကို အပ်ဒိတ်လုပ်သည် |
| DELETE | `/api/webhooks/[id]` | Webhook တစ်ခုကို ဖယ်ရှားသည် |
| POST | `/api/webhooks/[id]/test` | Webhook URL သို့ စမ်းသပ် payload တစ်ခု ပေးပို့ပြီး ပို့ဆောင်မှုအခြေအနေကို ပြန်ပေးသည် |
**အထောက်အထားစစ်ဆေးခြင်း:** စီမံခန့်ခွဲမှု session/API key (`requireManagementAuth`)။
---
## စာရင်းသွင်းထားသော Key များ (အလိုအလျောက်စီမံခန့်ခွဲမှု)
နေ့စဉ်/နာရီအလိုက် quota များဖြင့် နောက်ခံ provider/account တစ်ခုနှင့် ချိတ်ဆက်၍ API key များကို ထုတ်ပေးရန်နှင့် လဲလှယ်ရန် auto-key စီမံခန့်ခွဲမှု subsystem က အသုံးပြုသည်။
| Method | Path | ဖော်ပြချက် |
| ------ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/registered-keys` | စာရင်းသွင်းထားသော key များကို စာရင်းပြုစုသည် (ဖုံးကွယ်ထားသော prefix သာလျှင်) |
| POST | `/api/v1/registered-keys` | စာရင်းသွင်းထားသော key အသစ်တစ်ခု ထုတ်ပေးသည် — body: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`။ မူရင်း key ကို **တစ်ကြိမ်သာ** ပြန်ပေးသည်။ quota ကြောင့် ငြင်းပယ်ပါက `429` ကို ပြန်ပေးသည်။ |
| GET | `/api/v1/registered-keys/[id]` | စာရင်းသွင်းထားသော key ၏ metadata ကို ရယူသည် (မူရင်းအချက်အလက် မပါဝင်ပါ) |
| DELETE | `/api/v1/registered-keys/[id]` | စာရင်းသွင်းထားသော key ကို ရုပ်သိမ်းသည် |
| POST | `/api/v1/registered-keys/[id]/revoke` | ရုပ်သိမ်းရန် သီးခြားသတ်မှတ်ထားသော endpoint (DELETE နှင့် အကျိုးသက်ရောက်မှု တူညီသည်) |
**အထောက်အထားစစ်ဆေးခြင်း:** Bearer API key (`isAuthenticated`)။ `/v1/quotas/check` နှင့် `/v1/issues/report` ကိုလည်း ကြည့်ပါ။
---
## Agents Protocol
OmniRoute အသုံးပြုသူများကိုယ်စား အဝေးမှ လုပ်ဆောင်သည့် cloud agent လုပ်ငန်းများ (Claude Code၊ Codex Cloud၊ OpenHands စသည်တို့)။
| Method | Path | Description |
| ------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/agents/tasks` | လုပ်ငန်းများကို စာရင်းပြုစုသည် — ရွေးချယ်နိုင်သော `?provider=`၊ `?status=`၊ `?limit=` (1–500၊ မူလတန်ဖိုး 50) |
| POST | `/api/v1/agents/tasks` | လုပ်ငန်းဖန်တီးသည် — body ကို `CreateCloudAgentTaskSchema` (`providerId`၊ `prompt`၊ `source`၊ `options?`) ဖြင့် စစ်ဆေးအတည်ပြုသည်။ task envelope နှင့်အတူ `201` ကို ပြန်ပေးသည် |
| DELETE | `/api/v1/agents/tasks?id=...` | လုပ်ငန်းတစ်ခုကို ဖျက်သည် |
| GET | `/api/v1/agents/tasks/[id]` | လုပ်ငန်းကို ဖတ်သည် — `external_id` သတ်မှတ်ထားပါက upstream cloud agent ထံမှ status ကို synchronous ပုံစံဖြင့် ပြန်လည်အပ်ဒိတ်လုပ်သည် |
| POST | `/api/v1/agents/tasks/[id]` | ခွဲခြားသတ်မှတ်ထားသော action: `{action: "approve"}`၊ `{action: "message", message}` သို့မဟုတ် `{action: "cancel"}` |
| DELETE | `/api/v1/agents/tasks/[id]` | id ဖြင့် သီးခြားလုပ်ငန်းတစ်ခုကို ဖျက်သည် |
> **Auth:** method တိုင်းတွင် management auth လိုအပ်သည် (`requireCloudAgentManagementAuth`)။ v3.8.0 မတိုင်မီတွင် ၎င်းတို့သည် authentication မလိုအပ်ခဲ့ပါ — breaking change အတွက် commit `588a0333` ကို ကြည့်ပါ။
```bash
# Claude Code cloud လုပ်ငန်းတစ်ခု ဖန်တီးရန်
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":"..."}}'
```
---
## Management Proxies
Provider များ၊ account များ သို့မဟုတ် global အဆင့်တွင် သတ်မှတ်ပေးနိုင်သော outbound HTTP(S)/SOCKS proxy များ။
| Method | Path | Description |
| ------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/management/proxies` | Proxy များကို စာရင်းပြုစုသည် (`?id=` ဖြင့် တစ်ခုကို ပြန်ပေးပြီး `?id=&where_used=1` ဖြင့် assignment graph ကို ပြန်ပေးသည်) |
| POST | `/api/v1/management/proxies` | Proxy ဖန်တီးသည် — body ကို `createProxyRegistrySchema` ဖြင့် စစ်ဆေးအတည်ပြုသည် |
| PATCH | `/api/v1/management/proxies` | Proxy ကို အပ်ဒိတ်လုပ်သည် — body ကို `updateProxyRegistrySchema` ဖြင့် စစ်ဆေးအတည်ပြုသည် (`id` လိုအပ်သည်) |
| DELETE | `/api/v1/management/proxies?id=...&force=1` | Proxy ကို ဖျက်သည် (assignment များကို ဖြုတ်ရန် `force=1` ကို အသုံးပြုပါ) |
| GET | `/api/v1/management/proxies/assignments` | Assignment များကို စာရင်းပြုစုသည် — `proxy_id`၊ `scope`၊ `scope_id` ဖြင့် စစ်ထုတ်နိုင်သည်။ connection တစ်ခုအတွက် လက်ရှိအသုံးပြုနေသော proxy ကို ဖြေရှင်းရန် `resolve_connection_id=<id>` ကို ပေးပို့ပါ |
| PUT | `/api/v1/management/proxies/assignments` | သတ်မှတ်ပေးသည် — body ကို `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`) ဖြင့် စစ်ဆေးအတည်ပြုသည်။ dispatcher cache ကို ရှင်းလင်းသည် |
| PUT | `/api/v1/management/proxies/bulk-assign` | အစုလိုက်သတ်မှတ်ပေးသည် — body ကို `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) ဖြင့် စစ်ဆေးအတည်ပြုသည် |
| GET | `/api/v1/management/proxies/health?hours=24` | သတ်မှတ်ထားသော အချိန်ကာလတစ်ခုအတွင်း proxy health (အောင်မြင်/မအောင်မြင် အရေအတွက်များ၊ latency) ကို စုစည်းဖော်ပြသည် |
**Auth:** route တိုင်းတွင် management session/API key လိုအပ်သည် (`requireManagementAuth`)။
> လုပ်ငန်းဖော်ပြချက်ထဲရှိ `POST /api/v1/management/proxies/[id]/assignments` နှင့် `POST /api/v1/management/proxies/[id]/health` တို့ကို အထက်တွင်ပြထားသော flat `/assignments` နှင့် `/health` route များက ဆောင်ရွက်ပေးသည် — codebase ထဲတွင် id တစ်ခုချင်းအလိုက် subroute များ မရှိပါ။
---
## ခံနိုင်ရည်ရှိမှု (တိုးချဲ့)
OmniRoute သည် တစ်ခုနှင့်တစ်ခု သီးခြားဖြစ်သော ယာယီချို့ယွင်းမှု ကိုင်တွယ်ရေး ယန္တရား သုံးမျိုးကို ဖော်ထုတ်ပေးထားသည်။ အောက်ပါ စီမံခန့်ခွဲမှု endpoint များမှတစ်ဆင့် အော်ပရေတာများသည် ၎င်းတို့ကို ဖတ်ရှုနိုင်ပြီး မူလသတ်မှတ်ချက်ကို ပြောင်းလဲသတ်မှတ်နိုင်သည်-
| အတိုင်းအတာ | အခြေအနေသိမ်းဆည်းမှု | ဖတ်ရှုရန် | ပြန်လည်သတ်မှတ်ရန် / ရှင်းလင်းရန် |
| ------------------- | ---------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------ |
| Provider breaker | `domain_circuit_breakers` + memory အတွင်း | `/api/monitoring/health` | `POST /api/resilience/reset` |
| Connection cooldown | provider connection များရှိ `rateLimitedUntil` | `/api/rate-limits`, `/api/providers/[id]` | (လိုအပ်ချိန်တွင် ပြန်လည်ဖွင့်ပေးသည်၊ provider PUT မှတစ်ဆင့် ရှင်းလင်းပါ) |
| Model lockout | Memory အတွင်းရှိ model-availability registry | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` |
`PATCH /api/resilience` သည် `providerBreaker.oauth` နှင့် `providerBreaker.apikey` အောက်ရှိ provider breaker override များကို လက်ခံသည်။ Profile တစ်ခုစီသည် `degradationThreshold`, `failureThreshold` နှင့် `resetTimeoutMs` တို့ကို ပံ့ပိုးပြီး တူညီသော field များကို Dashboard → Settings → Resilience တွင်လည်း ရရှိနိုင်သည်။
```bash
# Model lockout တစ်ခုကို ရှင်းလင်းရန်
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"}'
# Lockout အားလုံးကို ရှင်းလင်းရန်
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
```
အယူအဆဆိုင်ရာ ရည်ညွှန်းချက်အပြည့်အစုံနှင့် breaker မူလသတ်မှတ်ချက်များအတွက် [`CLAUDE.md`](../../CLAUDE.md) → "Resilience Runtime State" ကို ကြည့်ပါ။
---
## Skill များ
OmniRoute ကို စိတ်ကြိုက် executable handler များနှင့် marketplace ပေါင်းစည်းမှုများဖြင့် တိုးချဲ့ရန်အတွက် Skill framework ဖြစ်သည်။
| Method | Path | ဖော်ပြချက် |
| ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/skills` | ထည့်သွင်းထားသော skill များကို စာရင်းပြုစုသည် — `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local` တို့ဖြင့် စစ်ထုတ်နိုင်ပြီး စာမျက်နှာခွဲထားသည် |
| GET | `/api/skills/[id]` | Skill တစ်ခုကို ရယူသည် |
| PUT | `/api/skills/[id]` | Skill ကို အပ်ဒိတ်လုပ်သည် (အမည်၊ ဖော်ပြချက်၊ mode၊ schema၊ handler၊ tag များ) |
| DELETE | `/api/skills/[id]` | Skill တစ်ခုကို ဖြုတ်ချသည် |
| POST | `/api/skills/install` | Raw manifest တစ်ခုမှ skill ကို ထည့်သွင်းသည် — body: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
| GET | `/api/skills/executions` | လတ်တလော skill လုပ်ဆောင်မှုများကို စာရင်းပြုစုသည် (input/output/duration ပါဝင်သော audit trail) |
| GET | `/api/skills/marketplace?q=...` | SkillsMP marketplace မှ ရှာဖွေမှု/လူကြိုက်များသောစာရင်း (`skillsmpApiKey` setting လိုအပ်သည်) |
| POST | `/api/skills/marketplace/install` | SkillsMP မှ id ဖြင့် skill တစ်ခုကို ထည့်သွင်းသည် |
| GET | `/api/skills/skillssh?q=&limit=` | skills.sh registry တွင် ရှာဖွေသည် |
| POST | `/api/skills/skillssh/install` | skills.sh မှ id ဖြင့် skill တစ်ခုကို ထည့်သွင်းသည် |
**အထောက်အထားစိစစ်ခြင်း:** စီမံခန့်ခွဲမှု session/API key။ Marketplace ရှာဖွေမှု route များသည် စီမံခန့်ခွဲမှု အထောက်အထားစိစစ်ခြင်း သို့မဟုတ် Bearer API key (`isAuthenticated`) တစ်ခုခုကို လက်ခံသည်။
---
## မမ်မိုရီ
API key / session တစ်ခုချင်းစီအလိုက် သီးခြားသတ်မှတ်ထားသည့် ရေရှည်တည်တံ့သော စကားဝိုင်းဆိုင်ရာ/အချက်အလက်ဆိုင်ရာ မမ်မိုရီသိုလှောင်မှု။
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| -------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/memory` | မမ်မိုရီများကို စာရင်းပြုစုခြင်း — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, `offset/limit` သို့မဟုတ် `page/limit` စာမျက်နှာခွဲခြင်းနှင့်အတူ |
| POST | `/api/memory` | မမ်မိုရီဖန်တီးခြင်း — Zod ဖြင့် စစ်ဆေးအတည်ပြုထားသော body: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET | `/api/memory/[id]` | မမ်မိုရီတစ်ခုကို ရယူခြင်း |
| DELETE | `/api/memory/[id]` | မမ်မိုရီတစ်ခုကို ဖျက်ခြင်း |
| GET | `/api/memory/health` | မမ်မိုရီစနစ်ခွဲ၏ လည်ပတ်မှုအခြေအနေ (DB ချိတ်ဆက်နိုင်မှု၊ embeddings backend၊ vector index အခြေအနေ) |
**အထောက်အထားစိစစ်ခြင်း:** စီမံခန့်ခွဲမှု session/API key (`requireManagementAuth`)။ `type` enum: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (`src/lib/memory/types.ts` ရှိ `MemoryType` ကိုကြည့်ပါ)။
---
## MCP ဆာဗာ
OmniRoute တွင် transport ၃ မျိုး (stdio, SSE, streamable-http) နှင့် scope သတ်မှတ်ထားသော tools များပါဝင်သည့် ထည့်သွင်းတည်ဆောက်ထားသော Model Context Protocol ဆာဗာတစ်ခု ပါရှိသည်။ အောက်ပါ dashboard endpoint များသည် အခြေအနေ/audit ဒေတာကို ဖတ်ရှုပြီး HTTP transport များကို proxy လုပ်ပေးသည်။
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Heartbeat၊ transport၊ အွန်လိုင်းအခြေအနေ၊ နောက်ဆုံးခေါ်ဆိုမှု၊ အသုံးအများဆုံး tools နှင့် 24 နာရီအတွင်း အောင်မြင်မှုနှုန်း |
| GET | `/api/mcp/tools` | `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` တို့ပါဝင်သော MCP tools စာရင်း |
| GET | `/api/mcp/sse` | SSE transport အတွက် SSE stream ကို ဖွင့်ခြင်း (MCP ပိတ်ထားလျှင် သို့မဟုတ် transport မကိုက်ညီလျှင် `503` ပြန်ပေးသည်) |
| POST | `/api/mcp/sse` | SSE transport ပေါ်တွင် JSON-RPC frame ပေးပို့ခြင်း |
| GET | `/api/mcp/stream` | Streamable HTTP transport ၏ SSE ဘက်ခြမ်းကို ဖွင့်ခြင်း (ဆာဗာမှ စတင်ပေးပို့သော မက်ဆေ့ချ်များ) |
| POST | `/api/mcp/stream` | Streamable HTTP transport ပေါ်တွင် JSON-RPC frame ပေးပို့ခြင်း |
| DELETE | `/api/mcp/stream` | Streamable HTTP session တစ်ခုကို အဆုံးသတ်ခြင်း |
| GET | `/api/mcp/audit` | Audit မှတ်တမ်းကို မေးမြန်းခြင်း — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | စုစည်းထားသော audit ကိန်းဂဏန်းများ (စုစုပေါင်း၊ အောင်မြင်မှုနှုန်း၊ ပျမ်းမျှကြာချိန်၊ အသုံးအများဆုံး tools) |
**အထောက်အထားစိစစ်ခြင်း:** `sse`/`stream` transport များသည် MCP သီးသန့် အထောက်အထားစိစစ်မှုမျက်နှာပြင် (`mcp` scope ပါသော Bearer API key) ကို လိုက်နာသည်။ `status`/`tools`/`audit*` route များကို dashboard မှ ဖတ်ရှုနိုင်သည် (dashboard host သို့ ရောက်ရှိနိုင်ခြင်းအပြင် နောက်ထပ်အထောက်အထားစိစစ်မှု မလိုအပ်ပါ)။
> HTTP transport နှစ်မျိုးလုံးကို `settings.mcpEnabled` နှင့် `settings.mcpTransport` တို့ဖြင့် ထိန်းချုပ်ထားသည် — transport မကိုက်ညီပါက `400` ပြန်ပေးပြီး MCP ပိတ်ထားပါက `503` ပြန်ပေးသည်။
---
## A2A ဆာဗာ
OmniRoute သည် A2A (Agent-to-Agent) JSON-RPC 2.0 endpoint တစ်ခုနှင့် စစ်ဆေးခြင်း/dashboard အသုံးပြုမှုအတွက် 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": "ဤ coding task ကို လမ်းကြောင်းရွေးပေးပါ"}]
}
}
```
ပံ့ပိုးထားသော method များ (အားလုံးကို `settings.a2aEnabled` ဖြင့် ထိန်းချုပ်ထားသည်)-
| Method | ဖော်ပြချက် |
| ---------------- | --------------------------------------------------------------------------------------- |
| `message/send` | တစ်ပြိုင်တည်းလုပ်ဆောင်သော skill execution; `{task, artifacts, metadata}` ကို ပြန်ပေးသည် |
| `message/stream` | တူညီသော skill အစု၏ streaming SSE execution |
| `tasks/get` | `taskId` ဖြင့် task တစ်ခုကို ရယူသည် |
| `tasks/cancel` | `taskId` ဖြင့် task တစ်ခုကို ပယ်ဖျက်သည် |
အသင့်ပါရှိသော skill များ- `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`။
### Agent Card
```bash
GET /.well-known/agent.json
```
အများသုံး A2A agent card (အမည်၊ ဖော်ပြချက်၊ စွမ်းဆောင်ရည်များ၊ skill catalog၊ auth scheme) ကို ပြန်ပေးသည် — အများသုံးအဖြစ် 1h ကြာ cache လုပ်ထားသည်။ auth မလိုအပ်ပါ။
### REST အကူအညီများ
| Method | Path | ဖော်ပြချက် |
| ------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/a2a/status` | A2A ဖွင့်ထားမှု + task စာရင်းအင်းများ + cache လုပ်ထားသော agent card အနှစ်ချုပ် |
| GET | `/api/a2a/tasks` | task များကို စာရင်းပြုစုသည် — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST | `/api/a2a/tasks` | (REST helper အဖြစ် မတည်ဆောက်ရသေးပါ — JSON-RPC `message/send` မှတစ်ဆင့် ဖန်တီးပါ) |
| GET | `/api/a2a/tasks/[id]` | task တစ်ခုကို ရယူသည် |
| POST | `/api/a2a/tasks/[id]/cancel` | task တစ်ခုကို ပယ်ဖျက်သည် |
**Auth:** REST helper များသည် management auth မပါဘဲ အလုပ်လုပ်သည် (dashboard မှ ဖတ်ရှုနိုင်သည်); JSON-RPC `/a2a` route သည် ပြင်ဆင်သတ်မှတ်ထားပါက Bearer `OMNIROUTE_API_KEY` ကို အသုံးပြုသည်။
---
## Cloud၊ Evals နှင့် Assess
| Method | Path | ဖော်ပြချက် |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Bearer key တစ်ခုကို အတည်ပြုပြီး cloud sync client များအတွက် ဖုံးကွယ်ထားသော provider connection များ + model alias များကို ပြန်ပေးသည် |
| POST | `/api/cloud/credentials/update` | cloud နှင့် sync လုပ်ထားသော provider တစ်ခုအတွက် ကုဒ်ဝှက်ထားသည့် credential များကို အပ်ဒိတ်လုပ်သည် |
| POST | `/api/cloud/model/resolve` | local routing table ကို အသုံးပြု၍ logical model id တစ်ခုကို တိကျသော provider/model အဖြစ် ဖြေရှင်းသတ်မှတ်သည် |
| GET | `/api/cloud/models/alias` | cloud sync သို့ ဖော်ထုတ်ထားသည့် model alias များကို စာရင်းပြုစုသည် |
| GET | `/api/assess` | နောက်ဆုံး assessment အမျိုးအစားခွဲခြားမှုများကို ဖတ်ရှုသည် (provider/model တစ်ခုချင်းစီအလိုက်) |
| POST | `/api/assess` | assessment တစ်ခုကို လုပ်ဆောင်သည် — body: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | အသင့်ပါရှိသော eval suite များ + နောက်ဆုံး run များကို စာရင်းပြုစုသည် |
| POST | `/api/evals` | eval run တစ်ခုကို စတင်စေသည် |
| POST | `/api/evals/suites` | စိတ်ကြိုက် eval suite တစ်ခုကို ဖန်တီးသည် — body ကို `evalSuiteSaveSchema` ဖြင့် အတည်ပြုသည် |
| GET | `/api/evals/suites/[id]` | စိတ်ကြိုက် eval suite တစ်ခုကို ရယူသည် |
**Auth:** `/api/cloud/auth` သည် Bearer key တစ်ခုကို တိုက်ရိုက်အတည်ပြုသည်; အခြား `/api/cloud/*`, `/api/evals/*` နှင့် `/api/assess` route များတွင် management session/API key လိုအပ်သည်။ `/api/assess` POST သည် discriminated-union scope schema ပါသော `validateBody` ကို အသုံးပြုသည်။
---
## ACP (Agent Client Protocol) စီမံခန့်ခွဲမှု
ကလေးလုပ်ငန်းစဉ်များအဖြစ် လုပ်ဆောင်သည်။ ဤ endpoint များသည် ACP agent ရှာဖွေသတ်မှတ်ခြင်းနှင့် စိတ်ကြိုက် agent မှတ်ပုံတင်ခြင်းတို့ကို စီမံခန့်ခွဲသည်။
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/acp/agents` | သိရှိထားသည့် CLI agent အားလုံးကို (ပင်မပါဝင်သော + စိတ်ကြိုက်) ထည့်သွင်းမှုအခြေအနေ၊ ဗားရှင်း၊ binary တို့နှင့်အတူ စာရင်းပြုစုဖော်ပြသည် |
| POST | `/api/acp/agents` | စိတ်ကြိုက် ACP agent တစ်ခုကို မှတ်ပုံတင်ရန် သို့မဟုတ် cache ကို ပြန်လည်စတင်ရန် — body: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` သို့မဟုတ် `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | စိတ်ကြိုက် ACP agent တစ်ခုကို ဖယ်ရှားရန် — query parameter: `?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
}
```
**စစ်မှန်ကြောင်းအတည်ပြုခြင်း:** စီမံခန့်ခွဲမှု session (dashboard `auth_token` cookie) သို့မဟုတ်
စီမံခန့်ခွဲမှုနယ်ပယ်သတ်မှတ်ထားသည့် API key လိုအပ်သည်။
အသေးစိတ်အချက်အလက်အပြည့်အစုံအတွက် [ACP Framework](../frameworks/ACP.md) ကို ကြည့်ပါ။
---
## ခွဲခြမ်းစိတ်ဖြာမှုနှင့် စောင့်ကြည့်လေ့လာနိုင်မှု
routing၊ compression နှင့် provider မျိုးစုံကွဲပြားမှုတို့ကို စောင့်ကြည့်ရန် အချိန်နှင့်တစ်ပြေးညီ ခွဲခြမ်းစိတ်ဖြာမှု endpoint များဖြစ်သည်။ ၎င်းတို့သည် `/dashboard/analytics/*` စာမျက်နှာများကို ပံ့ပိုးပေးသည်။
### အလိုအလျောက် routing ခွဲခြမ်းစိတ်ဖြာမှု
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| -------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/auto-routing` | စုစည်းထားသော အလိုအလျောက် routing ကိန်းဂဏန်းများ- ခေါ်ဆိုမှုစုစုပေါင်း၊ strategy ဖြန့်ကျက်မှု၊ tier ဖြန့်ကျက်မှု၊ ထိပ်တန်း provider များ |
| GET | `/api/analytics/auto-routing?days=7` | အချိန်အပိုင်းအခြားအလိုက် ကိန်းဂဏန်းများ (မူလသတ်မှတ်ချက် 24h) |
**တုံ့ပြန်မှု နမူနာ**:
```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 }
]
}
```
### Compression ခွဲခြမ်းစိတ်ဖြာမှု
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| -------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/compression` | စုစည်းထားသော compression ကိန်းဂဏန်းများ- ချွေတာထားသည့် token များ၊ ချွေတာမှု ရာခိုင်နှုန်း၊ mode ဖြန့်ကျက်မှု၊ engine အသုံးပြုမှု |
**တုံ့ပြန်မှု နမူနာ**:
```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
}
}
```
### Provider မျိုးစုံကွဲပြားမှု ခြေရာခံခြင်း
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/diversity` | Shannon entropy အခြေပြု မျိုးစုံကွဲပြားမှု ခြေရာခံခြင်း- provider များအကြား ဖြန့်ကျက်မှုကို တိုင်းတာခြင်းဖြင့် တစ်နေရာတည်းမှ ချို့ယွင်းနိုင်သည့် အခြေအနေများကို ကာကွယ်သည် |
**တုံ့ပြန်မှု နမူနာ**:
```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"]
}
```
**စစ်မှန်ကြောင်းအတည်ပြုခြင်း:** စီမံခန့်ခွဲမှု session သို့မဟုတ် စီမံခန့်ခွဲမှုနယ်ပယ်သတ်မှတ်ထားသည့် API key လိုအပ်သည်။
---
## စီမံခန့်ခွဲသူ လုပ်ဆောင်ချက်များ
လုပ်ငန်းလည်ပတ်မှုဆိုင်ရာ စီမံခန့်ခွဲမှုအတွက် စီမံခန့်ခွဲသူများသာ အသုံးပြုနိုင်သည့် endpoint များ။
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| -------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/admin/concurrency` | လက်ရှိ တစ်ပြိုင်နက်လုပ်ဆောင်နိုင်မှု ကန့်သတ်ချက်များကို ဖတ်ရှုရန် (global + provider တစ်ခုချင်းအလိုက်) |
| POST | `/api/admin/concurrency` | တစ်ပြိုင်နက်လုပ်ဆောင်နိုင်မှု ကန့်သတ်ချက်များကို အပ်ဒိတ်လုပ်ရန် — body: `{global?: number, perProvider?: Record<string, number>}` |
**အထောက်အထားစိစစ်ခြင်း:** admin scope ပါဝင်သည့် management session လိုအပ်သည်။
---
## CLI ကိရိယာများ စီမံခန့်ခွဲမှု
OmniRoute နှင့် ပေါင်းစည်းအသုံးပြုသည့် CLI ကိရိယာများ (antigravity, chipotle, commandCode,
devin-cli စသည်တို့) ကို စီမံခန့်ခွဲရန်။ စာရင်းအပြည့်အစုံအတွက် [Provider ကိုးကားချက်](./PROVIDER_REFERENCE.md) ကို ကြည့်ပါ။
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| -------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cli-tools/all-statuses` | CLI ကိရိယာအားလုံး၏ အခြေအနေ (ထည့်သွင်းထားမှု၊ version၊ နောက်ဆုံးတွေ့ရှိချိန်) |
| GET | `/api/cli-tools/status` | CLI ကိရိယာတစ်ခု၏ အခြေအနေအသေးစိတ် (`?tool=` query) |
| POST | `/api/cli-tools/apply` | ကိရိယာတစ်ခု၏ ထုတ်လုပ်ထားသော config ကို ရေးသားရန် (`dryRun` ဖြင့် အစမ်းကြည့်နိုင်သည်၊ container အတွင်း လုပ်ဆောင်သည့်အခါ `422` + `containerEphemeralTarget`၊ `migration` သည် အဟောင်း Codex YAML ကို မှတ်သားဖော်ပြသည်) |
| GET | `/api/cli-tools/backups` | CLI ကိရိယာ configuration backup များကို စာရင်းပြုစုရန် |
| POST | `/api/cli-tools/backups` | CLI ကိရိယာ configuration အားလုံး၏ backup တစ်ခု ဖန်တီးရန် |
| POST | `/api/cli-tools/backups` | ပြန်လည်ရယူရန်- body ထဲတွင် `{tool, backupId}` ထည့်ပြီး တူညီသော endpoint ကို အသုံးပြုပါက ထို backup ကို ပြန်လည်ရယူပေးမည် |
| GET | `/api/cli-tools/antigravity-mitm` | Antigravity MITM proxy အခြေအနေ ("antigravity-mitm" CLI ကိရိယာ) |
| POST | `/api/cli-tools/antigravity-mitm/alias` | antigravity-mitm alias များကို စီစဉ်သတ်မှတ်ရန် |
**အထောက်အထားစိစစ်ခြင်း:** management session လိုအပ်သည်။
---
## Agent ကျွမ်းကျင်မှုများ
AI agent ကျွမ်းကျင်မှုများကို စီမံခန့်ခွဲရန် (OpenAI ၏ custom GPT များနှင့် ဆင်တူသော်လည်း agent များအတွက် ဖြစ်သည်)။
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| -------- | ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| GET | `/api/agent-skills` | agent ကျွမ်းကျင်မှုအားလုံးကို စာရင်းပြုစုရန် (ပါရှိပြီးသား + စိတ်ကြိုက်) |
| GET | `/api/agent-skills/[id]` | သတ်မှတ်ထားသော agent ကျွမ်းကျင်မှုတစ်ခုကို ရယူရန် |
| POST | `/api/agent-skills` | စိတ်ကြိုက် agent ကျွမ်းကျင်မှုတစ်ခု ဖန်တီးရန် — body: `{name, description, prompt, model?, temperature?}` |
| PUT | `/api/agent-skills/[id]` | စိတ်ကြိုက် agent ကျွမ်းကျင်မှုတစ်ခုကို အပ်ဒိတ်လုပ်ရန် |
| DELETE | `/api/agent-skills/[id]` | စိတ်ကြိုက် agent ကျွမ်းကျင်မှုတစ်ခုကို ဖျက်ရန် |
| GET | `/api/agent-skills/[id]/raw` | မူရင်း prompt + metadata ကို ရယူရန် (လုပ်ဆောင်မှုမရှိ) |
| POST | `/api/agent-skills/generate` | သဘာဝဘာသာစကား ဖော်ပြချက်တစ်ခုမှ ကျွမ်းကျင်မှုအသစ်တစ်ခုကို AI ဖြင့် ထုတ်လုပ်ရန် |
**အထောက်အထားစိစစ်ခြင်း:** management session သို့မဟုတ် management scope ပါဝင်သည့် API key လိုအပ်သည်။
---
## Cache စီမံခန့်ခွဲမှု
Semantic cache နှင့် reasoning cache ကို စီမံခန့်ခွဲပါ။
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| -------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cache` | Cache အနှစ်ချုပ်- စုစုပေါင်း entry အရေအတွက်၊ hit rate နှင့် disk ပေါ်ရှိ အရွယ်အစား |
| GET | `/api/cache/entries` | Cache လုပ်ထားသော entry များကို စာမျက်နှာခွဲခြင်းဖြင့် စာရင်းပြုစုရန် |
| DELETE | `/api/cache/entries` | Cache entry များကို ဖျက်ရန် (query parameter များဖြင့် စစ်ထုတ်ရန်) |
| GET | `/api/cache/stats` | အသေးစိတ် cache ကိန်းဂဏန်းများ (provider တစ်ခုချင်း၊ model တစ်ခုချင်းအလိုက်) |
| GET | `/api/cache/reasoning` | Reasoning cache အခြေအနေ (reasoning ပြန်လည်ဖွင့်ခြင်းအတွက်) |
| DELETE | `/api/cache/reasoning` | Reasoning cache ကို ရှင်းလင်းရန် — query params: `?toolCallId=<id>` (တစ်ခုတည်း) သို့မဟုတ် `?provider=<p>` သို့မဟုတ် parameter မပါဘဲ (အားလုံး) |
**အထောက်အထားစိစစ်ခြင်း:** Management session လိုအပ်သည်။
---
## Memory စနစ်
အမြဲတမ်းသိမ်းဆည်းထားသော memory (FTS5 + vector embeddings) ကို စီမံခန့်ခွဲပါ။
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| -------- | ------------------ | ------------------------------------------------------------------------------------ |
| GET | `/api/memory` | Memory entry များကို စာရင်းပြုစုရန် (scope၊ type၊ search query တို့ဖြင့် စစ်ထုတ်ရန်) |
| POST | `/api/memory` | Memory entry အသစ်တစ်ခု ဖန်တီးရန် — body: `{scope, type, content, metadata?}` |
| GET | `/api/memory/[id]` | သတ်မှတ်ထားသော memory entry တစ်ခုကို ရယူရန် |
| PUT | `/api/memory/[id]` | Memory entry တစ်ခုကို အပ်ဒိတ်လုပ်ရန် |
| DELETE | `/api/memory/[id]` | Memory entry တစ်ခုကို ဖျက်ရန် |
| GET | `/api/memory?q=` | Memory ကို ရှာဖွေရန် (FTS5 + vector) — တူညီသော response တွင် ကိန်းဂဏန်းများ ပါဝင်သည် |
**အထောက်အထားစိစစ်ခြင်း:** Management session သို့မဟုတ် management scope ပါသော API key လိုအပ်သည်။
---
## Webhook များ
Event များအတွက် webhook subscription များကို စီမံခန့်ခွဲပါ။
| နည်းလမ်း | လမ်းကြောင်း | ဖော်ပြချက် |
| -------- | ------------------------------- | --------------------------------------------------------------------------------------------- |
| GET | `/api/webhooks` | Webhook subscription အားလုံးကို စာရင်းပြုစုရန် |
| POST | `/api/webhooks` | Webhook subscription တစ်ခု ဖန်တီးရန် — body: `{url, events[], secret?, active?}` |
| GET | `/api/webhooks/[id]` | သတ်မှတ်ထားသော webhook subscription တစ်ခုကို ရယူရန် |
| PUT | `/api/webhooks/[id]` | Webhook subscription တစ်ခုကို အပ်ဒိတ်လုပ်ရန် |
| DELETE | `/api/webhooks/[id]` | Webhook subscription တစ်ခုကို ဖျက်ရန် |
| GET | `/api/webhooks/[id]/deliveries` | Webhook တစ်ခုအတွက် ပေးပို့မှုမှတ်တမ်းကို စာရင်းပြုစုရန် (အောင်မြင်မှု/မအောင်မြင်မှု မှတ်တမ်း) |
| POST | `/api/webhooks/[id]/test` | Webhook တစ်ခုသို့ စမ်းသပ် event တစ်ခု ပေးပို့ရန် |
**အထောက်အထားစိစစ်ခြင်း:** Management session လိုအပ်သည်။
Event အမျိုးအစား အပြည့်အစုံအတွက် [Webhooks Framework](../frameworks/WEBHOOKS.md) ကို ကြည့်ပါ။
---
## Skills Framework
Skills (agentic extensions framework) ကို စီမံခန့်ခွဲပါ။
| Method | Path | Description |
| ------ | ------------------------ | --------------------------------------------------------------------------------------------------- |
| GET | `/api/skills` | ထည့်သွင်းထားသော skills အားလုံးကို စာရင်းပြုစုပါ (built-in + custom) |
| POST | `/api/skills/install` | local path သို့မဟုတ် URL မှ skill တစ်ခုကို ထည့်သွင်းပါ |
| DELETE | `/api/skills/[id]` | skill တစ်ခုကို ဖယ်ရှားပါ |
| PUT | `/api/skills/[id]` | skill တစ်ခုကို ဖွင့် သို့မဟုတ် ပိတ်ပါ — body: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST | `/api/skills/executions` | skill တစ်ခုကို လုပ်ဆောင်ပါ — body: `{skillName, apiKeyId, input?, sessionId?}` |
| GET | `/api/skills/executions` | skills အားလုံးအတွက် လုပ်ဆောင်မှုမှတ်တမ်းကို စာရင်းပြုစုပါ (`?apiKeyId=` ဖြင့် စစ်ထုတ်နိုင်သည်) |
**Auth:** management session သို့မဟုတ် management scope ပါသော API key လိုအပ်သည်။
အသေးစိတ်အပြည့်အစုံအတွက် [Skills Framework](../frameworks/SKILLS.md) ကို ကြည့်ပါ။
---
## Plugins
OmniRoute plugins (third-party extensions) ကို စီမံခန့်ခွဲပါ။
| Method | Path | Description |
| ------ | ---------------------------------- | --------------------------------------------- |
| GET | `/api/plugins` | ထည့်သွင်းထားသော plugins များကို စာရင်းပြုစုပါ |
| POST | `/api/plugins/marketplace/install` | marketplace မှ plugin တစ်ခုကို ထည့်သွင်းပါ |
| DELETE | `/api/plugins/[name]` | plugin တစ်ခုကို ဖယ်ရှားပါ |
| POST | `/api/plugins/[name]/activate` | plugin တစ်ခုကို အသက်သွင်းပါ |
| POST | `/api/plugins/[name]/deactivate` | plugin တစ်ခုကို ပိတ်ပါ |
| GET | `/api/plugins/[name]/config` | plugin configuration ကို ရယူပါ |
| PUT | `/api/plugins/[name]/config` | plugin configuration ကို အပ်ဒိတ်လုပ်ပါ |
**Auth:** management session လိုအပ်သည်။
အသေးစိတ်အပြည့်အစုံအတွက် [Plugins Framework](../frameworks/PLUGIN_SDK.md) ကို ကြည့်ပါ။
---
## Shadow Routing
Provider များ၏ Shadow / A-B နှိုင်းယှဉ်မှုသည် **သီးခြား REST surface မဟုတ်ပါ** — ၎င်းကို combo routing မှတစ်ဆင့် ပြင်ဆင်သတ်မှတ်ရသည် ([Auto-Combo](../routing/AUTO-COMBO.md) ကို ကြည့်ပါ)။ Combo တစ်ခုချင်းစီအလိုက် နှိုင်းယှဉ်မှု metrics များကို `GET /api/combos/metrics` မှ ပေးပါသည်။
---
## Guardrails
Runtime guardrails (PII ရှာဖွေခြင်း၊ prompt injection ရှာဖွေခြင်း၊ vision bridging) ကို စစ်ဆေးပါ။ Guardrails များသည် request တိုင်းတွင် လုပ်ဆောင်သည်။ Call တစ်ခုချင်းစီအတွက် opt-out လုပ်ရန် `x-omniroute-disabled-guardrails` request header ကို အသုံးပြုနိုင်သည် — အမြဲတမ်းသိမ်းဆည်းထားသော enable/disable surface မရှိပါ။
| Method | Path | Description |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------------- |
| GET | `/api/guardrails` | မှတ်ပုံတင်ထားသော guardrails များနှင့် ၎င်းတို့၏ status (name / enabled / priority) ကို စာရင်းပြုစုပါ |
| POST | `/api/guardrails/test` | နမူနာ input တစ်ခုပေါ်တွင် pre-call pipeline ကို dry-run လုပ်ပါ — body: `{input, disabledGuardrails?}` |
**Auth:** management session လိုအပ်သည်။
အသေးစိတ်အပြည့်အစုံအတွက် [Security > Guardrails](../security/GUARDRAILS.md) ကို ကြည့်ပါ။
---
---
## စစ်မှန်ကြောင်းအတည်ပြုခြင်း
အထောက်အထားအမျိုးအစား လေးမျိုး (dashboard session၊ local CLI token၊ `oma_live_…` Access Token၊ manage-scoped API key) နှင့် ၎င်းတို့သည် inference key များနှင့် မည်သို့ကွာခြားသည်ကို [Management Authentication](../guides/MANAGEMENT-AUTH.md) တွင် ကြည့်ပါ။
- Dashboard route များ (`/dashboard/*`) သည် `auth_token` cookie ကို အသုံးပြုသည်
- Login သည် သိမ်းဆည်းထားသော password hash ကို အသုံးပြုပြီး၊ မရရှိပါက `INITIAL_PASSWORD` ကို အစားထိုးအသုံးပြုသည်
- `requireLogin` ကို `/api/settings/require-login` မှတစ်ဆင့် ဖွင့်/ပိတ် ပြောင်းလဲနိုင်သည်
- `REQUIRE_API_KEY=true` ဖြစ်သည့်အခါ `/v1/*` route များသည် Bearer API key ကို လိုအပ်နိုင်သည်
- ဤအကိုးအကားတွင် "management token" / "management-scoped API key" ဆိုသည်မှာ အထက်ပါလမ်းညွှန်ရှိ အမျိုးအစားများထဲမှ တစ်ခုကို ဆိုလိုခြင်းဖြစ်ပြီး သတ်မှတ်မထားသော လျှို့ဝှက်အမျိုးအစားတစ်ခုကို ထပ်မံဆိုလိုခြင်း မဟုတ်ပါ
> **နောက်ပြန်လိုက်ဖက်မှုမရှိသော ပြောင်းလဲမှု (v3.8.0)** — `/api/v1/agents/tasks/*` နှင့် cooldown စီမံခန့်ခွဲမှု endpoint များသည် ယခုအခါ **management auth** (dashboard `auth_token` cookie သို့မဟုတ် management-scoped API key) ကို လိုအပ်သည်။ ယခင်က အထောက်အထားမပြဘဲ ဤ route များကို ခေါ်ယူခဲ့သော client များသည် `401 Unauthorized` ကို လက်ခံရရှိမည်ဖြစ်သည်။ commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`) ကို ကြည့်ပါ။
Reference in New Issue View Git Blame Copy Permalink