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

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 مراجعه کنید.

---

فهرست مطالب

• تکمیل چت
• اجارههای انحصاری نشست مدیریتشده
• تعبیهها
• تولید تصویر
• OCR سند
• لیست مدلها
• مانیفست افزونه ارائهدهنده
• نقاط پایانی سازگاری
• API فایلها
• API دستهها
• API جستجو
• استریمینگ WebSocket
• گزارشدهی سهمیهها و مشکلات
• کش معنایی
• داشبورد و مدیریت
• مدیریت ترکیبی
• وبهوکها
• کلیدهای ثبتشده (مدیریت خودکار)
• پروتکل عاملها
• پراکسیهای مدیریت
• تابآوری (توسعهیافته)
• مهارتها
• حافظه
• سرور MCP
• سرور A2A
• ابر، ارزیابیها و سنجش
• پردازش درخواست
• احراز هویت

---

تکمیل چت

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

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

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

هدر	جهت	توضیحات
X-OmniRoute-No-Cache	درخواست	برای دور زدن کش، روی true تنظیم شود
x-omniroute-no-memory	درخواست	برای این درخواست، تزریق حافظه + مهارتها را نادیده میگیرد (مشابه no-cache؛ از سربار توکن/هزینه به ازای هر فراخوانی جلوگیری میکند)
X-OmniRoute-Progress	درخواست	برای رویدادهای پیشرفت، روی true تنظیم شود
X-Session-Id	درخواست	کلید نشست چسبنده برای وابستگی نشست خارجی
x_session_id	درخواست	نوع آندرسکور نیز پذیرفته میشود (HTTP مستقیم)
X-OmniRoute-Session-Id	درخواست	برچسب نشست/مکالمه ارائهشده توسط تماسگیرنده (همچنین حافظه را تغذیه میکند). در صورت وجود، به صورت کلمهبهکلمه در call_logs.session_tag برای تخصیص هزینه به ازای هر نشست (8249#) ذخیره میشود — هرگز در صورت عدم وجود، سنتز نمیشود
Idempotency-Key	درخواست	کلید حذف تکرار (پنجره 5 ثانیه)
X-Request-Id	درخواست	کلید جایگزین حذف تکرار
X-OmniRoute-Cache	پاسخ	HIT یا MISS (غیر استریمینگ)
X-OmniRoute-Idempotent	پاسخ	true اگر تکرار حذف شده باشد
X-OmniRoute-Progress	پاسخ	enabled اگر ردیابی پیشرفت فعال باشد
X-OmniRoute-Session-Id	پاسخ	شناسه نشست مؤثر مورد استفاده OmniRoute
X-OmniRoute-Request-Id	پاسخ	شناسه همبستگی درخواست (در صورت معلوم بودن)
X-OmniRoute-Version	پاسخ	نسخه ساخت OmniRoute (همیشه موجود است)
X-OmniRoute-Cost-Saved	پاسخ	دلار آمریکا که کش در یک HIT از آن جلوگیری کرده است (فقط در صورت HIT کش)
X-OmniRoute-Decision	پاسخ	ردیابی مسیریابی: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> استراتژی ترکیبی است، یا single برای یک درخواست غیر ترکیبی) — همیشه در پاسخهای تکمیل موجود است

نکته Nginx: اگر به هدرهای آندرسکور (به عنوان مثال x_session_id) تکیه میکنید، underscores_in_headers on; را فعال کنید.

هدرهای تلهمتری هزینه: پاسخهای موفق غیرجریانی نیز مجموعه تلهمتری هزینه X-OmniRoute-* را حمل میکنند — X-OmniRoute-Response-Cost (دلار آمریکا، ثابت ۱۰ رقم اعشار؛ 0.0000000000 برای رایگان/بدون قیمتگذاری)، X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out، X-OmniRoute-Model، X-OmniRoute-Provider، X-OmniRoute-Latency-Ms، X-OmniRoute-Cache-Hit، و X-OmniRoute-Fallback-Attempts (فقط زمانی که > 0)، به علاوه X-OmniRoute-Request-Id و X-OmniRoute-Version. اینها توسط تکمیل چت، /v1/responses، /v1/messages، و نقاط پایانی رسانه — /v1/embeddings، /v1/images/generations، /v1/audio/speech، /v1/audio/transcriptions، /v1/rerank، /v1/videos/generations، /v1/music/generations، و /v1/moderations (همیشه هزینه 0) منتشر میشوند. هزینه رسانه بر اساس هر حالت (به ازای هر تصویر، به ازای هر ثانیه، به ازای هر کاراکتر، به ازای هر واحد جستجو) محاسبه میشود، در صورتی که قیمتگذاری موجود باشد، در غیر این صورت 0 (fail-open).

معناشناسی هزینه Cache-hit: در یک HIT کش معنایی (X-OmniRoute-Cache-Hit: true) هیچ فراخوانی بالادستی انجام نمیشود، بنابراین X-OmniRoute-Response-Cost برابر با 0.0000000000 است (هزینه افزایشی ارائه hit). هزینه اصلی/که میتوانست باشد به طور جداگانه در X-OmniRoute-Cost-Saved گزارش میشود. مصرفکنندگان صورتحساب باید X-OmniRoute-Response-Cost را جمع کنند (hitها هزینهای ندارند)؛ تحلیلگران کش میتوانند X-OmniRoute-Cost-Saved را تجمیع کنند.

اجارههای انحصاری نشست مدیریتشده

اجاره انحصاری نشست مدیریتشده یک قرارداد مسیریابی اختیاری و مستقل از کلاینت است: یک مالک فعال یک اتصال OmniRoute واجد شرایط را در اختیار دارد. این قرارداد یک مدل را اجاره نمیدهد، به OAuth نیاز ندارد، یک کلاینت خاص را شناسایی نمیکند، یا به یک ارائهدهنده خاص نیاز ندارد.

کلید API احراز هویت باید دارای دامنه lease:exclusive و یک لیست allowedConnections صریح و غیرخالی باشد. مرز تغییر پایگاه داده هر دو فیلد را هنگام ایجاد کلید و بهروزرسانیهای جزئی با هم اعمال میکند.

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

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

