OmniRoute/docs/i18n/ka/docs/reference/API_REFERENCE.md

API Reference (ქართული)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

---

🌐 ენები: 🇺🇸 English | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇩🇪 Deutsch | 🇬🇷 Ελληνικά | 🇪🇸 Español | 🇪🇪 Eesti | 🇮🇷 فارسی | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇪 Gaeilge | 🇮🇳 ગુજરાતી | 🇳🇬 Hausa | 🇮🇱 עברית | 🇮🇳 हिन्दी | 🇭🇷 Hrvatski | 🇭🇺 Magyar | 🇦🇲 Հայերեն | 🇮🇩 Bahasa Indonesia | 🇳🇬 Igbo | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇬🇪 ქართული | 🇰🇭 ខ្មែរ | 🇮🇳 ಕನ್ನಡ | 🇰🇷 한국어 | 🇱🇹 Lietuvių | 🇱🇻 Latviešu | 🇮🇳 മലയാളം | 🇮🇳 मराठी | 🇲🇾 Bahasa Melayu | 🇲🇹 Malti | 🇲🇲 မြန်မာ | 🇳🇵 नेपाली | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇮🇳 ଓଡ଼ିଆ | 🇮🇳 ਪੰਜਾਬੀ | 🇵🇭 Filipino | 🇵🇱 Polski | 🇵🇹 Português (Portugal) | 🇧🇷 Português (Brasil) | 🇷🇴 Română | 🇷🇺 Русский | 🇱🇰 සිංහල | 🇸🇰 Slovenčina | 🇸🇮 Slovenščina | 🇷🇸 Српски | 🇸🇪 Svenska | 🇰🇪 Kiswahili | 🇮🇳 தமிழ் | 🇮🇳 తెలుగు | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇵🇰 اردو | 🇺🇿 Oʻzbekcha | 🇻🇳 Tiếng Việt | 🇳🇬 Yorùbá | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

OmniRoute API-ის ძირითადი ცნობარი. იგი მოიცავს საჯარო /v1 ინტერფეისსა და მართვის ყველაზე ხშირად გამოყენებულ საბოლოო წერტილებს; ამომწურავი წყაროებია მანქანურად წაკითხვადი docs/openapi.yaml და მარშრუტების ხე src/app/api/-ის ქვეშ.

---

სარჩევი

• ჩატის დასრულებები
• ექსკლუზიური მართული სესიის იჯარები
• ჩაშენებები
• სურათების გენერირება
• დოკუმენტის OCR
• მოდელების სია
• პროვაიდერის დანამატის მანიფესტი
• თავსებადობის საბოლოო წერტილები
• ფაილების API
• პაკეტური დამუშავების API
• ძიების API
• WebSocket-სტრიმინგი
• კვოტებისა და პრობლემების ანგარიშგება
• სემანტიკური კეში
• მართვის პანელი და მართვა
• კომბინაციების მართვა
• ვებჰუკები
• რეგისტრირებული გასაღებები (ავტომატური მართვა)
• აგენტების პროტოკოლი
• მართვის პროქსი-სერვერები
• მდგრადობა (გაფართოებული)
• უნარები
• მეხსიერება
• MCP სერვერი
• A2A სერვერი
• ღრუბელი, შეფასებები და შემოწმება
• მოთხოვნების დამუშავება
• ავთენტიფიკაცია

---

ჩატის დასრულებები

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
}

მორგებული სათაურები

სათაური	მიმართულება	აღწერა
X-OmniRoute-No-Cache	მოთხოვნა	კეშის გვერდის ასავლელად დააყენეთ true
x-omniroute-no-memory	მოთხოვნა	ამ მოთხოვნისთვის მეხსიერებისა და უნარების ჩასმის გამოსატოვებლად დააყენეთ true (no-cache-ის ანალოგია; თავიდან აგაცილებთ თითოეული გამოძახების ტოკენებისა და ღირებულების ზედნადებ ხარჯებს)
X-OmniRoute-Progress	მოთხოვნა	პროგრესის მოვლენების მისაღებად დააყენეთ true
X-Session-Id	მოთხოვნა	მუდმივი სესიის გასაღები გარე სესიურ მიჯაჭვულობასთან თავსებადობისთვის
x_session_id	მოთხოვნა	ასევე მიიღება ქვედა ტირილის მქონე ვარიანტი (პირდაპირი HTTP)
X-OmniRoute-Session-Id	მოთხოვნა	გამომძახებლის მიერ მოწოდებული სესიის/საუბრის ტეგი (ასევე მიეწოდება მეხსიერებას). არსებობის შემთხვევაში უცვლელად ინახება call_logs.session_tag-ში, თითოეული სესიის ხარჯების მისაკუთვნებლად (#8249) — არარსებობის შემთხვევაში არასოდეს გენერირდება
Idempotency-Key	მოთხოვნა	დუბლიკატების აღმოფხვრის გასაღები (5-წამიანი ფანჯარა)
X-Request-Id	მოთხოვნა	დუბლიკატების აღმოფხვრის ალტერნატიული გასაღები
X-OmniRoute-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	პასუხი	USD-ში გამოხატული თანხა, რომლის დახარჯვაც კეშმა თავიდან აიცილა HIT-ის დროს (მხოლოდ კეშში მოხვედრისას)
X-OmniRoute-Decision	პასუხი	მარშრუტიზაციის კვალი: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> არის კომბინაციის სტრატეგია, ან single არაკომბინირებული მოთხოვნისთვის) — დასრულების პასუხებში ყოველთვის წარმოდგენილია

შენიშვნა Nginx-ის შესახებ: თუ ქვედა ტირილის მქონე სათაურებს იყენებთ (მაგალითად, x_session_id), ჩართეთ underscores_in_headers on;.

ხარჯების ტელემეტრიის სათაურები: წარმატებული არანაკადური პასუხები ასევე შეიცავს ხარჯების ტელემეტრიის 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. მათ აბრუნებენ ჩატის დასრულებები, /v1/responses, /v1/messages, და მედიის საბოლოო წერტილები — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations და /v1/moderations (ხარჯი ყოველთვის 0). მედიის ხარჯი, ფასის ხელმისაწვდომობის შემთხვევაში, გამოითვლება მოდალობის მიხედვით (თითო სურათზე, წამზე, სიმბოლოზე ან ძიების ერთეულზე), წინააღმდეგ შემთხვევაში კი არის 0 (fail-open).

ქეშში დამთხვევის ხარჯის სემანტიკა: სემანტიკურ ქეშში დამთხვევისას (X-OmniRoute-Cache-Hit: true) ზედა დონის სერვისთან გამოძახება არ სრულდება, ამიტომ X-OmniRoute-Response-Cost არის 0.0000000000 (დამთხვევის მომსახურების ინკრემენტული ხარჯი). თავდაპირველი/სავარაუდო ხარჯი ცალკე აისახება X-OmniRoute-Cost-Saved-ში. ბილინგის მომხმარებლებმა უნდა შეაჯამონ X-OmniRoute-Response-Cost (ქეშში დამთხვევები არაფერს ღირს); ქეშის ანალიტიკისთვის შესაძლებელია X-OmniRoute-Cost-Saved-ის აგრეგირება.

ექსკლუზიური მართული სესიის იჯარები

ექსკლუზიური მართული სესიის იჯარით გაცემა არის არჩევითი, კლიენტისგან დამოუკიდებელი მარშრუტიზაციის კონტრაქტი: ერთი აქტიური მფლობელი ფლობს ერთ შესაბამის OmniRoute კავშირს. ის არ გასცემს მოდელს იჯარით, არ მოითხოვს OAuth-ს, არ ახდენს კონკრეტული კლიენტის იდენტიფიცირებას და არ მოითხოვს კონკრეტულ პროვაიდერს.

ავთენტიფიკაციისთვის გამოყენებულ API გასაღებს უნდა ჰქონდეს lease:exclusive არე და ცალსახად მითითებული, არაცარიელი allowedConnections სია. მონაცემთა ბაზის მუტაციის საზღვარი გასაღების შექმნისა და ნაწილობრივი განახლებებისას ორივე ველს ერთობლივად ამოწმებს.

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

წარმატებული მოპოვების, განახლებისა და გათავისუფლების პასუხები შეიცავს დროის ნიშნულებს, state-სა და ზუსტ დადებით generation-ს, თუმცა არასოდეს შეიცავს არჩეულ კავშირს ან ავტორიზაციის მონაცემებს. განახლებისა და გათავისუფლებისას generation JSON-ის სხეულში გადაიცემა:

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

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

აქტიური იჯარის მფლობელს შეუძლია თავისი მიმდინარე მიბმისთვის პირდაპირ მოითხოვოს კონფიდენციალურობის მხრივ უსაფრთხო საჩვენებელი მეტამონაცემები:

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

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

ეს არჩევითი სტატუსის მოქმედება ერთ მონაცემთა ბაზის ტრანზაქციაში შემოსაზღვრულია გაუმჭვირვალე მფლობელით, ავთენტიფიცირებული მართული API გასაღებითა და ზუსტი აქტიური generation-ით. displayName არის მხოლოდ კონფიგურირებული კავშირის ჩამოჭრილი სახელი; თუ უსაფრთხო კონფიგურირებული სახელი არ არსებობს, მისი მნიშვნელობაა null. OmniRoute მას არასოდეს ანაცვლებს ელფოსტის მისამართით ან გენერირებული ანგარიშის იდენტობით. პროვაიდერის მნიშვნელობა არის არასენსიტიური საჩვენებელი ჭდე და არასოდეს წარმოადგენს გენერირებული თავსებადი პროვაიდერის იდენტიფიკატორს. ავტორიზაციის მონაცემები, ტოკენები, cookie-ები, კავშირის ან API გასაღების დაუმუშავებელი id-ები, მფლობელის ჰეშები, შემოსაზღვრის საიდუმლოებები და მარშრუტიზაციის შიდა მონაცემები გამორიცხულია.

არასწორი გასაღებით, არასწორი მფლობელით, მოძველებული generation-ით შესრულებული, არარსებული, ვადაგასული, გათავისუფლებული და გაუქმებული ძიებები ყველა აბრუნებს ერთსა და იმავე 409 LEASE_FENCE_STALE შეცდომას, კავშირის მეტამონაცემების გარეშე. კლიენტს, რომელმაც სიმძლავრის მოლოდინის პასუხი მიიღო, შესამოწმებელი აქტიური მიბმა არ აქვს. როდესაც მარშრუტიზაცია აქტიურ იჯარას სხვა მდგომარეობაში გადაიყვანს, იგივე generation ძალაში რჩება და სტატუსი ატომურად აბრუნებს ახალ მიბმას — არასოდეს ძველს. არსებული კლიენტები უცვლელი რჩება, რადგან მოპოვების, განახლების, გათავისუფლებისა და მოლოდინის პასუხები ინარჩუნებს თავის წინა ფორმებს.

ეს სერვერული კონტრაქტი არ ცვლის სტანდარტულ OpenAI Codex /status-ს. სტანდარტული Codex ამჟამად აჩვენებს მოდელის პროვაიდერსა და ჩაშენებულ ავთენტიფიკაციის/ანგარიშის მდგომარეობას, თუმცა არ ასახავს მორგებული პროვაიდერის ანგარიშის ნებისმიერ მეტამონაცემს; სამომავლო კლიენტის ინტეგრაციამ უნდა გამოიძახოს ეს მოქმედება და გადაწყვიტოს, როგორ აჩვენოს connection.displayName.

ამის შემდეგ, ყოველი მართული ინფერენსის მოთხოვნა ორივე საკონტროლო სათაურს გადასცემს:

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

ზუსტი მფლობელი, generation, აქტიური კავშირი და ავთენტიფიცირებული API გასაღები თითოეული მხარდაჭერილი ზედა დონის სერვისზე მიმართვის მცდელობის უშუალოდ წინ შემოისაზღვრება. მფლობელისა და generation-ის სხვა გასაღებით ხელახლა გამოყენება წარუმატებელია მაშინაც კი, როდესაც ეს გასაღები იმავე კავშირს უშვებს. დაუმუშავებელი მფლობელები არ ინახება მუდმივად, არ აღირიცხება ჟურნალში, არ რჩება მოთხოვნის მომენტალურ ასლში და არ გადაიგზავნება ზედა დონის სერვისზე.

დროებითი კონკურენცია აბრუნებს HTTP 429-ს Retry-After-ით და შემდეგი შიგთავსით:

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

ეს პასუხი მხოლოდ იმას ნიშნავს, რომ ჩვეულებრივი შესაბამისი სიმრავლე არ იყო ცარიელი და ყოველი თავისუფალი კანდიდატი უცხო აქტიურ იჯარას ეკავა. მხარდაუჭერელი მოდელები/პროვაიდერები, პოლიტიკის შეუსაბამობა, დაყოვნების პერიოდი, კვოტა, სიჯანსაღე და შესაბამისობის სხვა ჩვეულებრივი წარუმატებლობები ინარჩუნებს თავის არსებულ OmniRoute პასუხებს.

x-omniroute-compression

