Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

274 KB
Raw Blame

API Reference (ქართული)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 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 | 🇧🇬 Български | 🇧🇩 বাংলা | 🇧🇦 Bosanski | 🇨🇿 Č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/-ში არსებული მარშრუტების ხე.

OpenAI-თან თავსებადი პროტოკოლისა და პროვაიდერების შესაძლებლობების დეტალური მატრიცისთვის იხილეთ OPENAI_COMPATIBILITY.md.


სარჩევი


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

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 მოთხოვნა დუბლიკატების მოცილების გასაღები (5s ფანჯარა)
X-Request-Id მოთხოვნა დუბლიკატების მოცილების ალტერნატიული გასაღები
x-omniroute-connection მოთხოვნა ერთი მოდელის მოთხოვნის მიბმა პროვაიდერის ერთ კავშირზე (ანგარიშზე) მისი 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;.

ანგარიშის მიბმა თითოეულ მოთხოვნაზე

როდესაც პროვაიდერს რამდენიმე კავშირი აქვს (ანგარიშები ან გასაღებები), OmniRoute ჩვეულებრივ ერთ-ერთს ანგარიშის შერჩევის სტრატეგიის მეშვეობით ირჩევს. ამის ნაცვლად, მოთხოვნას შეუძლია ერთი კონკრეტული კავშირი x-omniroute-connection სათაურით მიაბას:

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer <your OmniRoute API key>" \
  -H "Content-Type: application/json" \
  -H "x-omniroute-connection: <connection id>" \
  -d '{"model": "codex/gpt-5.5", "messages": [{"role": "user", "content": "hi"}]}'
  • სად იპოვოთ id. გახსენით პროვაიდერის გვერდი მართვის პანელში (მართვის პანელი → პროვაიდერები → ) და კავშირის სტრიქონში დააწკაპუნეთ xxxxxxxx… id-ის ნიშნულზე — შედეგად კავშირის სრული id დაკოპირდება.
  • რომელი მოთხოვნები ითვალისწინებს მას. ერთი მოდელის მოთხოვნები (provider/model) შემდეგ მისამართებზე: /v1/chat/completions, /v1/messages და /v1/responses. კომბინაციები სათაურს უგულებელყოფს: ამის ნაცვლად, თითოეული კომბინაციის ეტაპისთვის ანგარიში თავად ამ ეტაპის კავშირის მეშვეობით მიამაგრეთ.
  • მიმაგრება მკაცრია და არა უბრალოდ უპირატესობა. გამოიყენება მხოლოდ მიმაგრებული კავშირი. მოთხოვნის შესრულებისას წარმოქმნილი შეცდომა ანგარიშის მოცდის პერიოდს აღრიცხავს, მაგრამ იმავე პროვაიდერის სხვა ანგარიშზე არ გადაერთვება.
  • მოცდის პერიოდი და კვოტა მიმაგრებას აუქმებს. სანამ მიმაგრებული კავშირი მოცდის პერიოდშია, კვოტა ამოწურული აქვს ან კვოტის პოლიტიკითაა დაბლოკილი, შემდგომი მოთხოვნები პროვაიდერის სხვა კავშირებზე გადაერთვება, ზუსტად ისე, როგორც მიუმაგრებელი ტრაფიკი.
  • უცნობი ან გათიშული id-ები შეცდომას იწვევს. id, რომელიც პროვაიდერის აქტიურ პულში არ არის (წაშლილია, დეაქტივირებულია ან სხვა პროვაიდერს ეკუთვნის), არცერთ დასაშვებ ანგარიშს არ ტოვებს, ამიტომ მოთხოვნა სხვა მიმართულებით ჩუმად გადამისამართების ნაცვლად შეცდომით სრულდება.

Claude Code მორგებულ სათაურებს ANTHROPIC_CUSTOM_HEADERS-ის მეშვეობით აგზავნის. მოათავსეთ ის env ბლოკში, ფაილში ~/.claude/settings.json, ან პროექტის დონის .claude/settings.json ფაილში, რათა თითოეული პროექტისთვის განსხვავებული ანგარიში მიამაგროთ:

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

წყარო: src/sse/handlers/chat.ts (სათაურის წაკითხვა), src/sse/services/auth.ts და src/sse/services/sessionAffinityPin.ts (მიმაგრების გაუქმება და პულში არარსებობის შემოწმება).

