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

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

134 KiB
Raw Blame History

API Reference (עברית)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 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

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

מסמך העזר המרכזי עבור OmniRoute API. הוא מכסה את הממשק הציבורי /v1 ואת נקודות הקצה הנפוצות ביותר לניהול; הקובץ הניתן לקריאה על ידי מכונה docs/openapi.yaml ועץ הנתיבים תחת src/app/api/ הם המקורות המקיפים.

תוכן עניינים

השלמות צ׳אט

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 כדי לדלג על הזרקת זיכרון ומיומנויות עבור בקשה זו (מקביל להתנהגות ללא מטמון; מונע את תקורת האסימונים/העלות לכל קריאה)
X-OmniRoute-Progress בקשה הגדירו כ-true לקבלת אירועי התקדמות
X-Session-Id בקשה מפתח הפעלה דביקה לצורך שיוך חיצוני של הפעלות
x_session_id בקשה מתקבלת גם גרסה עם קו תחתון (HTTP ישיר)
X-OmniRoute-Session-Id בקשה תג הפעלה/שיחה שסופק על ידי הקורא (ומוזן גם לזיכרון). כאשר הוא קיים, הוא נשמר כלשונו ב-call_logs.session_tag לצורך שיוך עלויות לפי הפעלה (#8249) — ולעולם אינו נוצר כאשר הוא חסר
Idempotency-Key בקשה מפתח למניעת כפילויות (חלון של 5 שניות)
X-Request-Id בקשה מפתח חלופי למניעת כפילויות
X-OmniRoute-Cache תגובה HIT או MISS (ללא הזרמה)
X-OmniRoute-Idempotent תגובה true אם בוצע ניכוי כפילויות
X-OmniRoute-Progress תגובה enabled אם מעקב ההתקדמות מופעל
X-OmniRoute-Session-Id תגובה מזהה ההפעלה בפועל שבו OmniRoute משתמש
X-OmniRoute-Request-Id תגובה מזהה מתאם של הבקשה (כאשר הוא ידוע)
X-OmniRoute-Version תגובה גרסת הבנייה של OmniRoute (קיימת תמיד)
X-OmniRoute-Cost-Saved תגובה הסכום בדולר ארה״ב שנחסך באמצעות המטמון בעת HIT (פגיעות מטמון בלבד)
X-OmniRoute-Decision תגובה עקבת ניתוב: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> היא אסטרטגיית השילוב, או single עבור בקשה שאינה שילוב) — קיימת תמיד בתגובות השלמה

הערה לגבי Nginx: אם אתם מסתמכים על כותרות הכוללות קווים תחתונים (לדוגמה x_session_id), הפעילו את underscores_in_headers on;.

כותרות טלמטריית עלויות: תגובות הצלחה שאינן מוזרמות כוללות גם את ערכת טלמטריית העלויות X-OmniRoute-* —‏ X-OmniRoute-Response-Cost (בדולר ארה״ב, עם 10 ספרות קבועות אחרי הנקודה העשרונית; 0.0000000000 עבור שימוש חינמי או ללא תמחור), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit ו-X-OmniRoute-Fallback-Attempts (רק כאשר > 0), וכן X-OmniRoute-Request-Id ו-X-OmniRoute-Version. כותרות אלה נשלחות בהשלמות צ׳אט, ב-/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 (המשך פעולה במקרה של כשל).

סמנטיקת העלות בפגיעה במטמון: בפגיעה במטמון הסמנטי (X-OmniRoute-Cache-Hit: true) לא מתבצעת קריאה לספק במעלה הזרם, ולכן X-OmniRoute-Response-Cost הוא 0.0000000000 (העלות השולית של אספקת התוצאה מהמטמון). העלות המקורית, או העלות שהייתה צפויה, מדווחת בנפרד ב-X-OmniRoute-Cost-Saved. צרכני נתוני חיוב צריכים לסכם את X-OmniRoute-Response-Cost (פגיעות במטמון אינן כרוכות בעלות); מערכות ניתוח נתוני מטמון יכולות לצבור את X-OmniRoute-Cost-Saved.

חכירות בלעדיות של הפעלות מנוהלות

חכירה בלעדית של הפעלות מנוהלות היא חוזה ניתוב אופציונלי שאינו תלוי בלקוח: בעלים פעיל יחיד מחזיק חיבור OmniRoute כשיר אחד. היא אינה מחכירה מודל, אינה דורשת OAuth, אינה מזהה לקוח מסוים ואינה דורשת ספק מסוים.

מפתח ה-API המאמת חייב להיות בעל ההרשאה lease:exclusive ורשימת allowedConnections מפורשת שאינה ריקה. גבול השינוי של מסד הנתונים אוכף את שני השדות יחד בעת יצירת מפתח ובעדכונים חלקיים.

POST /api/v1/session-leases
Authorization: Bearer <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>

{"action":"acquire","model":"glm/glm-4.6"}

תגובות מוצלחות לרכישה, לחידוש ולשחרור חושפות חותמות זמן, state ואת ערך generation החיובי המדויק, אך לעולם לא את החיבור או פרטי האימות שנבחרו. חידוש ושחרור מספקים את הדור בגוף ה-JSON:

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

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

בעלים של חכירה פעילה יכול לבקש במפורש מטא-נתוני תצוגה שומרי פרטיות עבור השיוך הנוכחי שלו:

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

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

פעולת מצב אופציונלית זו מגודרת באמצעות הבעלים האטום, מפתח ה-API המנוהל המאומת והדור הפעיל המדויק, בטרנזקציה יחידה של מסד הנתונים. displayName הוא רק שם החיבור המוגדר לאחר הסרת רווחים מיותרים; ערכו הוא null כאשר לא קיים שם מוגדר ובטוח. OmniRoute לעולם אינו מחליף אותו בכתובת דוא"ל או בזהות חשבון שנוצרה. ערך הספק הוא תווית תצוגה שאינה רגישה ולעולם אינו מזהה שנוצר עבור ספק תואם. פרטי אימות, אסימונים, קובצי Cookie, מזהים גולמיים של חיבורים או של מפתחות API, גיבובי בעלים, סודות גידור ונתוני ניתוב פנימיים אינם נכללים.

חיפושים עם מפתח שגוי, בעלים שגוי, דור מיושן, חכירה חסרה, שפג תוקפה, ששוחררה או שבוטלה, מחזירים כולם את אותה שגיאת 409 LEASE_FENCE_STALE ללא מטא-נתוני חיבור. ללקוח שקיבל את תגובת ההמתנה לקיבולת אין שיוך פעיל שאפשר לבדוק. כאשר הניתוב מעביר חכירה פעילה, אותו דור נשאר תקף ופעולת המצב מחזירה באופן אטומי את השיוך החדש, ולעולם לא את הישן. לקוחות קיימים נותרים ללא שינוי, משום שתגובות הרכישה, החידוש, השחרור וההמתנה שומרות על המבנים הקודמים שלהן.