შეკუმშვის გეგმის თითოეული მოთხოვნის დონეზე ჩანაცვლება. უმაღლესი პრიორიტეტი — გადაწონის მარშრუტიზაციის კომბინაციის ჩანაცვლებას, აქტიურ პროფილს, ავტომატურ ტრიგერსა და პანელის ნაგულისხმევ მნიშვნელობას. მნიშვნელობები:

მნიშვნელობა	ეფექტი
off	ამ მოთხოვნისთვის შეკუმშვა არ გამოიყენება.
default	პანელიდან მიღებული ნაგულისხმევი პროფილი (აქტიურ პროფილს უგულებელყოფს).
engine:<id>	ერთი ძრავა, როდესაც ის ჩართულია, მაგ. engine:rtk.
<combo>	სახელდებული კომბინაცია; დამთხვევა ჯერ სახელით (რეგისტრის გაუთვალისწინებლად), შემდეგ კი id-ით ხდება.

შენიშვნები:

• უცნობი მნიშვნელობები იგნორირდება (მოთხოვნა არასოდეს უარყოფილა); განსაზღვრა გადადის ოპერატორების ჩვეულებრივ პრიორიტეტზე.
• თუ რამდენიმე კომბინაციას ერთი და იგივე სახელი აქვს, დეტერმინისტული დამთხვევისთვის გადაეცით კომბინაციის id.
• კომბინაცია, რომლის სახელიც არის off ან default, სახელით ვერ შეირჩევა (ეს საკვანძო სიტყვები პირველად განიმარტება); ასეთ კომბინაციას მისი id-ით მიმართეთ.
• შეკუმშვის მთავარი გადამრთველი მკაცრი ბარიერია: როდესაც შეკუმშვა გლობალურად გამორთულია, ეს სათაური მას ვერ ჩართავს.

გამოყენებული გეგმა პასუხის სათაურში აისახება:

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

სადაც <source> არის ერთ-ერთი შემდეგიდან: request-header, routing-override, active-profile, auto-trigger, default ან off.

---

ემბედინგები

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

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

ხელმისაწვდომი პროვაიდერები: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

კატალოგის იდენტიფიკატორების ფორმატია provider/model (მაგალითად: jina-ai/jina-embeddings-v5-omni-small). რეესტრში არსებული Jina-ს მოდელების უპრეფიქსო იდენტიფიკატორებიც (მაგალითად, jina-embeddings-v5-text-small, jina-reranker-v3.5) მუშავდება. Jina-ს embed/rerank/classify/segment ოპერაციები თავდაპირველად მართვის პანელის jina-ai ავტორიზაციის მონაცემებს იყენებს; JINA_AI_API_KEY მხოლოდ მაშინ გამოიყენება სარეზერვო ვარიანტად, როდესაც მართვის პანელში გასაღები არ არსებობს. jina-reader ბარათი განკუთვნილია მხოლოდ Reader-ისთვის / r.jina.ai-ისთვის (POST /v1/web/fetch) და არასოდეს უზრუნველყოფს ემბედინგებს ან ხელახალ რანჟირებას.

რეესტრის მოდელები, რომლებიც მულტიმოდალურ მხარდაჭერას აცხადებს, ასევე იღებს პროვაიდერისგან დამოუკიდებელ, მაქსიმუმ 32 სტრუქტურირებულ ელემენტს. მედია-ელემენტების ტიპებია text, image, audio, video და document. მათი მედიის 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 და ოჯახის ფსევდონიმი jina-ai/jina-embeddings-v5-omni → omni-small) ასევე იღებს Jina-ს მშობლიურ EmbeddingsV5Request დოკუმენტებს და უცვლელად გადაგზავნის მათ მისამართზე https://api.jina.ai/v1/embeddings:

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "task": "retrieval.query",
  "normalized": true,
  "input": [
    { "text": "a red bicycle" },
    { "image": "https://example.com/bike.png" },
    {
      "content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }]
    }
  ]
}

მშობლიური { image | audio | video | pdf } მნიშვნელობები შეიძლება იყოს საჯარო HTTPS URL, data: URI ან დაუმუშავებელი base64. OmniRoute ამ ობიექტებს სტრიქონებად არ გარდაქმნის და მშობლიური სურათების URL-ებიდან მონაცემებს არ ჩამოტვირთავს — საჯარო მედიას თავად Jina იღებს. Jina-ს დამატებითი ველები (task, normalized, truncate, embedding_type) გადაგზავნილია. მხოლოდ ტექსტისთვის განკუთვნილი Jina SKU-ები კვლავ უარყოფს არატექსტურ დოკუმენტებს.

უსაფრთხოებისა და ტრანსპორტირების შეზღუდვები:

• დისტანციური მედიის URL-ები საჯარო HTTPS უნდა იყოს. კანონიკური {type,source:url} ელემენტები სერვერის მხარეს იტვირთება (გადამისამართებების ხელახალი ვალიდაციით, დროის ლიმიტით, ზომის შეზღუდვებით, საჯარო DNS-ითა და კავშირის ფიქსირებით) და პროვაიდერის გამოძახებამდე უშუალოდ მოთხოვნაში თავსდება. Jina-ს მშობლიური {image:"https://..."} ელემენტები იმავე საჯარო HTTPS შემოწმების შემდეგ უცვლელად გადაიგზავნება; URL-ს Jina ტვირთავს.
• მოთხოვნაში ჩასმული base64 მედია შეზღუდულია თითოეულ ელემენტზე დეკოდირებული 8 MiB-ით და მთელ მოთხოვნაში დეკოდირებული 16 MiB-ით.

პროვაიდერისთვის გარდაქმნა (კანონიკური ელემენტები არასოდეს გადაიგზავნება უცვლელად):

• Jina-ს მულტიმოდალური მოდელები: თითოეული ზედა დონის ელემენტი გარდაიქმნება მოდალობის გასაღების მქონე ერთ ობიექტად (text / image / audio / video / pdf), მოთხოვნაში ჩასმული მედიისთვის data URI-ების გამოყენებით; თითო ვექტორი ყოველ ზედა დონის ელემენტზე.
• Gemini Embedding 2-ის ოჯახი: ზედა დონის ერთი მასივი გარდაიქმნება ერთ მშობლიურ models/{model}:embedContent მოთხოვნად, content.parts-ით (text ან inline_data).
• უცნობი/დინამიკური მოდელები, რომლებსაც მოდალობის ცხადი მეტამონაცემები არ გააჩნია, სტრუქტურირებულ შეყვანას HTTP 400-ით უარყოფს.

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}

მოდელისა და მოდალობის მხარდაუჭერელი კომბინაციები ელემენტის იძულებით გარდაქმნის ნაცვლად HTTP 400-ს აბრუნებს. ძველი სტრიქონული/ტოკენური მოთხოვნების შეყვანასთან დაუკავშირებელი გაფართოების ველები კვლავ უცვლელად გადაიცემა.

# ყველა ემბედინგის მოდელის ჩამონათვალი
GET /v1/embeddings

---

სურათების გენერაცია

POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "openai/gpt-image-2",
  "prompt": "A beautiful sunset over mountains",
  "size": "1024x1024"
}

ხელმისაწვდომი პროვაიდერები: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (ლოკალური), ComfyUI (ლოკალური).

# სურათების ყველა მოდელის ჩამონათვალი
GET /v1/images/generations

---

დოკუმენტის OCR

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

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

model ირჩევს OCR-ის პროვაიდერს provider/model პრეფიქსის მეშვეობით; მხოლოდ მოდელის 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)	სინქრონული — პასუხი პირდაპირ ბრუნდება ერთადერთი ზედა დონის გამოძახებიდან.
azure-document-intelligence	prebuilt-read	azure-document-intelligence/prebuilt-read	ასინქრონული ზედა დონე (analyze + გამოკითხვა) — იხილეთ ქვემოთ.
vertex-deepseek-ocr	deepseek-ocr-maas	vertex-deepseek-ocr/deepseek-ocr-maas	სინქრონული, Vertex AI-ის openapi/chat/completions პარტნიორული საბოლოო წერტილის მეშვეობით — ავტორიზაციის/URL-ისთვის იხილეთ ქვემოთ.

სამივე პროვაიდერი პასუხობს Mistral-ის ერთნაირი სტრუქტურის მქონე სხეულით:

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

Azure Document Intelligence-ის გამოკითხვის ნაკადი

Azure Document Intelligence-ის analyze API ასინქრონულია: საწყისი მოთხოვნა სხეულის ნაცვლად Operation-Location სათაურს აბრუნებს და შედეგის მისაღებად პერიოდული გამოკითხვაა საჭირო. დამმუშავებელი (open-sse/handlers/ocr.ts) ამ URL-ს ყოველ წამში ერთხელ, მაქსიმუმ 30 მცდელობის განმავლობაში გამოკითხავს, დაუყოვნებლივ წყდება (არ აგრძელებს გამოკითხვას) არა-ok გამოკითხვის პასუხის ან "failed" სტატუსის შემთხვევაში და აბრუნებს 504-ს, თუ მცდელობების ლიმიტის ამოწურვის შემდეგ ოპერაცია ჯერ კიდევ მიმდინარეობს. Azure-ის საბოლოო პასუხი დაბრუნებამდე ნორმალიზდება Mistral-ის მიერ გამოყენებულ იმავე pages/markdown სტრუქტურაში, ამიტომ კლიენტის კოდს პროვაიდერისთვის სპეციალური დამუშავება არ სჭირდება.

Vertex AI DeepSeek OCR-ის ავტორიზაცია და საბოლოო წერტილის განსაზღვრა

vertex-deepseek-ocr ხელახლა იყენებს Vertex AI-ის ავტორიზაციის იმავე მექანიზმს, რომელსაც OmniRoute უკვე უჭერს მხარს ჩატის/სურათების ტრაფიკისთვის (open-sse/executors/vertex.ts): კავშირის API გასაღები არის ან Service Account JSON-ის ავტორიზაციის მონაცემები (რომლებიც JWT-bearer ნაკადის მეშვეობით იცვლება ხანმოკლე OAuth წვდომის ტოკენზე), ან უკვე შექმნილი OAuth წვდომის ტოკენი, რომელიც უცვლელად გამოიყენება. ზედა დონის საბოლოო წერტილის URL არის Vertex-ის ზოგადი openapi/chat/completions პარტნიორული საბოლოო წერტილი, რომელიც კავშირის პროექტისა და რეგიონის საფუძველზე აიგება — ცხადად მითითებულ providerSpecificData.project/providerSpecificData.region-ს ყოველთვის ენიჭება უპირატესობა; წინააღმდეგ შემთხვევაში პროექტი მიიღება Service Account JSON-ის project_id-დან, ხოლო რეგიონის ნაგულისხმევი მნიშვნელობაა us-central1. ორივე განსაზღვრა ხდება open-sse/handlers/ocr.ts-ში (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl) და გამოიყენება src/app/api/v1/ocr/route.ts-ის მიერ handleOcr-ზე გადამისამართებამდე.

---

მოდელების სია

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

→ აბრუნებს ჩატის, embedding-ისა და სურათების ყველა მოდელს + კომბინაციებს OpenAI-ის ფორმატში

მოდელის id-ის პრეფიქსები (?prefix=)

მოდელების უმეტესობა წარმოდგენილია პროვაიდერის პრეფიქსით. მიღებულ პრეფიქსს აკონტროლებს MODELS_CATALOG_PREFIX_MODE ფუნქციური ალამი და მისი ჩანაცვლება შესაძლებელია თითოეული მოთხოვნისთვის query-პარამეტრით — ეს სასარგებლოა კლიენტისთვის, რომელსაც სუფთა სია სურს სერვერის საერთო პარამეტრის ყველა დანარჩენისთვის შეცვლის გარეშე:

GET /v1/models?prefix=alias        # თითო id თითო მოდელზე — მოკლე alias-პრეფიქსი
GET /v1/models?prefix=dual         # ორივე ფორმა (სერვერის ნაგულისხმევი პარამეტრი)
GET /v1/models?prefix=canonical    # მხოლოდ სრული provider-id პრეფიქსი

რეჟიმი	აბრუნებს	შენიშვნები
dual	cc/claude-sonnet-4-6 და claude/claude-sonnet-4-6	ნაგულისხმევი. ორივე id ერთსა და იმავე მოდელზე მარშრუტდება; შენარჩუნებულია, რათა იმუშაოს კლიენტების კონფიგურაციებმა, რომლებშიც რომელიმე ფორმაა პირდაპირ გაწერილი. კატალოგის ზომას დაახლოებით აორმაგებს.
alias	cc/claude-sonnet-4-6	თითო ჩანაწერი თითო მოდელზე. განსხვავებული alias-ის არმქონე პროვაიდერებიც მაინც აბრუნებენ თავიანთ ჩანაწერს, ამიტომ არაფერი იკარგება.
canonical	claude/claude-sonnet-4-6	თითო ჩანაწერი თითო მოდელზე, სრული provider-id პრეფიქსით. განსხვავებული alias-ის არმქონე პროვაიდერებიც (მაგ., antigravity/…, agy/…) აქაც აბრუნებენ თავიანთ ერთადერთ id-ს, ამიტომ არაფერი იკარგება.