پاسخهای موفقیتآمیز برای کسب، تمدید و آزادسازی، مهرهای زمانی، state و generation مثبت دقیق را نمایش میدهند، اما هرگز اتصال یا اعتبارنامه انتخابشده را نمایش نمیدهند. تمدید و آزادسازی generation را در بدنه JSON ارائه میدهند:

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

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

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

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

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

این عمل وضعیت اختیاری توسط مالک مبهم، کلید API مدیریتشده احراز هویتشده، و generation فعال دقیق در یک تراکنش پایگاه داده محافظت میشود. displayName فقط نام اتصال پیکربندیشده و کوتاه شده است؛ اگر نام پیکربندیشده ایمنی وجود نداشته باشد، null است. OmniRoute هرگز یک ایمیل یا هویت حساب تولیدشده را جایگزین نمیکند. مقدار ارائهدهنده یک برچسب نمایش غیرحساس است و هرگز یک شناسه ارائهدهنده سازگار تولیدشده نیست. اعتبارنامهها، توکنها، کوکیها، شناسههای اتصال خام یا کلید API، هشهای مالک، اسرار محافظت، و دادههای مسیریابی داخلی حذف میشوند.

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

این قرارداد سرور، /status استاندارد OpenAI Codex را تغییر نمیدهد. Codex استاندارد در حال حاضر ارائهدهنده مدل و وضعیت احراز هویت/حساب داخلی خود را گزارش میدهد اما متادیتای حساب ارائهدهنده سفارشی دلخواه را نمایش نمیدهد؛ یک ادغام کلاینت بعدی باید این عمل را فراخوانی کند و تصمیم بگیرد که چگونه connection.displayName را نمایش دهد.

سپس هر درخواست استنتاج مدیریتشده هر دو هدر کنترل را ارائه میدهد:

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

مالک دقیق، generation، اتصال فعال و کلید API احراز هویتشده بلافاصله قبل از هر تلاش پشتیبانیشده بالادستی محافظت میشوند. تکرار مالک و generation با کلید دیگر حتی زمانی که آن کلید همان اتصال را مجاز میداند، با شکست مواجه میشود. مالکان خام پایدار نمیشوند، ثبت نمیشوند، در snapshot درخواست نگهداری نمیشوند، یا به بالادست ارسال نمیشوند.

رقابت موقت 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) نیز شناسایی میشوند. عملیات embed/rerank/classify/segment در 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": "غروب زیبای خورشید بر فراز کوهها",
  "size": "1024x1024"
}

ارائهدهندگان موجود شامل OpenAI (GPT Image 2)، xAI (Grok Image)، Together AI (FLUX)، Fireworks AI، Nebius (FLUX)، Hyperbolic، NanoBanana، OpenRouter، ZenMux، SD WebUI (محلی) و ComfyUI (محلی) هستند.

ZenMux از اتصال موجودِ کلید API دوباره استفاده میکند و پیشوندهای zenmux/ یا zm/ را میپذیرد:

• zenmux/openai/gpt-image-2 از API تصاویر OpenAI در 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 و API تصاویر OpenAI مراجعه کنید.

# فهرستکردن همه مدلهای تصویر
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) هر ثانیه تا 30 بار آن 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 برمیگرداند