חוזה שרת זה אינו משנה את /status המובנה של OpenAI Codex. נכון לעכשיו, Codex המובנה מדווח על ספק המודל שלו ועל מצב האימות/החשבון המובנה, אך אינו מציג מטא-נתוני חשבון שרירותיים של ספק מותאם אישית; שילוב עתידי בצד הלקוח חייב לקרוא לפעולה זו ולהחליט כיצד להציג את connection.displayName.

לאחר מכן, כל בקשת הסקה מנוהלת מספקת את שתי כותרות הבקרה:

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

הבעלים המדויק, הדור, החיבור הפעיל ומפתח ה-API המאומת מגודרים מיד לפני כל ניסיון נתמך מול השירות במעלה הזרם. הפעלה חוזרת של הבעלים והדור עם מפתח אחר נכשלת גם כאשר מפתח זה מתיר את אותו חיבור. בעלים גולמיים אינם נשמרים, אינם נרשמים ביומן, אינם נשמרים בתמונת המצב של הבקשה ואינם מועברים במעלה הזרם.

התנגשות זמנית מחזירה HTTP 429 עם Retry-After ועם:

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

משמעות תגובה זו היא רק שקבוצת החיבורים הכשירים הרגילה לא הייתה ריקה ושכל מועמד פנוי הוחזק בידי חכירה פעילה זרה. מודלים/ספקים שאינם נתמכים, אי-התאמה למדיניות, תקופת צינון, מכסה, תקינות וכשלי כשירות רגילים אחרים ממשיכים להחזיר את תגובות OmniRoute הקיימות שלהם.

x-omniroute-compression

דריסה ברמת הבקשה של תוכנית הדחיסה. בעלת הקדימות הגבוהה ביותר — גוברת על דריסת שילוב הניתוב, הפרופיל הפעיל, ההפעלה האוטומטית וברירת המחדל של הלוח. ערכים:

ערך השפעה
off ללא דחיסה עבור בקשה זו.
default פרופיל ברירת המחדל הנגזר מהלוח (מתעלם מהפרופיל הפעיל).
engine:<id> מנוע יחיד כאשר הוא מופעל, לדוגמה engine:rtk.
<combo> שילוב בעל שם, שמותאם תחילה לפי שם (ללא תלות ברישיות) ולאחר מכן לפי מזהה.

הערות:

  • המערכת מתעלמת מערכים לא מוכרים (הבקשה לעולם אינה נדחית); הפתרון ממשיך לפי סדר הקדימות הרגיל של האופרטורים.
  • אם מספר שילובים חולקים שם, העבירו את ה-id של השילוב כדי לקבל התאמה דטרמיניסטית.
  • לא ניתן לבחור לפי שם שילוב ששמו 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 משתמשות תחילה בפרטי הגישה 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) מקבל גם מסמכי EmbeddingsV5Request המקוריים של Jina ומעביר אותם ללא שינוי אל 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 } מקוריים יכולים להיות כתובת URL ציבורית מסוג HTTPS, כתובת URI מסוג data:, או base64 גולמי. OmniRoute אינו ממיר אובייקטים אלה למחרוזות ואינו מוריד כתובות URL מקוריות של תמונות — Jina מאחזרת את המדיה הציבורית בעצמה. שדות Jina נוספים (task,‏ normalized,‏ truncate,‏ embedding_type) מועברים הלאה. מק"טים של Jina המיועדים לטקסט בלבד עדיין דוחים מסמכים שאינם טקסטואליים.

מגבלות אבטחה ותעבורה:

  • כתובות URL מרוחקות של מדיה חייבות להיות ציבוריות ולהשתמש ב-HTTPS. פריטים קנוניים מסוג {type,source:url} מורדים בצד השרת (אימות מחדש של הפניות, זמן קצוב, מגבלות גודל, DNS ציבורי וקיבוע חיבור) ומשובצים לפני הקריאה לספק. פריטי {image:"https://..."} מקוריים של Jina מועברים כפי שהם לאחר אותה בדיקת HTTPS ציבורי; Jina מורידה את התוכן מכתובת ה-URL.
  • מדיית base64 משובצת מוגבלת ל-8 MiB לאחר פענוח לכל פריט ול-16 MiB לאחר פענוח בכל הבקשה.

תרגום לספק (פריטים קנוניים לעולם אינם מועברים ללא שינוי):

  • מודלים מולטימודליים של Jina: כל פריט ברמה העליונה הופך לאובייקט אחד בעל מפתח לפי אופן הייצוג (text / image / audio / video / pdf), תוך שימוש בכתובות URI מסוג data עבור מדיה משובצת; וקטור אחד לכל פריט ברמה העליונה.
  • משפחת Gemini Embedding 2: מערך אחד ברמה העליונה הופך לבקשת models/{model}:embedContent מקורית יחידה עם content.parts (text או inline_data).
  • מודלים לא ידועים/דינמיים ללא מטא-נתונים מפורשים של אופני ייצוג דוחים קלט מובנה עם HTTP 400.
{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}

שילובים שאינם נתמכים של מודל ואופן ייצוג מחזירים HTTP 400 במקום לכפות המרה של הפריט. שדות הרחבה שאינם שדות קלט בבקשות מחרוזת/אסימון מדור קודם ממשיכים לעבור ללא שינוי.

# הצגת כל מודלי ההטמעה
GET /v1/embeddings

יצירת תמונות

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

{
  "model": "openai/gpt-image-2",
  "prompt": "שקיעה יפהפייה מעל הרים",
  "size": "1024x1024"
}

ספקים זמינים: OpenAI (GPT Image 2),‏ xAI (Grok Image),‏ Together AI (FLUX),‏ Fireworks AI,‏ Nebius (FLUX),‏ Hyperbolic,‏ NanoBanana,‏ OpenRouter,‏ SD WebUI (מקומי),‏ ComfyUI (מקומי).

# הצגת כל מודלי התמונות
GET /v1/images/generations

OCR למסמכים

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

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

model בוחר את ספק ה-OCR באמצעות קידומת provider/model; מזהה מודל ללא קידומת (למשל mistral-ocr-latest) משויך לספק הרשום שלו, ואם model אינו מצוין, ברירת המחדל היא Mistral‏ (mistral-ocr-latest). ספקים רשומים (open-sse/config/ocrRegistry.ts):

