Skip to content

API_REFERENCE.md

Latest commit

 

History

History
2263 lines (1739 loc) · 214 KB

API_REFERENCE.md

File metadata and controls

2263 lines (1739 loc) · 214 KB
Raw

API Reference (فارسی)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 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

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

مرجع اصلی API مربوط به OmniRoute. این سند سطح عمومی /v1 و پرکاربردترین نقاط پایانی مدیریتی را پوشش میدهد؛ فایل ماشینخوانِ docs/openapi.yaml و درخت مسیر زیر src/app/api/ منابع جامع هستند.

برای پروتکل متمرکزِ سازگار با OpenAI و ماتریس قابلیتهای ارائهدهندگان، به OPENAI_COMPATIBILITY.md مراجعه کنید.

فهرست مطالب

تکمیلهای گفتگو

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

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Write a function to..."}
  ],
  "stream": true
}

هدرهای سفارشی

هدر جهت توضیحات
X-OmniRoute-No-Cache درخواست برای دور زدن کش، روی true تنظیم کنید
x-omniroute-no-memory درخواست برای رد کردن تزریق حافظه و مهارتها در این درخواست، روی true تنظیم کنید (مشابه حالت بدون کش؛ از سربار توکن/هزینه بهازای هر فراخوانی جلوگیری میکند)
X-OmniRoute-Progress درخواست برای رویدادهای پیشرفت، روی true تنظیم کنید
X-Session-Id درخواست کلید نشست چسبنده برای وابستگی نشست خارجی
x_session_id درخواست گونه دارای زیرخط نیز پذیرفته میشود (HTTP مستقیم)
X-OmniRoute-Session-Id درخواست برچسب نشست/مکالمه ارائهشده توسط فراخواننده (همچنین حافظه را تغذیه میکند). در صورت وجود، بدون تغییر در call_logs.session_tag برای انتساب هزینه بهازای هر نشست (#8249) ذخیره میشود — در صورت نبود هرگز ساخته نمیشود
Idempotency-Key درخواست کلید حذف موارد تکراری (بازه ۵ ثانیهای)
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 (دلار آمریکا، با ۱۰ رقم اعشار ثابت؛ 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 هرگز ایمیل یا هویت حساب تولیدشدهای را جایگزین نمیکند. مقدار ارائهدهنده، یک برچسب نمایشی غیرحساس است و هرگز شناسه تولیدشده یک ارائهدهنده سازگار نیست. اطلاعات اعتبارسنجی، توکنها، کوکیها، شناسههای خام اتصال یا کلید 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 پروفایل پیشفرض برگرفته از پنل را اعمال میکند (پروفایل فعال نادیده گرفته میشود). موتورهای اتلافی خاموش باقی میمانند.
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) و هرگز تعبیهسازی یا بازرتبهبندی ارائه نمیکند.

مدلهای رجیستری که پشتیبانی چندوجهی را اعلام میکنند، حداکثر ۳۲ آیتم ساختاریافته و مستقل از ارائهدهنده را نیز میپذیرند. انواع آیتمهای رسانهای عبارتاند از 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 عمومی و تثبیت اتصال) و پیش از فراخوانی ارائهدهنده بهصورت درونخطی درج میشوند. آیتمهای بومی Jina از نوع {image:"https://..."} پس از همان بررسی عمومیبودن HTTPS، بدون تغییر ارسال میشوند؛ Jina آن URL را واکشی میکند.
  • رسانههای base64 درونخطی به ۸ MiB دادهٔ رمزگشاییشده برای هر آیتم و ۱۶ MiB دادهٔ رمزگشاییشده در کل درخواست محدود هستند.

ترجمه برای ارائهدهندگان (آیتمهای متعارف هرگز بدون تغییر ارسال نمیشوند):

  • مدلهای چندوجهی Jina: هر آیتم سطح بالا به یک شیء دارای کلید وجه (text / image / audio / video / pdf) تبدیل میشود که برای رسانههای درونخطی از URIهای داده استفاده میکند؛ برای هر آیتم سطح بالا یک بردار تولید میشود.
  • خانوادهٔ Gemini Embedding 2: یک آرایهٔ سطح بالا به یک درخواست بومی models/{model}:embedContent با content.parts (text یا inline_data) تبدیل میشود.
  • llama.cpp (llama-cpp/<model>، هر مدلی که سرور محلی بارگذاری کرده باشد): آیتمهای متعارف text به رشتههای ساده تبدیل میشوند و هرکدام از image / audio / video به یک شیء {"content": [part]} تبدیل میشوند؛ این کار با استفاده از بخشهای محتوای گفتوگوی llama-server (image_url، input_audio با قالب wav / mp3 / flac و input_video) و دادههای درونخطی انجام میشود؛ برای هر آیتم سطح بالا یک بردار تولید میشود. سرور باید با --embedding --mmproj … اجرا شود؛ بدون پروژکتور، خود سرور رسانه را رد میکند. document پشتیبانی نمیشود.
  • مدلهای ناشناخته/پویا که فرادادهٔ صریحی دربارهٔ وجه ندارند، ورودی ساختاریافته را با HTTP 400 رد میکنند.
{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}

ترکیبهای پشتیبانینشدهٔ مدل/وجه، بهجای تبدیل اجباری آیتم، HTTP 400 برمیگردانند. فیلدهای توسعهای غیرورودی در درخواستهای قدیمی رشتهای/توکنی همچنان بدون تغییر عبور داده میشوند.

# فهرستکردن همهٔ مدلهای تعبیهسازی
GET /v1/embeddings

تولید تصویر

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