dual რეჟიმის სარკისებრი ჩანაწერის ამოცნობა query-პარამეტრის გარეშეც შეიძლება: მას აქვს parent ველი, რომელიც ძირითად id-ზე მიუთითებს.

კლიენტებმა, რომლებიც მოდელის ასარჩევ ინტერფეისს აჩვენებენ, უნდა მოითხოვონ ?prefix=alias — სწორედ ასე იქცევა OmniCopilot VS Code გაფართოება.

მოდელების no-thinking ვარიანტები

აზროვნების უნარის მქონე Claude მოდელებისთვის /v1/models ასევე წარმოადგენს no-thinking ვარიანტს, რომლის id-ს აქვს პრეფიქსი claude-3-omniroute-no-thinking/:

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

ამ id-ის არჩევისას (მაგ., Claude Code-ის კონფიგურაციაში, რომელიც ყოველთვის ურთავს thinking ბლოკს), ის კვლავ რეალურ <provider>/<model>-ად გარდაიქმნება, თუმცა მსჯელობა ჩახშობილია — /v1/messages მარშრუტზე გამოიყენება thinking:{type:"disabled"}, ხოლო /v1/chat/completions მარშრუტზე reasoning/reasoning_effort ველები გამოიტოვება. ვარიანტი ჩამონათვალში შედის მხოლოდ Claude-ის ოჯახის იმ მოდელებისთვის, რომლებსაც აქვთ აზროვნების მხარდაჭერა და ითვალისწინებენ disabled-ს (ამიტომ, მაგალითად, adaptive-only მოდელები, რომლებიც disabled-ს უარყოფენ, გამორიცხულია). ოპერატორებს შეუძლიათ თითოეული მოდელისთვის ამ ვარიანტის იძულებით ჩართვა ან გამორთვა ModelSpec.noThinkingAlias-ის მეშვეობით.

---

პროვაიდერის პლაგინის მანიფესტი

GET /api/v1/provider-plugin-manifest

აბრუნებს JSON-თან თავსებად პროვაიდერის პლაგინის მანიფესტს, რომელსაც იყენებენ Bifrost, CLIProxyAPI და სამომავლო sidecar-როუტერები. პასუხი გენერირდება TypeScript-ის პროვაიდერთა რეესტრიდან და განზრახ არ შეიცავს OAuth კლიენტის საიდუმლოებებს, შესრულების გარემოს განსაზღვრას, executor ფუნქციებს, მოთხოვნის სათაურებსა და ანგარიშის მონაცემებს.

გამოიყენეთ ეს endpoint, როდესაც sidecar პროცესის გარეთ მუშაობს და open-sse/config/providerPluginManifestRegistry.ts-ის პირდაპირ იმპორტს ვერ ახერხებს.

---