מזהה ספק מזהה מודל ערך 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 סינכרוני, דרך נקודת הקצה השותפה openapi/chat/completions של Vertex AI — לפרטי אימות/URL ראו להלן.

כל שלושת הספקים משיבים באותו גוף במבנה של Mistral:

{
  "pages": [{ "index": 0, "markdown": "# טקסט שחולץ..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}

תהליך התשאול של Azure Document Intelligence

ה-API מסוג analyze של Azure Document Intelligence הוא אסינכרוני: הבקשה הראשונית מחזירה כותרת Operation-Location במקום גוף, ויש לתשאל לקבלת התוצאה. המטפל (open-sse/handlers/ocr.ts) מתשאל כתובת URL זו מדי שנייה, עד 30 ניסיונות, נכשל מיד (ואינו ממשיך לתשאל) במקרה של תגובת תשאול שאינה ok או סטטוס "failed", ומחזיר 504 אם הפעולה עדיין מתבצעת לאחר שמכסת הניסיונות מוצתה. תגובת Azure הסופית מנורמלת לאותו מבנה pages/markdown המשמש את Mistral לפני שהיא מוחזרת למבצע הקריאה, כך שקוד הלקוח אינו צריך לטפל בספק כמקרה מיוחד.

אימות ופתרון נקודת קצה עבור Vertex AI DeepSeek OCR

vertex-deepseek-ocr עושה שימוש חוזר באותו אימות Vertex AI שבו OmniRoute כבר תומך עבור תעבורת צ'אט/תמונות (open-sse/executors/vertex.ts): מפתח ה-API של החיבור הוא אישור JSON של Service Account (המומר לאסימון גישה קצר-מועד מסוג OAuth באמצעות תהליך JWT-bearer) או אסימון גישה מסוג OAuth שכבר הופק ונעשה בו שימוש כפי שהוא. כתובת ה-URL של נקודת הקצה בשירות החיצוני היא נקודת הקצה הכללית לשותפים openapi/chat/completions של Vertex, הנבנית מהפרויקט ומהאזור של החיבור — ערך מפורש של providerSpecificData.project/providerSpecificData.region תמיד גובר; אחרת, הפרויקט נגזר מהשדה project_id ב-JSON של ה-Service Account, וברירת המחדל של האזור היא 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

→ מחזיר את כל מודלי הצ'אט, ההטמעות והתמונות וכן שילובים, בפורמט OpenAI

קידומות מזהי מודלים (?prefix=)

רוב המודלים מוצגים תחת קידומת ספק. הקידומת שתקבלו נקבעת על ידי דגל התכונה MODELS_CATALOG_PREFIX_MODE, וניתן לעקוף אותה לכל בקשה בנפרד באמצעות פרמטר שאילתה — שימושי עבור לקוח שמעוניין ברשימה נקייה מבלי לשנות את ההגדרה הכללית בשרת עבור כל שאר המשתמשים:

GET /v1/models?prefix=alias        # מזהה אחד לכל מודל — קידומת הכינוי הקצרה
GET /v1/models?prefix=dual         # שתי הצורות (ברירת המחדל של השרת)
GET /v1/models?prefix=canonical    # רק קידומת מזהה הספק המלאה
מצב פלט הערות
dual cc/claude-sonnet-4-6 וגם claude/claude-sonnet-4-6 ברירת המחדל. שני המזהים מנותבים לאותו מודל; האפשרות נשמרה כדי שתצורות לקוח שבהן אחת מהצורות הוגדרה באופן קשיח ימשיכו לפעול. מגדיל בקירוב פי שניים את הקטלוג.
alias cc/claude-sonnet-4-6 רשומה אחת לכל מודל. ספקים ללא כינוי נפרד עדיין מפיקים את הרשומה שלהם, כך שדבר אינו הולך לאיבוד.
canonical claude/claude-sonnet-4-6 רשומה אחת לכל מודל תחת קידומת מזהה הספק המלאה. ספקים ללא כינוי נפרד (למשל antigravity/…, agy/…) מפיקים גם כאן את המזהה היחיד שלהם, כך שדבר אינו הולך לאיבוד.

ניתן לזהות שיקוף במצב dual גם ללא פרמטר השאילתה: הוא מכיל שדה parent המצביע על המזהה הראשי.

לקוחות המציגים בורר מודלים צריכים לבקש ?prefix=alias — זה מה שעושה תוסף OmniCopilot עבור VS Code.

וריאנטים של מודלים ללא חשיבה

עבור מודלי Claude בעלי יכולת חשיבה, /v1/models מציג גם וריאנט ללא חשיבה, שהמזהה שלו מתחיל בקידומת claude-3-omniroute-no-thinking/:

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

בחירה במזהה זה (למשל בתצורת Claude Code שמצרפת תמיד בלוק thinking) מפנה בחזרה אל <provider>/<model> האמיתי כאשר ההסקה מושבתת — thinking:{type:"disabled"} בנתיב /v1/messages, או השמטת השדות reasoning/reasoning_effort בנתיב /v1/chat/completions. הווריאנט מופיע רק עבור מודלים ממשפחת Claude שתומכים בחשיבה וגם מכבדים את disabled (כך שלמשל מודלים אדפטיביים בלבד, שדוחים את disabled, אינם נכללים). מפעילים יכולים לאלץ את הפעלת הווריאנט או את השבתתו לכל מודל באמצעות ModelSpec.noThinkingAlias.

מניפסט תוסף ספק

GET /api/v1/provider-plugin-manifest

מחזיר את מניפסט תוספי הספקים הבטוח לשימוש ב-JSON, המשמש את Bifrost, את CLIProxyAPI ואת נתבי ה-sidecar העתידיים. התגובה נוצרת ממרשם הספקים של TypeScript ומשמיטה במכוון סודות לקוח של OAuth, פתרון סביבת זמן ריצה, פונקציות ביצוע, כותרות בקשה ונתוני חשבון.

השתמשו בנקודת קצה זו כאשר 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 (עריכה/השלמת תמונה)
POST /v1/videos/generations יצירת וידאו בסגנון OpenAI
POST /v1/music/generations יצירת מוזיקה בסגנון OpenAI
POST /v1/audio/transcriptions OpenAI Audio (דיבור לטקסט)
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/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 + גוף JSON שעבר אימות באמצעות Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema וכו'; ראו src/shared/validation/schemas.ts). במקרה של כשל באימות הסכימה מוחזר 4xx.

עבור לקוחות שאינם יכולים לצרף Authorization: Bearer ..., OmniRoute מקבל גם מפתחות API בכתובת ה-URL, באמצעות תאימות למחרוזת שאילתה (?token=..., ?apiKey=..., ?api_key=..., ?key=...) או באמצעות נקודות הקצה הייעודיות /api/v1/vscode/{token}/... המתועדות להלן.

# דירוג מחדש
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" }

# עריכת תמונה (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# יצירת וידאו / מוזיקה (מזהה מודל עם קידומת ספק)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

נתיבי ספק ייעודיים

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

קידומת הספק מתווספת אוטומטית אם היא חסרה. מודלים שאינם תואמים מחזירים 400.

API לקבצים

נקודת קצה תואמת OpenAI לקלט/פלט באצווה ולהעלאות קבצים לפי ייעוד.

שיטה נתיב תיאור
POST /v1/files העלאת קובץ (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — עד 512 MiB
GET /v1/files הצגת רשימת הקבצים עבור מפתח ה-API המאומת
GET /v1/files/[id] אחזור המטא-נתונים של קובץ
DELETE /v1/files/[id] מחיקת קובץ
GET /v1/files/[id]/content הזרמת גוף הקובץ הגולמי בחזרה

אימות: מפתח API מסוג Bearer — הקבצים מוגבלים לפי מפתח API באמצעות getApiKeyRequestScope. מפתח רואה, מוריד ומוחק רק את הקבצים שלו; סשן לוח בקרה ללא מפתח יכול לקרוא את המופע כולו; הגישה לקובץ ללא בעלים (העלאה אנונימית או מסשן לוח הבקרה) נדחית עבור כל פונה שאינו משתמש בסשן. GET /v1/files דוחה פונה אנונימי — וכן מפתח שסופק אך אינו מזוהה — עם 401, גם כאשר REQUIRE_API_KEY=false, במקום להציג את הקבצים של כל הדיירים (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

API לאצוות

עיבוד באצווה תואם OpenAI.

שיטה נתיב תיאור
POST /v1/batches יצירת אצווה — גוף הבקשה מאומת באמצעות v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET /v1/batches הצגת רשימת האצוות
GET /v1/batches/[id] אחזור מצב האצווה + request_counts
DELETE /v1/batches/[id] מחיקת אצווה שהסתיימה/נכשלה
POST /v1/batches/[id]/cancel ביטול אצווה הנמצאת בעיבוד

אימות: מפתח API מסוג Bearer. האצוות מוגבלות לפי מפתח 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 נתוני פגיעות/זמן השהיה/מטמון לפי ספק

אימות: מפתח API מסוג Bearer (extractApiKey + isValidApiKey). מדיניות החיפוש נאכפת באמצעות enforceApiKeyPolicy.

API לאחזור מהאינטרנט

חילוץ תוכן מכתובת URL באמצעות ספק אחזור מהאינטרנט מוגדר (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

שיטה נתיב תיאור
POST /v1/web/fetch אחזור/גירוד של כתובת URL — גוף הבקשה מאומת באמצעות v1WebFetchSchema

אימות: מפתח API מסוג Bearer (extractApiKey + isValidApiKey). המדיניות נאכפת באמצעות enforceApiKeyPolicy.

מעבר לספק חלופי בהתחשב במכסה (#8297): כאשר לא מצוין provider מפורש, עוברים במאגר (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) לפי סדר עדיפות קבוע (מילוי הראשון תחילה) — מדלגים על ספק מוגדר שהוגבל בקצב במקום להפסיק את הבקשה, וכשל במעלה הזרם שניתן לניסיון חוזר/קשור למכסה (HTTP 429 תמיד; 402/403 עבור מכסות בסגנון מסלול חינמי של Firecrawl/Tavily/TinyFish — לא עבור Jina Reader, ולעולם לא עבור בקשה שגויה רגילה מסוג 400) מוביל למעבר לספק הבא שטרם נוסה ושעבורו קיימים פרטי גישה, בזמן הבקשה. כאשר כל הספקים במאגר מוצו, נקודת הקצה מחזירה 429 יחיד (עם כותרת Retry-After) במקום ה-400 הכללי הקודם. כאשר מתבקש provider מפורש, אין מעבר שקט לספק חלופי — ספק מפורש שהוגבל בקצב או נכשל מחזיר את השגיאה שלו (429 אם הוגבל בקצב, אחרת קוד הסטטוס ממעלה הזרם).

הזרמה באמצעות WebSocket

GET /v1/ws?handshake=1

מאמת לחיצת יד לשדרוג WebSocket ומחזיר הודעות לדוגמה של פרוטוקול התקשורת (request, cancel). מסגרות WS בפועל מטופלות בידי שרת ה-WS המצורף, מחוץ לטבלת הנתיבים של Next.js.

אימות: מפתח API מסוג Bearer במהלך לחיצת היד.

Responses API דרך WebSocket (עבור codex בלבד)

# אותו host:port כמו API ה-HTTP (ברירת המחדל היא 20128); שדרגו את החיבור:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (או: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# המסגרת הראשונה חייבת להיות response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

פרוקסי של Responses-API-over-WebSocket מחובר באופן בלעדי ל-codex (קצה עורפי של ChatGPT). הוא מאזין באותה יציאה כמו ה-API/לוח הבקרה בנתיבים /v1/responses, /responses ו-/api/v1/responses. במסגרת response.create הראשונה הוא מבצע אימות + הכנה באמצעות הגשר הפנימי codex-responses-ws, בוחר חיבור OAuth של codex ויוצר מנהרה אל wss://chatgpt.com/backend-api/codex/responses באמצעות תעבורת wreq-js. מודלים שאינם 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.

אימות: מפתח API מסוג Bearer במהלך לחיצת היד. שרת ה-HTTP המצורף (server-ws.mjs) חייב להיות נקודת הכניסה הפעילה (וזו ברירת המחדל כאשר app/server-ws.mjs קיים).

מזהה מודל: השתמשו במזהה ChatGPT ללא קידומת (ללא קידומת codex/)

Codex CLI של OpenAI מאמת את שם המודל בצד הלקוח כאשר supports_websockets = true ודוחה מזהים עם קידומת ספק כגון codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). שלחו את המזהה ללא קידומת (למשל gpt-5.5). הגשר של OmniRoute מיועד ל-codex בלבד, ולכן הוא פותר מחדש מזהה ללא קידומת כמודל codex (resolveCodexWsModelInfo) לפני יצירת המנהרה למעלה הזרם — אף על פי שמזהה gpt-5.5 ללא קידומת היה מנותב אחרת לספק אחר דרך HTTP.

הגדרת OpenAI Codex CLI

הפנו את Codex CLI אל OmniRoute באמצעות הוספת ספק מותאם אישית עם תמיכה ב-WebSocket אל ~/.codex/config.toml (השתמשו ב-CODEX_HOME נפרד כדי להימנע משינוי הגדרה קיימת):

model = "gpt-5.5"                 # מזהה ללא קידומת — לא "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # ללא לוכסן סוגר; כתובת ה-WS נגזרת ממנו (השתמשו ב-https/wss בסביבת ייצור)
wire_api = "responses"                    # הערך היחיד הנתמך מאז פברואר 2026
supports_websockets = true                # מפעיל את תעבורת Responses-over-WS
env_key = "OMNIROUTE_API_KEY"             # מכיל את מפתח ה-API של OmniRoute ‏(Bearer)

export OMNIROUTE_API_KEY=sk-...           # מפתח API של OmniRoute (כל מפתח אם REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

ה-CLI משדרג את base_url + /responses ל-WebSocket, ו-OmniRoute יוצר מנהרה אל חיבור ה-OAuth הנבחר של codex. התהליך אומת מקצה לקצה מול השרת המקומי: ChatGPT מחזיר codex.rate_limits + response.created ומזרים את ההשלמה.

מכסות ודיווח על בעיות

שיטה נתיב תיאור
GET /v1/quotas/check אימות מראש של המכסה עבור provider + accountId לפני הנפקת מפתח רשום
POST /v1/issues/report דיווח על כשל במכסה/בהנפקת מפתח ל-GitHub (דורש GITHUB_ISSUES_REPO + אסימון)

אימות: מפתח API מסוג Bearer (isAuthenticated).

שימוש בשירות עצמי (/api/usage/om-usage)

כל מפתח API יכול לקרוא את נתוני השימוש והמכסות שלו עצמו — ללא אימות ניהולי. זוהי נקודת הקצה שבה משתמש לקוח (CLI, הלוח של OmniCopilot) כדי להציג לבעל המפתח את ההוצאות שלו.

# תצורת טקסט (החוזה ההיסטורי — טקסט פשוט עבור מסוף)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# תצורה מובנית — זו שצורך ממשק משתמש
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

במפתח חייבת להיות האפשרות allowUsageCommand מופעלת (כבויה כברירת מחדל — מנהל מפתחות ה-API בלוח הבקרה מפעיל או מכבה אותה עבור כל מפתח). בלעדיה נקודת הקצה מחזירה 403.

?format=json מחזיר מבנה מבחין, כך שהגורם הקורא לעולם אינו קורא שדה נתונים מתוך סירוב. במקרה של הצלחה:

{
  "allowed": true,
  // קיים רק כאשר המפתח הצטרף למגבלות שימוש לפי מפתח (בדולר ארה"ב, יומיות/שבועיות):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // תמונת מצב של מכסת הספק שנבחר, או null כאשר טרם נשמר דבר במטמון:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // תמונות המצב של כל החיבורים, כדי שממשק משתמש יוכל להציג כמה ספקים זה לצד זה:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

במקרה של סירוב (401 מפתח שגוי / 403 אין הרשאה), אותו נתיב מחזיר { "allowed": false, "error": { "message": "…" } } — personal/provider קיימים אך ריקים (המפתח מורשה, אך עדיין לא התקבל מידע) הם מצב שונה מסירוב, ורק תצורת ה-JSON מבחינה ביניהם.

אימות: מפתח ה-API מסוג Bearer של הגורם הקורא, מאומת באמצעות isValidApiKey — זהו לא ממשק הניהול (/api/keys/…), שנשאר מוגן באמצעות requireManagementAuth.

מטמון סמנטי

# קבלת נתונים סטטיסטיים של המטמון
GET /api/cache/stats

# ניקוי כל המטמונים
DELETE /api/cache/stats

דוגמת תגובה:

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

השפעה על זמן ההשהיה

פגיעה במטמון הסמנטי (HIT) מחזירה את התגובה מהמטמון **ללא קריאה לשירות במעלה הזרם **, ולכן הערך המדווח של X-OmniRoute-Response-Latency קרוב לאפס (ללא תלות בזמן ההשהיה המקורי במעלה הזרם). לקוחות הרגישים לזמן השהיה (מדידת ביצועים, ניטור p50/p99) צריכים לבדוק את כותרת התגובה X-OmniRoute-Cache-Latency:

ערך משמעות
synthetic התגובה הוחזרה מהמטמון; זמן ההשהיה אינו זמן אמיתי במעלה הזרם
(חסר) תגובה מקריאה אמיתית במעלה הזרם

עקיפת מטמון לפי מפתח

מפתחות API יכולים לבחור שלא לבצע קריאות מהמטמון הסמנטי באמצעות cacheDefaultMode:

ערך התנהגות
legacy התנהגות מטמון רגילה (ברירת מחדל)
bypass דילוג מלא על חיפוש במטמון; תמיד פנייה למעלה הזרם

ניתן להגדיר בעת יצירת מפתח (POST /api/keys) או בעדכון (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

עקיפה לפי בקשה

כל בקשה יכולה לעקוף את המטמון ללא תלות בהגדרות המפתח:

X-OmniRoute-No-Cache: true

לוח בקרה וניהול

נתיבי ניהול (/api/* למעט אימות/התחברות ציבוריים) אינם מורשים באמצעות מפתחות API רגילים להסקה. משפחות פרטי כניסה, היקפי הרשאה ודוגמאות curl: אימות לניהול.

אימות

נקודת קצה שיטה תיאור
/api/auth/login POST התחברות
/api/auth/logout POST התנתקות
/api/settings/require-login GET/PUT הפעלה/השבתה של דרישת התחברות

ניהול ספקים

נקודת קצה שיטה תיאור
/api/providers GET/POST הצגת ספקים / יצירת ספקים
/api/providers/[id] GET/PUT/DELETE ניהול ספק
/api/providers/[id]/test POST בדיקת החיבור לספק
/api/providers/[id]/models GET הצגת המודלים של הספק
/api/providers/validate POST אימות תצורת הספק
/api/providers/bulk POST הוספה מרוכזת של מפתחות API עבור ספק אחד
/api/providers/import POST ייבוא רשימת ספקים הטרוגנית מקובץ CSV/JSON שנותח (#6836); תוצאות כשל חלקי לכל שורה
/api/provider-nodes* שיטות שונות ניהול צומתי ספקים
/api/provider-models GET/POST/PATCH/DELETE מודלים מותאמים אישית (הוספה, עדכון, הסתרה/הצגה, מחיקה)

תהליכי OAuth

נקודת קצה שיטה תיאור
/api/oauth/[provider]/[action] שיטות שונות OAuth ייעודי לספק

ניתוב ותצורה

נקודת קצה שיטה תיאור
/api/models/alias GET/POST כינויים למודלים
/api/models/catalog GET כל המודלים לפי ספק + סוג
/api/combos* שיטות שונות ניהול שילובים
/api/keys* שיטות שונות ניהול מפתחות API
/api/pricing GET תמחור מודלים

שימוש וניתוח נתונים

נקודת קצה שיטה תיאור
/api/usage/history GET היסטוריית שימוש
/api/usage/logs GET יומני שימוש
/api/usage/request-logs GET יומנים ברמת הבקשה
/api/usage/[connectionId] GET שימוש לפי חיבור
/api/usage/token-limits GET/POST/DELETE תקציבי מגבלת טוקנים לפי מפתח API
/api/usage/model-latency-stats GET נתונים מצטברים בחלון נע של זמני השהיה לפי ספק/מודל (ממוצע/p50/p95/p99, שיעור הצלחה); מסננים: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health GET סיכום תקינות מטמון הפרומפטים על פני call_logs — יחס כתיבה/קריאה, התפלגות גודל הכתיבה לפי p50/p90/p99, ריכוז כתיבות כבדות, פילוח לפי מודל והכרעה מסוג healthy/degraded/thrash/no-data; פרמטרים של שאילתה: range (1h|24h|7d|30d, ברירת מחדל 24h) ו-model אופציונלי (#8827)

הגדרות

נקודת קצה שיטה תיאור
/api/settings GET/PUT/PATCH הגדרות כלליות
/api/settings/proxy GET/PUT תצורת פרוקסי רשת
/api/settings/proxy/test POST בדיקת חיבור הפרוקסי
/api/settings/ip-filter GET/PUT רשימת כתובות IP מורשות/חסומות
/api/settings/thinking-budget GET/PUT מצב שכתוב בקשות לתקציב חשיבה/הסקה (העברה ללא שינוי / הסרה אוטומטית / מותאם אישית / מסתגל). בלתי תלוי בדחיסה. ראו THINKING_BUDGET.md.
/api/settings/system-prompt GET/PUT פרומפט מערכת גלובלי
/api/settings/compression GET/PUT תצורת דחיסה גלובלית
/api/settings/purge-request-history POST מחיקת שורות יומן הבקשות ופריטי יומן הקריאות המקומיים

הקשר ודחיסה

נקודת קצה שיטה תיאור
/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 קריאת פלט גולמי מצונזר שנשמר לפי מזהה מצביע
/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 (test_status דביק של SQLite, לא המדד). ראו 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‏ (no-store)
/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/export GET הורדת מסד הנתונים כקובץ .sqlite
/api/db-backups/import POST העלאת קובץ .sqlite להחלפת מסד הנתונים
/api/db-backups/exportAll GET הורדת גיבוי מלא כארכיון .tar.gz

סנכרון ענן

נקודת קצה שיטה תיאור
/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 ניהול מדיניות ניתוב

תאימות

נקודת קצה שיטה תיאור
/api/compliance/audit-log GET יומן ביקורת תאימות (N האחרונים)

v1beta (תואם Gemini)

נקודת קצה שיטה תיאור
/v1beta/models GET הצגת מודלים בפורמט Gemini
/v1beta/models/{...path} POST נקודת הקצה generateContent של Gemini

נקודות קצה אלה משקפות את פורמט ה-API של Gemini עבור לקוחות המצפים לתאימות מקורית עם Gemini SDK.

ממשקי API פנימיים / של המערכת

נקודת קצה שיטה תיאור
/api/init GET בדיקת אתחול היישום (בשימוש בהפעלה הראשונה)
/api/tags GET תגיות מודלים תואמות Ollama (עבור לקוחות Ollama)
/api/restart POST הפעלת אתחול מחדש מבוקר של השרת
/api/shutdown POST הפעלת כיבוי מבוקר של השרת
/api/system/env/repair POST תיקון משתני סביבה של ספק OAuth

הערה: נקודות קצה אלה משמשות באופן פנימי את המערכת או לצורך תאימות ללקוחות Ollama. בדרך כלל משתמשי קצה אינם פונים אליהן.

תיקון סביבת OAuth (v3.6.1+)

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

{
  "provider": "claude-code"
}

מתקן משתני סביבת OAuth חסרים או פגומים עבור ספק מסוים. מחזיר:

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

תמלול שמע

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

תמללו קובצי שמע באמצעות כל ספק STT שהוגדר. מקטע הנתיב הראשון בוחר את הספק המקורי (openai/…, deepgram/…). שערים שמייצאים מחדש מודל של ספק אחר משתמשים במזהה מלא (openrouter/deepgram/nova-3).

בקשה:

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

תגובה:

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

מזהי מודלים לדוגמה: openai/whisper-1 (דורש מפתח OpenAI), openrouter/deepgram/nova-3 (דורש מפתח OpenRouter), deepgram/nova-3 (דורש מפתח מקורי של Deepgram). בקשה עם deepgram/nova-3 בלבד אינה משתמשת ב-OpenRouter.

פורמטים נתמכים: mp3, wav, m4a, flac, ogg, webm.

תאימות ל-Ollama

עבור לקוחות המשתמשים בפורמט ה-API של Ollama:

# נקודת קצה לצ'אט (פורמט 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 עשויים להופיע ביומני שרתי proxy הפוכים, בהיסטוריית הדפדפן ובטלמטריה מחוץ ל-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
}

# מחיקת מגבלת טוקנים לפי מזהה
DELETE /api/usage/token-limits?id=tl-abc

הערות לסכמה (setTokenLimitSchema): השדות apiKeyId ו-scopeType (model | provider | global) הם שדות חובה. השדה scopeValue נדרש אלא אם scopeType הוא global (לדוגמה, מזהה מודל עבור תחום model, או מזהה ספק עבור תחום 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. המודל מזוהה (ספק/מודל ישיר או כינוי/שילוב)
  4. פרטי הגישה נבחרים ממסד הנתונים המקומי, תוך סינון לפי זמינות החשבון
  5. עבור צ'אט: handleChatCore בודק את מטמון הסמנטיקה/החתימות ומזהה את הגדרות הדחיסה של השילוב
  6. דחיסה יזומה מתבצעת לפני התרגום לספק כאשר היא מופעלת (lite,‏ Caveman,‏ RTK או שילוב שלהם)
  7. מבצע הספק שולח את הבקשה לשירות במעלה הזרם
  8. התגובה מתורגמת בחזרה לפורמט הלקוח (צ'אט) או מוחזרת כפי שהיא (הטמעות/תמונות/שמע)
  9. נתוני שימוש, ניתוחי דחיסה ויומני בקשות נרשמים
  10. במקרה של שגיאות מתבצע מעבר לחלופה בהתאם לכללי השילוב

הפניה לארכיטקטורה המלאה: ARCHITECTURE.md

ניהול שילובים

ניתן גם למפות שילובי ניתוב ברמה גבוהה יותר (שכבר סוכמו תחת /api/combos*) ביחס של 1:1 מתבנית מזהה מודל, ובכך לאפשר הפניה שקופה של מזהה מודל בסגנון OpenAI לשילוב.

שיטה נתיב תיאור
GET /api/model-combo-mappings הצגת כל מיפויי מודל→שילוב
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).

Webhooks

מינויים ל-webhooks יוצאים עבור אירועי OmniRoute (השלמת בקשה, מיצוי מכסה, החלפת מפתח וכו').

שיטה נתיב תיאור
GET /api/webhooks הצגת רשימת webhooks (הסודות מוסווים כ-<prefix>...)
POST /api/webhooks יצירת webhook — גוף הבקשה: {url, events?: ["*"], secret?, description?}
GET /api/webhooks/[id] אחזור webhook
PUT /api/webhooks/[id] עדכון url/events/secret/description
DELETE /api/webhooks/[id] הסרת webhook
POST /api/webhooks/[id]/test שליחת מטען בדיקה לכתובת ה-URL של ה-webhook והחזרת סטטוס המסירה

אימות: הפעלת ניהול/מפתח 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 מסוג Bearer (isAuthenticated). ראו גם /v1/quotas/check ו-/v1/issues/report.

פרוטוקול סוכנים

משימות של סוכני ענן (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
POST /api/v1/agents/tasks/[id] פעולה מובחנת: {action: "approve"}, {action: "message", message}, או {action: "cancel"}
DELETE /api/v1/agents/tasks/[id] מחיקת משימה מסוימת לפי מזהה

אימות: נדרש אימות ניהולי בכל שיטה (requireCloudAgentManagementAuth). לפני v3.8.0 נקודות קצה אלה לא דרשו אימות — ראו commit 588a0333 לגבי השינוי השובר.

# יצירת משימת ענן של Claude Code
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'

שרתי Proxy לניהול

שרתי Proxy יוצאים מסוג HTTP(S)/SOCKS שניתן להקצות לספקים, לחשבונות או באופן גלובלי.

שיטה נתיב תיאור
GET /api/v1/management/proxies הצגת רשימת שרתי Proxy (עם ?id= מוחזר אחד; עם ?id=&where_used=1 מוחזר גרף ההקצאות)
POST /api/v1/management/proxies יצירת שרת Proxy — גוף הבקשה מאומת באמצעות createProxyRegistrySchema
PATCH /api/v1/management/proxies עדכון שרת Proxy — גוף הבקשה מאומת באמצעות updateProxyRegistrySchema (דורש id)
DELETE /api/v1/management/proxies?id=...&force=1 מחיקת שרת Proxy (השתמשו ב-force=1 כדי לנתק הקצאות)
GET /api/v1/management/proxies/assignments הצגת רשימת הקצאות — ניתן לסינון לפי proxy_id,‏ scope,‏ scope_id; העבירו resolve_connection_id=<id> כדי לאתר את שרת ה-Proxy הפעיל עבור חיבור
PUT /api/v1/management/proxies/assignments הקצאה — גוף הבקשה מאומת באמצעות proxyAssignmentSchema ({scope, scopeId?, proxyId?}). מנקה את מטמון ה-dispatcher
PUT /api/v1/management/proxies/bulk-assign הקצאה מרוכזת — גוף הבקשה מאומת באמצעות bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET /api/v1/management/proxies/health?hours=24 נתוני תקינות מצטברים של שרתי Proxy (ספירות הצלחה/כישלון, זמן השהיה) לאורך חלון זמן

אימות: נדרשים הפעלת ניהול/מפתח API בכל נתיב (requireManagementAuth).

הנתיבים POST /api/v1/management/proxies/[id]/assignments ו-POST /api/v1/management/proxies/[id]/health שבתיאור המשימה מטופלים על ידי הנתיבים השטוחים /assignments ו-/health המוצגים לעיל — אין בקוד הבסיס נתיבי משנה לפי מזהה.

עמידות (מורחב)

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; אותם שדות זמינים גם בלוח הבקרה ← הגדרות ← עמידות.

# ניקוי נעילה של מודל יחיד
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 ← "מצב זמן הריצה של העמידות".

מיומנויות

מסגרת מיומנויות להרחבת 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 התקנת מיומנות לפי id מ-SkillsMP
GET /api/skills/skillssh?q=&limit= חיפוש במרשם skills.sh
POST /api/skills/skillssh/install התקנת מיומנות לפי id מ-skills.sh

אימות: הפעלת ניהול/מפתח API. נתיבי החיפוש בזירת המסחר מקבלים אימות ניהול או מפתח API מסוג Bearer (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 תקינות תת־מערכת הזיכרון (קישוריות למסד הנתונים, מנגנון ההטמעות, מצב האינדקס הווקטורי)

אימות: הפעלת ניהול/מפתח API (requireManagementAuth). ערכי ה־enum של type:‏ FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (ראו MemoryType בקובץ src/lib/memory/types.ts).

שרת MCP

OmniRoute כולל שרת מובנה של פרוטוקול הקשר למודלים עם 3 תעבורות (stdio, SSE, streamable-http) וכלים בעלי תחומי הרשאה מוגדרים. נקודות הקצה של לוח הבקרה שלהלן קוראות נתוני מצב/ביקורת ומשמשות כ־proxy לתעבורות 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 פתיחת צד ה־SSE של תעבורת Streamable HTTP (הודעות ביוזמת השרת)
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 (מפתח API מסוג Bearer עם תחום ההרשאה 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 הציבורי (שם, תיאור, יכולות, קטלוג מיומנויות וסכמת אימות) — נשמר במטמון ציבורי למשך שעה. לא נדרש אימות.

כלי עזר של 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 פועלים ללא אימות ניהול (וניתנים לקריאה מלוח הבקרה); הנתיב /a2a של JSON-RPC משתמש ב-Bearer‏ OMNIROUTE_API_KEY, אם הוגדר.

ענן, הערכות ובחינה

שיטה נתיב תיאור
POST /api/cloud/auth אימות מפתח Bearer והחזרת חיבורי ספקים מוסווים + כינויי מודלים עבור לקוחות סנכרון ענן
POST /api/cloud/credentials/update עדכון פרטי כניסה מוצפנים עבור ספק המסונכרן עם הענן
POST /api/cloud/model/resolve המרת מזהה מודל לוגי לספק/מודל קונקרטי באמצעות טבלת הניתוב המקומית
GET /api/cloud/models/alias הצגת כינויי המודלים כפי שהם נחשפים לסנכרון הענן
GET /api/assess קריאת הסיווגים מהבחינה האחרונה (לפי ספק/מודל)
POST /api/assess הפעלת בחינה — גוף: `{scope: {type:"all"} {type:"provider", providerId} {type:"model", modelId}, trigger?}`
GET /api/evals הצגת חבילות ההערכה המובנות + ההרצות האחרונות
POST /api/evals הפעלת הרצת הערכה
POST /api/evals/suites יצירת חבילת הערכה מותאמת אישית — הגוף מאומת באמצעות evalSuiteSaveSchema
GET /api/evals/suites/[id] אחזור חבילת הערכה מותאמת אישית

אימות: /api/cloud/auth מאמת מפתח Bearer ישירות; הנתיבים האחרים תחת /api/cloud/*,‏ /api/evals/* ו-/api/assess דורשים הפעלת ניהול/מפתח API. בקשות POST אל /api/assess משתמשות ב-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
}

אימות: נדרשת הפעלת ניהול (קובץ cookie מסוג auth_token של לוח הבקרה) או מפתח 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 בעל הרשאת ניהול.

פעולות מנהל מערכת

נקודות קצה למנהלי מערכת בלבד עבור ניהול תפעולי.

שיטה נתיב תיאור
GET /api/admin/concurrency קריאת מגבלות המקביליות הנוכחיות (גלובלית + לפי ספק)
POST /api/admin/concurrency עדכון מגבלות המקביליות — גוף הבקשה: {global?: number, perProvider?: Record<string, number>}

אימות: נדרשת הפעלת ניהול עם הרשאת מנהל מערכת.

ניהול כלי CLI

ניהול כלי CLI המשתלבים עם OmniRoute‏ (antigravity, chipotle, 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 מציין קובץ YAML ישן של Codex)
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 מצב פרוקסי ה-MITM של Antigravity (כלי ה-CLI ‏"antigravity-mitm")
POST /api/cli-tools/antigravity-mitm/alias הגדרת כינויים עבור antigravity-mitm

אימות: נדרשת הפעלת ניהול.

מיומנויות סוכן

ניהול מיומנויות של סוכני בינה מלאכותית (בדומה ל-GPTs המותאמים אישית של OpenAI, אך עבור סוכנים).

שיטה נתיב תיאור
GET /api/agent-skills הצגת כל מיומנויות הסוכן (מובנות + מותאמות אישית)
GET /api/agent-skills/[id] קבלת מיומנות סוכן מסוימת
POST /api/agent-skills יצירת מיומנות סוכן מותאמת אישית — גוף הבקשה: {name, description, prompt, model?, temperature?}
PUT /api/agent-skills/[id] עדכון מיומנות סוכן מותאמת אישית
DELETE /api/agent-skills/[id] מחיקת מיומנות סוכן מותאמת אישית
GET /api/agent-skills/[id]/raw קבלת ההנחיה הגולמית + מטא-נתונים (ללא הפעלה)
POST /api/agent-skills/generate יצירת מיומנות חדשה באמצעות בינה מלאכותית מתיאור בשפה טבעית

אימות: נדרשת הפעלת ניהול או מפתח 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 בהיקף ניהול.

Webhooks

ניהול מינויים ל-webhook עבור אירועים.

שיטה נתיב תיאור
GET /api/webhooks הצגת כל המינויים ל-webhook
POST /api/webhooks יצירת מינוי ל-webhook — גוף: {url, events[], secret?, active?}
GET /api/webhooks/[id] קבלת מינוי מסוים ל-webhook
PUT /api/webhooks/[id] עדכון מינוי ל-webhook
DELETE /api/webhooks/[id] מחיקת מינוי ל-webhook
GET /api/webhooks/[id]/deliveries הצגת היסטוריית המסירות של webhook (יומן הצלחות/כישלונות)
POST /api/webhooks/[id]/test שליחת אירוע בדיקה ל-webhook

אימות: נדרשת הפעלת ניהול.

לכל סוגי האירועים, ראו מסגרת Webhooks.

מסגרת המיומנויות

ניהול מיומנויות (מסגרת ההרחבות הסוכניות).

שיטה נתיב תיאור
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.

מנגנוני הגנה

בדיקת מנגנוני ההגנה בזמן ריצה (זיהוי מידע אישי מזהה, זיהוי הזרקת הנחיות, גישור ראייה). מנגנוני ההגנה מופעלים בכל בקשה; ניתן לבטל את הפעלתם עבור קריאה בודדת באמצעות כותרת הבקשה x-omniroute-disabled-guardrails — אין ממשק מתמשך להפעלה או להשבתה.

שיטה נתיב תיאור
GET /api/guardrails הצגת מנגנוני ההגנה הרשומים והסטטוס שלהם (שם / מופעל / עדיפות)
POST /api/guardrails/test הרצה יבשה של צינור העיבוד שלפני הקריאה על קלט לדוגמה — גוף: {input, disabledGuardrails?}

אימות: נדרשת הפעלת ניהול.

לפרטים מלאים, ראו אבטחה > מנגנוני הגנה.

אימות

ראו אימות לניהול לפרטים על ארבע משפחות פרטי ההזדהות (הפעלת לוח הבקרה, אסימון CLI מקומי, אסימון גישה oma_live_…, מפתח API בהיקף ניהול) ועל ההבדלים ביניהן לבין מפתחות היסק.

  • נתיבי לוח הבקרה (/dashboard/*) משתמשים בקובץ cookie בשם auth_token
  • הכניסה משתמשת בגיבוב הסיסמה השמור; אם אינו זמין, נעשה שימוש ב־INITIAL_PASSWORD
  • ניתן להפעיל או להשבית את requireLogin דרך /api/settings/require-login
  • נתיבי /v1/* עשויים לדרוש מפתח API מסוג Bearer כאשר REQUIRE_API_KEY=true
  • המונחים "אסימון ניהול" / "מפתח API בהיקף ניהול" במסמך זה מתייחסים לאחת המשפחות המתוארות במדריך זה — ולא לסוג נוסף ולא מוגדר של סוד

שינוי שובר תאימות (v3.8.0) — הנתיבים /api/v1/agents/tasks/* ונקודות הקצה לניהול תקופת ההמתנה דורשים כעת אימות לניהול (קובץ cookie בשם auth_token של לוח הבקרה או מפתח API בהיקף ניהול). לקוחות שקראו בעבר לנתיבים אלה ללא אימות יקבלו 401 Unauthorized. ראו commit‏ 588a0333 (fix(auth): require management auth for agent and cooldown APIs).

Reference in New Issue View Git Blame Copy Permalink