{
  "model": "openai/gpt-image-2",
  "prompt": "A beautiful sunset over mountains",
  "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 فراخوانی جداگانه بالادستی انجام میشود که حداکثر ۴ مورد از آنها بهطور همزمان در حال اجرا خواهند بود. یک seed ثابت بر اساس اندیس فراخوانی افزایش مییابد (seed، seed + 1، …)، بنابراین تصاویر متفاوت هستند اما همچنان قابلیت بازتولید دارند. مقدار n حداکثر ۱۰ است. اگر هرکدام از فراخوانیها ناموفق باشد، کل درخواست ناموفق خواهد بود. فهرست قالبهای fan-out در 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 بستگی دارد. به API مربوط به Vertex در 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 بدون پیشوند) همگام — پاسخ مستقیماً از تنها فراخوانی بالادستی برگردانده میشود.
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": "# Extracted text..." }],
  "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 را هر ثانیه و حداکثر طی ۳۰ تلاش نظرسنجی میکند، در صورت دریافت پاسخ نظرسنجی غیر ok یا وضعیت "failed" بلافاصله شکست میخورد (به نظرسنجی ادامه نمیدهد) و اگر پس از تمامشدن تعداد تلاشهای مجاز، عملیات همچنان در حال اجرا باشد، 504 برمیگرداند. پاسخ نهایی Azure پیش از بازگرداندهشدن به فراخواننده، به همان ساختار pages/markdown مورد استفاده Mistral نرمالسازی میشود؛ بنابراین کد کلاینت نیازی ندارد برای این ارائهدهنده حالت خاصی در نظر بگیرد.

احراز هویت و تفکیک نقطه پایانی Vertex AI DeepSeek OCR

vertex-deepseek-ocr از همان احراز هویت Vertex AI که OmniRoute از قبل برای ترافیک چت/تصویر پشتیبانی میکند، مجدداً استفاده میکند (open-sse/executors/vertex.ts): کلید API اتصال یا یک اعتبارنامه JSON حساب سرویس است (که از طریق جریان JWT-bearer با یک توکن دسترسی OAuth کوتاهعمر مبادله میشود) یا یک توکن دسترسی OAuth از قبل صادرشده که بدون تغییر استفاده میشود. URL نقطه پایانی بالادستی، نقطه پایانی عمومی شریک openapi/chat/completions در Vertex است که با استفاده از پروژه و منطقه اتصال ساخته میشود — مقدار صریح providerSpecificData.project/providerSpecificData.region همیشه اولویت دارد؛ در غیر این صورت، پروژه از project_id موجود در JSON حساب سرویس استخراج میشود و مقدار پیشفرض منطقه 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 برمیگرداند

قیمت مدلها (pricing)

هنگامی که OmniRoute قیمت مدل را بداند، ورودی مربوطه دارای یک شیء pricing خواهد بود. قیمت از جدول قیمتگذاری مورد استفاده برای محاسبه هزینه میآید: مقادیر پیشفرض داخلی، قیمتهای همگامشده و بازنویسیهای تنظیمشده از طریق /api/pricing. اینها قیمتهای فهرست هستند، بنابراین ارائهدهندگان اشتراکی نیز قیمت بهازای هر توکن را نمایش میدهند.

"pricing": {
  "prompt": "0.000005",
  "completion": "0.000025",
  "input_cache_read": "0.0000005",
  "input_cache_write": "0.00000625",
  "input": 5,
  "output": 25,
  "cached": 0.5,
  "cache_creation": 6.25
}
فیلدها واحد توضیحات
prompt, completion, input_cache_read, input_cache_write دلار آمریکا بهازای هر توکن، رشته اعشاری سازگار با OpenRouter و هرگز با نمادگذاری نمایی نمایش داده نمیشود. دو فیلد کش فقط زمانی ظاهر میشوند که قیمتی برای کش وجود داشته باشد.
input, output, cached, cache_creation دلار آمریکا بهازای ۱ میلیون توکن، عدد فیلدهایی از نسخههای قبلی کاتالوگ که برای کلاینتهای موجود حفظ شدهاند. هنگامی که ردیف قیمتگذاری شامل reasoning و long_context باشد، آنها نیز ظاهر میشوند.
  • ترکیبها قیمت نخستین مقصد قابلمشاهده خود را دارند. ترکیبهای داخلی auto/* در زمان درخواست یک مقصد را انتخاب میکنند، بنابراین pricing ندارند.
  • مدلهای رایگان هنگامی که قیمتشان صفر باشد، "0" (و 0) را نمایش میدهند. مدلی که ردیف قیمتگذاری ندارد نیز هنگامی "0" را نمایش میدهد که کاتالوگ آن را رایگان علامتگذاری کرده باشد (free: true) یا کاتالوگ داخلی مدلهای رایگان آن را فهرست کرده باشد.
  • قیمت نامشخص: ورودی فاقد کلید pricing است.
  • ارائهدهندگان مبتنی بر اعتبار (مانند Kiro) بهجای هر توکن، بهازای هر درخواست هزینه دریافت میکنند. ورودیهای آنها فیلدهای عددی بهازای ۱ میلیون توکن قبلی را حفظ میکنند و هیچ فیلد رشتهای بهازای هر توکن ندارند.
  • گونهها (شناسههای میزان تلاش استدلال، نامهای مستعار بدون تفکر، آینههای اکتشاف و درگاه) قیمت مدلی را که درخواستها را به آن هدایت میکنند، کپی میکنند.
  • این فیلدها فقط نرخهای پایه را در بر میگیرند. سطوح زمینه طولانی (فیلد عددی long_context) و ضرایب سطح سرویس (برای مثال Codex سریع یا انعطافپذیر) مقدار prompt یا completion را تغییر نمیدهند.
  • این شیء برای همه شیوههای احراز هویت یکسان است، از جمله درخواست به سبک Anthropic با x-api-key و anthropic-version (پاسخ همچنان { "object": "list", "data": [...] } باقی میماند). پیادهسازی: src/app/api/v1/models/catalogPricing.ts.

پیشوندهای شناسه مدل (?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   # همه قابلیتهای فهرستشده باید درست باشند
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 ۱ تا ۲۰۰ نویسه

یک مقدار ناشناخته، یا یک 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-safe افزونه ارائهدهنده را برمیگرداند که توسط Bifrost، CLIProxyAPI و مسیریابهای sidecar آینده استفاده میشود. پاسخ از رجیستری ارائهدهندگان TypeScript تولید میشود و عمداً اسرار کلاینت OAuth، تفکیک محیط زمان اجرا، توابع اجراکننده، هدرهای درخواست و دادههای حساب را شامل نمیشود.

زمانی از این نقطه پایانی استفاده کنید که یک sidecar خارج از پردازش اجرا میشود و نمیتواند open-sse/config/providerPluginManifestRegistry.ts را مستقیماً import کند.

تولید صوت ElevenLabs

یک اتصال ارائهدهنده elevenlabs را در OmniRoute با کلید API مربوط به ElevenLabs پیکربندی کنید. کلاینتها با کلید OmniRoute خود احراز هویت میکنند (Authorization: Bearer $OMNIROUTE_API_KEY)؛ دروازه، کلید ذخیرهشده ارائهدهنده را بهعنوان xi-api-key ارسال میکند. هرگز کلید ElevenLabs را بهعنوان توکن bearer دروازه ارسال نکنید.

روش مسیر پاسخ دستهبندی نقطه پایانی کلید API
POST /v1/sound-generation بایتهای صوتی بومی elevenlabs
POST /v1/music بایتهای صوتی بومی music
POST /v1/music/stream بایتهای صوتی جریانی music
POST /v1/music/detailed صوت multipart بومی و طرح آهنگسازی music
POST /v1/music/detailed/stream فراداده SSE بومی و قطعههای صوتی music
POST /v1/music/plan طرح آهنگسازی JSON music

این نقاط پایانی، مسیرهای موجود /v1/audio/speech، /v1/audio/transcriptions، /v1/voices، /v1/text-to-speech/{voiceId} و /v1/speech-to-text را تکمیل میکنند. فیلدهای JSON بومی و پارامترهای کوئری مانند output_format و enable_logging حفظ میشوند. پاسخهای /v1/music/detailed مرزهای multipart خود را حفظ میکنند؛ آنها را بهصورت multipart تجزیه کنید. /v1/music/detailed/stream نوع text/event-stream را با فراداده آهنگسازی و قطعههای صوتی base64 در رویدادهای SSE برمیگرداند. هر شش مسیر از پیشدرخواست CORS پشتیبانی میکنند.

export OMNIROUTE_BASE_URL="http://localhost:20128"
export OMNIROUTE_API_KEY="your-omniroute-api-key"

# یک جلوه صوتی کوتاه. مدتزمان: ۰٫۵ تا ۳۰ ثانیه.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/sound-generation?output_format=mp3_44100_128" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"A single soft bell chime","duration_seconds":1,"model_id":"eleven_text_to_sound_v2"}' \
  --output effect.mp3

# مدتزمان موسیقی بر حسب میلیثانیه بیان میشود: ۳۰۰۰ تا ۶۰۰۰۰۰.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music?output_format=mp3_44100_128" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Gentle instrumental piano","music_length_ms":10000,"force_instrumental":true,"model_id":"music_v1"}' \
  --output music.mp3

برای تحویل تدریجی صوت، از /v1/music/stream با همان بدنه JSON استفاده کنید. آهنگسازی دقیقاً یکی از prompt یا composition_plan را میپذیرد؛ /v1/music/plan به prompt نیاز دارد و بهصورت اختیاری source_composition_plan را میپذیرد. طرحوارههای بومی، فیلدهای اضافی ارائهدهنده را حفظ میکنند تا نسخههای طرح آهنگسازی و گزینههای تنظیم دقیق به ElevenLabs برسند.

نقطه پایانی یکپارچه /v1/music/generations نیز elevenlabs/music_v1، elevenlabs/music_v2 و elevenlabs/music_v2_5 را میپذیرد. با یک اتصال فعال ElevenLabs، این مدلها از طریق کاتالوگ موسیقی ارائه میشوند. این نقطه پایانی {"created":...,"data":[{"b64_json":"...","format":"mp3"}]} را برمیگرداند. فیلد duration آن بر حسب ثانیه است و به music_length_ms نگاشت میشود؛ مقدار صریح music_length_ms اولویت دارد. instrumental به force_instrumental نگاشت میشود و فیلد بومی اولویت دارد. برای استریم از نقاط پایانی استریم بومی و برای درخواستهایی که صرفاً توسط یک طرح آهنگسازی هدایت میشوند، از نقطه پایانی آهنگسازی بومی استفاده کنید.

curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music/generations" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs/music_v1","prompt":"Gentle instrumental piano","duration":10,"instrumental":true}'

محدودیتهای نقطه پایانی، مدل، بودجه و اتصال پیش از فراخوانی سرویس بالادستی اعمال میشوند. مسیرهای بومی، کدهای وضعیت و بدنههای خطای سرویس بالادستی را بدون تغییر برمیگردانند، از جمله 402 برای یک محدودیت طرح و 429 برای محدودیت سهمیه. هدرهای character-cost، song-id، request-id و retry-after در صورت وجود حفظ میشوند. موجودی اعتبار رایگان، دسترسی به همه مدلهای موسیقی، قالبهای خروجی یا قابلیتهای API را تضمین نمیکند: ElevenLabs استحقاق دسترسی هر درخواست را تعیین میکند. نقطه پایانی یکپارچه، کدهای وضعیت خطا را در پوشش خطای نرمالسازیشده OmniRoute حفظ میکند.

قراردادهای سرویس بالادستی: جلوههای صوتی، آهنگسازی موسیقی و جزئیات موسیقی جریانی.

نقاط پایانی سازگاری

متد مسیر قالب
POST /v1/chat/completions OpenAI
POST /v1/messages Anthropic
POST /v1/responses پاسخهای OpenAI
POST /v1/embeddings OpenAI
POST /v1/images/generations تصاویر OpenAI
POST /v1/images/edits تصاویر OpenAI (ویرایش/ترمیم)
POST /v1/videos/generations تولید ویدئو به سبک OpenAI
POST /v1/music/generations تولید موسیقی به سبک OpenAI
POST /v1/audio/transcriptions صوت OpenAI (تبدیل گفتار به متن)
POST /v1/audio/speech تبدیل متن به گفتار OpenAI (بدنهٔ صوتی برمیگرداند)
POST /v1/rerank بازرتبهبندی به سبک Cohere/Voyage
POST /v1/classify دستهبندی Jina (api.jina.ai)
POST /v1/segment قطعهبند Jina (segment.jina.ai)
POST /v1/moderations تعدیل محتوای OpenAI
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
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": "..." }

# تبدیل متن به گفتار — بدنهٔ audio/mpeg (یا قالب درخواستی) را برمیگرداند
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# تبدیل متن به گفتار Soniox به یک زبان و یک صدا نیاز دارد: مقدار پیشفرض `language` برابر با "en" است؛ صدای
# مشخصنشده یا نام یکی از صداهای استاندارد OpenAI (alloy، nova، …) به "Adrian" تبدیل میشود
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }

# ویرایش تصویر (چندبخشی)
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": "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 یا پراکسی سنجاقشدهٔ یک اتصال فراخوانی نمیشوند). گرههای مستقر روی هر میزبان دیگری — مانند یک دستگاه در 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 برمیگردانند.

API فایلها

نقطه پایانی سازگار با OpenAI برای ورودی/خروجی دستهای و بارگذاری فایل با هدف مشخص.

روش مسیر توضیحات
POST /v1/files بارگذاری فایل (چندبخشی: 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 — فایلها از طریق getApiKeyRequestScope بهازای هر کلید API محدودهبندی میشوند. هر کلید فقط فایلهای متعلق به خودش را میبیند، دانلود و حذف میکند؛ نشست داشبورد بدون کلید، کل نمونه را میخواند؛ دسترسی به فایلی بدون مالک (بارگذاری ناشناس یا از طریق نشست داشبورد) برای هر فراخواننده فاقد نشست رد میشود. GET /v1/files درخواست فراخواننده ناشناس — و کلید ارائهشدهای که قابل شناسایی نیست — را حتی زمانی که REQUIRE_API_KEY=false باشد، بهجای فهرستکردن فایلهای همه مستأجرها، با 401 رد میکند (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 درخواست فراخواننده ناشناس را حتی زمانی که REQUIRE_API_KEY=false باشد، با 401 رد میکند.

جستجوی API

انتزاع ارائه دهنده Web/search (Tavily، Brave، Exa، Serper و غیره).

روش مسیر توضیحات
GET /v1/search قابلیت های + ارائه دهندگان جستجوی پیکربندی شده را فهرست کنید
POST /v1/search یک عبارت جستجوی — را اجرا کنید که توسط v1SearchSchema تأیید شده است، از caching/coalescing پشتیبانی می کند
GET /v1/search/analytics آمار hit/latency/cache هر ارائه دهنده

احراز هویت: کلید حامل API (extractApiKey + isValidApiKey). سیاست جستجو از طریق enforceApiKeyPolicy اجرا شد.

اگزا و طویلی provider_options

Exa و Tavily فیلدهای خاص ارائه دهنده را از یک کیسه namespaced می خوانند: provider_options.exa (یا provider_options["exa-search"]) و provider_options.tavily (یا provider_options["tavily-search"]). فقط کلیدهای زیر فوروارد می شوند. هر کدام با طرح Zod خود در open-sse/handlers/search/providerOptionsPassthrough.ts بررسی می شود و یک کلید با نوع اشتباه حذف می شود. هر کلید دیگری از جمله auth، base URL، stream و outputSchema نادیده گرفته میشود. کلیدهای مسطح استفاده شده توسط سایر ارائه دهندگان (cx، depth، ...) مانند قبل کار می کنند.

ارائه دهنده زمینه های سطح بالا تو در تو
امتحان type, category, userLocation, moderation, additionalQueries, objective, systemPrompt, compliance (ابتدایی مسطح) , startPublishedDate, endPublishedDate contents.{text, highlights, summary, extras, livecrawlTimeout, maxAgeHours} روی { text: true, highlights: true } پیشفرض ادغام شد
تاویلی 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" را نگه میدارد. طویلی نیز search_type: "finance" (topic: "finance") را می پذیرد.

هزینه جستجوی Firecrawl برای هر بلوک شروع شده از 10 نتیجه بازگشتی، 0.002 دلار (2 اعتبار) هر بلوک و حداقل یک بلوک در هر تماس ( صورتحساب Firecrawl ) ثبت می شود: 11 نتیجه 0.004 دلار هزینه دارد.

time_range عمومی اکنون به هر دو ارائهدهنده میرسد: Exa startPublishedDate (مهر زمانی ISO ) و Tavily start_date (YYYY-MM-DD) دریافت میکند. تاریخ صریح در provider_options تاریخ نگاشت شده را لغو می کند.

نتایج Exa id, highlight_scores, summary, subpages, entities و extras را در provider_raw نگه می دارند . طویلی نتایج حفظ images و favicon.

هزینه جستجوی پیوند 0.005 دلار برای depth fast و standard و 0.05 دلار برای deep ( قیمت گذاری پیوندها ) ثبت می شود، چه depth از provider_options باشد یا از تنظیمات اتصال.

Exa type: "lite" (Exa 3.0) مجموعه کوچکتری از فیلدها را می پذیرد و در صورت تنظیم هر فیلد دیگری، کل درخواست را رد می کند. برای lite، additionalQueries، systemPrompt و هر کلید contents به جز text و highlights قبل از تماس حذف میشوند. subpages، subpageTarget، highlights.numSentences و highlights.highlightsPerUrl منسوخ شده دیگر ارسال نمیشوند.

حسابداری بهای تمام شده costPerQuery ثبت ثابت است، به جز Exa، که از قیمت گذاری خود Exa پیروی می کند: 0.007 دلار در هر تماس برای auto (و fast میراث) یا 0.004 دلار برای lite (و instant میراث)، که 10 نتیجه را پوشش می دهد. 0.001 دلار برای هر نتیجه بعدی؛ و 0.001 دلار به ازای هر نتیجه برگشتی زمانی که contents.summary تنظیم شود. Tavily با 1 اعتبار (0.008 دلار) برای search_depth basic، fast و ultra-fast، و 2 اعتبار (0.016 دلار) برای advanced ( اعتبارات Tavily API ) ثبت شده است. تماس با auto_parameters: true که Tavily آن را به پیشرفته ارتقا میدهد همچنان با 1 اعتبار ثبت میشود.

API واکشی وب

محتوا را از یک URL از طریق ارائهدهنده پیکربندیشده واکشی وب (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 معمولی) در زمان درخواست به ارائهدهنده بعدیِ امتحاننشده که دارای اعتبارنامه است منتقل میشود. وقتی همه ارائهدهندگان مخزن به پایان برسند، نقطه پایانی بهجای 400 عمومی قبلی، یک 429 واحد (همراه با هدر Retry-After) برمیگرداند. وقتی یک provider مشخص درخواست شود، هیچ بازگشت جایگزین پنهانیای وجود ندارد — ارائهدهنده مشخصی که با محدودیت نرخ یا خرابی مواجه شده باشد، خطای خودش را نمایش میدهد (429 در صورت محدودیت نرخ، وگرنه وضعیت سرویس بالادستی).

استریم WebSocket

GET /v1/ws?handshake=1

یک هندشیک ارتقای WebSocket را اعتبارسنجی میکند و پیامهای نمونه پروتکل انتقال (request، cancel) را برمیگرداند. فریمهای واقعی WS توسط سرور WS همراهشده در خارج از جدول مسیرهای Next.js مدیریت میشوند.

احراز هویت: کلید API از نوع Bearer هنگام هندشیک.

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 را انتخاب میکند و از طریق انتقالدهنده wreq-js به wss://chatgpt.com/backend-api/codex/responses تونل میزند. مدلهای غیر codex رد میشوند (codex_ws_provider_required). برای مسیریابی اشتراک سهمیه از model: "qtSd/<group>/codex/<model>" استفاده کنید. پیادهسازی در app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts قرار دارد.

احراز هویت: کلید 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 به ارائهدهنده دیگری مسیریابی میشد.

پیکربندی Codex CLI مربوط به OpenAI

با افزودن یک ارائهدهنده سفارشی دارای پشتیبانی WebSocket به ~/.codex/config.toml، Codex CLI را به OmniRoute متصل کنید (برای جلوگیری از تغییر پیکربندی موجود، از یک 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"   # بدون اسلش پایانی؛ URL مربوط به 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 باقی میماند.

درصدهای سهمیه خام در برابر درصدهای تعدیلشده با حد توقف

هنگام استفاده از /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(...)).

مثال توضیحی

پنجره یک ارائهدهنده را با ۶۰٪ استفاده خام (و در نتیجه ۴۰٪ سهمیه خام باقیمانده) و آستانه حد توقف ۲۵٪ از سهمیه باقیمانده در نظر بگیرید:

نمایش محاسبه باقیمانده استفاده ضمنی
JSON خام (?format=json) نمای فوری بالادستی (quotas[window]) ۴۰٪ ۶۰٪
قالب متنی (NN% left) ((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100 ۲۰٪ ۸۰٪ (در صورت محاسبه 100 - remaining)
  • چرا متن ۲۰٪ باقیمانده را نشان میدهد: از ۴۰٪ سهمیه فیزیکی باقیمانده حساب، ۲۵٪ توسط سیاست حد توقف رزرو شده است. فراخوان فقط ۱۵٪ از مجموع ۷۵٪ فضای قابلاستفاده را پیش از آنکه مسیریاب هدایت درخواستها به این اتصال را متوقف کند، در اختیار دارد. مقیاسبندی تضمین میکند که اتصال دقیقاً زمانی پایان ظرفیت (0% left) را اعلام کند که مسیریابی متوقف خواهد شد.
  • چرا JSON مقادیر خام را حفظ میکند: بار JSON نمای فوری دقیق ارائهدهنده (UsageSnapshot) را برمیگرداند تا ابزارهای خارجی بدون مقیاسبندی اتلافی سمت سرور، به میزان بهرهبرداری واقعی بالادستی و quotaWindowThresholds در سطح اتصال دسترسی داشته باشند.

راهنمای مهاجرت مصرفکنندگان

اگر یک یکپارچهسازی خارجی (مانند افزونهٔ ویرایشگر یا افزونهٔ عامل) قبلاً endpoint متنی (NN% left) را استخراج میکرد و درصد استفادهشده را بهصورت 100 - NN محاسبه میکرد، مهاجرت به ?format=json به این معناست:

  • خواندن مقادیر خام JSON، مصرف واقعی بالادستی را منعکس خواهد کرد (در مثال بالا، 60٪ استفادهشده).
  • اگر یکپارچهسازی بخواهد معناشناسی میزان مجازِ قابلاستفاده در endpoint متنی را حفظ کند، میتواند فرمول مؤثرِ مقدار باقیمانده را در سمت کلاینت و با استفاده از quotaWindowThresholds برای بازنویسیهای سطح اتصال ارزیابی کند.

کش معنایی

# دریافت آمار کش
GET /api/cache/stats

# پاککردن همه کشها
DELETE /api/cache/stats

نمونه پاسخ:

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

تأثیر بر تأخیر

در صورت اصابت به کش معنایی، پاسخ بدون فراخوانی بالادستی از کش ارائه میشود؛ بنابراین مقدار گزارششده برای 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 و ارائهدهندگان عادی ساختار بومی درخواست خود را حفظ میکنند. برای اجبار به عبور عادی reasoning_effort در OpenAI، reasoningControl را روی openai تنظیم کنید؛ یا برای استفاده از تشخیص خودکار، آن را حذف کنید/روی null قرار دهید.

درخواستهای طبقهبند حالت خودکار Claude Code، هنگامی که فاقد کنترلهای صریح استدلال باشند، حالت بومی تفکر را بهطور پیشفرض غیرفعال میکنند. تشخیص از نشانگر سیستمی طبقهبند در درخواستهای قالب Claude استفاده میکند، نه از نام مدلها یا محدودیتهای تکمیل. کنترلهای صریح بدنه، سرآیندهای پشتیبانیشده تلاش/تفکر، قوانین مسیریابی و سطح تلاش نهایی مدل، اولویت فعلی خود را حفظ میکنند. هر دو مرحله طبقهبند، پرامپتها، محدودیتهای تکمیل، توالیهای توقف و نتایج واقعی مجوزدهی بالادستی خود را حفظ میکنند؛ مرحله دوم همچنان میتواند استدلال قابلمشاهده درخواستی خود را بهصورت متن عادی تولید کند.

جریانهای OAuth

نقطه پایانی متد توضیحات
/api/oauth/[provider]/[action] مختلف OAuth مختص ارائهدهنده

مسیریابی و پیکربندی

نقطه پایانی متد توضیحات
/api/models/alias GET/POST نامهای مستعار مدل
/api/models/catalog GET همه مدلها بر اساس ارائهدهنده و نوع
/api/combos* متنوع مدیریت ترکیبها
/api/keys* متنوع مدیریت کلید API
/api/pricing GET قیمتگذاری مدل

استفاده و تحلیلها

نقطه پایانی متد توضیحات
/api/usage/history GET تاریخچه استفاده
/api/usage/logs GET گزارشهای استفاده
/api/usage/request-logs GET گزارشهای سطح درخواست
/api/usage/[connectionId] GET میزان استفاده بهازای هر اتصال
/api/usage/token-limits GET/POST/DELETE بودجه محدودیت توکن بهازای هر کلید API
/api/usage/model-latency-stats GET تجمیع چرخشی تأخیر بهازای هر ارائهدهنده/مدل (میانگین/p50/p95/p99، نرخ موفقیت)؛ فیلترها: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health GET خلاصه سلامت کش پرامپت بر روی call_logs — نسبت نوشتن/خواندن، توزیع اندازه نوشتن در p50/p90/p99، تمرکز نوشتنهای سنگین، تفکیک بر اساس مدل و نتیجه ارزیابی healthy/degraded/thrash/no-data؛ پارامترهای کوئری range (1h|24h|7d|30d، پیشفرض 24h) و model اختیاری (#8827)

مجوزهای کلید API

PATCH /api/keys/{id} مجوزهای یک کلید موجود را بهروزرسانی میکند. مانند همه مسیرهای /api/keys*، این مسیر به مجوز مدیریتی نیاز دارد (به احراز هویت مدیریتی مراجعه کنید)، نه کلید استنتاج. فقط فیلدهایی را ارسال کنید که میخواهید تغییر دهید؛ درخواستی که هیچیک از آنها را نداشته باشد با No valid fields to update رد میشود. فیلدهای پذیرفتهشده توسط updateKeyPermissionsSchema در src/shared/validation/schemas/keys.ts تعریف شدهاند.

فیلد نوع توضیحات
name رشته، ۱ تا ۲۰۰ نویسه
isActive بولی
isBanned بولی
expiresAt تاریخوزمان ISO 8601 یا null null تاریخ انقضا را پاک میکند
modelAccessMode all | restricted وقتی حالت all است، allowedModels باید خالی باشد
allowedModels, blockedModels آرایهای از رشتهها، حداکثر ۱۰۰۰ مورد
allowedCombos آرایهای از رشتهها، حداکثر ۵۰۰ مورد تعیین میکند کلید مجاز به فراخوانی کدام کمبوها است؛ مدلهای مستقیم توسط modelAccessMode / allowedModels کنترل میشوند
connectionAccessMode all | restricted در حالت restricted، مقدار allowedConnections نباید خالی باشد و در حالت all باید خالی باشد
allowedConnections آرایهای از UUIDها، حداکثر ۱۰۰ مورد
allowAutoCombos بولی مقدار false درخواستهای مدلهای auto/* با این کلید را رد میکند؛ کلیدهایی که هرگز آن را تنظیم نکردهاند مجاز هستند
catalogScope all | combos | models مشخص میکند GET /v1/models چه مواردی را برای این کلید فهرست کند (فقط کمبوها، فقط مدلها یا هر دو)؛ این گزینه موارد قابل فراخوانی توسط کلید را تغییر نمیدهد
forcedModel رشتهای با حداکثر ۳۰۰ نویسه، یا null درخواستهای چت را با اولویت بالاتر از X-Route-Model و body.model به این مدل/کمبو هدایت میکند؛ محدودیتهای کلید همچنان اعمال میشوند
noLog, autoResolve بولی
throttleDelayMs عدد صحیح، ۰ تا ۳۰۰۰۰۰
maxSessions عدد صحیح، ۰ تا ۱۰۰۰۰
rateLimits آرایهای از { limit, window } (اعداد صحیح مثبت، حداکثر ۵۰ مورد) یا null null محدودیتها را پاک میکند
accessSchedule شیء زمانبندی یا null null زمانبندی را پاک میکند
scopes آرایهای از رشتهها، حداکثر ۳۲ مورد
allowedEndpoints آرایهای از رشتهها، حداکثر ۲۰ مورد
streamDefaultMode legacy | json
cacheDefaultMode legacy | bypass به دور زدن کش برای هر کلید مراجعه کنید
compressionEnabled بولی
codexServiceMode یکی از حالتهای سرویس Codex
disableNonPublicModels boolean
allowUsageCommand boolean
usageLimitEnabled boolean
dailyUsageLimitUsd, weeklyUsageLimitUsd number >= 0 یا null
chaosModeEnabled boolean 
curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \
  -H "Authorization: Bearer <management-credential>" \
  -H "Content-Type: application/json" \
  -d '{ "allowAutoCombos": false, "catalogScope": "combos" }'

تنظیمات

نقطه پایانی متد توضیحات
/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 بررسی سختگیرانه حلقه بازگشتی مورداعتماد پیش از احراز هویت/کاوش مدیریتی؛ وضعیت دسترسپذیری و نسخههای پاکسازیشده FFmpeg/ffprobe (بدون ذخیرهسازی)
/api/modality-bridge/video/extract POST کارگزار داخلی و احرازشده بایت روی حلقه بازگشتی مورداعتماد؛ ورودی 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 Various عملیات همگامسازی ابری
/api/sync/initialize POST مقداردهی اولیه همگامسازی
/api/cloud/* Various مدیریت فضای ابری

تونلها

نقطه پایانی متد توضیحات
/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) است.

تابآوری و محدودیت نرخ

Endpoint Method Description
/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/POST وضعیت محدودیت نرخ برای هر حساب (GET) یا فعال/غیرفعالکردن محافظت در برابر محدودیت نرخ برای یک اتصال (POST با {connectionId, enabled}). مسیر نوشتن پشتیبانیشده برای rateLimitProtection (هرگز از طریق PUT /api/providers/[id] تغییر داده نمیشود). توجه: enabled: false محافظت صریح را غیرفعال میکند، اما اتصال فعال مبتنی بر کلید API را از سازوکار ایمنی فعالسازی خودکار سراسری (autoEnableApiKeyProviders) خارج نمیکند.
/api/rate-limit GET پیکربندی سراسری محدودیت نرخ (منسوخشده؛ نام مستعار /api/rate-limits)

هر چهار مسیر /api/resilience/* به احراز هویت مدیریتی (requireManagementAuth) نیاز دارند. برای شرح کامل تفاوت میان قطعکننده ارائهدهنده، دوره انتظار اتصال و قفل مدل، به تابآوری (توسعهیافته) مراجعه کنید.

ارزیابیها

Endpoint Method Description
/api/evals GET/POST فهرست مجموعههای ارزیابی / اجرای ارزیابی

سیاستها

Endpoint Method Description
/api/policies GET/POST/DELETE مدیریت سیاستهای مسیریابی

انطباق

Endpoint Method Description
/api/compliance/audit-log GET گزارش ممیزی انطباق (آخرین N مورد)

v1beta (سازگار با Gemini)

Endpoint Method Description
/v1beta/models GET فهرست مدلها در قالب Gemini
/v1beta/models/{...path} POST نقطه پایانی generateContent در Gemini

این نقاط پایانی، قالب API مربوط به Gemini را برای کلاینتهایی که به سازگاری بومی با SDK مربوط به Gemini نیاز دارند، بازتاب میدهند.

APIهای داخلی / سیستمی

Endpoint Method Description
/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 مربوط به بیلد در حال اجرا: 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 fallback رجیستری)، که با همان TTL دهدقیقهای latest کش میشود. latest همیشه وجود دارد (ابتدا به فیلد latest و سپس به "unavailable" برمیگردد)؛ next، nightly و lts تنها زمانی ظاهر میشوند که آن dist-tag وجود داشته باشد. درخواست Cache-Control: no-cache هر دو جستوجو را تازهسازی میکند.

مدل کانال (latest = v3 تا انتشار عمومی 4.0، next = rc، nightly = بیلدهای 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 "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 ممکن است در گزارشهای پراکسی معکوس، تاریخچه مرورگر و دادههای تلهمتری خارج از 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).

وبهوکها

اشتراکهای وبهوک خروجی برای رویدادهای OmniRoute (تکمیل درخواست، اتمام سهمیه، چرخش کلید و غیره).

متد مسیر توضیحات
GET /api/webhooks فهرست وبهوکها (مقادیر محرمانه بهشکل <prefix>... پوشانده میشوند)
POST /api/webhooks ایجاد وبهوک — بدنه: {url, events?: ["*"], secret?, description?}
GET /api/webhooks/[id] بازیابی یک وبهوک
PUT /api/webhooks/[id] بهروزرسانی url/events/secret/description
DELETE /api/webhooks/[id] حذف یک وبهوک
POST /api/webhooks/[id]/test ارسال یک payload آزمایشی به URL وبهوک و بازگرداندن وضعیت تحویل

احراز هویت: نشست مدیریت/کلید API (requireManagementAuth).

کلیدهای ثبتشده (مدیریت خودکار)

زیرسامانه مدیریت خودکار کلید از این موارد برای صدور و چرخش کلیدهای API در یک ارائهدهنده/حساب پشتیبان، با سهمیههای روزانه/ساعتی استفاده میکند.

متد مسیر توضیحات
GET /api/v1/registered-keys فهرست کلیدهای ثبتشده (فقط پیشوند پوشاندهشده)
POST /api/v1/registered-keys صدور یک کلید ثبتشده جدید — بدنه: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. کلید خام را فقط یکبار بازمیگرداند. در صورت رد بهدلیل سهمیه، 429 بازمیگرداند.
GET /api/v1/registered-keys/[id] بازیابی فراداده یک کلید ثبتشده (بدون داده خام)
DELETE /api/v1/registered-keys/[id] لغو یک کلید ثبتشده
POST /api/v1/registered-keys/[id]/revoke نقطه پایانی صریح برای لغو (با اثری یکسان با DELETE)

احراز هویت: نشست مدیریت/کلید API (requireManagementAuth) — همان محافظ /api/keys: یک نشست داشبورد، توکن محلی CLI، یا یک کلید API با دامنه manage/admin؛ کلیدهای API مختص استنتاج، 403 دریافت میکنند. همچنین /v1/quotas/check و /v1/issues/report را ببینید.

پروتکل عاملها

وظایف عامل ابری (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":"..."}}'

پروکسیهای مدیریتی

پروکسیهای خروجی HTTP(S)/SOCKS که میتوان آنها را به ارائهدهندگان، حسابها یا بهصورت سراسری اختصاص داد.

متد مسیر توضیحات
GET /api/v1/management/proxies فهرست پروکسیها (با ?id= یک مورد را برمیگرداند؛ با ?id=&where_used=1 گراف تخصیص را برمیگرداند)
POST /api/v1/management/proxies ایجاد پروکسی — بدنه توسط createProxyRegistrySchema اعتبارسنجی میشود
PATCH /api/v1/management/proxies بهروزرسانی پروکسی — بدنه توسط updateProxyRegistrySchema اعتبارسنجی میشود (id الزامی است)
DELETE /api/v1/management/proxies?id=...&force=1 حذف پروکسی (برای جدا کردن تخصیصها از force=1 استفاده کنید)
GET /api/v1/management/proxies/assignments فهرست تخصیصها — قابل فیلتر بر اساس proxy_id، scope، scope_id؛ برای تعیین پروکسی فعال یک اتصال، resolve_connection_id=<id> را ارسال کنید
PUT /api/v1/management/proxies/assignments تخصیص — بدنه توسط proxyAssignmentSchema اعتبارسنجی میشود ({scope, scopeId?, proxyId?}). کش توزیعکننده را پاک میکند
PUT /api/v1/management/proxies/bulk-assign تخصیص گروهی — بدنه توسط bulkProxyAssignmentSchema اعتبارسنجی میشود ({scope, scopeIds[], proxyId?})
GET /api/v1/management/proxies/health?hours=24 وضعیت سلامت تجمیعی پروکسی (تعداد موفقیت/شکست و تأخیر) در یک بازه زمانی

احراز هویت: نشست مدیریتی/کلید API در همه مسیرها الزامی است (requireManagementAuth).

POST /api/v1/management/proxies/[id]/assignments و POST /api/v1/management/proxies/[id]/health ذکرشده در توضیحات وظیفه، توسط مسیرهای مسطح /assignments و /health که در بالا نمایش داده شدهاند ارائه میشوند — در کدبیس هیچ زیرمسیر جداگانهای برای هر شناسه وجود ندارد.

تابآوری (توسعهیافته)

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 ← «وضعیت زمان اجرای تابآوری» و docs/architecture/RESILIENCE_GUIDE.md مراجعه کنید.

صف محدودیت نرخ و شبکه ایمنی فعالسازی خودکار

  • مسیر نوشتن پشتیبانیشده: POST /api/rate-limits با بدنه {"connectionId": "<id>", "enabled": true|false} نقطه پایانی مدیریتی پشتیبانیشده برای فعال یا غیرفعالکردن محافظت در برابر محدودیت نرخ برای یک اتصال است. PUT /api/providers/[id] عمداً rateLimitProtection را تغییر نمیدهد یا وارونه نمیکند (#11278).
  • معنای enabled: false: تنظیم enabled: false محافظت صریح اتصال را حذف میکند، اما یک اتصال فعال مبتنی بر کلید API را از شبکه ایمنی سراسری فعالسازی خودکار (autoEnableApiKeyProviders = true) خارج نمیکند. در reconcileEnabledConnections (open-sse/services/rateLimitManager.ts)، مقادیر false و undefined معادلاند؛ اتصالهای فعال مبتنی بر کلید API که محافظت صریح ندارند، همچنان تحت شبکه ایمنی فعالسازی خودکار محافظت میشوند.
  • غیرفعالسازی سراسری: برای اجرای اتصالهای مبتنی بر کلید API بدون صفهای محدودیت نرخ، شبکه ایمنی را بهصورت سراسری از طریق RATE_LIMIT_AUTO_ENABLE=false (متغیر محیطی) یا resilienceSettings.requestQueue.autoEnableApiKeyProviders = false (تنظیمات ← تابآوری / PATCH /api/resilience) غیرفعال کنید.

مهارتها

چارچوب مهارت برای گسترش 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). مقادیر enum برای type:‏ FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (به MemoryType در src/lib/memory/types.ts مراجعه کنید).

سرور MCP

OmniRoute همراه با یک سرور داخلی Model Context Protocol با ۳ انتقال (stdio، SSE، streamable-http) و ابزارهای دارای محدوده ارائه میشود. نقاط پایانی داشبورد در زیر، دادههای وضعیت/ممیزی را میخوانند و انتقالهای HTTP را پروکسی میکنند.

| متد | مسیر | توضیحات | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- | | GET | /api/mcp/status | ضربان حیات، انتقال، وضعیت آنلاین، آخرین فراخوانی، ابزارهای برتر، نرخ موفقیت ۲۴ ساعته | | GET | /api/mcp/tools | فهرست ابزارهای MCP بههمراه name، description، scopes، phase، auditLevel، sourceEndpoints | | GET | /api/mcp/sse | باز کردن جریان SSE برای انتقال SSE (اگر MCP غیرفعال باشد یا انتقال مطابقت نداشته باشد، 503 برمیگرداند) | | 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 (نام، توضیحات، قابلیتها، کاتالوگ مهارتها و طرح احراز هویت) را برمیگرداند — این کارت بهمدت 1h بهصورت عمومی کش میشود. نیازی به احراز هویت نیست.

ابزارهای کمکی REST

متد مسیر توضیحات
GET /api/a2a/status وضعیت فعال بودن A2A + آمار وظایف + خلاصه کارت عامل کششده
GET /api/a2a/tasks فهرست وظایف — ?state=submitted|working|completed|failed|cancelled، ?skill=، ?limit= (≤200)، ?offset=
POST /api/a2a/tasks (بهعنوان ابزار کمکی REST پیادهسازی نشده است — از طریق JSON-RPC و message/send ایجاد کنید)
GET /api/a2a/tasks/[id] بازیابی یک وظیفه
POST /api/a2a/tasks/[id]/cancel لغو یک وظیفه

احراز هویت: ابزارهای کمکی REST بدون احراز هویت مدیریتی اجرا میشوند (قابل خواندن توسط داشبورد)؛ مسیر JSON-RPC یعنی /a2a، در صورت پیکربندی، از Bearer OMNIROUTE_API_KEY استفاده میکند.

Cloud، Evals و Assess

| متد | مسیر | توضیحات | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | 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 را اعتبارسنجی میکند و فقط برای کلیدی با دامنه manage / admin، کلید ماسکشده و projectId هر اتصال را برمیگرداند؛ سایر مسیرهای /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
}

احراز هویت: به نشست مدیریتی (کوکی auth_token داشبورد) یا یک کلید API با محدودهٔ مدیریتی نیاز دارد.

برای جزئیات کامل، به چارچوب ACP مراجعه کنید.

تحلیل و مشاهدهپذیری

نقاط پایانی تحلیل بلادرنگ برای نظارت بر مسیریابی، فشردهسازی و تنوع ارائهدهندگان. این نقاط پایانی، صفحات /dashboard/analytics/* را پشتیبانی میکنند.

تحلیل مسیریابی خودکار

متد مسیر توضیحات
GET /api/analytics/auto-routing آمار تجمیعی مسیریابی خودکار: مجموع فراخوانیها، توزیع راهبردها، توزیع سطحها و برترین ارائهدهندگان
GET /api/analytics/auto-routing?days=7 آمار محدودشده به بازهٔ زمانی (پیشفرض ۲۴ ساعت)

نمونه پاسخ:

{
  "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= query)
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

احراز هویت: به نشست مدیریتی نیاز دارد.

مهارتهای عامل

مهارتهای عامل هوش مصنوعی را مدیریت کنید (مشابه GPTهای سفارشی 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 با محدوده مدیریتی نیاز دارد.

وبهوکها

اشتراکهای وبهوک برای رویدادها را مدیریت کنید.

متد مسیر توضیحات
GET /api/webhooks فهرست همه اشتراکهای وبهوک
POST /api/webhooks ایجاد یک اشتراک وبهوک — بدنه: {url, events[], secret?, active?}
GET /api/webhooks/[id] دریافت یک اشتراک وبهوک مشخص
PUT /api/webhooks/[id] بهروزرسانی یک اشتراک وبهوک
DELETE /api/webhooks/[id] حذف یک اشتراک وبهوک
GET /api/webhooks/[id]/deliveries فهرست تاریخچه تحویل برای یک وبهوک (گزارش موفقیت/شکست)
POST /api/webhooks/[id]/test ارسال یک رویداد آزمایشی به یک وبهوک

احراز هویت: به نشست مدیریتی نیاز دارد.

برای مشاهده همه انواع رویدادها، به چارچوب وبهوکها مراجعه کنید.

چارچوب مهارتها

مهارتها (چارچوب افزونههای عاملمحور) را مدیریت کنید.

متد مسیر توضیحات
GET /api/skills فهرستکردن همه مهارتهای نصبشده (داخلی + سفارشی)
POST /api/skills/install نصب یک مهارت از مسیر محلی یا URL
DELETE /api/skills/[id] حذف نصب یک مهارت
PUT /api/skills/[id] فعال یا غیرفعالکردن یک مهارت — بدنه: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST /api/skills/executions اجرای یک مهارت — بدنه: {skillName, apiKeyId, input?, sessionId?}
GET /api/skills/executions فهرستکردن تاریخچه اجرا برای همه مهارتها (فیلتر با ?apiKeyId=)

احراز هویت: به نشست مدیریتی یا کلید API با دامنه مدیریتی نیاز دارد.

برای جزئیات کامل، به چارچوب مهارتها مراجعه کنید.

افزونهها

افزونههای OmniRoute (افزونههای شخص ثالث) را مدیریت کنید.

متد مسیر توضیحات
GET /api/plugins فهرستکردن افزونههای نصبشده
POST /api/plugins/marketplace/install نصب یک افزونه از بازار
DELETE /api/plugins/[name] حذف نصب یک افزونه
POST /api/plugins/[name]/activate فعالکردن یک افزونه
POST /api/plugins/[name]/deactivate غیرفعالکردن یک افزونه
GET /api/plugins/[name]/config دریافت پیکربندی افزونه
PUT /api/plugins/[name]/config بهروزرسانی پیکربندی افزونه

احراز هویت: به نشست مدیریتی نیاز دارد.

برای جزئیات کامل، به چارچوب افزونهها مراجعه کنید.

مسیریابی سایه

مقایسه سایه / A-B ارائهدهندگان یک سطح REST مستقل نیست — این قابلیت از طریق مسیریابی ترکیبی پیکربندی میشود (به ترکیب خودکار مراجعه کنید). معیارهای مقایسه هر ترکیب از طریق GET /api/combos/metrics ارائه میشوند.

حفاظها

حفاظهای زمان اجرا (تشخیص PII، تشخیص تزریق پرامپت، پلزنی بینایی) را بررسی کنید. حفاظها در هر درخواست اجرا میشوند؛ انصراف برای هر فراخوانی از طریق هدر درخواست x-omniroute-disabled-guardrails انجام میشود — هیچ سطح ماندگاری برای فعال/غیرفعالسازی وجود ندارد.

متد مسیر توضیحات
GET /api/guardrails فهرستکردن حفاظهای ثبتشده و وضعیت آنها (نام / فعال / اولویت)
POST /api/guardrails/test اجرای آزمایشی خط لوله پیش از فراخوانی روی یک ورودی نمونه — بدنه: {input, disabledGuardrails?}

احراز هویت: به نشست مدیریتی نیاز دارد.

برای جزئیات کامل، به امنیت > حفاظها مراجعه کنید.

احراز هویت

برای آشنایی با چهار خانوادهٔ اعتبارنامه (نشست داشبورد، توکن CLI محلی، توکن دسترسی oma_live_… و کلید API با دامنهٔ مدیریتی) و تفاوت آنها با کلیدهای استنتاج، به احراز هویت مدیریتی مراجعه کنید.

  • مسیرهای داشبورد (/dashboard/*) از کوکی auth_token استفاده میکنند
  • ورود به سیستم از هش گذرواژهٔ ذخیرهشده استفاده میکند؛ در صورت عدم دسترسی، از INITIAL_PASSWORD استفاده میشود
  • گزینهٔ requireLogin از طریق /api/settings/require-login قابل تغییر است
  • مسیرهای /v1/* در صورت تنظیم REQUIRE_API_KEY=true میتوانند به کلید API از نوع Bearer نیاز داشته باشند
  • «توکن مدیریتی» / «کلید API با دامنهٔ مدیریتی» در این مرجع به یکی از خانوادههای ذکرشده در آن راهنما اشاره دارد — نه به یک نوع رمز محرمانهٔ اضافی و تعریفنشده

تغییر ناسازگار (v3.8.0) — مسیرهای /api/v1/agents/tasks/* و نقاط پایانی مدیریت دورهٔ انتظار اکنون به احراز هویت مدیریتی (کوکی auth_token داشبورد یا یک کلید API با دامنهٔ مدیریتی) نیاز دارند. کلاینتهایی که پیشتر این مسیرها را بدون احراز هویت فراخوانی میکردند، پاسخ 401 Unauthorized دریافت خواهند کرد. به کامیت 588a0333 (fix(auth): require management auth for agent and cooldown APIs) مراجعه کنید.