ღირებულების ტელემეტრიის სათაურები: წარმატებული არანაკადური პასუხები ასევე შეიცავს X-OmniRoute-* ღირებულების ტელემეტრიის ნაკრებს — X-OmniRoute-Response-Cost (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 (შეცდომისას მუშაობა გრძელდება).

ქეშიდან მიღების ღირებულების სემანტიკა: სემანტიკური ქეშიდან HIT-ისას (X-OmniRoute-Cache-Hit: true) ზედა დონის სერვისთან გამოძახება არ ხდება, ამიტომ X-OmniRoute-Response-Cost არის 0.0000000000 (HIT-ის მომსახურების ინკრემენტული ღირებულება). თავდაპირველი/სავარაუდო ღირებულება ცალკე, X-OmniRoute-Cost-Saved-ში აისახება. ბილინგის მომხმარებლებმა უნდა შეაჯამონ X-OmniRoute-Response-Cost (HIT-ები არაფერს ღირს); ქეშის ანალიტიკას კი შეუძლია 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-ს, მაგრამ არასოდეს არჩეულ კავშირს ან სერთიფიკატებს. განახლება და გამოშვება JSON სხეულში აწვდის generation-ს:

{ "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 არასოდეს ცვლის ელფოსტას ან გენერირებულ ანგარიშის იდენტობას. პროვაიდერის მნიშვნელობა არის არამგრძნობიარე ჩვენების ეტიკეტი და არასოდეს გენერირებული თავსებადი პროვაიდერის იდენტიფიკატორი. სერთიფიკატები, ტოკენები, ქუქიები, ნედლი კავშირის ან 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 პანელიდან მიღებული ნაგულისხმევი პროფილი (უგულებელყოფს აქტიურ პროფილს). დანაკარგიანი ძრავები გამორთულია.
safe მხოლოდ დედუპლიკაცია და ცარიელი სივრცის დაკეცვა.
allow-lossy შეინარჩუნეთ ოპერატორის გეგმა ამ მოთხოვნისთვის, მათ შორის შეჯამებები და სტილის გადაწერები.
engine:<id> ერთი ძრავა ჩართვისას, მაგ. engine:rtk. მოთხოვნის მიხედვით ჩართვა ამ ძრავისთვის.
<combo> დასახელებული კომბინაცია, ჯერ სახელის მიხედვით (რეგისტრის მიმართ არამგრძნობიარე), შემდეგ ID-ის მიხედვით.

შენიშვნები:

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

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

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

სადაც <source> არის request-header, routing-override, active-profile, auto-trigger, default ან off.


ჩაშენებები

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).
  • llama.cpp (llama-cpp/<model>, ლოკალური სერვერის მიერ ჩატვირთული ნებისმიერი მოდელი): კანონიკური text ელემენტები გარდაიქმნება უბრალო სტრიქონებად, ხოლო image / audio / video — თითოეულისთვის ერთ {"content": [part]} ობიექტად, llama-server-ის ჩატის შიგთავსის ნაწილების გამოყენებით (image_url, input_audio ფორმატით wav / mp3 / flac, input_video) და ჩაშენებული მონაცემებით; თითო ვექტორი ზედა დონის თითოეულ ელემენტზე. სერვერი გაშვებული უნდა იყოს --embedding --mmproj … პარამეტრებით; პროექტორის გარეშე ის თავად უარყოფს მედიას. document მხარდაჭერილი არ არის.
  • აშკარა მოდალობის მეტამონაცემების არმქონე უცნობი/დინამიკური მოდელები სტრუქტურირებულ შეყვანას 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": "ლამაზი მზის ჩასვლა მთების ფონზე",
  "size": "1024x1024"
}

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

n აბრუნებს n სურათს data[]-ში. პროვაიდერებისთვის, რომელთა ზედა დონის API თითო გამოძახებაზე ერთ სურათს აბრუნებს (Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik, NVIDIA NIM, Cloudflare Workers AI), სრულდება n ცალკეული ზედა დონის გამოძახება, რომელთაგან ერთდროულად მაქსიმუმ 4 მიმდინარეობს. ფიქსირებულ seed-ს ემატება გამოძახების ინდექსი (seed, seed + 1, …), ამიტომ სურათები განსხვავდება, თუმცა მათი კვლავწარმოება კვლავ შესაძლებელია. n-ის ზედა ზღვარია 10. თუ რომელიმე გამოძახება ვერ შესრულდება, მთლიანი მოთხოვნა წარუმატებლად ჩაითვლება. განშტოებით გამოძახების ფორმატების სია არის SINGLE_IMAGE_FANOUT_FORMATS ფაილში open-sse/handlers/imageGeneration/fanOut.ts.

ZenMux ხელახლა იყენებს API-გასაღების არსებულ კავშირს და იღებს zenmux/ ან zm/ პრეფიქსებს:

  • zenmux/openai/gpt-image-2 იყენებს ZenMux-ის OpenAI Images API-ს. პარამეტრებს შორისაა size, quality, n, output_format, output_compression, background და response_format.
  • სხვა გამომცემლები, მაგალითად zm/meta/muse-image-1.0, იყენებენ ZenMux-ის Vertex AI :predict საბოლოო წერტილს. n შეესაბამება sampleCount-ს, aspect_ratio — aspectRatio-ს, ხოლო image_size (1K, 2K, 4K) — sampleImageSize-ს. პიქსელებში მითითებული size განსაზღვრავს მხოლოდ გვერდების თანაფარდობას და არა გარანტირებულ პიქსელურ ზომებს. მხარდაჭერილი თანაფარდობები, გარჩევადობები და რაოდენობები მოდელის მიხედვით განსხვავდება.
  • zm/inclusionai/ming-image-0.1-design ზომებს თავად ირჩევს. გამოტოვეთ size, aspect_ratio და image_size; მათი ცხადად მითითება აბრუნებს HTTP 400-ს. PNG, JPEG და WebP ფორმატების მოთხოვნა შესაძლებელია output_format-ის გამოყენებით.

ეს ინტეგრაცია მხარს უჭერს ტექსტიდან სურათის გენერაციას და არა საცნობარო სურათის რედაქტირებას. Vertex-ის გამომავალი ნორმალიზდება data[].b64_json-ში; response_format: "url" აბრუნებს ზედა დონის HTTPS URL-ს ან base64 მონაცემთა URL-ს, როდესაც ხელმისაწვდომია მხოლოდ სურათის ბაიტები. ცარიელი/გაფილტრული გამომავალი ცარიელი წარმატებული პასუხის ნაცვლად შეცდომას აბრუნებს. მოდელზე წვდომა დამოკიდებულია ZenMux-ის ანგარიშზე. იხილეთ ZenMux-ის Vertex API და OpenAI Images API.

# ყველა სურათის მოდელის ჩამონათვალი
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    # მხოლოდ პროვაიდერის სრული 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 თითო მოდელზე ერთი ჩანაწერი პროვაიდერის სრული id-ის პრეფიქსით. განსხვავებული alias-ის არმქონე პროვაიდერებიც (მაგ. antigravity/…, agy/…) აქაც გამოსცემენ თავიანთ ერთადერთ id-ს, ამიტომ არაფერი იკარგება.

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

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

აღმოჩენის ფილტრები (?capability=, ?min_context=, ?kind=, ?q=)

GET /v1/models იღებს არჩევით აღმოჩენის ფილტრებს. მათ გარეშე პასუხი უცვლელია. ისინი ავიწროებენ კატალოგს, რომელსაც გამომძახებელი უკვე ხედავს (ჯერ API-გასაღების ნებართვები გამოიყენება), და სრულდება OpenAI-ის სტილის limit / after გვერდებად დაყოფამდე:

GET /v1/models?capability=vision&capability=tool_calling   # ჩამოთვლილი ყველა შესაძლებლობა true უნდა იყოს
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding                              # კატალოგის `type`; მის გარეშე სტრიქონები `chat`-ია
GET /v1/models?q=sonnet&limit=10                           # რეგისტრისგან დამოუკიდებელი დამთხვევა id-ზე ან სახელზე
პარამეტრი მნიშვნელობები
capability attachment, reasoning, structured_output, temperature, thinking, tool_calling, vision
min_context არაუარყოფითი მთელი რიცხვი, რომელიც შედარებულია context_length-თან
kind chat, audio, embedding, image, moderation, music, rerank, video
q 1–200 სიმბოლო

უცნობი მნიშვნელობა ან min_context, რომელიც არაუარყოფითი მთელი რიცხვი არ არის (მაგალითად, 1.5), აბრუნებს HTTP 400-ს, ხოლო შეტყობინებაში ჩამოთვლილია დასაშვები მნიშვნელობები. იმპლემენტაცია: src/app/api/v1/models/catalogFilters.ts.

მოდელების მოკლე სია (POST /v1/models/query)

POST /v1/models/query იმავე კატალოგიდან აბრუნებს მოკლე, დეტერმინისტულ სიას, იმავე ავტორიზაციითა და თითოეული გასაღებისთვის იგივე ხილვადობით, რაც GET /v1/models-ს აქვს:

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

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

→ { "object": "list", "data": [ ...მოდელები ] }

ყველა ველი არჩევითია. capabilities და exclude იღებს მასივს ან მძიმეებით გამოყოფილ სტრიქონს; max_output შედარებულია max_output_tokens-თან. შედეგები ჯერ owned_by-ის, შემდეგ კი id-ის მიხედვით ლაგდება. limit-ის ნაგულისხმევი მნიშვნელობაა 20, ხოლო 100-ზე მაღალი მნიშვნელობები 100-მდე იზღუდება. არასწორი JSON, უცნობი ველი ან არასწორი მნიშვნელობა აბრუნებს HTTP 400-ს.

ცალკეულად დამალული ჩატის მოდელები

პროვაიდერის გვერდზე Hidden ნიშნით მონიშნული მოდელი კატალოგიდან გამორიცხულია და აშკარა მოთხოვნისას უარყოფილია HTTP 404 / model_not_found პასუხით. შემოწმება იყენებს განსაზღვრულ პროვაიდერსა და მოდელს, მათ შორის პროვაიდერის alias-ებს, თავსებადი პროვაიდერის კვანძის პრეფიქსებსა და კავშირის ნაგულისხმევ პარამეტრებს. კომბინაცია გამოტოვებს დამალულ სამიზნეებს და შეუძლია ხილული მონათესავე მოდელის გამოყენება; როდესაც შესრულებადი სამიზნე აღარ რჩება, ის იმავე შეცდომის კოდს აბრუნებს. დამალვის გაუქმება ძალაში შედის მომდევნო მოთხოვნიდან. მხოლოდ სურათებისთვის განკუთვნილი ხილვადობის გადაფარვები არ მალავს იმავე ID-ის მქონე ჩატის მოდელს.

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

აზროვნების გარეშე მოდელების ვარიანტები

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

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

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


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

GET /api/v1/provider-plugin-manifest

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

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


თავსებადობის ენდპოინტები

მეთოდი გზა ფორმატი
POST /v1/chat/completions OpenAI
POST /v1/messages Anthropic
POST /v1/responses OpenAI Responses
POST /v1/embeddings OpenAI
POST /v1/images/generations OpenAI Images
POST /v1/images/edits OpenAI Images (რედაქტირება/inpaint)
POST /v1/videos/generations OpenAI-ის სტილის ვიდეოს გენერირება
POST /v1/music/generations OpenAI-ის სტილის მუსიკის გენერირება
POST /v1/audio/transcriptions OpenAI Audio (STT)
POST /v1/audio/speech OpenAI TTS (აბრუნებს აუდიოს სხეულს)
POST /v1/rerank Cohere/Voyage-ის სტილის ხელახალი რანჟირება
POST /v1/classify Jina-ს კლასიფიკაცია (api.jina.ai)
POST /v1/segment Jina-ს სეგმენტატორი (segment.jina.ai)
POST /v1/moderations OpenAI Moderations
GET /v1/models OpenAI
POST /v1/models/query მოდელების გაფილტრული მოკლე სია
POST /v1/messages/count_tokens Anthropic
GET /v1beta/models Gemini
POST /v1beta/models/{...path} Gemini generateContent
POST /v1/api/chat Ollama
GET /api/v1/vscode/{token}/ OpenAI-ის კატალოგის ალიასი
GET /api/v1/vscode/{token}/models OpenAI-ის მოდელების ალიასი
POST /api/v1/vscode/{token}/chat/completions OpenAI-ის ტოკენიზებული ალიასი
POST /api/v1/vscode/{token}/responses OpenAI Responses-ის ტოკენიზებული ალიასი
POST /api/v1/vscode/{token}/api/chat Ollama-ს ტოკენიზებული ალიასი
GET /api/v1/vscode/{token}/api/tags Ollama-ს ტეგების ტოკენიზებული ალიასი

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

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

# ხელახალი რანჟირება (ღრუბლოვანი რეესტრის პროვაიდერი, ან OpenAI-სთან თავსებადი პროვაიდერის კვანძი ფორმატით "<prefix>/<model>")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina-ს კლასიფიკაცია (Foundation API-ის ავტორიზაციის მონაცემები)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina-ს სეგმენტატორი
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina-ს ძიება (s.jina.ai; პროვაიდერის ალიასები: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# მოდერაცია
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — აბრუნებს audio/mpeg-ის (ან მოთხოვნილი ფორმატის) სხეულს
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Soniox TTS მოითხოვს ენასა და ხმას: `language`-ის ნაგულისხმევი მნიშვნელობაა "en"; გამოტოვებული
# ხმა ან OpenAI-ის სტანდარტული ხმის სახელი (alloy, nova, …) გარდაიქმნება "Adrian"-ად
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }

# სურათის რედაქტირება (multipart)
POST /v1/images/edits  -F [email protected] -F prompt="..." -F [email protected]

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