پیشوندهای شناسه مدل (?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 انجام میدهد.

مدلهای چت پنهانشده بهصورت مجزا

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

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

گونههای بدون تفکر مدل

برای مدلهای Claude دارای قابلیت تفکر، /v1/models یک گونه بدون تفکر را نیز معرفی میکند که شناسه آن با claude-3-omniroute-no-thinking/ آغاز میشود:

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

انتخاب این شناسه (برای مثال در پیکربندی Claude Code که همیشه یک بلوک thinking اضافه میکند) دوباره به <provider>/<model> واقعی نگاشت میشود، در حالی که استدلال غیرفعال شده است — thinking:{type:"disabled"} در مسیر /v1/messages، یا حذف فیلدهای reasoning/reasoning_effort در مسیر /v1/chat/completions. این گونه فقط برای مدلهای خانواده Claude فهرست میشود که از تفکر پشتیبانی میکنند و مقدار disabled را میپذیرند (بنابراین، برای مثال، مدلهای صرفاً تطبیقی که disabled را رد میکنند، مستثنا میشوند). اپراتورها میتوانند این گونه را برای هر مدل از طریق ModelSpec.noThinkingAlias بهاجبار فعال یا غیرفعال کنند.

---

مانیفست پلاگین ارائهدهنده

GET /api/v1/provider-plugin-manifest

مانیفست پلاگین ارائهدهنده ایمن JSON را که توسط Bifrost، CLIProxyAPI و روترهای سایدکار آینده استفاده میشود، برمیگرداند. پاسخ از رجیستری ارائهدهنده TypeScript تولید میشود و عمداً اسرار کلاینت OAuth، حل و فصل محیط زمان اجرا، توابع اجرایی، هدرهای درخواست و دادههای حساب را مستثنی میکند.

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

---

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

متد	مسیر	قالب
POST	/v1/chat/completions	OpenAI
POST	/v1/messages	Anthropic
POST	/v1/responses	OpenAI Responses
POST	/v1/embeddings	OpenAI
POST	/v1/images/generations	OpenAI Images
POST	/v1/images/edits	OpenAI Images (ویرایش/ترمیم)
POST	/v1/videos/generations	تولید ویدئو به سبک OpenAI
POST	/v1/music/generations	تولید موسیقی به سبک OpenAI
POST	/v1/audio/transcriptions	OpenAI Audio (تبدیل گفتار به متن)
POST	/v1/audio/speech	OpenAI TTS (بدنهٔ صوتی را برمیگرداند)
POST	/v1/rerank	بازرتبهبندی به سبک Cohere/Voyage
POST	/v1/classify	دستهبندی Jina (api.jina.ai)
POST	/v1/segment	قطعهبند Jina (segment.jina.ai)
POST	/v1/moderations	تعدیل محتوای OpenAI
GET	/v1/models	OpenAI
POST	/v1/messages/count_tokens	Anthropic
GET	/v1beta/models	Gemini
POST	/v1beta/models/{...path}	Gemini generateContent
POST	/v1/api/chat	Ollama
GET	/api/v1/vscode/{token}/	نام مستعار کاتالوگ OpenAI
GET	/api/v1/vscode/{token}/models	نام مستعار مدلهای OpenAI
POST	/api/v1/vscode/{token}/chat/completions	نام مستعار توکندار OpenAI
POST	/api/v1/vscode/{token}/responses	نام مستعار توکندار OpenAI Responses
POST	/api/v1/vscode/{token}/api/chat	نام مستعار توکندار Ollama
GET	/api/v1/vscode/{token}/api/tags	نام مستعار توکندار برچسبهای Ollama

همهٔ مسیرهای POST از ساختار یکسانی پیروی میکنند: Bearer your-api-key بههمراه بدنهٔ JSON اعتبارسنجیشده با Zod (v1RerankSchema، v1ModerationSchema، v1AudioSpeechSchema و غیره؛ به src/shared/validation/schemas.ts مراجعه کنید). در صورت شکست اعتبارسنجی طرحواره، 4xx برگردانده میشود.

برای کلاینتهایی که نمیتوانند Authorization: Bearer ... را پیوست کنند، OmniRoute همچنین کلیدهای API را در URL، یا از طریق سازگاری رشتهٔ پرسوجو (?token=...، ?apiKey=...، ?api_key=...، ?key=...) یا از طریق نقاط پایانی اختصاصی /api/v1/vscode/{token}/... که در ادامه مستند شدهاند، میپذیرد.

# بازرتبهبندی (ارائهدهندهٔ رجیستری ابری، یا یک گرهٔ ارائهدهندهٔ سازگار با OpenAI بهصورت "<prefix>/<model>")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# دستهبندی Jina (اعتبارنامههای Foundation API)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# قطعهبند Jina
POST /v1/segment     { "content": "...", "return_chunks": true }

# جستوجوی Jina (s.jina.ai؛ نامهای مستعار ارائهدهنده: jina-search، jina-ai، jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# تعدیل محتوا
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

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

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

# ویرایش تصویر (multipart)
POST /v1/images/edits  -F 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> آدرسدهی شدهاند، هدایت میکند. گرههای loopback (localhost، 127.0.0.1، 172.16.0.0/12) همیشه واجد شرایط هستند؛ همین موضوع دربارهٔ نامهای میزبانی که اپراتور در OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS فهرست میکند نیز صدق میکند (برای مثال، نام یک سرویس Docker/Compose مانند http://reranker:8080/v1؛ این موارد مستقیماً فراخوانی میشوند و هرگز از طریق HTTP(S)_PROXY یا پروکسی پینشدهٔ یک اتصال عبور نمیکنند). گرههای مستقر روی هر میزبان دیگری — یک دستگاه در LAN یا همتای Tailscale — تنها زمانی واجد شرایط هستند که اپراتور پرچم قابلیت RERANK_REMOTE_PROVIDER_NODES را فعال کند و URL پایهٔ گره از سیاست URL خروجی ارائهدهنده (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS / OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS) عبور کند. مرحلهٔ بازرتبهبندی موتور حافظه، این مسیر را از طریق loopback فراخوانی میکند؛ بنابراین همین قاعده بر rerankProviderModel در تنظیمات حافظه حاکم است.

ساختارهای سرور محلی: گره ابتدا در <base>/v1/rerank و در صورت دریافت 404، در <base>/rerank (Infinity، TEI) فراخوانی میشود. بدنهٔ ارسالی به بالادست، هم نامگذاری Cohere/OpenAI (documents، return_documents) و هم نامگذاری TEI (texts، return_text) را شامل میشود و پاسخ بالادست به پوش Cohere نرمالسازی میشود: آرایهٔ خام TEI یعنی [{index, score, text}]، ساختار {results: [{index, score}]} از دروازههای سبک، و ساختار به سبک Voyage یعنی {data: [...]} همگی بهشکل {results: [{index, relevance_score, document?}]} به کلاینت بازگردانده میشوند، بر اساس امتیاز مرتب میشوند و به top_n محدود میگردند.

کشف گره ارائهدهنده: مدلهای موجود در یک گره ارائهدهنده سازگار با OpenAI، در GET /v1/models زیر پیشوند گره نمایش داده میشوند. ردیفهایی که فاقد فراداده نقطه پایانی هستند (که برای فهرستهای محلی /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]) — حداکثر ۵۱۲ مگابایت
GET	/v1/files	لیست کردن فایلها برای کلید API احراز هویت شده
GET	/v1/files/[id]	بازیابی فراداده (metadata) یک فایل
DELETE	/v1/files/[id]	حذف یک فایل
GET	/v1/files/[id]/content	بازگرداندن بدنه خام فایل به صورت جریانی (stream)

احراز هویت: کلید API Bearer — فایلها از طریق getApiKeyRequestScope به ازای هر کلید API محدود میشوند. یک کلید فقط فایلهای خود را میبیند، دانلود میکند و حذف میکند؛ یک نشست داشبورد بدون کلید، کل نمونه را میخواند؛ دسترسی به فایلی که مالکی ندارد (آپلود شده توسط کاربر ناشناس یا نشست داشبورد) برای هر تماسگیرنده غیر-نشست ممنوع است. GET /v1/files یک تماسگیرنده ناشناس — و یک کلید ارائه شده که حل نمیشود — را با کد 401 رد میکند، حتی زمانی که REQUIRE_API_KEY=false باشد، به جای لیست کردن فایلهای هر مستأجر (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

API دستهها

پردازش دستهای سازگار با OpenAI.

متد	مسیر	توضیحات
POST	/v1/batches	ایجاد دسته — بدنه توسط v1BatchCreateSchema اعتبارسنجی میشود (input_file_id, endpoint, completion_window)
GET	/v1/batches	لیست کردن دستهها
GET	/v1/batches/[id]	بازیابی وضعیت دسته + request_counts
DELETE	/v1/batches/[id]	حذف یک دسته تکمیل شده/ناموفق
POST	/v1/batches/[id]/cancel	لغو یک دسته در حال انجام

احراز هویت: کلید API Bearer. دستهها تحت همان قانون سهگانه فایلها، به ازای هر کلید API محدود میشوند: فقط کلید خود، نشست داشبورد در سطح نمونه، رکوردهای بدون مالک برای هر تماسگیرنده غیر-نشست ممنوع است (بازیابی، حذف، لغو، و بررسی input_file_id هنگام ایجاد). GET /v1/batches یک تماسگیرنده ناشناس را با کد 401 رد میکند، حتی زمانی که REQUIRE_API_KEY=false باشد.

---

API جستجو

انتزاع ارائهدهنده وب/جستجو (Tavily, Brave, Exa, Serper و غیره).

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

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

---

API واکشی وب

استخراج محتوا از یک URL از طریق یک ارائهدهنده واکشی وب پیکربندی شده (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).

متد	مسیر	توضیحات
POST	/v1/web/fetch	واکشی/اسکرپ کردن یک URL — بدنه توسط v1WebFetchSchema اعتبارسنجی میشود

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

بازگشت به عقب آگاه از سهمیه (#8297): هنگامی که provider صریحی داده نمیشود، پول (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) به ترتیب اولویت ثابت (پر کردن اول) پیمایش میشود — یک ارائهدهنده با محدودیت نرخ اما پیکربندی شده به جای قطع درخواست، نادیده گرفته میشود، و یک خطای بالادستی قابل تکرار/سهمیه (HTTP 429 همیشه؛ 402/403 برای Firecrawl/Tavily/TinyFish در سطوح رایگان سهمیهای — نه برای Jina Reader، و هرگز برای یک درخواست نامعتبر 400) به ارائهدهنده معتبر بعدی که امتحان نشده است در زمان درخواست منتقل میشود. هنگامی که هر ارائهدهنده در پول تمام شود، نقطه پایانی به جای 400 عمومی قبلی، یک 429 واحد (با هدر Retry-After) برمیگرداند. هنگامی که یک provider صریح درخواست میشود، هیچ بازگشت به عقب پنهانی وجود ندارد — یک ارائهدهنده صریح با محدودیت نرخ یا ناموفق، خطای خود را نشان میدهد (429 اگر محدودیت نرخ داشته باشد، در غیر این صورت وضعیت بالادستی).

---

استریمینگ WebSocket

GET /v1/ws?handshake=1

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

احراز هویت: کلید API Bearer در طول دستدهی.

API پاسخها از طریق WebSocket (فقط codex)

# Same host:port as the HTTP API (default 20128); upgrade the connection:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (or: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# First frame MUST be 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/)

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 فقط برای کدکس است، بنابراین یک شناسه خام را به عنوان یک مدل کدکس (resolveCodexWsModelInfo) قبل از تونلزنی به بالادست مجدداً حل میکند — حتی اگر یک gpt-5.5 خام در غیر این صورت از طریق HTTP به ارائهدهنده دیگری مسیریابی شود.

پیکربندی OpenAI Codex CLI

CLI کدکس را با افزودن یک ارائهدهنده سفارشی با پشتیبانی WebSocket به ~/.codex/config.toml به OmniRoute اشاره دهید (از یک CODEX_HOME جداگانه برای جلوگیری از دستکاری یک پیکربندی موجود استفاده کنید):

model = "gpt-5.5"                 # bare id — NOT "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # no trailing slash; the WS URL is derived (use https/wss in production)
wire_api = "responses"                    # only supported value since Feb 2026
supports_websockets = true                # enables the Responses-over-WS transport
env_key = "OMNIROUTE_API_KEY"             # holds the OmniRoute API key (Bearer)

export OMNIROUTE_API_KEY=sk-...           # an OmniRoute API key (any key if REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

CLI، base_url + /responses را به یک WebSocket ارتقا میدهد و OmniRoute آن را به اتصال OAuth کدکس انتخاب شده تونل میزند. اعتبارسنجی سرتاسری در برابر سرور محلی: ChatGPT، codex.rate_limits + response.created را برمیگرداند و تکمیل را استریم میکند.

---

گزارش سهمیهها و مشکلات

متد	مسیر	توضیحات
GET	/v1/quotas/check	اعتبارسنجی اولیه سهمیه برای یک provider + accountId قبل از صدور یک کلید ثبتشده
POST	/v1/issues/report	گزارش خرابی صدور سهمیه/کلید به گیتهاب (نیاز به GITHUB_ISSUES_REPO + توکن دارد)

احراز هویت: کلید API از نوع Bearer (isAuthenticated).

---

استفادهٔ سلفسرویس (/api/usage/om-usage)

هر کلید API میتواند میزان استفاده و سهمیههای خودش را بخواند — بدون نیاز به احراز هویت مدیریتی. این همان نقطهٔ پایانیای است که یک کلاینت (CLI، پنل OmniCopilot) برای نمایش هزینهکرد دارندهٔ کلید استفاده میکند.

# قالب متنی (قرارداد قدیمی — متن ساده برای ترمینال)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# قالب ساختیافته — آنچه یک رابط کاربری مصرف میکند
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

کلید باید گزینهٔ allowUsageCommand را فعال کرده باشد (بهطور پیشفرض غیرفعال است — مدیر کلید API در داشبورد آن را برای هر کلید تغییر میدهد). بدون آن، نقطهٔ پایانی با 403 پاسخ میدهد.

?format=json ساختاری متمایزکننده برمیگرداند تا فراخواننده هرگز فیلد دادهای را از یک پاسخ رد درخواست نخواند. در صورت موفقیت:

{
  "allowed": true,
  // فقط زمانی وجود دارد که محدودیتهای استفادهٔ مختص هر کلید (روزانه/هفتگی بر حسب USD) فعال شده باشند:
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // تصویر لحظهای سهمیهٔ ارائهدهندهٔ انتخابشده، یا در صورتی که هنوز چیزی کش نشده باشد null:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // تصویر لحظهای همهٔ اتصالها، تا رابط کاربری بتواند چند ارائهدهنده را کنار یکدیگر نمایش دهد:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

در صورت رد درخواست (401 برای کلید نامعتبر / 403 برای نداشتن مجوز)، همان مسیر { "allowed": false, "error": { "message": "…" } } را برمیگرداند — وجود personal/provider خالی (کلید مجاز است، اما هنوز دادهای به دست نیامده) وضعیتی متفاوت از رد درخواست است و فقط قالب JSON این دو را از هم متمایز میکند.

احراز هویت: کلید 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(...)).

مثال توضیحی

یک بازهٔ ارائهدهنده با 60% استفادهٔ خام (در نتیجه 40% سهمیهٔ خام باقیمانده) و آستانهٔ 25% نقطهٔ قطع سهمیهٔ باقیمانده را در نظر بگیرید:

نمایش	محاسبه	باقیمانده	استفادهٔ ضمنی
JSON خام (?format=json)	تصویر لحظهای بالادستی (quotas[window])	40%	60%
قالب متنی (NN% left)	((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100	20%	80% (در صورت محاسبهٔ 100 - remaining)

• چرا متن 20% باقیمانده نشان میدهد: از 40% سهمیهٔ فیزیکی باقیمانده در حساب، 25% توسط سیاست نقطهٔ قطع رزرو شده است. فراخواننده از مجموع 75% فضای قابلاستفاده، تنها 15% ظرفیت باقیمانده دارد تا زمانی که مسیریاب هدایت درخواستها به این اتصال را متوقف کند. مقیاسبندی تضمین میکند که اتصال دقیقاً در زمان توقف مسیریابی، اتمام ظرفیت (0% left) را اعلام کند.
• چرا JSON مقادیر خام را حفظ میکند: محمولهٔ JSON تصویر لحظهای دقیق ارائهدهنده (UsageSnapshot) را برمیگرداند تا ابزارهای خارجی به میزان استفادهٔ واقعی و معتبر بالادستی و quotaWindowThresholds در سطح اتصال، بدون مقیاسبندی اتلافی سمت سرور، دسترسی داشته باشند.

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

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

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

---

کش معنایی

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

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

مثال پاسخ:

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

تأثیر تأخیر

یک HIT کش معنایی، پاسخ را از کش بدون فراخوانی بالادستی ارائه میدهد، بنابراین X-OmniRoute-Response-Latency گزارششده نزدیک به صفر است (صرفنظر از تأخیر اصلی بالادستی). کلاینتهای حساس به تأخیر (بنچمارکینگ، نظارت p50/p99) باید هدر پاسخ X-OmniRoute-Cache-Latency را بررسی کنند:

مقدار	معنی
synthetic	پاسخ از کش ارائه شده است؛ تأخیر زمان واقعی بالادستی نیست
(غایب)	پاسخ از فراخوانی واقعی بالادستی

دور زدن کش به ازای هر کلید

کلیدهای API میتوانند از خواندن کش معنایی از طریق cacheDefaultMode انصراف دهند:

مقدار	رفتار
legacy	رفتار عادی کش (پیشفرض)
bypass	بهطور کامل از جستجوی کش صرفنظر کنید؛ همیشه به بالادست مراجعه کنید

در زمان ایجاد کلید (POST /api/keys) یا بهروزرسانی (PATCH /api/keys/[id]) تنظیم میشود:

{ "cacheDefaultMode": "bypass" }

دور زدن به ازای هر درخواست

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

X-OmniRoute-No-Cache: true

داشبورد و مدیریت

مسیرهای مدیریتی (/api/* بهجز احراز هویت/ورود عمومی) با کلیدهای API معمولیِ استنتاجی مجاز نمیشوند. برای خانوادههای اعتبارنامه، دامنههای دسترسی و نمونههای curl، به این بخش مراجعه کنید: احراز هویت مدیریتی.

احراز هویت

نقطه پایانی	متد	توضیحات
/api/auth/login	POST	ورود
/api/auth/logout	POST	خروج
/api/settings/require-login	GET/PUT	فعال یا غیرفعال کردن الزام ورود

مدیریت ارائهدهندگان

نقطه پایانی	متد	توضیحات
/api/providers	GET/POST	فهرست کردن / ایجاد ارائهدهندگان
/api/providers/[id]	GET/PUT/DELETE	مدیریت یک ارائهدهنده
/api/providers/[id]/test	POST	آزمایش اتصال ارائهدهنده
/api/providers/[id]/models	GET	فهرست کردن مدلهای ارائهدهنده
/api/providers/validate	POST	اعتبارسنجی پیکربندی ارائهدهنده
/api/providers/bulk	POST	افزودن گروهی کلیدهای API برای یک ارائهدهنده
/api/providers/import	POST	وارد کردن یک فهرست ناهمگون از ارائهدهندگان از فایل CSV/JSON تجزیهشده (#6836)؛ همراه با نتایج شکست جزئی برای هر ردیف
/api/provider-nodes*	مختلف	مدیریت گره ارائهدهنده
/api/provider-models	GET/POST/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 استفاده میکند، نه از نام مدلها یا محدودیتهای تکمیل. کنترلهای صریح بدنه، هدرهای پشتیبانیشده effort/thinking، قواعد مسیریابی و میزان effort نهایی مدل، اولویت فعلی خود را حفظ میکنند. هر دو مرحله طبقهبند، پرامپتها، محدودیتهای تکمیل، توالیهای توقف و احکام واقعی مجوز بالادستی خود را حفظ میکنند؛ مرحله دوم همچنان میتواند استدلال قابلمشاهده درخواستی خود را بهصورت متن عادی تولید کند.

جریانهای 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 برای این کلید چه مواردی را فهرست کند (فقط ترکیبها، فقط مدلها یا هر دو)؛ این گزینه موارد قابل فراخوانی توسط کلید را تغییر نمیدهد
noLog, autoResolve	بولی
throttleDelayMs	عدد صحیح، ۰ تا ۳۰۰۰۰۰
maxSessions	عدد صحیح، ۰ تا ۱۰۰۰۰
rateLimits	آرایهای از { limit, window } (اعداد صحیح مثبت، حداکثر ۵۰ مورد) یا null	null محدودیتها را پاک میکند
accessSchedule	شیء زمانبندی یا null	null زمانبندی را پاک میکند
scopes	آرایهای از رشتهها، حداکثر ۳۲ مورد
allowedEndpoints	آرایهای از رشتهها، حداکثر ۲۰ مورد
streamDefaultMode	legacy | json
cacheDefaultMode	legacy | bypass	به نادیدهگرفتن کش برای هر کلید مراجعه کنید
compressionEnabled	بولی
codexServiceMode	یکی از حالتهای سرویس Codex
disableNonPublicModels	بولی
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	تنظیمات عمومی
/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	نام مستعار تحلیلهای فشردهسازی

پایش

Endpoint	Method	Description
/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 عمومی بارگذاری نیست

پشتیبانگیری و خروجی/ورودی

Endpoint	Method	Description
/api/db-backups	GET	فهرست پشتیبانهای موجود
/api/db-backups	PUT	ایجاد پشتیبان دستی
/api/db-backups	POST	بازیابی از یک پشتیبان مشخص
/api/db-backups/export	GET	دانلود پایگاه داده بهصورت فایل .sqlite
/api/db-backups/import	POST	بارگذاری فایل .sqlite برای جایگزینی پایگاه داده
/api/db-backups/exportAll	GET	دانلود پشتیبان کامل بهصورت آرشیو .tar.gz

همگامسازی ابری

Endpoint	Method	Description
/api/sync/cloud	متنوع	عملیات همگامسازی ابری
/api/sync/initialize	POST	مقداردهی اولیه همگامسازی
/api/cloud/*	متنوع	مدیریت فضای ابری

تونلها

Endpoint	Method	Description
/api/tunnels/cloudflared	GET	خواندن وضعیت نصب/اجرای Cloudflare Quick Tunnel برای داشبورد
/api/tunnels/cloudflared	POST	فعال یا غیرفعال کردن Cloudflare Quick Tunnel (action=enable/disable)
/api/tunnels/ngrok	GET	خواندن وضعیت اجرای ngrok Tunnel برای داشبورد
/api/tunnels/ngrok	POST	فعال یا غیرفعال کردن ngrok Tunnel (action=enable/disable)

ابزارهای CLI

نقطه پایانی	متد	توضیحات
/api/cli-tools/claude-settings	GET	وضعیت Claude CLI
/api/cli-tools/codex-settings	GET	وضعیت Codex CLI
/api/cli-tools/droid-settings	GET	وضعیت Droid CLI
/api/cli-tools/openclaw-settings	GET	وضعیت OpenClaw CLI
/api/cli-tools/runtime/[toolId]	GET	محیط اجرای عمومی CLI

پاسخهای CLI شامل این موارد هستند: installed، runnable، command، commandPath، runtimeMode، reason.

عاملهای ACP

نقطه پایانی	متد	توضیحات
/api/acp/agents	GET	فهرستکردن همه عاملهای شناساییشده (داخلی + سفارشی) بههمراه وضعیت
/api/acp/agents	POST	افزودن عامل سفارشی یا تازهسازی حافظه نهان شناسایی
/api/acp/agents	DELETE	حذف یک عامل سفارشی با پارامتر کوئری id

پاسخ GET شامل agents[] (id، name، binary، version، installed، protocol، isCustom) و summary (total، installed، notFound، builtIn، custom) است.

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

نقطه پایانی	متد	توضیحات
/api/resilience	GET/PATCH	دریافت/بهروزرسانی صف درخواست، دوره انتظار اتصال، قطعکننده ارائهدهنده و تنظیمات انتظار
/api/resilience/reset	POST	بازنشانی قطعکنندههای مدار ارائهدهنده
/api/resilience/model-cooldowns	GET	فهرستکردن قفلهای فعال بهازای هر (ارائهدهنده، اتصال، مدل)، مرتبشده بر اساس زمان باقیمانده
/api/resilience/model-cooldowns	DELETE	پاککردن قفل مدل — بدنه {provider, model} یا {all: true} برای پاککردن همه موارد
/api/rate-limits	GET	وضعیت محدودیت نرخ بهازای هر حساب
/api/rate-limit	GET	پیکربندی سراسری محدودیت نرخ

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

ارزیابیها

نقطه پایانی	متد	توضیحات
/api/evals	GET/POST	فهرستکردن مجموعههای ارزیابی / اجرای ارزیابی

سیاستها

نقطه پایانی	متد	توضیحات
/api/policies	GET/POST/DELETE	مدیریت سیاستهای مسیریابی

انطباق

نقطه پایانی	متد	توضیحات
/api/compliance/audit-log	GET	گزارش ممیزی انطباق (آخرین N مورد)

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

نقطه پایانی	متد	توضیحات
/v1beta/models	GET	فهرستکردن مدلها در قالب Gemini
/v1beta/models/{...path}	POST	نقطه پایانی generateContent در Gemini

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

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

نقطه پایانی	متد	توضیحات
/api/init	GET	بررسی مقداردهی اولیه برنامه (مورد استفاده در نخستین اجرا)
/api/tags	GET	برچسبهای مدل سازگار با Ollama (برای کلاینتهای Ollama)
/api/restart	POST	راهاندازی مجدد کنترلشده سرور
/api/shutdown	POST	خاموشکردن کنترلشده سرور
/api/system/env/repair	POST	تعمیر متغیرهای محیطی ارائهدهنده OAuth
/api/system/version	GET	نسخه فعلی/جدیدترین، وضعیت بهروزرسانی، کانال انتشار
/api/system/version	POST	آغاز بهروزرسانی آگاه از استقرار به جدیدترین نسخه

توجه: این نقاط پایانی بهصورت داخلی توسط سیستم یا برای سازگاری با کلاینت Ollama استفاده میشوند. معمولاً کاربران نهایی مستقیماً آنها را فراخوانی نمیکنند.

تعمیر محیط OAuth (v3.6.1+)

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

{
  "provider": "claude-code"
}

متغیرهای محیطی OAuth مفقود یا خراب را برای یک ارائهدهنده مشخص تعمیر میکند. خروجی:

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

نسخه و کانال انتشار

GET /api/system/version

مسیر مدیریتی مختص loopback (احراز هویت مدیر). نسخه در حال اجرا، جدیدترین نسخه منتشرشده و وضعیت بهروزرسانی خودکار را برمیگرداند. releaseChannel و channels فیلدهای افزایشی هستند (rail 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 رجیستری بهعنوان راهکار جایگزین)، که با همان 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-key (متفاوت از بودجه دلاری ذکر شده در بالا). این محدودیتها به صورت درونخطی در مسیر درخواست اعمال میشوند: هنگامی که استفاده فعلی یک کلید در بازه زمانی خود به حد مجاز برسد، درخواستها با خطای 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 غنی میکنند. این یک نقطه پایانی از کلاس مدیریت است (احراز هویت به صورت مرکزی توسط خط لوله authz اعمال میشود).

پردازش درخواست

۱. کلاینت درخواست را به /v1/* ارسال میکند ۲. کنترلکننده مسیر، handleChat، handleEmbedding، handleAudioTranscription یا handleImageGeneration را فراخوانی میکند ۳. مدل حل میشود (ارائهدهنده/مدل مستقیم یا نام مستعار/ترکیب) ۴. اعتبارنامهها از پایگاه داده محلی با فیلتر در دسترس بودن حساب انتخاب میشوند ۵. برای چت: handleChatCore حافظه پنهان معنایی/امضا را بررسی میکند و تنظیمات فشردهسازی ترکیب را حل میکند ۶. فشردهسازی پیشگیرانه قبل از ترجمه ارائهدهنده در صورت فعال بودن اجرا میشود (lite، Caveman، RTK یا stacked) ۷. اجراکننده ارائهدهنده درخواست بالادستی را ارسال میکند ۸. پاسخ به فرمت کلاینت (چت) ترجمه میشود یا به همان صورت (embeddings/images/audio) بازگردانده میشود ۹. استفاده، تحلیلهای فشردهسازی و لاگهای درخواست ثبت میشوند ۱۰. بازگشت به حالت قبل در صورت بروز خطا طبق قوانین ترکیب اعمال میشود

مرجع کامل معماری: ARCHITECTURE.md

---

مدیریت ترکیبها

ترکیبهای مسیریابی سطح بالاتر (که قبلاً در /api/combos* خلاصه شدهاند) نیز میتوانند به صورت ۱:۱ از یک الگوی شناسه مدل نگاشت شوند، که امکان تغییر مسیر شفاف یک شناسه مدل به سبک 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 key (requireManagementAuth).

---

وبهوکها

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

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

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

---

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

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

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

احراز هویت: کلید API Bearer (isAuthenticated). همچنین به /v1/quotas/check و /v1/issues/report مراجعه کنید.

---

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

وظایف عامل ابری (Claude Code، Codex Cloud، OpenHands و غیره) که از راه دور به نمایندگی از کاربران OmniRoute اجرا میشوند.

متد	مسیر	توضیحات
GET	/api/v1/agents/tasks	لیست وظایف — اختیاری ?provider=, ?status=, ?limit= (1–500, پیشفرض 50)
POST	/api/v1/agents/tasks	ایجاد وظیفه — بدنه توسط CreateCloudAgentTaskSchema (providerId, prompt, source, options?) اعتبارسنجی میشود. 201 را با پاکت وظیفه برمیگرداند
DELETE	/api/v1/agents/tasks?id=...	حذف یک وظیفه
GET	/api/v1/agents/tasks/[id]	خواندن وظیفه — وضعیت را به صورت همزمان از عامل ابری بالادستی زمانی که external_id تنظیم شده باشد، بهروزرسانی میکند
POST	/api/v1/agents/tasks/[id]	عمل متمایز: {action: "approve"}, {action: "message", message}, یا {action: "cancel"}
DELETE	/api/v1/agents/tasks/[id]	حذف یک وظیفه خاص بر اساس شناسه

احراز هویت: احراز هویت مدیریتی در هر متد الزامی است (requireCloudAgentManagementAuth). قبل از نسخه 3.8.0 اینها بدون احراز هویت بودند — برای تغییرات اساسی به commit 588a0333 مراجعه کنید.

# ایجاد یک وظیفه ابری Claude Code
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'

---

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

پروکسیهای خروجی 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 ← "Resilience Runtime State" مراجعه کنید.

---

مهارتها

چارچوب مهارت برای توسعه OmniRoute با کنترلکنندههای اجرایی سفارشی، به علاوه ادغامهای بازار.

متد	مسیر	توضیحات
GET	/api/skills	لیست مهارتهای نصبشده — قابل فیلتر با ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, صفحهبندیشده
GET	/api/skills/[id]	بازیابی یک مهارت
PUT	/api/skills/[id]	بهروزرسانی مهارت (نام، توضیحات، حالت، طرح، کنترلکننده، برچسبها)
DELETE	/api/skills/[id]	حذف نصب یک مهارت
POST	/api/skills/install	نصب یک مهارت از یک مانیفست خام — بدنه: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET	/api/skills/executions	لیست اجرای مهارتهای اخیر (ردیابی حسابرسی با ورودیها/خروجیها/مدت زمان)
GET	/api/skills/marketplace?q=...	لیست جستجو/محبوب از بازار SkillsMP (نیاز به تنظیم skillsmpApiKey دارد)
POST	/api/skills/marketplace/install	نصب یک مهارت با شناسه از SkillsMP
GET	/api/skills/skillssh?q=&limit=	جستجو در رجیستری skills.sh
POST	/api/skills/skillssh/install	نصب یک مهارت با شناسه از skills.sh

احراز هویت: جلسه مدیریت/کلید API. مسیرهای جستجوی بازار هم احراز هویت مدیریت و هم یک کلید API Bearer (isAuthenticated) را میپذیرند.

---

حافظه

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

متد	مسیر	توضیحات
GET	/api/memory	لیست حافظهها — ?apiKeyId=, ?type=, ?sessionId=, ?q=, با صفحهبندی offset/limit یا page/limit
POST	/api/memory	ایجاد حافظه — بدنه توسط Zod اعتبارسنجی میشود: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET	/api/memory/[id]	بازیابی یک حافظه
DELETE	/api/memory/[id]	حذف یک حافظه
GET	/api/memory/health	وضعیت سلامت زیرسیستم حافظه (اتصال به پایگاه داده، بکاند جاسازیها، وضعیت شاخص برداری)

احراز هویت: نشست مدیریتی/کلید API (requireManagementAuth). شمارشگر type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (به MemoryType در src/lib/memory/types.ts مراجعه کنید).

---

سرور MCP

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

متد	مسیر	توضیحات
GET	/api/mcp/status	ضربان قلب، انتقال، وضعیت آنلاین، آخرین تماس، ابزارهای برتر، نرخ موفقیت 24 ساعته
GET	/api/mcp/tools	لیست ابزارهای MCP با name, description, scopes, phase, auditLevel, sourceEndpoints
GET	/api/mcp/sse	باز کردن جریان SSE برای انتقال SSE (در صورت غیرفعال بودن MCP یا عدم تطابق انتقال، 503 برمیگرداند)
POST	/api/mcp/sse	ارسال فریم JSON-RPC از طریق انتقال SSE
GET	/api/mcp/stream	باز کردن سمت SSE از انتقال HTTP قابل جریان (پیامهای آغاز شده توسط سرور)
POST	/api/mcp/stream	ارسال فریم JSON-RPC از طریق انتقال HTTP قابل جریان
DELETE	/api/mcp/stream	پایان دادن به یک نشست HTTP قابل جریان
GET	/api/mcp/audit	پرس و جو از گزارش حسابرسی — ?limit=, ?offset=, ?tool=, `?success=true
GET	/api/mcp/audit/stats	آمار تجمیعی حسابرسی (مجموع، نرخ موفقیت، میانگین مدت زمان، ابزارهای برتر)

احراز هویت: انتقالهای sse/stream از سطح احراز هویت خاص MCP (کلید API Bearer با دامنه mcp) پیروی میکنند؛ مسیرهای status/tools/audit* از داشبورد قابل خواندن هستند (هیچ احراز هویت اضافی فراتر از دسترسی به هاست داشبورد مورد نیاز نیست).

هر دو انتقال HTTP توسط settings.mcpEnabled و settings.mcpTransport کنترل میشوند — عدم تطابق انتقال 400 و وضعیت غیرفعال MCP 503 را برمیگرداند.

---

سرور A2A

OmniRoute یک نقطه پایانی JSON-RPC 2.0 A2A (Agent-to-Agent) به همراه یک پوشش REST برای استفاده در بازرسی/داشبورد ارائه میدهد.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # اختیاری است مگر اینکه OMNIROUTE_API_KEY تنظیم شده باشد
Content-Type: application/json

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

متدهای پشتیبانی شده (همه مشروط به settings.a2aEnabled):

متد	توضیحات
message/send	اجرای همزمان مهارت؛ {task, artifacts, metadata} را برمیگرداند
message/stream	اجرای جریانی SSE از همان مجموعه مهارت
tasks/get	بازیابی یک وظیفه بر اساس taskId
tasks/cancel	لغو یک وظیفه بر اساس taskId

مهارتهای داخلی: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

کارت عامل

GET /.well-known/agent.json

کارت عامل عمومی A2A (نام، توضیحات، قابلیتها، کاتالوگ مهارت، طرح احراز هویت) را برمیگرداند — به صورت عمومی برای ۱ ساعت کش میشود. احراز هویت لازم نیست.

کمککنندههای REST

متد	مسیر	توضیحات
GET	/api/a2a/status	A2A فعال + آمار وظایف + خلاصه کارت عامل کش شده
GET	/api/a2a/tasks	لیست وظایف — `?state=submitted
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 (پروتکل کلاینت عامل)

به عنوان فرآیندهای فرزند. این نقاط پایانی، شناسایی عامل 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": ["اوپنایآی ۴۰٪ از ترافیک را به خود اختصاص داده است — تنوعبخشی را در نظر بگیرید"]
}

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

---

عملیات مدیریتی

نقاط پایانی (endpoints) فقط برای مدیران جهت مدیریت عملیاتی.

متد	مسیر	توضیحات
GET	/api/admin/concurrency	خواندن محدودیتهای همزمانی فعلی (سراسری + به ازای هر ارائهدهنده)
POST	/api/admin/concurrency	بهروزرسانی محدودیتهای همزمانی — بدنه: {global?: number, perProvider?: Record<string, number>}

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

---

مدیریت ابزارهای CLI

مدیریت ابزارهای CLI که با OmniRoute یکپارچه میشوند (antigravity, commandCode, devin-cli و غیره). برای مشاهده لیست کامل به مرجع ارائهدهنده مراجعه کنید.

متد	مسیر	توضیحات
GET	/api/cli-tools/all-statuses	وضعیت تمام ابزارهای CLI (نصبشده، نسخه، آخرین مشاهده)
GET	/api/cli-tools/status	جزئیات وضعیت برای یک ابزار CLI (پرسوجوی ?tool=)
POST	/api/cli-tools/apply	نوشتن پیکربندی تولیدشده یک ابزار (پیشنمایشهای dryRun؛ 422 + containerEphemeralTarget در حالت کانتینری؛ migration به یک Codex YAML قدیمی اشاره دارد)
GET	/api/cli-tools/backups	لیست پشتیبانگیریهای پیکربندی ابزار CLI
POST	/api/cli-tools/backups	ایجاد یک پشتیبان از تمام پیکربندیهای ابزار CLI
POST	/api/cli-tools/backups	بازیابی: همین نقطه پایانی با {tool, backupId} در بدنه، آن پشتیبان را بازیابی میکند
GET	/api/cli-tools/antigravity-mitm	وضعیت پروکسی MITM آنتیگراویتی (ابزار CLI "antigravity-mitm")
POST	/api/cli-tools/antigravity-mitm/alias	پیکربندی نامهای مستعار (aliases) antigravity-mitm

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

---

مهارتهای عامل (Agent)

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

---

مدیریت کش

کش معنایی و کش استدلال را مدیریت کنید.

Method	Path	Description
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 + جاسازیهای برداری) را مدیریت کنید.

Method	Path	Description
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 با دامنه مدیریتی دارد.

---

وبهوکها

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

Method	Path	Description
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	ارسال یک رویداد آزمایشی به یک وبهوک

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

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

---

چارچوب مهارتها (Skills Framework)

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

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

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

برای جزئیات کامل به چارچوب مهارتها (Skills Framework) مراجعه کنید.

---

افزونهها (Plugins)

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

Method	Path	Description
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	بهروزرسانی پیکربندی افزونه

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

برای جزئیات کامل به چارچوب افزونهها (Plugins Framework) مراجعه کنید.

---

مسیریابی سایه (Shadow Routing)

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

---

محافظها (Guardrails)

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

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

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

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

---

---

احراز هویت

برای چهار خانواده اعتبارنامه (نشست داشبورد، توکن 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/* و نقاط پایانی مدیریت زمانبندی (cooldown) اکنون به احراز هویت مدیریت (کوکی auth_token داشبورد یا یک کلید API با دامنه مدیریت) نیاز دارند. کلاینتهایی که قبلاً این مسیرها را بدون احراز هویت فراخوانی میکردند، اکنون 401 Unauthorized دریافت خواهند کرد. به کامیت 588a0333 (fix(auth): require management auth for agent and cooldown APIs) مراجعه کنید.