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
API Reference (עברית)
🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 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
🌐 שפות: 🇺🇸 אנגלית | 🇪🇹 אמהרית | 🇸🇦 ערבית | 🇦🇿 אזרית | 🇧🇬 בולגרית | 🇧🇩 בנגלית | 🇧🇦 בוסנית | 🇨🇿 צ׳כית | 🇩🇰 דנית | 🇩🇪 גרמנית | 🇬🇷 יוונית | 🇪🇸 ספרדית | 🇪🇪 אסטונית | 🇮🇷 פרסית | 🇫🇮 פינית | 🇫🇷 צרפתית | 🇮🇪 אירית | 🇮🇳 גוג׳ראטית | 🇳🇬 האוסה | 🇮🇱 עברית | 🇮🇳 הינדי | 🇭🇷 קרואטית | 🇭🇺 הונגרית | 🇦🇲 ארמנית | 🇮🇩 אינדונזית | 🇳🇬 איגבו | 🇮🇹 איטלקית | 🇯🇵 יפנית | 🇬🇪 גאורגית | 🇰🇭 חמרית | 🇮🇳 קנאדה | 🇰🇷 קוריאנית | 🇱🇹 ליטאית | 🇱🇻 לטבית | 🇮🇳 מלאיאלאם | 🇮🇳 מראטהית | 🇲🇾 מלאית | 🇲🇹 מלטית | 🇲🇲 בורמזית | 🇳🇵 נפאלית | 🇳🇱 הולנדית | 🇳🇴 נורווגית | 🇮🇳 אודיה | 🇮🇳 פנג׳אבית | 🇵🇭 פיליפינית | 🇵🇱 פולנית | 🇵🇹 פורטוגזית (פורטוגל) | 🇧🇷 פורטוגזית (ברזיל) | 🇷🇴 רומנית | 🇷🇺 רוסית | 🇱🇰 סינהלית | 🇸🇰 סלובקית | 🇸🇮 סלובנית | 🇷🇸 סרבית | 🇸🇪 שוודית | 🇰🇪 סווהילית | 🇮🇳 טמילית | 🇮🇳 טלוגו | 🇹🇭 תאית | 🇹🇷 טורקית | 🇺🇦 אוקראינית | 🇵🇰 אורדו | 🇺🇿 אוזבקית | 🇻🇳 וייטנאמית | 🇳🇬 יורובה | 🇨🇳 סינית (מפושטת) | 🇹🇼 סינית (מסורתית)
תיעוד הליבה של OmniRoute API. הוא מכסה את הממשק הציבורי /v1 ואת נקודות הקצה הנפוצות ביותר לניהול; הקובץ הקריא למכונה docs/openapi.yaml ועץ הנתיבים תחת src/app/api/ הם המקורות המקיפים.
לפרוטוקול הממוקד התואם ל-OpenAI ולמטריצת היכולות של הספקים, ראו
OPENAI_COMPATIBILITY.md.
תוכן עניינים
- השלמות צ'אט
- חכירות בלעדיות של הפעלות מנוהלות
- הטמעות
- יצירת תמונות
- OCR למסמכים
- רשימת מודלים
- מניפסט תוסף ספק
- נקודות קצה לתאימות
- API לקבצים
- API לאצוות
- API לחיפוש
- הזרמה באמצעות WebSocket
- דיווח על מכסות ובעיות
- מטמון סמנטי
- לוח בקרה וניהול
- ניהול קומבינציות
- Webhooks
- מפתחות רשומים (ניהול אוטומטי)
- פרוטוקול סוכנים
- שרתי Proxy לניהול
- עמידות (מורחבת)
- מיומנויות
- זיכרון
- שרת MCP
- שרת A2A
- ענן, הערכות ואומדן
- עיבוד בקשות
- אימות
השלמות צ'אט
POST /v1/chat/completions
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "cc/claude-opus-4-6",
"messages": [
{"role": "user", "content": "Write a function to..."}
],
"stream": true
}
כותרות מותאמות אישית
| כותרת | כיוון | תיאור |
|---|---|---|
X-OmniRoute-No-Cache |
בקשה | יש להגדיר כ־true כדי לעקוף את המטמון |
x-omniroute-no-memory |
בקשה | יש להגדיר כ־true כדי לדלג על הזרקת זיכרון ומיומנויות עבור בקשה זו (משקף מצב ללא מטמון; מונע את תקורת האסימונים/העלות לכל קריאה) |
X-OmniRoute-Progress |
בקשה | יש להגדיר כ־true עבור אירועי התקדמות |
X-Session-Id |
בקשה | מפתח הפעלה דביקה לצורך שיוך הפעלות חיצוני |
x_session_id |
בקשה | מתקבלת גם גרסה עם קו תחתון (HTTP ישיר) |
X-OmniRoute-Session-Id |
בקשה | תג הפעלה/שיחה שסופק על ידי מבצע הקריאה (מזין גם את הזיכרון). כאשר הוא קיים, הוא נשמר כפי שהוא ב־call_logs.session_tag לצורך שיוך עלויות לפי הפעלה (#8249) — לעולם אינו נוצר כאשר הוא חסר |
Idempotency-Key |
בקשה | מפתח מניעת כפילויות (חלון של 5 שניות) |
X-Request-Id |
בקשה | מפתח חלופי למניעת כפילויות |
x-omniroute-connection |
בקשה | קיבוע בקשה למודל יחיד לחיבור ספק (חשבון) אחד לפי המזהה שלו — ראו קיבוע חשבון לכל בקשה |
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;.
קיבוע חשבון לכל בקשה
כאשר לספק יש כמה חיבורים (חשבונות או מפתחות), 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"}]}'
- היכן למצוא את המזהה. פתחו את דף הספק בלוח הבקרה
(לוח הבקרה → ספקים → ) ולחצו על תגית המזהה
xxxxxxxx…בשורת חיבור — פעולה זו מעתיקה את מזהה החיבור המלא. - אילו בקשות מכבדות אותו. בקשות למודל יחיד (
provider/model) בנקודות הקצה/v1/chat/completions,/v1/messagesו-/v1/responses. שילובים מתעלמים מהכותרת: במקום זאת, הצמידו חשבון לכל שלב בשילוב באמצעות החיבור של השלב עצמו. - ההצמדה מחייבת, ואינה רק העדפה. נעשה שימוש בלעדי בחיבור המוצמד. כשל בתוך הבקשה מתעד את תקופת הצינון של החשבון, אך אינו עובר לחשבון מקביל של אותו ספק.
- תקופת צינון ומכסה משחררות את ההצמדה. בזמן שהחיבור המוצמד נמצא בתקופת צינון, מיצה את המכסה או נחסם בידי מדיניות מכסה, בקשות מאוחרות יותר חוזרות לחיבורים האחרים של הספק, בדיוק כמו תעבורה שאינה מוצמדת.
- מזהים לא מוכרים או מושבתים גורמים לכשל. מזהה שאינו נמצא במאגר הפעיל של הספק (נמחק, הושבת או שייך לספק אחר) אינו מותיר חשבון כשיר, ולכן הבקשה נכשלת במקום להיות מנותבת בשקט ליעד אחר.
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(בדולר ארה״ב, עם 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-base664url-characters>
{"action":"acquire","model":"glm/glm-4.6"}
תגובות מוצלחות של רכישה, חידוש ושחרור חושפות חותמות זמן, state, ו-generation חיובי מדויק, אך לעולם לא את החיבור או האישורים שנבחרו. חידוש ושחרור מספקים את ה-generation בגוף ה-JSON:
{ "action": "renew", "generation": 1 }
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
בעל חכירה פעיל יכול לבקש במפורש מטא-נתונים תצוגתיים בטוחים לפרטיות עבור הקישור הנוכחי שלו:
{ "action": "status", "generation": 1 }
{
"state": "ACTIVE",
"generation": 1,
"acquiredAt": "2026-08-28T12:00:00.000Z",
"renewedAt": "2026-08-28T12:00:30.000Z",
"expiresAt": "2026-08-28T12:02:30.000Z",
"connection": {
"displayName": "Primary Codex",
"provider": "codex"
}
}
פעולת סטטוס אופציונלית זו מגודרת על ידי הבעלים האוטם, מפתח ה-API המנוהל המאומת, וה-generation הפעיל המדויק בעסקת מסד נתונים אחת. displayName הוא רק שם החיבור המוגדר המקוצר; הוא null כאשר אין שם מוגדר בטוח. OmniRoute לעולם אינו מחליף כתובת אימייל או זהות חשבון שנוצרה. ערך הספק הוא תווית תצוגה לא רגישה ולעולם אינו מזהה ספק תואם שנוצר. אישורים, אסימונים, קובצי Cookie, מזהי חיבור גולמיים או מזהי מפתח API, גיבובי בעלים, סודות גידור ונתוני ניתוב פנימיים אינם נכללים.
חיפושים עם מפתח שגוי, בעלים שגוי, generation מיושן, חסר, פג תוקף, משוחרר ולא חוקי, כולם מחזירים את אותה שגיאת 409 LEASE_FENCE_STALE ללא מטא-נתונים של חיבור. לקוח שקיבל את תגובת ההמתנה לקיבולת אינו בעל קישור פעיל לבדיקה. כאשר הניתוב מעביר חכירה פעילה, אותו generation נשאר תקף והסטטוס מחזיר באופן אטומי את הקישור החדש, לעולם לא את הישן. לקוחות קיימים נשארים ללא שינוי מכיוון שתגובות רכישה, חידוש, שחרור והמתנה שומרות על צורותיהן הקודמות.
חוזה שרת זה אינו משנה את /status הסטנדרטי של OpenAI Codex. 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> |
שילוב בעל שם, מתאים לפי שם (לא תלוי רישיות) תחילה, ואז לפי מזהה. |
הערות:
- ערכים לא ידועים מתעלמים (הבקשה לעולם אינה נדחית); הרזולוציה עוברת לעדיפות המפעיל הרגילה.
- אם מספר שילובים חולקים שם, העבר את מזהה השילוב להתאמה דטרמיניסטית.
- שילוב ששמו הוא
offאוdefaultלא ניתן לבחור לפי שם (מילות מפתח אלו מתפרשות תחילה); הפנה לשילוב כזה לפי מזההו. - מתג הדחיסה הראשי הוא שער קשיח: כאשר הדחיסה מושבתת גלובלית, כותרת זו אינה יכולה להפעיל אותה.
התוכנית המיושמת מוחזרת בכותרת התגובה:
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)
מועברים הלאה. יחידות SKU של 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). - 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משתמש ב-OpenAI Images API של ZenMux. האפשרויות כוללות אתsize,quality,n,output_format,output_compression,backgroundו-response_format.- מפרסמים אחרים, כגון
zm/meta/muse-image-1.0, משתמשים בנקודת הקצה:predictשל Vertex AI מבית ZenMux. 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" מחזיר כתובת URL מסוג HTTPS ממעלה הזרם
או כתובת URL של נתוני base64 כאשר זמינים רק בתים של התמונה. פלטים ריקים או מסוננים
מחזירים שגיאה במקום הצלחה ריקה. הגישה למודלים תלויה בחשבון ZenMux.
ראו Vertex API של ZenMux ואת
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; מזהה מודל ללא קידומת (למשל
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 ללא קידומת) |
סינכרוני — התגובה מוחזרת ישירות מקריאת ה-upstream היחידה. |
azure-document-intelligence |
prebuilt-read |
azure-document-intelligence/prebuilt-read |
upstream אסינכרוני (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 של נקודת הקצה ב-upstream היא
נקודת הקצה הכללית לשותפים 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.
מסנני גילוי (?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 # התאמה שאינה תלוית רישיות לפי מזהה או שם
| פרמטר | ערכים |
|---|---|
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": [ ...models ] }
כל שדה הוא אופציונלי. capabilities ו-exclude מקבלים מערך או מחרוזת המופרדת בפסיקים;
max_output מושווה ל-max_output_tokens. התוצאות ממוינות תחילה לפי owned_by, ולאחר מכן לפי id.
ערך ברירת המחדל של limit הוא 20, וערכים מעל 100 מוגבלים ל-100. JSON לא תקין, שדה לא מוכר
או ערך לא חוקי מחזירים HTTP 400.
מודלי צ'אט מוסתרים בנפרד
מודל שמסומן כ-מוסתר בדף הספק שלו אינו נכלל בקטלוג ונדחה
עם HTTP 404 / model_not_found כאשר מבקשים אותו במפורש. הבדיקה משתמשת בספק
ובמודל לאחר הפענוח, לרבות כינויי ספקים, קידומות צמתים של ספקים תואמים וברירות מחדל
של חיבורים. שילוב מדלג על יעדים מוסתרים ויכול להשתמש באפשרות גלויה מאותה קבוצה; כאשר לא
נותר יעד בר-הרצה, מוחזר אותו קוד שגיאה. ביטול ההסתרה נכנס לתוקף בבקשה
הבאה. עקיפות נראות לתמונות בלבד אינן מסתירות את מודל הצ'אט בעל אותו מזהה.
הגדרת מודל פרטנית זו נפרדת מ-
רשימות ההתרה/חסימה לחשיפת מודלים, שמסננות את פרסום הקטלוג
ואת המועמדים לניתוב אוטומטי, תוך שמירה על שיגור מפורש. הרשאות מודלים של מפתחות API
ממשיכות לחול באופן עצמאי. מצב קידומת הקטלוג המוגדר כברירת מחדל נשאר dual.
וריאנטים של מודלים ללא חשיבה
עבור מודלי 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/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 + גוף 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}/... המתועדות להלן.
# דירוג מחדש (ספק ממרשם הענן, או צומת ספק תואם 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]
# יצירת וידאו / מוזיקה (מזהה מודל עם קידומת ספק)
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>. צומתי לולאה חוזרת (localhost,127.0.0.1,172.16.0.0/12) תמיד כשירים, וכך גם שמות מארחים שהמפעיל מציין ב-OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS(לדוגמה, שם שירות של Docker/Compose כגוןhttp://reranker:8080/v1; הפנייה אליהם מתבצעת ישירות, לעולם לא דרךHTTP(S)_PROXYאו דרך ה-proxy המקובע של חיבור). צמתים בכל מארח אחר — מחשב ברשת LAN או עמית Tailscale — כשירים רק כאשר המפעיל מפעיל את דגל היכולתRERANK_REMOTE_PROVIDER_NODESוגם כתובת ה-URL הבסיסית של הצומת עומדת במדיניות כתובות ה-URL היוצאות של הספק (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS/OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS). שלב הדירוג מחדש של מנוע הזיכרון קורא לנתיב זה דרך לולאה חוזרת, ולכן אותו כלל חל על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תחת קידומת הצומת. שורות שאינן כוללות מטא-נתונים של נקודות קצה (כמקובל ברשימות/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 לקבצים עבור קלט/פלט באצווה והעלאות לפי ייעוד הקובץ.
| שיטה | נתיב | תיאור |
|---|---|---|
| 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).
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 |
ביטול אצווה הנמצאת בתהליך |
אימות: מפתח 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.
provider_options של Exa ושל Tavily
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 שומרות את id, highlight_scores, summary, subpages, entities ואת extras בתוך
provider_raw. תוצאות Tavily שומרות את images ואת favicon.
חישוב העלויות עדיין משתמש במאגר השטוח costPerQuery. Tavily מחייב
יותר קרדיטים לכל קריאה כאשר search_depth: "advanced", וההפרש הזה אינו משתקף
ב-usage.search_cost_usd.
Web Fetch API
חילוץ תוכן מכתובת URL באמצעות ספק web-fetch מוגדר (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract).
Parallel Extract (parallel-search, עם אותו מפתח API כמו Parallel Search) מחזיר Markdown
בלבד — כל format אחר גורר שגיאת 400 — ומגביל את התוכן ל-100,000 תווים. כאשר
לא ניתן לחלץ את דף היעד עצמו, השירות במעלה הזרם מדווח על כך בתוך תגובת HTTP 200;
OmniRoute מציג זאת כשגיאת 422 עם הודעה קבועה.
| שיטה | נתיב | תיאור |
|---|---|---|
| POST | /v1/web/fetch |
אחזור/גירוד של כתובת URL — גוף הבקשה מאומת באמצעות v1WebFetchSchema |
אימות: מפתח API מסוג Bearer (extractApiKey + isValidApiKey). המדיניות נאכפת באמצעות enforceApiKeyPolicy.
מעבר חלופי מודע למכסה (#8297): כאשר לא מצוין provider מפורש, מתבצעת סריקה של המאגר
(firecrawl → jina-reader → tavily-search → tinyfish → nimble-search →
parallel-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 בלבד)
# אותו מארח:פורט כמו 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,
// קיים רק כאשר המפתח בחר להשתמש במגבלות שימוש לכל מפתח (USD יומי/שבועי):
"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
מבחינה ביניהם.
אימות: מפתח ה-Bearer API של הקורא עצמו, המאומת באמצעות isValidApiKey — זהו לא
ממשק הניהול (/api/keys/…), שנותר מוגן באמצעות requireManagementAuth.
אחוזי מכסה גולמיים לעומת אחוזים מותאמי סף הפסקה
בעת צריכת /api/usage/om-usage, על הקוראים לשים לב להבדל בין
האחוזים המוצגים בפלט הטקסט הפשוט לבין פלט ה-JSON המובנה:
| היבט | תצורת טקסט פשוט (/api/usage/om-usage / @@om-usage) |
תצורת JSON (?format=json) |
|---|---|---|
| שדה פלט | NN% left (לדוגמה, 20% left) |
provider.quotas / providers[].quotas |
| מדידה | הקצאה זמינה מותאמת לסף הפסקה: הקיבולת שנותרה מעל סף ההפסקה | מכסת ספק גולמית: מדידת הספק ללא התאמות |
| התאמת סף הפסקה | מותאם באמצעות effectiveRemainingPercent() כך שהעתודה המוגנת מוצגת כ-0% left |
ללא (ערכי תמונת מצב גולמיים כפי שדווחו על ידי הספק) |
| נתוני סף | משוקללים באחוז המוצג | מאוחסנים ב-quotaWindowThresholds לכל חיבור (או ברירות המחדל של השרת) |
| צרכן עיקרי | ממשקי CLI אינטראקטיביים, הנחיות מסוף, מפעילים אנושיים | אינטגרציות תכנותיות, לוחות מחוונים, ניתוח נתונים, עוקבי חיוב |
נוסחת ההתאמה לסף ההפסקה
OmniRoute תומך בספי הפסקה יזומים של מכסות כדי למנוע את מיצוי משאבי הספק (המוגדרים באמצעות
quotaWindowThresholds של החיבור, ברירות המחדל של הספק או הגדרות חוסן גלובליות). כאשר סף הפסקה
(לדוגמה, cutoff = 25%) פעיל בחלון מכסה, מנגנון עיבוד הטקסט מחשב את ההקצאה שנותרה כך:
- אם
remaining <= cutoff: מוחזר0%. - אם
remaining > cutoff: מוחזר((remaining - cutoff) / (100 - cutoff)) * 100.
פלט הטקסט המעוצב מעגל זאת למספר השלם הקרוב ביותר (Math.round(...)).
דוגמה להמחשה
נבחן חלון ספק עם 60% שימוש גולמי (ולכן 40% מכסה גולמית שנותרה) ועם סף מוגדר של 25% הפסקה לפי מכסה שנותרה:
| ייצוג | חישוב | נותרו | שימוש משתמע |
|---|---|---|---|
JSON גולמי (?format=json) |
תמונת מצב מהספק (quotas[window]) |
40% | 60% |
תצורת טקסט (NN% left) |
((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100 |
20% | 80% (אם מחשבים 100 - remaining) |
- מדוע הטקסט מציג 20% שנותרו: מתוך 40% המכסה הפיזית שנותרה בחשבון, 25% שמורים על ידי
מדיניות סף ההפסקה. לקורא נותר רק מרווח שמיש של 15% מתוך 75% לפני שהנתב מפסיק
לנתב לחיבור זה. ההתאמה מבטיחה שהחיבור מאותת על מיצוי (
0% left) בדיוק כאשר הניתוב ייפסק. - מדוע JSON משמר ערכים גולמיים: מטען ה-JSON מחזיר את תמונת המצב המדויקת של הספק (
UsageSnapshot), כך שלכלים חיצוניים יש גישה לנתוני האמת של ניצול הספק ול-quotaWindowThresholdsברמת החיבור, ללא התאמה מאבדת מידע בצד השרת.
הנחיות להעברת צרכנים
אם אינטגרציה חיצונית (כגון תוסף לעורך או הרחבת סוכן) חילצה בעבר נתונים מנקודת הקצה
הטקסטואלית (NN% left) וחישבה את אחוז השימוש כ-100 - NN, מעבר ל-?format=json פירושו:
- קריאת ערכי JSON גולמיים תשקף את הצריכה בפועל אצל הספק (60% שימוש בדוגמה שלעיל).
- אם האינטגרציה מעוניינת לשמר את סמנטיקת ההקצאה הזמינה של נקודת הקצה הטקסטואלית, היא יכולה לחשב
בצד הלקוח את נוסחת היתרה האפקטיבית באמצעות
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 מותאמים אישית מתאימים ביטול מפורש של הסקת מסקנות למערכת הקצה העורפית. בדיקת
חיבור מוצלחת בוחרת אוטומטית פקדי תבנית צ'אט לכל מזהה מודל מדויק
שהרשומה שלו ב-/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 וספקים רגילים שומרים על מבנה הבקשה המקורי שלהם. הגדירו את reasoningControl ל-openai כדי לכפות העברה ישירה רגילה של reasoning_effort של 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 |
allowedModels חייב להיות ריק כאשר המצב הוא all |
allowedModels, blockedModels |
מערך של מחרוזות, עד 1000 | |
allowedCombos |
מערך של מחרוזות, עד 500 | קובע לאילו שילובים המפתח רשאי לקרוא; מודלים ישירים כפופים ל-modelAccessMode / allowedModels |
connectionAccessMode |
all | restricted |
allowedConnections חייב להיות לא ריק כאשר המצב הוא restricted, וריק כאשר המצב הוא 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 |
מספר >= 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" }'
הגדרות
| נקודת קצה | שיטה | תיאור |
|---|---|---|
/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 | קריאת פלט גולמי מצונזר שנשמר, לפי מזהה מצביע |
/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 (ללא אחסון) |
/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 (שחזור
לפי מזהה) ו-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 | ניהול מדיניות ניתוב |
תאימות
| נקודת קצה | שיטה | תיאור |
|---|---|---|
/api/compliance/audit-log |
GET | יומן ביקורת תאימות (N האחרונים) |
v1beta (תואם Gemini)
| נקודת קצה | שיטה | תיאור |
|---|---|---|
/v1beta/models |
GET | הצגת רשימת מודלים בפורמט Gemini |
/v1beta/models/{...path} |
POST | נקודת הקצה generateContent של Gemini |
נקודות קצה אלה משקפות את פורמט ה-API של Gemini עבור לקוחות המצפים לתאימות מקורית ל-SDK של Gemini.
ממשקי API פנימיים / מערכתיים
| נקודת קצה | שיטה | תיאור |
|---|---|---|
/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 | התחלת עדכון המותאם לפריסה לגרסה האחרונה |
הערה: נקודות קצה אלה משמשות באופן פנימי את המערכת או לצורך תאימות ללקוחות 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— ערוץ npm של גרסת ה-build הפועלת:nightlyעבור גרסאות-nightly.*, nextעבור גרסאות קדם-הפצה אחרות (-rc.*,-beta.*,-alpha.*),ltsעבור גרסה יציבה מגרסה ראשית ישנה יותר מ-channels.latest, ובכל מקרה אחרlatest. אותם כללים כמו ב-scripts/release/dist-tag.mjs, שבוחר את ה-dist-tag של npm בזמן הפרסום.channels— הגרסה האחרונה שפורסמה בכל dist-tag, מתוךnpm view omniroute dist-tags(עם חלופת HTTP לרישום), הנשמרת במטמון עם אותו TTL של 10 דקות כמוlatest. הערךlatestתמיד קיים (עם חזרה ל-latestולאחר מכן ל-"unavailable"); הערכיםnext,nightlyו-ltsמופיעים רק כאשר ה-dist-tag המתאים קיים. בקשה עםCache-Control: no-cacheמרעננת את שתי הבדיקות.
מודל הערוצים (latest = v3 עד לזמינות הכללית של 4.0, next = rc, nightly = גרסאות build של develop,
lts = תיקוני v3 לאחר הזמינות הכללית של 4.0) מתואר ב-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": "שלום, זהו תוכן האודיו שתומלל.",
"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":"שלום"}]}'
הערות:
- הכינויים המתומחררים משתמשים מחדש באותם מטפלים כמו
/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. זוהי נקודת קצה מסוג ניהול (האימות נאכף באופן מרכזי על ידי צינור ההרשאות).
עיבוד בקשות
- הלקוח שולח בקשה אל
/v1/* - מטפל הנתיב קורא ל-
handleChat, ל-handleEmbedding, ל-handleAudioTranscriptionאו ל-handleImageGeneration - המודל מזוהה (ספק/מודל ישיר או כינוי/שילוב)
- פרטי גישה נבחרים ממסד הנתונים המקומי, עם סינון לפי זמינות החשבון
- עבור צ'אט:
handleChatCoreבודק את מטמון הסמנטיקה/החתימות ומזהה את הגדרות הדחיסה של השילוב - דחיסה יזומה מופעלת לפני התרגום לספק כאשר היא מופעלת (
lite, Caveman, RTK או שילוב שכבות) - מנגנון הביצוע של הספק שולח את הבקשה לשירות המקור
- התגובה מתורגמת בחזרה לפורמט הלקוח (צ'אט) או מוחזרת כפי שהיא (הטמעות/תמונות/שמע)
- נתוני שימוש, ניתוחי דחיסה ויומני בקשות נרשמים
- במקרה של שגיאות, מופעל מנגנון גיבוי בהתאם לכללי השילוב
הפניה לארכיטקטורה המלאה: 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
מינויים ל-webhook יוצא עבור אירועי 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 (requireManagementAuth) — אותו מנגנון הגנה כמו ב-/api/keys: הפעלת לוח מחוונים, אסימון CLI מקומי, או מפתח API עם היקף manage/admin; מפתחות API להסקה בלבד מקבלים 403. ראו גם /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 נקודות קצה אלה לא דרשו אימות — ראו את הקומיט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?}). מנקה את מטמון המנתב |
| 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 |
התקנת מיומנות לפי מזהה מ-SkillsMP |
| GET | /api/skills/skillssh?q=&limit= |
חיפוש במרשם skills.sh |
| POST | /api/skills/skillssh/install |
התקנת מיומנות לפי מזהה מ-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). ערכי המנייה של 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 | פתיחת צד ה-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 ישירות ומחזיר את המפתח המוסווה ואת projectId של כל חיבור, רק עבור מפתח בעל ההרשאה manage / admin; הנתיבים האחרים תחת /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, 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 |
אימות: נדרשת הפעלת ניהול.
מיומנויות סוכן
ניהול מיומנויות של סוכני AI (בדומה ל-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 |
יצירת מיומנות חדשה באמצעות AI מתיאור בשפה טבעית |
אימות: נדרשת הפעלת ניהול או מפתח API בעל הרשאות ניהול.
ניהול מטמון
ניהול המטמון הסמנטי ומטמון ההסקה.
| שיטה | נתיב | תיאור |
|---|---|---|
| GET | /api/cache |
סקירת המטמון: מספר הרשומות הכולל, שיעור הפגיעות, גודל בדיסק |
| GET | /api/cache/entries |
הצגת רשומות המטמון (עם עימוד) |
| DELETE | /api/cache/entries |
מחיקת רשומות מהמטמון (סינון לפי פרמטרים של השאילתה) |
| GET | /api/cache/stats |
סטטיסטיקות מפורטות של המטמון (לפי ספק ולפי מודל) |
| GET | /api/cache/reasoning |
מצב מטמון ההסקה (להפעלה חוזרת של הסקה) |
| DELETE | /api/cache/reasoning |
ניקוי מטמון ההסקה — פרמטרים של השאילתה: ?toolCallId=<id> (יחיד), ?provider=<p> או ללא פרמטרים (הכול) |
אימות: נדרשת הפעלת ניהול.
מערכת זיכרון
ניהול זיכרון מתמיד (FTS5 + הטמעות וקטוריות).
| שיטה | נתיב | תיאור |
|---|---|---|
| GET | /api/memory |
הצגת רשומות הזיכרון (סינון לפי תחום, סוג ושאילתת חיפוש) |
| POST | /api/memory |
יצירת רשומת זיכרון חדשה — גוף: {scope, type, content, metadata?} |
| GET | /api/memory/[id] |
קבלת רשומת זיכרון מסוימת |
| PUT | /api/memory/[id] |
עדכון רשומת זיכרון |
| DELETE | /api/memory/[id] |
מחיקת רשומת זיכרון |
| GET | /api/memory?q= |
חיפוש בזיכרון (FTS5 + וקטור) — הסטטיסטיקות כלולות באותה תגובה |
אימות: נדרשת הפעלת ניהול או מפתח API בעל הרשאת ניהול.
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.
מנגנוני הגנה
בדיקת מנגנוני ההגנה בזמן ריצה (זיהוי PII, זיהוי הזרקת הנחיות, גישור ראייה). מנגנוני ההגנה פועלים בכל בקשה; ביטול הסכמה לכל קריאה מתבצע באמצעות כותרת הבקשה 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).