გადახარისხების პროვაიდერის კვანძები: POST /v1/rerank ასევე მარშრუტდება OpenAI-სთან თავსებადი პროვაიდერის კვანძებისკენ (oMLX, vLLM, Infinity, TEI კარიბჭის უკან, …), რომლებიც მისამართდება როგორც <node-prefix>/<model>. Loopback კვანძები (localhost, 127.0.0.1, 172.16.0.0/12) ყოველთვის დაშვებულია, ისევე როგორც ჰოსტების სახელები, რომლებსაც ოპერატორი უთითებს OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS-ში (მაგ., Docker/Compose სერვისის სახელი, როგორიცაა http://reranker:8080/v1; მათთან დაკავშირება ხდება პირდაპირ, არასდროს HTTP(S)_PROXY-ის ან კავშირის ფიქსირებული პროქსის გავლით). ნებისმიერ სხვა ჰოსტზე არსებული კვანძები — LAN-ის მოწყობილობა ან Tailscale-ის თანაწევრი — დაშვებულია მხოლოდ მაშინ, როცა ოპერატორი ჩართავს RERANK_REMOTE_PROVIDER_NODES ფუნქციის ალამს და კვანძის საბაზისო URL აკმაყოფილებს პროვაიდერის გამავალი URL-ების პოლიტიკას (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS / OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS). მეხსიერების ძრავის გადახარისხების ეტაპი ამ მარშრუტს loopback-ის გავლით იძახებს, ამიტომ იგივე წესი ვრცელდება მეხსიერების პარამეტრებში rerankProviderModel-ზეც.

ლოკალური სერვერის ფორმატები: კვანძი გამოიძახება მისამართზე <base>/v1/rerank, ხოლო 404-ის შემთხვევაში — მისამართზე <base>/rerank (Infinity, TEI). ზემდგომი მოთხოვნის სხეული შეიცავს როგორც Cohere/OpenAI-ის დასახელებებს (documents, return_documents), ასევე TEI-ის დასახელებებს (texts, return_text), ხოლო ზემდგომი პასუხი ნორმალიზდება Cohere-ის გარსის ფორმატში: TEI-ის უშუალო [{index, score, text}], მსუბუქი კარიბჭეებიდან მიღებული {results: [{index, score}]} და Voyage-ის სტილის {data: [...]} კლიენტს უბრუნდება ფორმატით {results: [{index, relevance_score, document?}]}, ქულის მიხედვით დალაგებული და top_n-ით შეზღუდული.

პროვაიდერის კვანძების აღმოჩენა: OpenAI-სთან თავსებადი პროვაიდერის კვანძის მოდელები GET /v1/models-ში კვანძის პრეფიქსით გამოჩნდება. ჩანაწერები, რომლებიც endpoint-ის მეტამონაცემებს არ შეიცავს (რაც ტიპურია ლოკალური /v1/models ჩამონათვალებისთვის), კვანძის apiType-ს მემკვიდრეობით იღებს, ამიტომ embeddings კვანძის მოდელებს აქვს type: "embedding", ხოლო rerank კვანძის მოდელებს — type: "rerank", ნაცვლად იმისა, რომ ნაგულისხმევად ჩატის ტიპი მიენიჭოს; სინქრონიზებულ ან ხელით დამატებულ ჩანაწერში ცხადად მითითებულ supportedEndpoints-ს კვლავ უპირატესობა ენიჭება.

პროვაიდერის გამოყოფილი მარშრუტები

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.


ძიების API

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

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

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

Exa-სა და Tavily-ის provider_options

Exa და Tavily პროვაიდერისთვის სპეციფიკურ ველებს სახელთა სივრცით გამოყოფილი ობიექტიდან კითხულობენ: provider_options.exa (ან provider_options["exa-search"]) და provider_options.tavily (ან provider_options["tavily-search"]). გადაეცემა მხოლოდ ქვემოთ ჩამოთვლილი გასაღებები. თითოეული მათგანი მოწმდება საკუთარი Zod სქემის მიხედვით ფაილში open-sse/handlers/search/providerOptionsPassthrough.ts, ხოლო არასწორი ტიპის მქონე გასაღები გამოიტოვება. ყველა სხვა გასაღები იგნორირდება, მათ შორის ავტორიზაცია, საბაზისო URL, stream და outputSchema. სხვა პროვაიდერების მიერ გამოყენებული ბრტყელი გასაღებები (cx, depth, ...) კვლავ ძველებურად მუშაობს.

პროვაიდერი ზედა დონის ველები ჩადგმული
Exa type, category, userLocation, moderation, additionalQueries, objective, systemPrompt, compliance (ბრტყელი პრიმიტივები), startPublishedDate, endPublishedDate contents.{text, highlights, summary, extras, subpages, subpageTarget, livecrawlTimeout, maxAgeHours} ერწყმის ნაგულისხმევ მნიშვნელობას { text: true, highlights: true }
Tavily search_depth, chunks_per_source, time_range, start_date, end_date, include_published_date, filter_by_published_date, include_answer, include_raw_content, include_images, include_image_descriptions, include_favicon, include_domains_mode, language, filter_by_language, auto_parameters, exact_match, include_usage, safe_search —

ზოგად ველებს ყოველთვის უპირატესობა ენიჭება: query, max_results, filters (დომენები), country და search_type-იდან მიღებული თემა. Exa-ში search_type: "news" ინარჩუნებს category: "news"-ს. Tavily ასევე იღებს search_type: "finance"-ს (topic: "finance").

ზოგადი time_range ახლა ორივე პროვაიდერს გადაეცემა: Exa იღებს startPublishedDate-ს (ISO დროის ნიშნული), ხოლო Tavily — start_date-ს (YYYY-MM-DD). provider_options-ში ცალსახად მითითებული თარიღი გადაფარავს გარდაქმნილ მნიშვნელობას.

Exa-ს შედეგები provider_raw-ში ინარჩუნებს id, highlight_scores, summary, subpages, entities და extras ველებს. Tavily-ის შედეგები ინარჩუნებს images და favicon ველებს.

ღირებულების აღრიცხვისთვის კვლავ გამოიყენება ბრტყელი რეესტრი costPerQuery. Tavily search_depth: "advanced"-ისთვის თითო გამოძახებაზე მეტ კრედიტს არიცხავს და ეს განსხვავება usage.search_cost_usd-ში არ აისახება.


Web Fetch API

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

Parallel Extract (parallel-search, იგივე API გასაღები, რაც Parallel Search-ს აქვს) მხოლოდ Markdown-ს აბრუნებს — ნებისმიერი სხვა format იწვევს 400-ს — ხოლო კონტენტის მოცულობა შეზღუდულია 100,000 სიმბოლოთი. როდესაც სამიზნე გვერდის ამოღება შეუძლებელია, გარე სერვისი ამის შესახებ HTTP 200 პასუხში იტყობინება; OmniRoute ამას აბრუნებს როგორც 422-ს ფიქსირებული შეტყობინებით.

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

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

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


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 გასაღებს შეუძლია წაიკითხოს საკუთარი გამოყენებისა და კვოტების მონაცემები — მართვის ავტორიზაცია საჭირო არ არის. ეს არის endpoint, რომელსაც კლიენტი (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 ჩართული უნდა იყოს (ნაგულისხმევად გამორთულია — dashboard-ის API-გასაღებების მენეჯერი მას თითოეული გასაღებისთვის ცალ-ცალკე რთავს ან თიშავს). მის გარეშე endpoint პასუხობს 403-ით.

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

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

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

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

დაუმუშავებელი და ზღვრის მიხედვით კორექტირებული კვოტის პროცენტები

/api/usage/om-usage-ის გამოყენებისას გამომძახებლებმა უნდა გაითვალისწინონ განსხვავება უბრალო ტექსტის გამომავალში და სტრუქტურირებულ JSON გამომავალში წარმოდგენილ პროცენტებს შორის:

ასპექტი უბრალო ტექსტის ფორმატი (/api/usage/om-usage / @@om-usage) JSON ფორმატი (?format=json)
გამომავალი ველი NN% დარჩა (მაგ., 20% დარჩა) provider.quotas / providers[].quotas
გაზომვა ზღვრის მიხედვით კორექტირებული გამოსაყენებელი რესურსი: ზღვრულ მნიშვნელობაზე მეტი დარჩენილი მოცულობა დაუმუშავებელი upstream-კვოტა: პროვაიდერის არაკორექტირებული გაზომვა
ზღვრის მასშტაბირება მასშტაბირდება effectiveRemainingPercent()-ის მეშვეობით, რათა დაცული რეზერვი გამოჩნდეს როგორც 0% დარჩა არ გამოიყენება (დაუმუშავებელი snapshot-ის მნიშვნელობები, როგორც პროვაიდერმა წარმოადგინა)
ზღვრული მონაცემები გათვალისწინებულია ნაჩვენებ პროცენტში ინახება quotaWindowThresholds-ში თითოეული კავშირისთვის (ან გამოიყენება სერვერის ნაგულისხმევი მნიშვნელობები)
ძირითადი მომხმარებელი ინტერაქციული CLI-ები, ტერმინალის მოთხოვნები, ოპერატორები პროგრამული ინტეგრაციები, dashboard-ები, ანალიტიკა, ბილინგის ტრეკერები

ზღვრის კორექტირების ფორმულა

OmniRoute მხარს უჭერს კვოტის პროაქტიულ შეზღუდვებს upstream-რესურსის ამოწურვის თავიდან ასაცილებლად (კონფიგურირდება კავშირის quotaWindowThresholds-ის, პროვაიდერის ნაგულისხმევი მნიშვნელობების ან მდგრადობის გლობალური პარამეტრების მეშვეობით). როდესაც კვოტის ფანჯარაზე აქტიურია ზღვრული მნიშვნელობა (მაგ., cutoff = 25%), ტექსტის renderer დარჩენილ რესურსს შემდეგნაირად ითვლის:

  • თუ remaining <= cutoff: აბრუნებს 0%-ს.
  • თუ remaining > cutoff: აბრუნებს ((remaining - cutoff) / (100 - cutoff)) * 100-ს.

დაფორმატებული ტექსტური გამომავალი მნიშვნელობას უახლოეს მთელ რიცხვამდე ამრგვალებს (Math.round(...)).

საილუსტრაციო მაგალითი

განვიხილოთ პროვაიდერის ფანჯარა 60% დაუმუშავებელი გამოყენებით (შესაბამისად, 40% დაუმუშავებელი დარჩენილი კვოტით) და კონფიგურირებული დარჩენილი კვოტის 25%-იანი ზღვრული მნიშვნელობით:

წარმოდგენა გამოთვლა დარჩენილი ნაგულისხმევი გამოყენებული ნაწილი
დაუმუშავებელი JSON (?format=json) Upstream snapshot (quotas[window]) 40% 60%
ტექსტური ფორმატი (NN% დარჩა) ((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100 20% 80% (თუ გამოითვლება როგორც 100 - remaining)
  • რატომ აჩვენებს ტექსტი, რომ 20% დარჩა: ანგარიშზე ფიზიკურად დარჩენილი 40%-იანი კვოტიდან 25% დაცულია ზღვრული პოლიტიკით. გამომძახებელს მხოლოდ 15% აქვს დარჩენილი 75%-იანი გამოსაყენებელი მარაგიდან, სანამ router ამ კავშირზე მარშრუტიზაციას შეწყვეტს. მასშტაბირება უზრუნველყოფს, რომ კავშირმა ამოწურვის შესახებ (0% დარჩა) ზუსტად მაშინ მიანიშნოს, როდესაც მარშრუტიზაცია შეწყდება.
  • რატომ ინარჩუნებს JSON დაუმუშავებელ მნიშვნელობებს: JSON payload აბრუნებს პროვაიდერის ზუსტ snapshot-ს (UsageSnapshot), რათა გარე ხელსაწყოებს ჰქონდეთ წვდომა upstream-ის რეალურ გამოყენებასა და კავშირის დონის quotaWindowThresholds-ზე სერვერის მხრიდან დანაკარგიანი მასშტაბირების გარეშე.

მომხმარებლების მიგრაციის სახელმძღვანელო

თუ გარე ინტეგრაცია (მაგალითად, რედაქტორის plugin ან აგენტის extension) ადრე ტექსტური endpoint-იდან (NN% დარჩა) აგროვებდა მონაცემებს და გამოყენებულ პროცენტს 100 - NN-ის სახით ითვლიდა, ?format=json-ზე მიგრაცია ნიშნავს:

  • დაუმუშავებელი JSON მნიშვნელობების წაკითხვა ასახავს რეალურ upstream-მოხმარებას (ზემოთ მოცემულ მაგალითში გამოყენებულია 60%).
  • თუ ინტეგრაციას სურს შეინარჩუნოს ტექსტური endpoint-ის გამოსაყენებელი რესურსის სემანტიკა, შეუძლია ეფექტურად დარჩენილი რესურსის ფორმულა კლიენტის მხარეს გამოთვალოს, კავშირის დონის გადაფარვებისთვის quotaWindowThresholds-ის გამოყენებით.

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

# ქეშის სტატისტიკის მიღება
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/POST შესვლის სტატუსი (GET, საჯარო). POST აყენებს პაროლს / რთავს ან თიშავს შესვლას: პაროლის არსებობის შემდეგ მხოლოდ ოპერატორისთვისაა ხელმისაწვდომი (დაფის სესია, ლოკალური CLI ან გამორთული შესვლა — API გასაღებები და oma_ ტოკენები იღებენ 403-ს); პაროლის შესაცვლელად დაფის სესია აგზავნის currentPassword-ს

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

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

სინქრონიზებული/იმპორტირებული მოდელებისთვის PUT /api/provider-models იღებს provider, modelId და maxOutputTokenOverride მნიშვნელობებს: დადებითი მთელი რიცხვი ადგენს გამომავალი ტოკენების ხელით განსაზღვრულ ზღვარს, ხოლო null ასუფთავებს მას ნაგულისხმევი მნიშვნელობის აღსადგენად. GET /api/provider-models?provider=<provider> ამ მნიშვნელობებს აბრუნებს modelOutputOverrides-ში, მათ შორის იმ მოდელებისთვისაც, რომლებსაც მორგებული მოდელის მწკრივი არ აქვთ. ჩანაცვლება იყენებს შესრულების დროის max_output_tokens შესაძლებლობას და მოდელის ხელახალი სინქრონიზაციის შემდეგაც ნარჩუნდება. OpenAI-თან თავსებადი პროვაიდერის გვერდი გვთავაზობს რედაქტირების/გასუფთავების იმავე მართვის საშუალებებს და მონიშნავს მოდელებს, რომლებსაც გამოსახულებების მხარდაჭერა ცალსახად აქვთ მითითებული.

მორგებული Chat Completions კვანძები მსჯელობის ცალსახა გამორთვას ზემდგომ ბექენდს არგებენ. კავშირის წარმატებული შემოწმება ავტომატურად ირჩევს ჩატის შაბლონის მართვის საშუალებებს თითოეული ზუსტი მოდელის ID-სთვის, რომლის /models ჩანაწერიც ადასტურებს ამოცნობილ owned_by მნიშვნელობას: vllm, sglang ან llamacpp. გამჭვირვალე, OpenAI-თან თავსებადმა შუამავლებმა შესაძლოა მოდელის თავდაპირველი ჩანაწერი ჩადგმულ openai ობიექტში შეინარჩუნონ; აღმოჩენა მაქსიმუმ სამ ასეთ გარსს მიჰყვება. მოდელები, რომელთა მფლობელობაც არ არის მითითებული, უცნობია ან ურთიერთგამომრიცხავია, ინარჩუნებენ OpenAI-ის ჩვეულებრივ ქცევას. აღმოჩენის პროცესი ხელახლა იყენებს კატალოგის არსებულ მოთხოვნას, არ წარმოქმნის დასრულების ტოკენებს და კავშირის საბოლოო წერტილის შეცვლისას უქმდება.

იმ ბექენდისთვის ქცევის დასაფიქსირებლად, რომელიც ამ მეტამონაცემებს არ ასაჯაროებს, გამოიყენეთ პროვაიდერის განახლების არსებული ნაწილობრივი API:

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

გაგზავნეთ ეს სხეული მოთხოვნით PUT /api/providers/<connection-id>. ამ კავშირზე მსჯელობის ძალისხმევის ცხადად მითითებული მნიშვნელობა none იგზავნება როგორც chat_template_kwargs.thinking=false და chat_template_kwargs.enable_thinking=false. ნატიური შაბლონის ცხადად მითითებული მნიშვნელობები პრიორიტეტული რჩება, თუ სერვერის მხარეს არსებული მსჯელობის წესი ძალისხმევის დონეს იძულებით არ განსაზღვრავს. ეს პარამეტრი მოქმედებს მხოლოდ მაშინ, როდესაც მორგებული OpenAI-თან თავსებადი კავშირი Chat Completions-ის სხეულს აგზავნის; Responses-ის მოთხოვნები და ჩვეულებრივი პროვაიდერები მოთხოვნის ნატიურ ფორმას ინარჩუნებენ. ჩვეულებრივი OpenAI-ის reasoning_effort-ის უცვლელად გადასაცემად reasoningControl-ს მიანიჭეთ openai, ხოლო ავტომატური გამოვლენის გამოსაყენებლად გამოტოვეთ ან მიანიჭეთ null.

Claude Code-ის ავტომატური რეჟიმის კლასიფიკატორის მოთხოვნებში ნატიური აზროვნება ნაგულისხმევად გამორთულია, როდესაც ისინი მსჯელობის ცხადად მითითებულ კონტროლის პარამეტრებს არ შეიცავს. გამოვლენა იყენებს კლასიფიკატორის სისტემურ მარკერს Claude-ის ფორმატის მოთხოვნებში და არა მოდელის სახელებს ან დასრულების ლიმიტებს. სხეულში ცხადად მითითებული კონტროლის პარამეტრები, მხარდაჭერილი ძალისხმევის/აზროვნების სათაურები, მარშრუტიზაციის წესები და მოდელისთვის განსაზღვრული ძალისხმევა არსებულ პრიორიტეტს ინარჩუნებს. კლასიფიკატორის ორივე ეტაპი ინარჩუნებს საკუთარ მოთხოვნებს, დასრულების ლიმიტებს, გაჩერების მიმდევრობებსა და ზედა დონის სერვერის რეალურ ნებართვის ვერდიქტებს; მეორე ეტაპს კვლავ შეუძლია მოთხოვნილი ხილული მსჯელობის ჩვეულებრივ ტექსტად გენერირება.

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 გასაღების ნებართვები

PATCH /api/keys/{id} განაახლებს არსებული გასაღების ნებართვებს. ისევე, როგორც ყველა /api/keys* მარშრუტს, მასაც სჭირდება მართვის ავტორიზაცია (იხილეთ მართვის ავთენტიფიკაცია) და არა ინფერენციის გასაღები. გაგზავნეთ მხოლოდ ის ველები, რომელთა შეცვლაც გსურთ; მოთხოვნა, რომელიც არცერთ მათგანს არ შეიცავს, უარყოფილი იქნება შეტყობინებით No valid fields to update. მიღებული ველები განსაზღვრულია updateKeyPermissionsSchema-ით ფაილში src/shared/validation/schemas/keys.ts.

ველი ტიპი შენიშვნები
name სტრიქონი, 1-200 სიმბოლო
isActive ლოგიკური მნიშვნელობა
isBanned ლოგიკური მნიშვნელობა
expiresAt ISO 8601 თარიღი და დრო ან null null აუქმებს ვადის გასვლის თარიღს
modelAccessMode all | restricted როდესაც რეჟიმია all, allowedModels ცარიელი უნდა იყოს
allowedModels, blockedModels სტრიქონების მასივი, მაქსიმუმ 1000
allowedCombos სტრიქონების მასივი, მაქსიმუმ 500 განსაზღვრავს, რომელი კომბინაციების გამოძახება შეუძლია გასაღებს; პირდაპირი მოდელები იმართება modelAccessMode / allowedModels-ით
connectionAccessMode all | restricted restricted-ის შემთხვევაში allowedConnections არ უნდა იყოს ცარიელი, ხოლო all-ის შემთხვევაში ცარიელი უნდა იყოს
allowedConnections UUID-ების მასივი, მაქსიმუმ 100
allowAutoCombos ლოგიკური მნიშვნელობა false უარყოფს ამ გასაღებით auto/* მოდელების მოთხოვნებს; გასაღებებისთვის, რომლებშიც ეს არასდროს დაყენებულა, მოთხოვნები დაშვებულია
catalogScope all | combos | models რას ჩამოთვლის GET /v1/models ამ გასაღებისთვის (მხოლოდ კომბინაციებს, მხოლოდ მოდელებს ან ორივეს); ეს არ ცვლის, რისი გამოძახება შეუძლია გასაღებს
forcedModel სტრიქონი, მაქსიმუმ 300 სიმბოლო, ან null ჩატის მოთხოვნებს მიმართავს ამ მოდელზე/კომბინაციაზე, X-Route-Model-სა და body.model-ზე უპირატესობით; გასაღების შეზღუდვები კვლავ მოქმედებს
noLog, autoResolve ლოგიკური მნიშვნელობა
throttleDelayMs მთელი რიცხვი, 0-300000
maxSessions მთელი რიცხვი, 0-10000
rateLimits { limit, window }-ის მასივი (დადებითი მთელი რიცხვები, მაქსიმუმ 50) ან null null აუქმებს შეზღუდვებს
accessSchedule განრიგის ობიექტი ან null null აუქმებს განრიგს
scopes სტრიქონების მასივი, მაქსიმუმ 32
allowedEndpoints სტრიქონების მასივი, მაქსიმუმ 20
streamDefaultMode legacy | json
cacheDefaultMode legacy | bypass იხილეთ ქეშის გვერდის ავლა თითოეული გასაღებისთვის
compressionEnabled ლოგიკური მნიშვნელობა
codexServiceMode Codex-ის სერვისის ერთ-ერთი რეჟიმი
disableNonPublicModels boolean
allowUsageCommand boolean
usageLimitEnabled boolean
dailyUsageLimitUsd, weeklyUsageLimitUsd number >= 0 ან null
chaosModeEnabled boolean
curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \
  -H "Authorization: Bearer <management-credential>" \
  -H "Content-Type: application/json" \
  -d '{ "allowAutoCombos": false, "catalogScope": "combos" }'

პარამეტრები

Endpoint Method აღწერა
/api/settings GET/PUT/PATCH ზოგადი პარამეტრები. უსაფრთხოების პოლიტიკის გასაღებებს (requireLogin, newPassword, oidc*, corsOrigins, bruteForceProtection) სჭირდება currentPassword და ოპერატორის ავტორიზაციის მონაცემი — API გასაღებები და oma_ ტოკენები მიიღებენ 403-ს; ყველა ცვლილებისთვის საჭიროა წვდომის ტოკენის admin ფარგლები
/api/settings/proxy GET/PUT ქსელური პროქსის კონფიგურაცია
/api/settings/proxy/test POST პროქსის კავშირის შემოწმება
/api/settings/ip-filter GET/PUT IP მისამართების ნებადართული/დაბლოკილი სია
/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 მოთხოვნების ჟურნალის მწკრივებისა და ლოკალური გამოძახებების ჟურნალის არტეფაქტების გასუფთავება

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

საბოლოო წერტილი მეთოდი აღწერა
/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 შეკუმშვის ანალიტიკის ფსევდონიმი

მონიტორინგი

საბოლოო წერტილი მეთოდი აღწერა
/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-ს

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

საბოლოო წერტილი მეთოდი აღწერა
/api/db-backups GET ხელმისაწვდომი სარეზერვო ასლების სიის მიღება
/api/db-backups PUT მექანიკური სარეზერვო ასლის შექმნა
/api/db-backups POST კონკრეტული სარეზერვო ასლიდან აღდგენა
/api/db-backups PATCH სარეზერვო ასლების შენახვის პარამეტრების შენახვა (მხოლოდ ოპერატორისთვის)
/api/db-backups DELETE შენახული სარეზერვო ასლების შემცირება შენახვის პარამეტრების შესაბამისად (მხოლოდ ოპერატორისთვის)
/api/db-backups/export GET მონაცემთა ბაზის .sqlite ფაილად ჩამოტვირთვა
/api/db-backups/import POST მონაცემთა ბაზის ჩასანაცვლებლად .sqlite ფაილის ატვირთვა (?dryRun=true მხოლოდ ვალიდაციას ახდენს)
/api/db-backups/exportAll GET სრული სარეზერვო ასლის .tar.gz არქივად ჩამოტვირთვა

/api/db-backups/export, /api/db-backups/exportAll და /api/settings/export-json გასცემს ყველა შენახულ ავტორიზაციის მონაცემს, ამიტომ მათთვის საჭიროა დაფის სესია ან ლოკალური CLI (ან გამორთული ავთენტიფიკაცია). ნებისმიერი მოქმედების არეალის API გასაღებები და oma_ წვდომის ტოკენები იღებს 403-ს. აღდგენებზეც იგივე შეზღუდვა ვრცელდება: POST /api/db-backups/import (dryRun=true-ის ჩათვლით), POST /api/db-backups (id-ით აღდგენა) და POST /api/settings/import-json ცვლის მოქმედ მონაცემთა ბაზას ან პარამეტრებს, ამიტომ მანქანური ავტორიზაციის მონაცემებიც იქ 403-ს იღებს; omniroute sync import აგზავნის ლოკალური CLI-ის ავტორიზაციის მონაცემს. იგივე ეხება DELETE /api/db-backups-ს (შენახული სარეზერვო ასლების შემცირება) და PATCH /api/db-backups-ს (შენახვის პარამეტრები: შენახული მნიშვნელობები განსაზღვრავს ავტომატურ შემცირებას ყოველი სარეზერვო ასლის შექმნის შემდეგ). სიის მიღება (GET) და მექანიკური სარეზერვო ასლის შექმნა (PUT) კვლავ ჩვეულებრივ მართვის ავთენტიფიკაციას იყენებს.

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

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

გვირაბები

საბოლოო წერტილი მეთოდი აღწერა
/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 ინსტრუმენტები

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

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

ACP აგენტები

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

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

მდგრადობა და სიხშირის შეზღუდვები

საბოლოო წერტილი მეთოდი აღწერა
/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). პროვაიდერის ამომრთველის, კავშირის დაყოვნებისა და მოდელის ბლოკირების სრული მიმოხილვისთვის იხილეთ მდგრადობა (გაფართოებული).

შეფასებები

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

პოლიტიკები

საბოლოო წერტილი მეთოდი აღწერა
/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-ები

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

შენიშვნა: ეს endpoint-ები გამოიყენება სისტემის შიგნით ან 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"
}

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

GET /api/system/version

მხოლოდ loopback-ით ხელმისაწვდომი მართვის მარშრუტი (ადმინისტრატორის ავტორიზაციით). აბრუნებს გაშვებულ ვერსიას, უახლეს გამოქვეყნებულ ვერსიასა და ავტომატური განახლების სტატუსს. releaseChannel და channels დამატებითი ველებია (3.8.54 ხაზიდან); channel ინარჩუნებს თავის მნიშვნელობას — განთავსების რეჟიმს, რომელსაც მართვის პანელის განახლების მექანიზმი იყენებს (npm, source ან docker-compose).

{
  "current": "3.8.52",
  "latest": "3.8.52",
  "updateAvailable": false,
  "channel": "npm",
  "autoUpdateSupported": true,
  "autoUpdateError": null,
  "news": null,
  "releaseChannel": "latest",
  "channels": { "latest": "3.8.52", "next": "3.8.53-rc.1" }
}
  • releaseChannel — გაშვებული build-ის npm არხი: nightly — -nightly.* ვერსიებისთვის, next — სხვა წინასწარი გამოშვებებისთვის (-rc.*, -beta.*, -alpha.*), lts — იმ ძველი ძირითადი ვერსიის სტაბილური ვერსიისთვის, რომელიც channels.latest-ზე ძველია, სხვა შემთხვევაში — latest. იგივე წესებია, რაც scripts/release/dist-tag.mjs-ში, რომელიც გამოქვეყნებისას npm dist-tag-ს ირჩევს.
  • channels — თითოეული dist-tag-ის უახლესი გამოქვეყნებული ვერსია, მიღებული npm view omniroute dist-tags-იდან (registry-ის HTTP სარეზერვო ვარიანტით), რომელიც latest-ის მსგავსად 10-წუთიანი TTL-ით კეშირდება. latest ყოველთვის არსებობს (სარეზერვოდ იყენებს latest ველს, შემდეგ კი "unavailable"-ს); next, nightly და lts გამოჩნდება მხოლოდ მაშინ, როდესაც შესაბამისი dist-tag არსებობს. Cache-Control: no-cache მოთხოვნა ორივე მოძიებას განაახლებს.

არხების მოდელი (latest = v3 4.0 GA-მდე, next = rc, nightly = develop build-ები, lts = v3-ის პატჩები 4.0 GA-ის შემდეგ) აღწერილია docs/ops/RELEASE_STRATEGY.md-ში.


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

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 "[email protected]" \
  -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-ს)

ავთენტიფიკაცია: მართვის სესია/API გასაღები (requireManagementAuth) — იგივე დამცავი მექანიზმი, რაც /api/keys-ისთვის: მართვის პანელის სესია, ლოკალური CLI ტოკენი ან API გასაღები manage/admin წვდომის ფარგლებით; მხოლოდ ინფერენციისთვის განკუთვნილი API გასაღებები იღებენ 403-ს. აგრეთვე იხილეთ /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 გასაღებს და თითოეული კავშირის შენიღბულ გასაღებსა და projectId-ს მხოლოდ manage / admin მოქმედების არეალის მქონე გასაღებისთვის აბრუნებს; დანარჩენი /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, commandCode, devin-cli და სხვ.). სრული სიისთვის იხილეთ პროვაიდერების ცნობარი.

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

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


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

მართეთ 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-ებისთვის მართვის ავთენტიფიკაციის მოთხოვნა).