თავსებადობის 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 (აბრუნებს აუდიოს სხეულს)
POST	/v1/rerank	Cohere/Voyage-ის სტილის rerank
POST	/v1/classify	Jina classify (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 კატალოგის alias
GET	/api/v1/vscode/{token}/models	OpenAI მოდელების alias
POST	/api/v1/vscode/{token}/chat/completions	OpenAI-ის ტოკენიზებული alias
POST	/api/v1/vscode/{token}/responses	OpenAI Responses-ის ტოკენიზებული alias
POST	/api/v1/vscode/{token}/api/chat	Ollama-ს ტოკენიზებული alias
GET	/api/v1/vscode/{token}/api/tags	Ollama tags-ის ტოკენიზებული alias

ყველა POST მარშრუტი ერთსა და იმავე სტრუქტურას იყენებს: Bearer your-api-key + Zod-ით ვალიდირებული JSON სხეული (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema და ა.შ.; იხილეთ src/shared/validation/schemas.ts). სქემის ვალიდაციის წარუმატებლობისას ბრუნდება 4xx.

კლიენტებისთვის, რომლებსაც არ შეუძლიათ Authorization: Bearer ...-ის დამატება, OmniRoute ასევე იღებს API გასაღებებს URL-ში — ან query-string თავსებადობის მეშვეობით (?token=..., ?apiKey=..., ?api_key=..., ?key=...), ან ქვემოთ დოკუმენტირებული სპეციალური /api/v1/vscode/{token}/... endpoint-ების საშუალებით.

# Rerank
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina classify (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 search (s.jina.ai; პროვაიდერის alias-ები: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Moderations
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — აბრუნებს audio/mpeg (ან მოთხოვნილ ფორმატს) სხეულს
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

# ვიდეოს / მუსიკის გენერაცია (პროვაიდერის პრეფიქსიანი მოდელის ID)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

პროვაიდერის სპეციალური მარშრუტები

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

პროვაიდერის პრეფიქსი ავტომატურად ემატება, თუ მითითებული არ არის. შეუსაბამო მოდელები აბრუნებენ 400-ს.

---

Files API

OpenAI-თან თავსებადი ფაილების endpoint პაკეტური შეყვანა/გამოტანისა და ფაილის დანიშნულების მიხედვით ატვირთვისთვის.

მეთოდი	გზა	აღწერა
POST	/v1/files	ფაილის ატვირთვა (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — მაქს. 512 MiB
GET	/v1/files	ავტორიზებული API გასაღების ფაილების სიის მიღება
GET	/v1/files/[id]	ფაილის მეტამონაცემების მიღება
DELETE	/v1/files/[id]	ფაილის წაშლა
GET	/v1/files/[id]/content	ფაილის დაუმუშავებელი შიგთავსის ნაკადის სახით დაბრუნება

ავტორიზაცია: Bearer API გასაღები — getApiKeyRequestScope-ის მეშვეობით ფაილები თითოეული API გასაღების მიხედვით იზოლირებულია. გასაღებს მხოლოდ საკუთარი ფაილების ნახვა, ჩამოტვირთვა და წაშლა შეუძლია; მართვის პანელის სესია გასაღების გარეშე მთელ ინსტანციას კითხულობს; მფლობელის არმქონე ფაილზე (ანონიმური ან მართვის პანელის სესიიდან ატვირთული) წვდომა ეკრძალება ყველა არასესიურ გამომძახებელს. GET /v1/files ანონიმური გამომძახებლისგან — ასევე წარდგენილი, მაგრამ ვერ ამოცნობილი გასაღების შემთხვევაში — აბრუნებს 401-ს მაშინაც კი, როცა REQUIRE_API_KEY=false, ნაცვლად იმისა, რომ ყველა tenant-ის ფაილები ჩამოთვალოს (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

Batches API

OpenAI-თან თავსებადი პაკეტური დამუშავება.

მეთოდი	მისამართი	აღწერა
POST	/v1/batches	პაკეტის შექმნა — მოთხოვნის სხეული მოწმდება v1BatchCreateSchema-ით (input_file_id, endpoint, completion_window)
GET	/v1/batches	პაკეტების სიის მიღება
GET	/v1/batches/[id]	პაკეტის სტატუსისა და request_counts-ის მიღება
DELETE	/v1/batches/[id]	დასრულებული/წარუმატებელი პაკეტის წაშლა
POST	/v1/batches/[id]/cancel	მიმდინარე პაკეტის გაუქმება

ავთენტიფიკაცია: Bearer API გასაღები. პაკეტები თითოეული API გასაღების მიხედვით იზოლირებულია იმავე სამმხრივი წესით, როგორც ფაილები: წვდომა აქვს მხოლოდ საკუთარ გასაღებს, დაფის სესიას — ინსტანციის მასშტაბით, ხოლო მფლობელის არმქონე ჩანაწერებზე წვდომა აკრძალულია ყველა არასესიური გამომძახებლისთვის (მიღება, წაშლა, გაუქმება და შექმნისას input_file_id-ის შემოწმება). GET /v1/batches ანონიმურ გამომძახებელს აბრუნებს 401-ს მაშინაც კი, როცა REQUIRE_API_KEY=false.

---

Search API

ვებ/ძიების მომწოდებლების აბსტრაქცია (Tavily, Brave, Exa, Serper და სხვ.).

მეთოდი	მისამართი	აღწერა
GET	/v1/search	კონფიგურირებული ძიების მომწოდებლებისა და მათი შესაძლებლობების სიის მიღება
POST	/v1/search	საძიებო მოთხოვნის გაშვება — მოთხოვნის სხეული მოწმდება v1SearchSchema-ით; მხარდაჭერილია ქეშირება/გაერთიანება
GET	/v1/search/analytics	თითოეული მომწოდებლისთვის დამთხვევების/დაყოვნების/ქეშის სტატისტიკა

ავთენტიფიკაცია: Bearer API გასაღები (extractApiKey + isValidApiKey). ძიების პოლიტიკა აღსრულდება enforceApiKeyPolicy-ის მეშვეობით.

---

Web Fetch API

კონფიგურირებული web-fetch პროვაიდერის მეშვეობით URL-დან კონტენტის ამოღება (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

მეთოდი	მისამართი	აღწერა
POST	/v1/web/fetch	URL-ის მიღება/სკრეპინგი — body მოწმდება v1WebFetchSchema-ით

ავთენტიფიკაცია: Bearer API გასაღები (extractApiKey + isValidApiKey). პოლიტიკა აღსრულდება enforceApiKeyPolicy-ის მეშვეობით.

კვოტის გათვალისწინებით სარეზერვო მექანიზმი (#8297): როდესაც provider ცალსახად არ არის მითითებული, პული (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) ფიქსირებული პრიორიტეტული თანმიმდევრობით (fill-first) მუშავდება — სიხშირით შეზღუდული, მაგრამ კონფიგურირებული პროვაიდერი გამოტოვებულია მოთხოვნის ნაადრევად შეწყვეტის ნაცვლად, ხოლო ხელახლა საცდელი/კვოტასთან დაკავშირებული upstream შეცდომისას (HTTP 429 ყოველთვის; 402/403 — Firecrawl/Tavily/TinyFish-ის კვოტის ტიპის უფასო დონეებისთვის — არა Jina Reader-ისთვის და არასდროს ჩვეულებრივი 400 არასწორი მოთხოვნისთვის) მოთხოვნის შესრულების დროს სისტემა გადადის შემდეგ ჯერ გამოუცდელ პროვაიდერზე, რომლის ავტორიზაციის მონაცემებიც ხელმისაწვდომია. როდესაც პულში არსებული ყველა პროვაიდერის შესაძლებლობა ამოწურულია, endpoint წინა ზოგადი 400-ის ნაცვლად აბრუნებს ერთიან 429-ს (Retry-After header-ით). როდესაც ცალსახად მოითხოვება კონკრეტული provider, ფარული სარეზერვო გადართვა არ ხდება — სიხშირით შეზღუდული ან გაუმართავი ცალსახად მითითებული პროვაიდერი საკუთარ შეცდომას აბრუნებს (სიხშირით შეზღუდვისას 429, სხვა შემთხვევაში კი upstream სტატუსს).

---

WebSocket სტრიმინგი

GET /v1/ws?handshake=1

ამოწმებს WebSocket upgrade handshake-ს და აბრუნებს wire protocol-ის შეტყობინებების მაგალითებს (request, cancel). რეალურ WS frame-ებს ამუშავებს ჩაშენებული WS სერვერი, Next.js-ის route-ების ცხრილის გარეთ.

ავთენტიფიკაცია: Bearer API გასაღები handshake-ის დროს.

Responses API WebSocket-ის მეშვეობით (მხოლოდ codex)

# იგივე host:port, რაც HTTP API-ს აქვს (ნაგულისხმევად 20128); განაახლეთ კავშირი:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (ან: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# პირველი frame აუცილებლად response.create უნდა იყოს:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Responses-API-over-WebSocket პროქსი ექსკლუზიურად codex-თან არის დაკავშირებული (ChatGPT backend). ის API/dashboard-ის იმავე პორტზე უსმენს მისამართებს /v1/responses, /responses და /api/v1/responses. პირველ response.create frame-ზე ის შიდა codex-responses-ws bridge-ის მეშვეობით ახორციელებს ავთენტიფიკაციასა და მომზადებას, ირჩევს codex OAuth კავშირს და wreq-js transport-ის მეშვეობით ქმნის გვირაბს wss://chatgpt.com/backend-api/codex/responses-მდე. არა-codex მოდელები უარყოფილია (codex_ws_provider_required). კვოტის გაზიარების მარშრუტიზაციისთვის გამოიყენეთ model: "qtSd/<group>/codex/<model>". იმპლემენტირებულია app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts-ში.

ავთენტიფიკაცია: Bearer API გასაღები handshake-ის დროს. ჩაშენებული HTTP სერვერი (server-ws.mjs) აქტიური entrypoint უნდა იყოს (და ნაგულისხმევად ასეცაა, როდესაც app/server-ws.mjs არსებობს).

მოდელის id: გამოიყენეთ ChatGPT-ის უშუალო id (codex/ პრეფიქსის გარეშე)

OpenAI Codex CLI მოდელის სახელს კლიენტის მხარეს ამოწმებს, როდესაც supports_websockets = true, და უარყოფს პროვაიდერის პრეფიქსიან id-ებს, როგორიცაა codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). გაგზავნეთ უშუალო id (მაგ. gpt-5.5). OmniRoute-ის bridge მხოლოდ codex-ისთვისაა განკუთვნილი, ამიტომ upstream გვირაბის შექმნამდე ის უშუალო id-ს ხელახლა განსაზღვრავს, როგორც codex მოდელს (resolveCodexWsModelInfo) — მიუხედავად იმისა, რომ უშუალო gpt-5.5 HTTP-ის მეშვეობით სხვა პროვაიდერთან გადაიგზავნებოდა.

OpenAI Codex CLI-ის კონფიგურაცია

მიუთითეთ Codex CLI-ს OmniRoute-ზე, ~/.codex/config.toml-ში WebSocket-ის მხარდაჭერის მქონე მორგებული პროვაიდერის დამატებით (არსებული კონფიგურაციის ხელშეუხებლად დასატოვებლად გამოიყენეთ ცალკე CODEX_HOME):

model = "gpt-5.5"                 # უშუალო id — არა "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # ბოლოში დახრილი ხაზი არ უნდა იყოს; WS URL მისგან წარმოიქმნება (production-ში გამოიყენეთ https/wss)
wire_api = "responses"                    # ერთადერთი მხარდაჭერილი მნიშვნელობა 2026 წლის თებერვლიდან
supports_websockets = true                # ააქტიურებს Responses-over-WS transport-ს
env_key = "OMNIROUTE_API_KEY"             # შეიცავს OmniRoute API გასაღებს (Bearer)

export OMNIROUTE_API_KEY=sk-...           # OmniRoute API გასაღები (ნებისმიერი გასაღები, თუ REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

CLI base_url + /responses-ს WebSocket-მდე აახლებს, ხოლო OmniRoute მას შერჩეულ codex OAuth კავშირთან გვირაბით აკავშირებს. სრულად შემოწმებულია ლოკალურ სერვერზე: ChatGPT აბრუნებს codex.rate_limits + response.created-ს და completion-ს ნაკადად გადასცემს.

---

კვოტები და პრობლემების შეტყობინება

მეთოდი	მისამართი	აღწერა
GET	/v1/quotas/check	რეგისტრირებული გასაღების გაცემამდე provider + accountId-ისთვის კვოტის წინასწარი ვალიდაცია
POST	/v1/issues/report	კვოტის/გასაღების გაცემის შეცდომის GitHub-ზე შეტყობინება (საჭიროებს GITHUB_ISSUES_REPO + ტოკენს)

ავთენტიფიკაცია: Bearer API-გასაღები (isAuthenticated).

---

თვითმომსახურების გამოყენება (/api/usage/om-usage)

ნებისმიერ API-გასაღებს შეუძლია ნახოს საკუთარი გამოყენება და კვოტები — მართვის ავთენტიფიკაცია საჭირო არ არის. ამ საბოლოო წერტილს კლიენტი (CLI, OmniCopilot-ის პანელი) იყენებს, რათა გასაღების მფლობელს აჩვენოს მისი დანახარჯი.

# ტექსტური ფორმა (ისტორიული კონტრაქტი — უბრალო ტექსტი ტერმინალისთვის)
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"

გასაღებისთვის allowUsageCommand ჩართული უნდა იყოს (ნაგულისხმევად გამორთულია — მართვის პანელის API-გასაღებების მენეჯერი მას თითოეული გასაღებისთვის ცალ-ცალკე რთავს ან თიშავს). მის გარეშე საბოლოო წერტილი პასუხობს 403-ით.

?format=json აბრუნებს განმასხვავებელი ნიშნით სტრუქტურირებულ ფორმას, რათა გამომძახებელმა უარყოფის პასუხიდან მონაცემთა ველი არასდროს წაიკითხოს. წარმატების შემთხვევაში:

{
  "allowed": true,
  // წარმოდგენილია მხოლოდ მაშინ, როდესაც გასაღებისთვის ჩართულია ინდივიდუალური გამოყენების ლიმიტები (დღიური/კვირეული USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // არჩეული პროვაიდერის კვოტის მყისიერი სურათი, ან null, როდესაც ქეშში ჯერ არაფერია:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // ყველა კავშირის მყისიერი სურათი, რათა UI-მ რამდენიმე პროვაიდერი ერთმანეთის გვერდით გამოსახოს:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

უარყოფის შემთხვევაში (401 არასწორი გასაღები / 403 ნებართვა არ არის) იგივე მარშრუტი აბრუნებს { "allowed": false, "error": { "message": "…" } }-ს — არსებული, მაგრამ ცარიელი personal/provider (გასაღები დაშვებულია, თუმცა ჯერ არაფერია მიღებული) უარყოფისგან განსხვავებული მდგომარეობაა და მათ მხოლოდ JSON-ფორმა განასხვავებს.

ავთენტიფიკაცია: გამომძახებლის საკუთარი Bearer API-გასაღები, რომელიც მოწმდება isValidApiKey-ით — ეს არ არის მართვის ინტერფეისი (/api/keys/…), რომელიც კვლავ requireManagementAuth-ით არის დაცული.

---

სემანტიკური ქეში

# ქეშის სტატისტიკის მიღება
GET /api/cache/stats

# ყველა ქეშის გასუფთავება
DELETE /api/cache/stats

პასუხის მაგალითი:

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

გავლენა დაყოვნებაზე

სემანტიკური ქეშის HIT პასუხს ქეშიდან ზედა დონის სერვისის გამოძახების გარეშე აწვდის, ამიტომ ნაჩვენები X-OmniRoute-Response-Latency თითქმის ნულის ტოლია (ზედა დონის სერვისის თავდაპირველი დაყოვნების მიუხედავად). დაყოვნებისადმი მგრძნობიარე კლიენტებმა (საორიენტაციო წარმადობის ტესტირება, p50/p99 მონიტორინგი) უნდა შეამოწმონ პასუხის სათაური X-OmniRoute-Cache-Latency:

მნიშვნელობა	განმარტება
synthetic	პასუხი მოწოდებულია ქეშიდან; დაყოვნება ზედა დონის სერვისის რეალური დრო არ არის
(არ არის)	პასუხი მიღებულია ზედა დონის სერვისის რეალური გამოძახებით

ქეშის გვერდის ავლა თითოეული გასაღებისთვის

API-გასაღებებს შეუძლიათ უარი თქვან სემანტიკური ქეშიდან წაკითხვაზე cacheDefaultMode-ის მეშვეობით:

მნიშვნელობა	ქცევა
legacy	ქეშის ჩვეულებრივი ქცევა (ნაგულისხმევი)
bypass	ქეშში ძიების სრულად გამოტოვება; ყოველთვის ზედა დონის სერვისის გამოძახება

დააყენეთ გასაღების შექმნისას (POST /api/keys) ან განახლებისას (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

ქეშის გვერდის ავლა თითოეული მოთხოვნისთვის

ნებისმიერ მოთხოვნას შეუძლია გასაღების პარამეტრების მიუხედავად გვერდი აუაროს ქეშს:

X-OmniRoute-No-Cache: true

---

საინფორმაციო პანელი და მართვა

მართვის მარშრუტები (/api/*, საჯარო ავთენტიფიკაციის/შესვლის გარდა) ჩვეულებრივი ინფერენსის API გასაღებებით არ ავტორიზდება. ავტორიზაციის მონაცემების ოჯახები, წვდომის სფეროები და curl-ის მაგალითები: მართვის ავთენტიფიკაცია.

ავთენტიფიკაცია

საბოლოო წერტილი	მეთოდი	აღწერა
/api/auth/login	POST	შესვლა
/api/auth/logout	POST	გამოსვლა
/api/settings/require-login	GET/PUT	შესვლის მოთხოვნის გადართვა

პროვაიდერების მართვა

საბოლოო წერტილი	მეთოდი	აღწერა
/api/providers	GET/POST	პროვაიდერების ჩამონათვალი / შექმნა
/api/providers/[id]	GET/PUT/DELETE	პროვაიდერის მართვა
/api/providers/[id]/test	POST	პროვაიდერთან კავშირის შემოწმება
/api/providers/[id]/models	GET	პროვაიდერის მოდელების ჩამონათვალი
/api/providers/validate	POST	პროვაიდერის კონფიგურაციის ვალიდაცია
/api/providers/bulk	POST	ერთი პროვაიდერისთვის API გასაღებების მასობრივად დამატება
/api/providers/import	POST	ჰეტეროგენული პროვაიდერების სიის იმპორტი დამუშავებული CSV/JSON ფაილიდან (#6836); ნაწილობრივი შეცდომების შედეგები თითოეული მწკრივისთვის
/api/provider-nodes*	სხვადასხვა	პროვაიდერის კვანძების მართვა
/api/provider-models	GET/POST/PATCH/DELETE	მორგებული მოდელები (დამატება, განახლება, დამალვა/ჩვენება, წაშლა)

OAuth პროცესები

საბოლოო წერტილი	მეთოდი	აღწერა
/api/oauth/[provider]/[action]	სხვადასხვა	პროვაიდერისთვის სპეციფიკური OAuth

მარშრუტიზაცია და კონფიგურაცია

საბოლოო წერტილი	მეთოდი	აღწერა
/api/models/alias	GET/POST	მოდელების ფსევდონიმები
/api/models/catalog	GET	ყველა მოდელი პროვაიდერისა და ტიპის მიხედვით
/api/combos*	სხვადასხვა	კომბინაციების მართვა
/api/keys*	სხვადასხვა	API გასაღებების მართვა
/api/pricing	GET	მოდელების ფასები

გამოყენება და ანალიტიკა

საბოლოო წერტილი	მეთოდი	აღწერა
/api/usage/history	GET	გამოყენების ისტორია
/api/usage/logs	GET	გამოყენების ჟურნალები
/api/usage/request-logs	GET	მოთხოვნის დონის ჟურნალები
/api/usage/[connectionId]	GET	გამოყენება თითოეული კავშირისთვის
/api/usage/token-limits	GET/POST/DELETE	ტოკენების ლიმიტის ბიუჯეტები თითოეული API გასაღებისთვის
/api/usage/model-latency-stats	GET	მოძრავი დაყოვნების აგრეგატი თითოეული პროვაიდერისა და მოდელისთვის (საშუალო/p50/p95/p99, წარმატების მაჩვენებელი); ფილტრები: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health	GET	call_logs-ზე დაფუძნებული მოთხოვნის ქეშის მდგომარეობის შეჯამება — ჩაწერა/წაკითხვის თანაფარდობა, ჩაწერის ზომის p50/p90/p99 განაწილება, დიდი მოცულობის ჩაწერების კონცენტრაცია, დაყოფა მოდელების მიხედვით და healthy/degraded/thrash/no-data შეფასება; მოთხოვნის პარამეტრები: range (1h|24h|7d|30d, ნაგულისხმევია 24h) და არასავალდებულო model (#8827)

პარამეტრები

საბოლოო წერტილი	მეთოდი	აღწერა
/api/settings	GET/PUT/PATCH	ზოგადი პარამეტრები
/api/settings/proxy	GET/PUT	ქსელური პროქსის კონფიგურაცია
/api/settings/proxy/test	POST	პროქსი-კავშირის შემოწმება
/api/settings/ip-filter	GET/PUT	IP მისამართების ნებადართული/დაბლოკილი სია
/api/settings/thinking-budget	GET/PUT	აზროვნების/მსჯელობის მოთხოვნის გადაწერის რეჟიმი (უცვლელად გადაცემა / ავტომატური მოცილება / მორგებული / ადაპტიური). შეკუმშვისგან დამოუკიდებელია. იხილეთ THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	გლობალური სისტემური პრომპტი
/api/settings/compression	GET/PUT	გლობალური შეკუმშვის კონფიგურაცია
/api/settings/purge-request-history	POST	მოთხოვნების ჟურნალის ჩანაწერებისა და ლოკალური გამოძახებების ჟურნალის არტეფაქტების გასუფთავება

კონტექსტი და შეკუმშვა

Endpoint	მეთოდი	აღწერა
/api/compression/preview	POST	off/lite/standard/aggressive/ultra/RTK/stacked შეკუმშვის წინასწარი ნახვა
/api/compression/language-packs	GET	ხელმისაწვდომი Caveman ენის პაკეტების სია
/api/compression/rules	GET	Caveman-ის წესების მეტამონაცემების სია
/api/context/caveman/config	GET/PUT	Caveman-ის სპეციფიკური პარამეტრების ფსევდონიმი
/api/context/rtk/config	GET/PUT	RTK-ის სპეციფიკური პარამეტრები, მათ შორის მორგებული ფილტრები და დაუმუშავებელი გამომავალი მონაცემების შენახვა
/api/context/rtk/filters	GET	RTK-ის ფილტრების კატალოგი და მორგებული ფილტრების დიაგნოსტიკა
/api/context/rtk/test	POST	RTK-ის წინასწარი ნახვის/ტესტის გაშვება ტექსტურ მონაცემებზე
/api/context/rtk/raw-output/[id]	GET	მაჩვენებლის id-ის მიხედვით შენახული, რედაქტირებული დაუმუშავებელი გამომავალი მონაცემების წაკითხვა
/api/context/combos	GET/POST	შეკუმშვის კომბინაციების სია/შექმნა
/api/context/combos/[id]	GET/PUT/DELETE	შეკუმშვის კომბინაციის დეტალები/განახლება/წაშლა
/api/context/combos/[id]/assignments	GET/PUT	შეკუმშვის კომბინაციების მარშრუტიზაციის კომბინაციებზე მინიჭება
/api/context/analytics	GET	შეკუმშვის ანალიტიკის ფსევდონიმი

მონიტორინგი

Endpoint	მეთოდი	აღწერა
/api/sessions	GET	აქტიური სესიების თვალყურის დევნება
/api/rate-limits	GET	თითოეული ანგარიშის მოთხოვნათა სიხშირის ლიმიტები
/api/monitoring/health	GET	სიჯანსაღის შემოწმება + პროვაიდერების შეჯამება (catalogCount, configuredCount, activeCount, monitoredCount). მართვის ხედი შეიცავს credentialHealth-ს: შემოწმების ქეშის სკალარულ მნიშვნელობებს, failedConnections-ს, როდესაც failed>0, და staleDbNonOkCount-ს (SQLite-ის მუდმივი test_status, და არა მაჩვენებელი). იხილეთ MONITORING_GUIDE.md.
/api/cache/stats	GET/DELETE	ქეშის სტატისტიკა / გასუფთავება
/api/modality-bridge/stats	GET	მეხსიერებაში არსებული attempts, წარმატებული მცდელობები/bridged, წარუმატებელი მცდელობები, ქეშის დამთხვევები, totalLatencyMs, latencySamples, ნიმუშების რაოდენობაზე დაფუძნებული averageLatencyMs და ბოლო გამოყენების დრო (ნულდება ხელახლა გაშვებისას; მართვის ავტორიზაცია)
/api/modality-bridge/video/runtime	GET	მკაცრი სანდო loopback-შემოწმება მართვის ავტორიზაციამდე/შემოწმებამდე; FFmpeg/ffprobe-ის ხელმისაწვდომობისა და ვერსიების გასუფთავებული მონაცემები (შენახვის გარეშე)
/api/modality-bridge/video/extract	POST	შიდა, ავტორიზებული, სანდო loopback ბაიტების ბროკერი; 50 MiB შემავალი მონაცემები, შეზღუდული რიგი/32 MiB გამომავალი მონაცემები, 503 სიმძლავრის ამოწურვისას, 499 კავშირის გაწყვეტისას, 504 ვადის ამოწურვისას; არ წარმოადგენს საჯარო ატვირთვის API-ს

სარეზერვო ასლი და ექსპორტი/იმპორტი

Endpoint	მეთოდი	აღწერა
/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 არქივად ჩამოტვირთვა

ღრუბლოვანი სინქრონიზაცია

Endpoint	მეთოდი	აღწერა
/api/sync/cloud	სხვადასხვა	ღრუბლოვანი სინქრონიზაციის ოპერაციები
/api/sync/initialize	POST	სინქრონიზაციის ინიციალიზაცია
/api/cloud/*	სხვადასხვა	ღრუბლის მართვა

გვირაბები

Endpoint	მეთოდი	აღწერა
/api/tunnels/cloudflared	GET	საინფორმაციო დაფისთვის Cloudflare Quick Tunnel-ის ინსტალაციის/გაშვების სტატუსის წაკითხვა
/api/tunnels/cloudflared	POST	Cloudflare Quick Tunnel-ის ჩართვა ან გამორთვა (action=enable/disable)
/api/tunnels/ngrok	GET	საინფორმაციო დაფისთვის ngrok Tunnel-ის გაშვების სტატუსის წაკითხვა
/api/tunnels/ngrok	POST	ngrok Tunnel-ის ჩართვა ან გამორთვა (action=enable/disable)

CLI ხელსაწყოები

Endpoint	მეთოდი	აღწერა
/api/cli-tools/claude-settings	GET	Claude CLI-ის სტატუსი
/api/cli-tools/codex-settings	GET	Codex CLI-ის სტატუსი
/api/cli-tools/droid-settings	GET	Droid CLI-ის სტატუსი
/api/cli-tools/openclaw-settings	GET	OpenClaw CLI-ის სტატუსი
/api/cli-tools/runtime/[toolId]	GET	ზოგადი CLI-ის გაშვების გარემო

CLI-ის პასუხები შეიცავს: installed, runnable, command, commandPath, runtimeMode, reason.

ACP აგენტები

Endpoint	მეთოდი	აღწერა
/api/acp/agents	GET	ყველა აღმოჩენილი აგენტის (ჩაშენებული + მორგებული) სტატუსით ჩამონათვალი
/api/acp/agents	POST	მორგებული აგენტის დამატება ან აღმოჩენის კეშის განახლება
/api/acp/agents	DELETE	მორგებული აგენტის წაშლა id მოთხოვნის პარამეტრის მიხედვით

GET პასუხი შეიცავს agents[]-ს (id, name, binary, version, installed, protocol, isCustom) და summary-ს (total, installed, notFound, builtIn, custom).

მდგრადობა და სიხშირის ლიმიტები

Endpoint	მეთოდი	აღწერა
/api/resilience	GET/PATCH	მოთხოვნების რიგის, კავშირის დაყოვნების, პროვაიდერის ამომრთველისა და ლოდინის პარამეტრების მიღება/განახლება
/api/resilience/reset	POST	პროვაიდერის წრედის ამომრთველების საწყის მდგომარეობაში დაბრუნება
/api/resilience/model-cooldowns	GET	აქტიური (პროვაიდერი, კავშირი, მოდელი) ბლოკირებების ჩამონათვალი, დარჩენილი დროის მიხედვით დალაგებული
/api/resilience/model-cooldowns	DELETE	მოდელის ბლოკირების გაუქმება — ყველაფერი გასასუფთავებლად სხეული {provider, model} ან {all: true}
/api/rate-limits	GET	თითოეული ანგარიშის სიხშირის ლიმიტის სტატუსი
/api/rate-limit	GET	სიხშირის ლიმიტის გლობალური კონფიგურაცია

ოთხივე /api/resilience/* მარშრუტი საჭიროებს მართვის ავტორიზაციას (requireManagementAuth). პროვაიდერის ამომრთველს, კავშირის დაყოვნებასა და მოდელის ბლოკირებას შორის განსხვავებების სრული მიმოხილვისთვის იხილეთ მდგრადობა (გაფართოებული).

შეფასებები

Endpoint	მეთოდი	აღწერა
/api/evals	GET/POST	შეფასების კომპლექტების ჩამონათვალი / შეფასების გაშვება

პოლიტიკები

Endpoint	მეთოდი	აღწერა
/api/policies	GET/POST/DELETE	მარშრუტიზაციის პოლიტიკების მართვა

შესაბამისობა

Endpoint	მეთოდი	აღწერა
/api/compliance/audit-log	GET	შესაბამისობის აუდიტის ჟურნალი (ბოლო N)

v1beta (Gemini-სთან თავსებადი)

Endpoint	მეთოდი	აღწერა
/v1beta/models	GET	მოდელების ჩამონათვალი Gemini-ის ფორმატში
/v1beta/models/{...path}	POST	Gemini-ის generateContent endpoint

ეს endpoint-ები იმეორებს Gemini-ის API ფორმატს იმ კლიენტებისთვის, რომლებიც Gemini-ის მშობლიურ SDK-სთან თავსებადობას მოელიან.

შიდა / სისტემური API-ები

საბოლოო წერტილი	მეთოდი	აღწერა
/api/init	GET	აპლიკაციის ინიციალიზაციის შემოწმება (გამოიყენება პირველი გაშვებისას)
/api/tags	GET	Ollama-სთან თავსებადი მოდელის ტეგები (Ollama-ს კლიენტებისთვის)
/api/restart	POST	სერვერის კორექტული გადატვირთვის ინიციირება
/api/shutdown	POST	სერვერის კორექტული გამორთვის ინიციირება
/api/system/env/repair	POST	OAuth პროვაიდერის გარემოს ცვლადების აღდგენა

შენიშვნა: ეს საბოლოო წერტილები გამოიყენება სისტემის შიდა მიზნებისთვის ან Ollama-ს კლიენტებთან თავსებადობისთვის. ჩვეულებრივ, საბოლოო მომხმარებლები მათ პირდაპირ არ იძახებენ.

OAuth გარემოს აღდგენა (v3.6.1+)

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

{
  "provider": "claude-code"
}

აღადგენს კონკრეტული პროვაიდერის დაკარგულ ან დაზიანებულ OAuth გარემოს ცვლადებს. აბრუნებს:

{
  "success": true,
  "repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
  "backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}

---

აუდიოს ტრანსკრიფცია

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

აუდიოფაილების ტრანსკრიფცია ნებისმიერი კონფიგურირებული STT პროვაიდერის გამოყენებით. ბილიკის პირველი სეგმენტი ირჩევს ნატიურ პროვაიდერს (openai/…, deepgram/…). კარიბჭეები, რომლებიც სხვა მომწოდებლის მოდელს ხელახლა ექსპორტირებენ, იყენებენ კვალიფიცირებულ იდენტიფიკატორს (openrouter/deepgram/nova-3).

მოთხოვნა:

curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@recording.mp3" \
  -F "model=openai/whisper-1"

პასუხი:

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

მოდელის იდენტიფიკატორების მაგალითები: openai/whisper-1 (საჭიროებს OpenAI-ის გასაღებს), openrouter/deepgram/nova-3 (საჭიროებს OpenRouter-ის გასაღებს), deepgram/nova-3 (საჭიროებს ნატიურ Deepgram-ის გასაღებს). არაკვალიფიცირებული deepgram/nova-3 მოთხოვნა OpenRouter-ს არ იყენებს.

მხარდაჭერილი ფორმატები: mp3, wav, m4a, flac, ogg, webm.

---

Ollama-სთან თავსებადობა

კლიენტებისთვის, რომლებიც Ollama-ს API ფორმატს იყენებენ:

# ჩატის საბოლოო წერტილი (Ollama-ს ფორმატი)
POST /v1/api/chat

# მოდელების ჩამონათვალი (Ollama-ს ფორმატი)
GET /api/tags

მოთხოვნები ავტომატურად გარდაიქმნება Ollama-სა და შიდა ფორმატებს შორის.

ტოკენიზებული VS Code / სათაურის გარეშე ფსევდონიმები

გამოიყენეთ ეს ფსევდონიმები, როდესაც ინტეგრაციას არ შეუძლია Authorization სათაურის ჩასმა და API გასაღები საბაზისო URL-ში უნდა იყოს ჩაშენებული.

# OpenAI-ის სტილის კატალოგის ფსევდონიმი
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# OpenAI-ის სტილის ჩატის ფსევდონიმები
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Ollama-ს სტილის ფსევდონიმები
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

მაგალითი:

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

შენიშვნები:

• ტოკენიზებული ფსევდონიმები ხელახლა იყენებენ იმავე დამმუშავებლებს, რომლებსაც /v1/* და /api/tags; პასუხების სტრუქტურა უცვლელი რჩება.
• თუ კლიენტს მორგებული სათაურების მხარდაჭერა აქვს, უპირატესობა მიანიჭეთ Authorization: Bearer ...-ს.
• URL-ზე დაფუძნებული ტოკენები შეიძლება გამოჩნდეს უკუპროქსის ჟურნალებში, ბრაუზერის ისტორიასა და OmniRoute-ის გარეთ არსებულ ტელემეტრიაში. განიხილეთ ისინი თავსებადობის ვარიანტად და არა ავთენტიფიკაციის ნაგულისხმევ რეჟიმად.

---

ტელემეტრია

# დაყოვნების ტელემეტრიის შეჯამების მიღება (p50/p95/p99 თითოეული პროვაიდერისთვის)
GET /api/telemetry/summary

პასუხი:

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

---

ბიუჯეტი

# ყველა API გასაღების ბიუჯეტის სტატუსის მიღება
GET /api/usage/budget

# ბიუჯეტის დაყენება ან განახლება
POST /api/usage/budget
Content-Type: application/json

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

სქემის შენიშვნები (setBudgetSchema): apiKeyId სავალდებულოა; dailyLimitUsd, weeklyLimitUsd ან monthlyLimitUsd ველებიდან სულ მცირე ერთი უნდა იყოს ნულზე მეტი. არასავალდებულო ველები: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). მოძველებული {keyId, limit, period} სტრუქტურა აბრუნებს 400 Bad Request პასუხს.

ტოკენების ლიმიტები

თითოეული API გასაღებისთვის განსაზღვრული ტოკენების ბიუჯეტები (განსხვავდება ზემოთ მოცემული USD-ზე დაფუძნებული ბიუჯეტისგან). კონტროლი უშუალოდ მოთხოვნის დამუშავების გზაზე ხორციელდება: როდესაც გასაღების მიმდინარე დროის ფანჯარაში გამოყენება მის ლიმიტს მიაღწევს, მოთხოვნები უარყოფილი იქნება პასუხით 429 Too Many Requests. ლიმიტები შეიძლება შემოიფარგლოს კონკრეტული model-ით, provider-ით ან გამოყენებულ იქნეს globalურად მთელი გასაღებისთვის; როდესაც მოთხოვნას რამდენიმე ლიმიტი შეესაბამება, უპირატესობა ყველაზე მკაცრს ენიჭება.

# გასაღების ტოკენების ლიმიტების ჩამონათვალი (მოიცავს მიმდინარე ფანჯრის გამოყენებას)
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

სქემის შენიშვნები (setTokenLimitSchema): apiKeyId და scopeType (model | provider | global) სავალდებულოა. scopeValue სავალდებულოა, გარდა იმ შემთხვევისა, როდესაც scopeType არის global (მაგ., მოდელის id model მოქმედების სფეროსთვის, პროვაიდერის id provider მოქმედების სფეროსთვის). tokenLimit უნდა იყოს დადებითი მთელი რიცხვი (სტრიქონიდან გარდაქმნილი). არასავალდებულო ველები: id (შექმნისას გამოტოვეთ, განახლებისას მიუთითეთ), resetInterval (daily | weekly | monthly, ნაგულისხმევი მნიშვნელობაა monthly), resetTime (HH:MM), enabled (ნაგულისხმევი მნიშვნელობაა true). GET პასუხები თითოეულ ლიმიტს ამდიდრებს ველებით tokensUsed, remaining, windowStart, periodStartAt და nextResetAt. ეს მართვის კლასის საბოლოო წერტილია (ავთენტიფიკაცია ცენტრალიზებულად კონტროლდება ავტორიზაციის კონვეიერის მიერ).

მოთხოვნის დამუშავება

1. კლიენტი აგზავნის მოთხოვნას /v1/*-ზე
2. მარშრუტის დამმუშავებელი იძახებს handleChat, handleEmbedding, handleAudioTranscription ან handleImageGeneration ფუნქციას
3. განისაზღვრება მოდელი (პირდაპირი provider/model ან alias/combo)
4. ავტორიზაციის მონაცემები შეირჩევა ლოკალური DB-დან, ანგარიშის ხელმისაწვდომობის ფილტრაციის გამოყენებით
5. ჩატისთვის: handleChatCore ამოწმებს სემანტიკურ/ხელმოწერის ქეშს და განსაზღვრავს combo-ს შეკუმშვის პარამეტრებს
6. ჩართვის შემთხვევაში, პროაქტიური შეკუმშვა სრულდება პროვაიდერის ფორმატში გარდაქმნამდე (lite, Caveman, RTK ან კომბინირებული)
7. პროვაიდერის შემსრულებელი მოთხოვნას ზედა დონის სერვისში აგზავნის
8. პასუხი გარდაიქმნება კლიენტის ფორმატში (ჩატი) ან უცვლელად ბრუნდება (ჩაშენებები/სურათები/აუდიო)
9. გამოყენება, შეკუმშვის ანალიტიკა და მოთხოვნის ჟურნალები აღირიცხება
10. შეცდომების შემთხვევაში, combo-ს წესების შესაბამისად გამოიყენება სარეზერვო ვარიანტი

არქიტექტურის სრული ცნობარი: ARCHITECTURE.md

---

Combo-ს მართვა

უფრო მაღალი დონის მარშრუტიზაციის combo-ები (უკვე შეჯამებული /api/combos*-ის ქვეშ) ასევე შეიძლება 1:1 თანაფარდობით მიებას მოდელის id-ის შაბლონს, რაც OpenAI-ის სტილის მოდელის id-ის combo-ზე გამჭვირვალედ გადამისამართების საშუალებას იძლევა.

მეთოდი	გზა	აღწერა
GET	/api/model-combo-mappings	ყველა model→combo შესაბამისობის ჩამონათვალი
POST	/api/model-combo-mappings	შესაბამისობის შექმნა — სხეული: {pattern, comboId, priority?, enabled?, description?}
GET	/api/model-combo-mappings/[id]	ერთი შესაბამისობის მიღება
PUT	/api/model-combo-mappings/[id]	არსებული შესაბამისობის ველების განახლება
DELETE	/api/model-combo-mappings/[id]	შესაბამისობის წაშლა

ავთენტიფიკაცია: მართვის სესია/API გასაღები (requireManagementAuth).

---

ვებჰუკები

OmniRoute-ის მოვლენებისთვის გამავალი ვებჰუკების გამოწერები (მოთხოვნის დასრულება, კვოტის ამოწურვა, გასაღების როტაცია და ა.შ.).

მეთოდი	გზა	აღწერა
GET	/api/webhooks	ვებჰუკების სია (საიდუმლოებები შენიღბულია, როგორც <prefix>...)
POST	/api/webhooks	ვებჰუკის შექმნა — სხეული: {url, events?: ["*"], secret?, description?}
GET	/api/webhooks/[id]	ვებჰუკის მიღება
PUT	/api/webhooks/[id]	url/events/secret/description-ის განახლება
DELETE	/api/webhooks/[id]	ვებჰუკის წაშლა
POST	/api/webhooks/[id]/test	სატესტო დატვირთვის გაგზავნა ვებჰუკის URL-ზე და მიწოდების სტატუსის დაბრუნება

ავთენტიფიკაცია: მართვის სესია/API გასაღები (requireManagementAuth).

---

რეგისტრირებული გასაღებები (ავტომატური მართვა)

გამოიყენება გასაღებების ავტომატური მართვის ქვესისტემის მიერ, რათა უზრუნველყოს API გასაღებების გაცემა და როტაცია დამხმარე პროვაიდერის/ანგარიშის მეშვეობით, ყოველდღიური/საათობრივი კვოტებით.

მეთოდი	გზა	აღწერა
GET	/api/v1/registered-keys	რეგისტრირებული გასაღებების სია (მხოლოდ შენიღბული პრეფიქსი)
POST	/api/v1/registered-keys	ახალი რეგისტრირებული გასაღების გაცემა — სხეული: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. დაუმუშავებელ გასაღებს აბრუნებს ერთხელ. კვოტის გამო უარის შემთხვევაში აბრუნებს 429-ს.
GET	/api/v1/registered-keys/[id]	რეგისტრირებული გასაღების მეტამონაცემების მიღება (დაუმუშავებელი მნიშვნელობის გარეშე)
DELETE	/api/v1/registered-keys/[id]	რეგისტრირებული გასაღების გაუქმება
POST	/api/v1/registered-keys/[id]/revoke	გაუქმების ცალკე საბოლოო წერტილი (იგივე ეფექტი, რაც DELETE-ს)

ავთენტიფიკაცია: Bearer API გასაღები (isAuthenticated). ასევე იხილეთ /v1/quotas/check და /v1/issues/report.

---

აგენტების პროტოკოლი

Cloud-აგენტის ამოცანები (Claude Code, Codex Cloud, OpenHands და სხვ.), რომლებიც OmniRoute-ის მომხმარებლების სახელით დისტანციურად სრულდება.

მეთოდი	მისამართი	აღწერა
GET	/api/v1/agents/tasks	ამოცანების სია — არასავალდებულო ?provider=, ?status=, ?limit= (1–500, ნაგულისხმევად 50)
POST	/api/v1/agents/tasks	ამოცანის შექმნა — მოთხოვნის სხეული მოწმდება CreateCloudAgentTaskSchema-ით (providerId, prompt, source, options?). აბრუნებს 201-ს ამოცანის კონვერტით
DELETE	/api/v1/agents/tasks?id=...	ამოცანის წაშლა
GET	/api/v1/agents/tasks/[id]	ამოცანის წაკითხვა — როდესაც external_id დაყენებულია, სინქრონულად განაახლებს სტატუსს ზედა დონის Cloud-აგენტიდან
POST	/api/v1/agents/tasks/[id]	დისკრიმინირებული მოქმედება: {action: "approve"}, {action: "message", message}, ან {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	კონკრეტული ამოცანის წაშლა id-ის მიხედვით

ავთენტიფიკაცია: თითოეული მეთოდისთვის საჭიროა მართვის ავთენტიფიკაცია (requireCloudAgentManagementAuth). v3.8.0-მდე ეს მეთოდები ავთენტიფიკაციას არ საჭიროებდა — შეუთავსებელი ცვლილებისთვის იხილეთ კომიტი 588a0333.

# 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":"..."}}'

---

მართვის პროქსიები

გამავალი HTTP(S)/SOCKS პროქსიები, რომლებიც შეიძლება მიენიჭოს პროვაიდერებს, ანგარიშებს ან გლობალურად.

მეთოდი	მისამართი	აღწერა
GET	/api/v1/management/proxies	პროქსიების სია (?id=-ით აბრუნებს ერთს; ?id=&where_used=1-ით აბრუნებს მინიჭებების გრაფს)
POST	/api/v1/management/proxies	პროქსის შექმნა — მოთხოვნის სხეული მოწმდება createProxyRegistrySchema-ით
PATCH	/api/v1/management/proxies	პროქსის განახლება — მოთხოვნის სხეული მოწმდება updateProxyRegistrySchema-ით (საჭიროებს id-ს)
DELETE	/api/v1/management/proxies?id=...&force=1	პროქსის წაშლა (მინიჭებების მოსახსნელად გამოიყენეთ force=1)
GET	/api/v1/management/proxies/assignments	მინიჭებების სია — იფილტრება proxy_id, scope, scope_id ველებით; კავშირისთვის აქტიური პროქსის განსაზღვრისთვის მიუთითეთ resolve_connection_id=<id>
PUT	/api/v1/management/proxies/assignments	მინიჭება — მოთხოვნის სხეული მოწმდება proxyAssignmentSchema-ით ({scope, scopeId?, proxyId?}). ასუფთავებს დისპეტჩერის კეშს
PUT	/api/v1/management/proxies/bulk-assign	მასობრივი მინიჭება — მოთხოვნის სხეული მოწმდება bulkProxyAssignmentSchema-ით ({scope, scopeIds[], proxyId?})
GET	/api/v1/management/proxies/health?hours=24	დროის მოცემულ მონაკვეთში პროქსის მდგომარეობის აგრეგირებული მონაცემები (წარმატებული/წარუმატებელი მცდელობების რაოდენობა, დაყოვნება)

ავთენტიფიკაცია: თითოეულ მარშრუტზე საჭიროა მართვის სესია/API-გასაღები (requireManagementAuth).

ამოცანის აღწერაში მითითებულ POST /api/v1/management/proxies/[id]/assignments და POST /api/v1/management/proxies/[id]/health მარშრუტებს ზემოთ ნაჩვენები ბრტყელი /assignments და /health მარშრუტები ემსახურება — კოდურ ბაზაში ცალკეული id-ის ქვემარშრუტები არ არსებობს.

---

მდგრადობა (გაფართოებული)

OmniRoute უზრუნველყოფს დროებითი შეფერხებების დამუშავების სამ დამოუკიდებელ მექანიზმს; ქვემოთ მოცემული მართვის საბოლოო წერტილები ოპერატორებს მათი მდგომარეობის წაკითხვისა და პარამეტრების ხელით შეცვლის საშუალებას აძლევს:

მოქმედების არეალი	მდგომარეობის საცავი	წაკითხვა	გადატვირთვა / გასუფთავება
პროვაიდერის ამომრთველი	domain_circuit_breakers + ოპერატიულ მეხსიერებაში	/api/monitoring/health	POST /api/resilience/reset
კავშირის დაყოვნება	rateLimitedUntil პროვაიდერის კავშირებზე	/api/rate-limits, /api/providers/[id]	(ხელახლა აქტიურდება საჭიროებისას; გასუფთავება შესაძლებელია პროვაიდერის PUT-ით)
მოდელის ბლოკირება	ოპერატიულ მეხსიერებაში არსებული მოდელების ხელმისაწვდომობის რეესტრი	GET /api/resilience/model-cooldowns	DELETE /api/resilience/model-cooldowns

PATCH /api/resilience იღებს პროვაიდერის ამომრთველის ჩანაცვლებით პარამეტრებს providerBreaker.oauth-სა და providerBreaker.apikey-ში. თითოეული პროფილი მხარს უჭერს degradationThreshold, failureThreshold და resetTimeoutMs ველებს; იგივე ველები ხელმისაწვდომია Dashboard → Settings → Resilience-ში.

# ერთი მოდელის ბლოკირების გასუფთავება
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o-mini"}'

# ყველა ბლოკირების წაშლა
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

სრული კონცეპტუალური ცნობარისა და ამომრთველის ნაგულისხმევი პარამეტრებისთვის იხილეთ CLAUDE.md → "Resilience Runtime State".

---

უნარები

უნარების ჩარჩო OmniRoute-ის მორგებული შესრულებადი დამმუშავებლებით გასაფართოებლად, აგრეთვე მარკეტპლეისის ინტეგრაციები.

მეთოდი	გზა	აღწერა
GET	/api/skills	დაინსტალირებული უნარების სია — გაფილტვრა შესაძლებელია ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local პარამეტრებით; მხარდაჭერილია გვერდებად დაყოფა
GET	/api/skills/[id]	ერთი უნარის მიღება
PUT	/api/skills/[id]	უნარის განახლება (სახელი, აღწერა, რეჟიმი, სქემა, დამმუშავებელი, ტეგები)
DELETE	/api/skills/[id]	უნარის დეინსტალაცია
POST	/api/skills/install	უნარის დაყენება დაუმუშავებელი მანიფესტიდან — მოთხოვნის სხეული: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	უნარების ბოლო შესრულებების სია (აუდიტის ჟურნალი შეყვანილი/გამოტანილი მონაცემებითა და ხანგრძლივობით)
GET	/api/skills/marketplace?q=...	ძიება/პოპულარული ელემენტების სია SkillsMP მარკეტპლეისიდან (საჭიროებს skillsmpApiKey პარამეტრს)
POST	/api/skills/marketplace/install	უნარის დაყენება SkillsMP-დან id-ის მიხედვით
GET	/api/skills/skillssh?q=&limit=	ძიება skills.sh რეესტრში
POST	/api/skills/skillssh/install	უნარის დაყენება skills.sh-დან id-ის მიხედვით

ავთენტიფიკაცია: მართვის სესია/API გასაღები. მარკეტპლეისის საძიებო მარშრუტები იღებს როგორც მართვის ავთენტიფიკაციას, ისე Bearer API გასაღებს (isAuthenticated).

---

მეხსიერება

მუდმივი სასაუბრო/ფაქტობრივი მეხსიერების საცავი, რომლის მოქმედების არე თითოეული API გასაღებით / სესიით განისაზღვრება.

მეთოდი	გზა	აღწერა
GET	/api/memory	მეხსიერების ჩანაწერების სია — ?apiKeyId=, ?type=, ?sessionId=, ?q=, offset/limit ან page/limit გვერდებად დაყოფით
POST	/api/memory	მეხსიერების ჩანაწერის შექმნა — მოთხოვნის სხეული მოწმდება Zod-ის მიერ: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	მეხსიერების ერთი ჩანაწერის მიღება
DELETE	/api/memory/[id]	მეხსიერების ჩანაწერის წაშლა
GET	/api/memory/health	მეხსიერების ქვესისტემის მდგომარეობა (DB-სთან კავშირი, embeddings-ის ბექენდი, ვექტორული ინდექსის სტატუსი)

ავტორიზაცია: მართვის სესია/API გასაღები (requireManagementAuth). type ჩამონათვალი: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (იხილეთ MemoryType ფაილში src/lib/memory/types.ts).

---

MCP სერვერი

OmniRoute-ს მოჰყვება ჩაშენებული Model Context Protocol სერვერი 3 ტრანსპორტით (stdio, SSE, streamable-http) და მოქმედების არით შეზღუდული ხელსაწყოებით. ქვემოთ მოცემული დაფის საბოლოო წერტილები კითხულობს სტატუსის/აუდიტის მონაცემებს და HTTP ტრანსპორტებისთვის პროქსის ფუნქციას ასრულებს.

მეთოდი	გზა	აღწერა
GET	/api/mcp/status	პერიოდული სიგნალი, ტრანსპორტი, ონლაინ-მდგომარეობა, ბოლო გამოძახება, ყველაზე ხშირად გამოყენებული ხელსაწყოები, ბოლო 24 საათის წარმატების მაჩვენებელი
GET	/api/mcp/tools	MCP ხელსაწყოების სია ველებით name, description, scopes, phase, auditLevel, sourceEndpoints
GET	/api/mcp/sse	SSE ტრანსპორტისთვის SSE ნაკადის გახსნა (აბრუნებს 503-ს, თუ MCP გამორთულია ან ტრანსპორტი არ ემთხვევა)
POST	/api/mcp/sse	JSON-RPC ფრეიმის გაგზავნა SSE ტრანსპორტით
GET	/api/mcp/stream	Streamable HTTP ტრანსპორტის SSE მხარის გახსნა (სერვერის მიერ ინიციირებული შეტყობინებები)
POST	/api/mcp/stream	JSON-RPC ფრეიმის გაგზავნა Streamable HTTP ტრანსპორტით
DELETE	/api/mcp/stream	Streamable HTTP სესიის დასრულება
GET	/api/mcp/audit	აუდიტის ჟურნალის მოთხოვნა — ?limit=, ?offset=, ?tool=, `?success=true	false, ?apiKeyId=`
GET	/api/mcp/audit/stats	აუდიტის აგრეგირებული სტატისტიკა (ჯამური მაჩვენებლები, წარმატების მაჩვენებელი, საშუალო ხანგრძლივობა, ყველაზე ხშირად გამოყენებული ხელსაწყოები)

ავტორიზაცია: sse/stream ტრანსპორტები იყენებს MCP-სთვის სპეციფიკურ ავტორიზაციის ზედაპირს (Bearer API გასაღები mcp მოქმედების არით); status/tools/audit* მარშრუტები იკითხება დაფიდან (დაფის ჰოსტზე წვდომის გარდა დამატებითი ავტორიზაცია საჭირო არ არის).

ორივე HTTP ტრანსპორტი კონტროლდება settings.mcpEnabled-ისა და settings.mcpTransport-ის საშუალებით — ტრანსპორტის შეუსაბამობა აბრუნებს 400-ს, ხოლო MCP-ის გამორთული მდგომარეობა — 503-ს.

---

A2A სერვერი

OmniRoute უზრუნველყოფს A2A (აგენტიდან აგენტთან) JSON-RPC 2.0 ბოლო წერტილს და REST გარსს ინსპექტირებისა და საინფორმაციო პანელში გამოყენებისთვის.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # არასავალდებულოა, თუ OMNIROUTE_API_KEY დაყენებული არ არის
Content-Type: application/json

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

მხარდაჭერილი მეთოდები (ყველა დამოკიდებულია settings.a2aEnabled-ზე):

მეთოდი	აღწერა
message/send	უნარის სინქრონული შესრულება; აბრუნებს {task, artifacts, metadata}
message/stream	იმავე უნარების ნაკრების ნაკადური SSE შესრულება
tasks/get	ამოცანის მიღება taskId-ით
tasks/cancel	ამოცანის გაუქმება taskId-ით

ჩაშენებული უნარები: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

აგენტის ბარათი

GET /.well-known/agent.json

აბრუნებს საჯარო A2A აგენტის ბარათს (სახელი, აღწერა, შესაძლებლობები, უნარების კატალოგი, ავთენტიფიკაციის სქემა) — საჯაროდ კეშირდება 1 საათით. ავთენტიფიკაცია საჭირო არ არის.

REST დამხმარე მექანიზმები

მეთოდი	მისამართი	აღწერა
GET	/api/a2a/status	A2A-ს ჩართულობის სტატუსი + ამოცანების სტატისტიკა + კეშირებული აგენტის ბარათის შეჯამება
GET	/api/a2a/tasks	ამოცანების სია — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST	/api/a2a/tasks	(REST დამხმარე მექანიზმის სახით არ არის რეალიზებული — შექმენით JSON-RPC message/send-ის მეშვეობით)
GET	/api/a2a/tasks/[id]	ერთი ამოცანის მიღება
POST	/api/a2a/tasks/[id]/cancel	ამოცანის გაუქმება

ავთენტიფიკაცია: REST დამხმარე მექანიზმები მართვის ავთენტიფიკაციის გარეშე მუშაობს (წაკითხვადია საინფორმაციო პანელიდან); JSON-RPC /a2a მარშრუტი იყენებს Bearer OMNIROUTE_API_KEY-ს, თუ ის კონფიგურირებულია.

---

ღრუბელი, შეფასებითი ტესტები და შეფასება

მეთოდი	მისამართი	აღწერა
POST	/api/cloud/auth	ამოწმებს Bearer გასაღებს და ღრუბელთან სინქრონიზაციის კლიენტებისთვის აბრუნებს პროვაიდერების შენიღბულ კავშირებსა და მოდელების ფსევდონიმებს
POST	/api/cloud/credentials/update	აახლებს დაშიფრულ ავტორიზაციის მონაცემებს ღრუბელთან სინქრონიზებული პროვაიდერისთვის
POST	/api/cloud/model/resolve	ადგილობრივი მარშრუტიზაციის ცხრილის გამოყენებით ლოგიკურ მოდელის ID-ს კონკრეტულ პროვაიდერად/მოდელად გარდაქმნის
GET	/api/cloud/models/alias	ჩამოთვლის მოდელების ფსევდონიმებს, რომლებიც ხელმისაწვდომია ღრუბელთან სინქრონიზაციისთვის
GET	/api/assess	კითხულობს უახლესი შეფასების კატეგორიზაციებს (თითოეული პროვაიდერის/მოდელის მიხედვით)
POST	/api/assess	ასრულებს შეფასებას — მოთხოვნის სხეული: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	/api/evals	ჩამოთვლის ჩაშენებულ შეფასებითი ტესტების კომპლექტებსა და უახლეს გაშვებებს
POST	/api/evals	იწყებს შეფასებითი ტესტის გაშვებას
POST	/api/evals/suites	ქმნის მორგებულ შეფასებითი ტესტების კომპლექტს — მოთხოვნის სხეული მოწმდება evalSuiteSaveSchema-ით
GET	/api/evals/suites/[id]	იღებს მორგებულ შეფასებითი ტესტების კომპლექტს

ავთენტიფიკაცია: /api/cloud/auth პირდაპირ ამოწმებს Bearer გასაღებს; დანარჩენი /api/cloud/*, /api/evals/* და /api/assess მარშრუტები მოითხოვს მართვის სესიას/API გასაღებს. /api/assess POST იყენებს validateBody-ს დისკრიმინირებული გაერთიანების ტიპის მოქმედების არეალის სქემასთან ერთად.

---

ACP-ის (Agent Client Protocol) მართვა

როგორც შვილობილი პროცესები. ეს საბოლოო წერტილები მართავს ACP აგენტების აღმოჩენასა და მორგებული აგენტების რეგისტრაციას.

მეთოდი	მისამართი	აღწერა
GET	/api/acp/agents	ყველა ცნობილი CLI აგენტის (ჩაშენებული + მორგებული) სია ინსტალაციის სტატუსით, ვერსიითა და ბინარული ფაილით
POST	/api/acp/agents	მორგებული ACP აგენტის რეგისტრაცია ან ქეშის განახლება — სხეული: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} ან {action: "refresh"}
DELETE	/api/acp/agents	მორგებული ACP აგენტის წაშლა — მოთხოვნის პარამეტრი: ?id=<agentId>

პასუხის მაგალითი (GET /api/acp/agents):

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

ავთენტიფიკაცია: საჭიროა მართვის სესია (მართვის პანელის auth_token cookie) ან მართვის არეზე შეზღუდული API გასაღები.

სრული დეტალებისთვის იხილეთ ACP ჩარჩო.

---

ანალიტიკა და დაკვირვებადობა

რეალურ დროში მოქმედი ანალიტიკის საბოლოო წერტილები მარშრუტიზაციის, შეკუმშვისა და პროვაიდერების მრავალფეროვნების მონიტორინგისთვის. ისინი უზრუნველყოფს /dashboard/analytics/* გვერდების მუშაობას.

ავტომატური მარშრუტიზაციის ანალიტიკა

მეთოდი	მისამართი	აღწერა
GET	/api/analytics/auto-routing	ავტომატური მარშრუტიზაციის აგრეგირებული სტატისტიკა: გამოძახებების ჯამური რაოდენობა, სტრატეგიების განაწილება, დონეების განაწილება, წამყვანი პროვაიდერები
GET	/api/analytics/auto-routing?days=7	დროის ფანჯრით შეზღუდული სტატისტიკა (ნაგულისხმევად 24 სთ)

პასუხის მაგალითი:

{
  "window": "24h",
  "totalCalls": 1234,
  "strategyBreakdown": {
    "rules": 800,
    "cost": 200,
    "latency": 150,
    "sla-aware": 50,
    "lkgp": 34
  },
  "tierBreakdown": {
    "ultra": 100,
    "pro": 500,
    "standard": 400,
    "free": 234
  },
  "topProviders": [
    { "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
    { "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
  ]
}

შეკუმშვის ანალიტიკა

მეთოდი	მისამართი	აღწერა
GET	/api/analytics/compression	შეკუმშვის აგრეგირებული სტატისტიკა: დაზოგილი ტოკენები, დაზოგვის %, რეჟიმების განაწილება, ძრავების გამოყენება

პასუხის მაგალითი:

{
  "window": "24h",
  "totalOriginalTokens": 5000000,
  "totalCompressedTokens": 3500000,
  "totalSavings": 1500000,
  "savingsPct": 30.0,
  "modeBreakdown": {
    "lite": 400,
    "standard": 600,
    "aggressive": 100,
    "ultra": 50,
    "rtk": 84
  },
  "engineBreakdown": {
    "caveman": 800,
    "rtk": 434
  }
}

პროვაიდერების მრავალფეროვნების თვალყურის დევნება

მეთოდი	მისამართი	აღწერა
GET	/api/analytics/diversity	შენონის ენტროპიაზე დაფუძნებული მრავალფეროვნების თვალყურის დევნება: პროვაიდერების განაწილების გაზომვით თავიდან იცილებს ერთეულ მარცხის წერტილებს

პასუხის მაგალითი:

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

ავთენტიფიკაცია: საჭიროა მართვის სესია ან მართვის არეზე შეზღუდული API გასაღები.

---

ადმინისტრატორის ოპერაციები

ოპერაციული მართვის მხოლოდ ადმინისტრატორისთვის განკუთვნილი endpoint-ები.

მეთოდი	გზა	აღწერა
GET	/api/admin/concurrency	კონკურენტულობის მიმდინარე ლიმიტების წაკითხვა (გლობალური + თითოეული პროვაიდერისთვის)
POST	/api/admin/concurrency	კონკურენტულობის ლიმიტების განახლება — body: {global?: number, perProvider?: Record<string, number>}

ავტორიზაცია: საჭიროა მართვის სესია ადმინისტრატორის scope-ით.

---

CLI ინსტრუმენტების მართვა

მართეთ CLI ინსტრუმენტები, რომლებიც OmniRoute-თან ინტეგრირდება (antigravity, chipotle, commandCode, devin-cli და სხვ.). სრული სიისთვის იხილეთ პროვაიდერის ცნობარი.

მეთოდი	გზა	აღწერა
GET	/api/cli-tools/all-statuses	ყველა CLI ინსტრუმენტის სტატუსი (დაინსტალირებული მდგომარეობა, ვერსია, ბოლო გამოჩენა)
GET	/api/cli-tools/status	ერთი CLI ინსტრუმენტის სტატუსის დეტალები (?tool= query)
POST	/api/cli-tools/apply	ინსტრუმენტის გენერირებული კონფიგურაციის ჩაწერა (dryRun აჩვენებს წინასწარ შედეგს; კონტეინერში გაშვებისას — 422 + containerEphemeralTarget; migration მიუთითებს მოძველებულ Codex YAML-ზე)
GET	/api/cli-tools/backups	CLI ინსტრუმენტების კონფიგურაციის სარეზერვო ასლების ჩამონათვალი
POST	/api/cli-tools/backups	ყველა CLI ინსტრუმენტის კონფიგურაციის სარეზერვო ასლის შექმნა
POST	/api/cli-tools/backups	აღდგენა: იგივე endpoint body-ში {tool, backupId}-ით აღადგენს შესაბამის სარეზერვო ასლს
GET	/api/cli-tools/antigravity-mitm	Antigravity MITM პროქსის სტატუსი (antigravity-mitm CLI ინსტრუმენტი)
POST	/api/cli-tools/antigravity-mitm/alias	antigravity-mitm-ის alias-ების კონფიგურაცია

ავტორიზაცია: საჭიროა მართვის სესია.

---

აგენტის უნარები

მართეთ AI აგენტის უნარები (OpenAI-ის მორგებული GPT-ების მსგავსი, მაგრამ აგენტებისთვის).

მეთოდი	გზა	აღწერა
GET	/api/agent-skills	აგენტის ყველა უნარის ჩამონათვალი (ჩაშენებული + მორგებული)
GET	/api/agent-skills/[id]	აგენტის კონკრეტული უნარის მიღება
POST	/api/agent-skills	აგენტის მორგებული უნარის შექმნა — body: {name, description, prompt, model?, temperature?}
PUT	/api/agent-skills/[id]	აგენტის მორგებული უნარის განახლება
DELETE	/api/agent-skills/[id]	აგენტის მორგებული უნარის წაშლა
GET	/api/agent-skills/[id]/raw	დაუმუშავებელი prompt-ისა და მეტამონაცემების მიღება (შესრულების გარეშე)
POST	/api/agent-skills/generate	ბუნებრივ ენაზე აღწერილობის საფუძველზე ახალი უნარის AI-ის მეშვეობით გენერირება

ავტორიზაცია: საჭიროა მართვის სესია ან მართვის scope-ის მქონე API გასაღები.

---

კეშის მართვა

მართეთ სემანტიკური კეში და მსჯელობის კეში.

მეთოდი	გზა	აღწერა
GET	/api/cache	კეშის მიმოხილვა: ჩანაწერების საერთო რაოდენობა, დამთხვევის სიხშირე, დისკზე დაკავებული ზომა
GET	/api/cache/entries	კეშირებული ჩანაწერების სია (გვერდებად დაყოფით)
DELETE	/api/cache/entries	კეშის ჩანაწერების წაშლა (მოთხოვნის პარამეტრების მიხედვით გაფილტვრით)
GET	/api/cache/stats	კეშის დეტალური სტატისტიკა (თითოეული პროვაიდერისა და მოდელისთვის)
GET	/api/cache/reasoning	მსჯელობის კეშის სტატუსი (მსჯელობის ხელახლა გასაშვებად)
DELETE	/api/cache/reasoning	მსჯელობის კეშის გასუფთავება — მოთხოვნის პარამეტრები: ?toolCallId=<id> (ერთი), ?provider=<p> ან პარამეტრების გარეშე (ყველა)

ავთენტიფიკაცია: საჭიროა მართვის სესია.

---

მეხსიერების სისტემა

მართეთ მუდმივი მეხსიერება (FTS5 + ვექტორული ჩაშენებები).

მეთოდი	გზა	აღწერა
GET	/api/memory	მეხსიერების ჩანაწერების სია (გაფილტვრა არეალის, ტიპისა და საძიებო მოთხოვნის მიხედვით)
POST	/api/memory	მეხსიერების ახალი ჩანაწერის შექმნა — სხეული: {scope, type, content, metadata?}
GET	/api/memory/[id]	მეხსიერების კონკრეტული ჩანაწერის მიღება
PUT	/api/memory/[id]	მეხსიერების ჩანაწერის განახლება
DELETE	/api/memory/[id]	მეხსიერების ჩანაწერის წაშლა
GET	/api/memory?q=	მეხსიერებაში ძიება (FTS5 + ვექტორი) — სტატისტიკა იმავე პასუხშია ჩართული

ავთენტიფიკაცია: საჭიროა მართვის სესია ან მართვის არეალის მქონე API გასაღები.

---

ვებჰუკები

მართეთ მოვლენების ვებჰუკ-გამოწერები.

მეთოდი	გზა	აღწერა
GET	/api/webhooks	ყველა ვებჰუკ-გამოწერის სია
POST	/api/webhooks	ვებჰუკ-გამოწერის შექმნა — სხეული: {url, events[], secret?, active?}
GET	/api/webhooks/[id]	კონკრეტული ვებჰუკ-გამოწერის მიღება
PUT	/api/webhooks/[id]	ვებჰუკ-გამოწერის განახლება
DELETE	/api/webhooks/[id]	ვებჰუკ-გამოწერის წაშლა
GET	/api/webhooks/[id]/deliveries	ვებჰუკის მიწოდებების ისტორიის სია (წარმატება/წარუმატებლობის ჟურნალი)
POST	/api/webhooks/[id]/test	ვებჰუკისთვის სატესტო მოვლენის გაგზავნა

ავთენტიფიკაცია: საჭიროა მართვის სესია.

მოვლენების ტიპების სრული სიისთვის იხილეთ ვებჰუკების ფრეიმვორკი.

---

უნარების ფრეიმვორკი

მართეთ უნარები (აგენტური გაფართოებების ფრეიმვორკი).

მეთოდი	გზა	აღწერა
GET	/api/skills	ყველა დაინსტალირებული უნარის სია (ჩაშენებული + მორგებული)
POST	/api/skills/install	უნარის დაინსტალირება ლოკალური გზიდან ან URL-დან
DELETE	/api/skills/[id]	უნარის დეინსტალაცია
PUT	/api/skills/[id]	უნარის ჩართვა ან გამორთვა — მოთხოვნის სხეული: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST	/api/skills/executions	უნარის შესრულება — მოთხოვნის სხეული: {skillName, apiKeyId, input?, sessionId?}
GET	/api/skills/executions	ყველა უნარის შესრულების ისტორიის სია (გაფილტრეთ ?apiKeyId=-ით)

ავტორიზაცია: საჭიროა მართვის სესია ან მართვის მასშტაბის API გასაღები.

სრული დეტალებისთვის იხილეთ უნარების ფრეიმვორკი.

---

პლაგინები

მართეთ OmniRoute-ის პლაგინები (მესამე მხარის გაფართოებები).

მეთოდი	გზა	აღწერა
GET	/api/plugins	დაინსტალირებული პლაგინების სია
POST	/api/plugins/marketplace/install	პლაგინის დაინსტალირება მარკეტპლეისიდან
DELETE	/api/plugins/[name]	პლაგინის დეინსტალაცია
POST	/api/plugins/[name]/activate	პლაგინის გააქტიურება
POST	/api/plugins/[name]/deactivate	პლაგინის დეაქტივაცია
GET	/api/plugins/[name]/config	პლაგინის კონფიგურაციის მიღება
PUT	/api/plugins/[name]/config	პლაგინის კონფიგურაციის განახლება

ავტორიზაცია: საჭიროა მართვის სესია.

სრული დეტალებისთვის იხილეთ პლაგინების ფრეიმვორკი.

---

ჩრდილოვანი მარშრუტიზაცია

პროვაიდერების ჩრდილოვანი / A-B შედარება არ არის დამოუკიდებელი REST ინტერფეისი — ის კონფიგურირდება კომბინირებული მარშრუტიზაციის მეშვეობით (იხილეთ ავტოკომბო). თითოეული კომბოს შედარების მეტრიკები ხელმისაწვდომია GET /api/combos/metrics-ის მეშვეობით.

---

დამცავი მექანიზმები

შეამოწმეთ შესრულების გარემოს დამცავი მექანიზმები (PII-ის გამოვლენა, პრომპტ-ინექციის გამოვლენა, ხედვის მოდელებთან დაკავშირება). დამცავი მექანიზმები სრულდება ყოველ მოთხოვნაზე; თითოეული გამოძახებისთვის მათი გამოტოვება შესაძლებელია მოთხოვნის x-omniroute-disabled-guardrails სათაურის მეშვეობით — მუდმივი ჩართვის/გამორთვის ინტერფეისი არ არსებობს.

მეთოდი	გზა	აღწერა
GET	/api/guardrails	რეგისტრირებული დამცავი მექანიზმებისა და მათი სტატუსის სია (სახელი / ჩართულია თუ არა / პრიორიტეტი)
POST	/api/guardrails/test	გამოძახებამდე მოქმედი კონვეიერის სატესტო გაშვება ნიმუშურ შეყვანაზე — მოთხოვნის სხეული: {input, disabledGuardrails?}

ავტორიზაცია: საჭიროა მართვის სესია.

სრული დეტალებისთვის იხილეთ უსაფრთხოება > დამცავი მექანიზმები.

---

---

ავთენტიფიკაცია

ოთხი ტიპის ავტორიზაციის მონაცემების (მართვის პანელის სესია, ლოკალური CLI ტოკენი, oma_live_… წვდომის ტოკენი, მართვის უფლებებით შეზღუდული API გასაღები) და მათი ინფერენციის გასაღებებისგან განსხვავებების შესახებ იხილეთ მართვის ავთენტიფიკაცია.

• მართვის პანელის მარშრუტები (/dashboard/*) იყენებს auth_token cookie-ს
• შესვლისას გამოიყენება შენახული პაროლის ჰეში; სარეზერვო ვარიანტია INITIAL_PASSWORD
• requireLogin-ის გადართვა შესაძლებელია /api/settings/require-login-ის მეშვეობით
• REQUIRE_API_KEY=true-ის შემთხვევაში, /v1/* მარშრუტებმა შესაძლოა Bearer API გასაღები მოითხოვოს
• ამ ცნობარში „მართვის ტოკენი“ / „მართვის უფლებებით შეზღუდული API გასაღები“ გულისხმობს აღნიშნულ სახელმძღვანელოში აღწერილი ტიპებიდან ერთ-ერთს და არა დამატებით, განუსაზღვრელ საიდუმლო მონაცემთა ტიპს

უკუთავსებადობის დამრღვევი ცვლილება (v3.8.0) — /api/v1/agents/tasks/* და დაყოვნების პერიოდის მართვის საბოლოო წერტილები ახლა მართვის ავთენტიფიკაციას მოითხოვს (მართვის პანელის auth_token cookie ან მართვის უფლებებით შეზღუდული API გასაღები). კლიენტები, რომლებიც ადრე ამ მარშრუტებს ავთენტიფიკაციის გარეშე იძახებდნენ, მიიღებენ პასუხს 401 Unauthorized. იხილეთ კომიტი 588a0333 (fix(auth): აგენტისა და დაყოვნების პერიოდის API-ებისთვის მართვის ავთენტიფიკაციის მოთხოვნა).