mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-18 04:42:30 +03:00

Files

Diego Rodrigues de Sa e Souza b637350680 fix(docs): re-sync the 65 documentation mirror sets; section-level docs pipeline; drift gate blocking (#13940 )

1,104 mirrors rewritten over five passes of run-translation on the 22-source core set: the 14 sources edited since their translation, the 322 mirrors that were still English copies, and the frontmatter the old extractor leaked into the newer locales' bodies. The pipeline now caches per-`## `-section hashes and retranslates only changed sections, never reuses a section that is still English, rebuilds English-copy / leaked mirrors even when the source is unchanged, merges the state on save (parallel runs), and the drift gate (scoped to the core set) is blocking. Final audit: 0 stale, 0 English copies, 0 leaked frontmatter across 1,430 core mirrors.

⚠️ base-red inherited: #12732

2026-09-17 02:55:31 -03:00

147 KiB

Raw Blame History

API Reference (فارسی)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 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

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

فهرست مطالب

تکمیلهای گفتگو
اجارههای انحصاری نشست مدیریتشده
تعبیهها
تولید تصویر
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`	درخواست	برای صرفنظر کردن از تزریق حافظه و مهارتها در این درخواست، روی `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-Cache`	پاسخ	`HIT` یا `MISS` (غیراستریمی)
`X-OmniRoute-Idempotent`	پاسخ	در صورت حذف تکرار، `true`
`X-OmniRoute-Progress`	پاسخ	اگر ردیابی پیشرفت فعال باشد، `enabled`
`X-OmniRoute-Session-Id`	پاسخ	شناسه نشست مؤثرِ استفادهشده توسط OmniRoute
`X-OmniRoute-Request-Id`	پاسخ	شناسه همبستگی درخواست (در صورت مشخص بودن)
`X-OmniRoute-Version`	پاسخ	نسخه ساخت OmniRoute (همیشه وجود دارد)
`X-OmniRoute-Cost-Saved`	پاسخ	مبلغ دلاری صرفهجوییشده توسط کش در یک `HIT` (فقط برای اصابتهای کش)
`X-OmniRoute-Decision`	پاسخ	ردگیری مسیریابی: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` راهبرد ترکیب است، یا برای درخواست غیرترکیبی `single`) — همیشه در پاسخهای تکمیل وجود دارد

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

هدرهای تلهمتری هزینه: پاسخهای موفقِ غیراستریم نیز مجموعه تلهمتری هزینه X-OmniRoute-* را شامل میشوند — X-OmniRoute-Response-Cost (دلار آمریکا، با دقیقاً ۱۰ رقم اعشار؛ 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).

معنای هزینه در حالت اصابت کش: در حالت اصابت به کش معنایی (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 را ارائه میکنند، اما هرگز اتصال انتخابشده یا اطلاعات احراز هویت را افشا نمیکنند. برای تمدید و آزادسازی، 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 با کلیدی دیگر، حتی اگر آن کلید همان اتصال را مجاز بداند، ناموفق خواهد بود. مالکان خام ماندگار یا ثبت نمیشوند، در تصویر لحظهای درخواست نگهداری نمیشوند و به بالادست ارسال نمیگردند.

رقابت موقت برای منابع، 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`

بازنویسی طرح فشردهسازی برای هر درخواست. دارای بالاترین اولویت است — از بازنویسی ترکیب مسیریابی، نمایه فعال، راهاندازی خودکار و مقدار Default پنل پیشی میگیرد. مقادیر:

مقدار	اثر
`off`	برای این درخواست فشردهسازی انجام نمیشود.
`default`	نمایه Default برگرفته از پنل (نمایه فعال را نادیده میگیرد).
`engine:<id>`	یک موتور واحد، در صورت فعال بودن؛ برای مثال `engine:rtk`.
`<combo>`	یک ترکیب نامگذاریشده که ابتدا بر اساس نام (بدون حساسیت به بزرگی و کوچکی حروف) و سپس بر اساس شناسه تطبیق داده میشود.

نکات:

مقادیر ناشناخته نادیده گرفته میشوند (درخواست هرگز رد نمیشود)؛ فرایند تعیین مقدار طبق تقدم معمول عملگرها ادامه مییابد.
اگر چند ترکیب نام یکسانی دارند، برای تطبیق قطعی، id ترکیب را ارسال کنید.
ترکیبی که نام آن off یا default است، نمیتواند بر اساس نام انتخاب شود (این کلمات کلیدی ابتدا تفسیر میشوند)؛ چنین ترکیبی را با id آن ارجاع دهید.
کلید اصلی فشردهسازی یک محدودیت قطعی است: هنگامی که فشردهسازی بهصورت سراسری غیرفعال باشد، این هدر نمیتواند آن را فعال کند.

طرح اعمالشده در هدر پاسخ بازگردانده میشود:

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

که در آن <source> یکی از مقادیر request-header، routing-override، active-profile، auto-trigger، default یا off است.

تعبیهها

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

{
  "model": "nebius/Qwen/Qwen3-Embedding-8B",
  "input": "The food was delicious"
}

ارائهدهندگان موجود: Nebius، OpenAI، Mistral، Together AI، Fireworks، NVIDIA، OpenRouter، Jina AI.

شناسههای کاتالوگ بهشکل provider/model هستند (مثال: jina-ai/jina-embeddings-v5-omni-small). شناسههای مدل Jina بدون پیشوند که در رجیستری وجود دارند (برای مثال jina-embeddings-v5-text-small و jina-reranker-v3.5) نیز شناسایی میشوند. عملیات embed/rerank/classify/segment در Jina ابتدا از اعتبارنامههای jina-ai در داشبورد استفاده میکنند؛ JINA_AI_API_KEY فقط زمانی جایگزین است که هیچ کلیدی در داشبورد وجود نداشته باشد. کارت jina-reader فقط برای Reader / r.jina.ai (POST /v1/web/fetch) است و هرگز تعبیه یا بازرتبهبندی ارائه نمیدهد.

مدلهای رجیستری که پشتیبانی چندوجهی را اعلام میکنند، حداکثر 32 آیتم ساختاریافته و مستقل از ارائهدهنده را نیز میپذیرند. انواع آیتمهای رسانهای عبارتاند از text، image، audio، video و document. مقدار source رسانه یا {"type":"url","url":"https://..."} است یا {"type":"base64","data":"...","media_type":"..."}.

Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small، jina-ai/jina-embeddings-v5-omni-nano و نام مستعار خانواده jina-ai/jina-embeddings-v5-omni → omni-small) همچنین مستندات بومی EmbeddingsV5Request متعلق به Jina را میپذیرد و آنها را بدون تغییر ارسال میکند به https://api.jina.ai/v1/embeddings:

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "task": "retrieval.query",
  "normalized": true,
  "input": [
    { "text": "a red bicycle" },
    { "image": "https://example.com/bike.png" },
    {
      "content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }]
    }
  ]
}

مقادیر بومی { image | audio | video | pdf } میتوانند یک URL عمومی HTTPS، یک URI از نوع data: یا base64 خام باشند. OmniRoute این اشیا را به رشته تبدیل نمیکند و URLهای بومی تصاویر را واکشی نمیکند — خود Jina رسانه عمومی را دریافت میکند. فیلدهای اضافی Jina (task، normalized، truncate، embedding_type) ارسال میشوند. SKUهای صرفاً متنی Jina همچنان مستندات غیرمتنی را رد میکنند.

محدودیتهای امنیتی و انتقال:

URLهای رسانه راهدور باید عمومی و از نوع HTTPS باشند. آیتمهای استاندارد {type,source:url} در سمت سرور واکشی میشوند (با اعتبارسنجی مجدد تغییر مسیر، مهلت زمانی، محدودیت اندازه، DNS عمومی و پینکردن اتصال) و پیش از فراخوانی ارائهدهنده بهصورت درونخطی قرار میگیرند. آیتمهای بومی Jina بهشکل {image:"https://..."} پس از همان بررسی عمومیبودن HTTPS، بدون تغییر ارسال میشوند؛ Jina خود URL را واکشی میکند.
رسانه base64 درونخطی به 8 MiB داده رمزگشاییشده برای هر آیتم و 16 MiB داده رمزگشاییشده در کل درخواست محدود است.

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

مدلهای چندوجهی Jina: هر آیتم سطح بالا به یک شیء دارای کلید وجه تبدیل میشود (text / image / audio / video / pdf) که برای رسانه درونخطی از URIهای داده استفاده میکند؛ یک بردار بهازای هر آیتم سطح بالا.
خانواده Gemini Embedding 2: یک آرایه سطح بالا به یک درخواست بومی models/{model}:embedContent با content.parts (text یا inline_data) تبدیل میشود.
مدلهای ناشناخته/پویا که فاقد فراداده صریح وجه هستند، ورودی ساختاریافته را با HTTP 400 رد میکنند.

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}

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

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

تولید تصویر

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

{
  "model": "openai/gpt-image-2",
  "prompt": "A beautiful sunset over mountains",
  "size": "1024x1024"
}

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

# فهرستکردن همه مدلهای تصویر
GET /v1/images/generations

OCR اسناد

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

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

model ارائهدهنده OCR را از طریق پیشوند provider/model انتخاب میکند؛ شناسه مدل بدون پیشوند (برای مثال mistral-ocr-latest) به ارائهدهنده ثبتشده آن نگاشت میشود و در صورت حذف model، مقدار پیشفرض Mistral (mistral-ocr-latest) خواهد بود. ارائهدهندگان ثبتشده (open-sse/config/ocrRegistry.ts):

شناسه ارائهدهنده	شناسه مدل	مقدار `model`	توضیحات
`mistral`	`mistral-ocr-latest`	`mistral/mistral-ocr-latest` (یا `mistral-ocr-latest` بدون پیشوند)	همگام — پاسخ مستقیماً از همان یک فراخوانی بالادستی بازگردانده میشود.
`azure-document-intelligence`	`prebuilt-read`	`azure-document-intelligence/prebuilt-read`	بالادست ناهمگام (`analyze` + نظرسنجی) — بخش زیر را ببینید.
`vertex-deepseek-ocr`	`deepseek-ocr-maas`	`vertex-deepseek-ocr/deepseek-ocr-maas`	همگام، از طریق نقطه پایانی شریک `openapi/chat/completions` در Vertex AI — برای احراز هویت/نشانی اینترنتی، بخش زیر را ببینید.

هر سه ارائهدهنده با بدنهای همشکل با 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) آن نشانی اینترنتی را هر ثانیه، حداکثر تا ۳۰ تلاش، نظرسنجی میکند؛ در صورت دریافت پاسخ نظرسنجی غیر-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 از پیش صادرشده است که بدون تغییر استفاده میشود. نشانی اینترنتی نقطه پایانی بالادستی، نقطه پایانی عمومی شریک 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 نیز همین کار را انجام میدهد.

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

برای مدلهای 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، تفکیک محیط زمان اجرا، توابع اجراکننده، هدرهای درخواست و دادههای حساب را شامل نمیشود.

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

Endpointهای سازگاری

متد	مسیر	قالب
POST	`/v1/chat/completions`	OpenAI
POST	`/v1/messages`	Anthropic
POST	`/v1/responses`	OpenAI Responses
POST	`/v1/embeddings`	OpenAI
POST	`/v1/images/generations`	OpenAI Images
POST	`/v1/images/edits`	OpenAI Images (ویرایش/inpaint)
POST	`/v1/videos/generations`	تولید ویدئو به سبک OpenAI
POST	`/v1/music/generations`	تولید موسیقی به سبک OpenAI
POST	`/v1/audio/transcriptions`	OpenAI Audio (STT)
POST	`/v1/audio/speech`	OpenAI TTS (بدنه صوتی برمیگرداند)
POST	`/v1/rerank`	بازرتبهبندی به سبک Cohere/Voyage
POST	`/v1/classify`	دستهبندی Jina (`api.jina.ai`)
POST	`/v1/segment`	قطعهبند Jina (`segment.jina.ai`)
POST	`/v1/moderations`	OpenAI Moderations
GET	`/v1/models`	OpenAI
POST	`/v1/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 مراجعه کنید). در صورت شکست اعتبارسنجی schema، پاسخ 4xx برگردانده میشود.

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

# بازرتبهبندی
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

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

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

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

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

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

# ویرایش تصویر (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# تولید ویدئو / موسیقی (شناسه مدل با پیشوند ارائهدهنده)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "suno/v3.5",   "prompt": "..." }

مسیرهای اختصاصی ارائهدهنده

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

اگر پیشوند ارائهدهنده وجود نداشته باشد، بهطور خودکار افزوده میشود. مدلهای ناسازگار پاسخ 400 برمیگردانند.

Files 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).

Batches API

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

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

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

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) با ترتیب اولویت ثابت (fill-first) انجام میشود — ارائهدهندهای که پیکربندی شده اما با محدودیت نرخ مواجه است، بهجای متوقفکردن زودهنگام درخواست نادیده گرفته میشود، و خطای بالادستی قابلتلاشمجدد/مرتبط با سهمیه (HTTP 429 همیشه؛ 402/403 برای سطوح رایگان مبتنی بر سهمیه Firecrawl/Tavily/TinyFish — نه برای Jina Reader و هرگز برای یک درخواست نامعتبر ساده 400) در زمان درخواست به ارائهدهنده بعدیِ امتحاننشده و دارای اعتبارنامه منتقل میشود. هنگامی که تمام ارائهدهندگان موجود در مجموعه تمام شوند، نقطه پایانی بهجای 400 عمومی قبلی، یک پاسخ 429 واحد (همراه با هدر Retry-After) برمیگرداند. هنگامی که یک provider مشخص درخواست شود، هیچ جایگزینی پنهانی انجام نمیشود — ارائهدهنده مشخصی که با محدودیت نرخ یا خرابی مواجه شده باشد، خطای خودش را برمیگرداند (429 در صورت محدودیت نرخ، وگرنه وضعیت بالادستی).

استریم WebSocket

GET /v1/ws?handshake=1

دستدهی ارتقای WebSocket را اعتبارسنجی میکند و پیامهای نمونه پروتکل روی سیم (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 به ارائهدهنده دیگری مسیریابی میشود.

پیکربندی OpenAI Codex CLI

با افزودن یک ارائهدهنده سفارشی دارای پشتیبانی 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"                    # تنها مقدار پشتیبانیشده از Feb 2026
supports_websockets = true                # انتقال Responses-over-WS را فعال میکند
env_key = "OMNIROUTE_API_KEY"             # کلید API متعلق به OmniRoute را نگه میدارد (Bearer)

export OMNIROUTE_API_KEY=sk-...           # یک کلید API متعلق به OmniRoute (اگر REQUIRE_API_KEY=false باشد، هر کلیدی)
codex exec "Responda apenas: PONG"

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

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

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

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

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

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

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

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

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

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

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

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

احراز هویت: کلید API از نوع Bearer متعلق به خود فراخواننده که با isValidApiKey اعتبارسنجی میشود — این سطح مدیریتی (/api/keys/…) نیست؛ سطح مدیریتی همچنان پشت requireManagementAuth باقی میماند.

کش معنایی

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

# پاکسازی همهٔ کشها
DELETE /api/cache/stats

نمونهٔ پاسخ:

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

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

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

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

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

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

مقدار	رفتار
`legacy`	رفتار عادی کش (پیشفرض)
`bypass`	جستوجو در کش را کاملاً رد میکند؛ همیشه بالادست را فراخوانی میکند

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

{ "cacheDefaultMode": "bypass" }

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

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

X-OmniRoute-No-Cache: true

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

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

احراز هویت

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

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

نقطه پایانی	متد	توضیحات
`/api/providers`	GET/POST	فهرست کردن / ایجاد ارائهدهندگان
`/api/providers/[id]`	GET/PUT/DELETE	مدیریت یک ارائهدهنده
`/api/providers/[id]/test`	POST	آزمایش اتصال ارائهدهنده
`/api/providers/[id]/models`	GET	فهرست کردن مدلهای ارائهدهنده
`/api/providers/validate`	POST	اعتبارسنجی پیکربندی ارائهدهنده
`/api/providers/bulk`	POST	افزودن گروهی کلیدهای API برای یک ارائهدهنده
`/api/providers/import`	POST	وارد کردن یک فهرست ناهمگون از ارائهدهندگان از فایل CSV/JSON تجزیهشده (#6836)؛ نتایج شکست جزئی برای هر ردیف
`/api/provider-nodes*`	مختلف	مدیریت گرههای ارائهدهنده
`/api/provider-models`	GET/POST/PATCH/DELETE	مدلهای سفارشی (افزودن، بهروزرسانی، پنهان/نمایان کردن، حذف)

جریانهای OAuth

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

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

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

میزان استفاده و تحلیلها

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

تنظیمات

نقطه پایانی	متد	توضیحات
`/api/settings`	GET/PUT/PATCH	تنظیمات عمومی
`/api/settings/proxy`	GET/PUT	پیکربندی پراکسی شبکه
`/api/settings/proxy/test`	POST	آزمایش اتصال پراکسی
`/api/settings/ip-filter`	GET/PUT	فهرست مجاز/مسدود IP
`/api/settings/thinking-budget`	GET/PUT	حالت بازنویسی درخواست بودجه تفکر/استدلال (عبور بدون تغییر / حذف خودکار / سفارشی / تطبیقی). مستقل از فشردهسازی است. به THINKING_BUDGET.md مراجعه کنید.
`/api/settings/system-prompt`	GET/PUT	پرامپت سیستمی سراسری
`/api/settings/compression`	GET/PUT	پیکربندی سراسری فشردهسازی
`/api/settings/purge-request-history`	POST	پاککردن ردیفهای گزارش درخواست و مصنوعات محلی گزارش فراخوانی

زمینه و فشردهسازی

نقطه پایانی	متد	توضیحات
`/api/compression/preview`	POST	پیشنمایش فشردهسازی off/lite/standard/aggressive/ultra/RTK/stacked
`/api/compression/language-packs`	GET	فهرست بستههای زبانی موجود Caveman
`/api/compression/rules`	GET	فهرست فرادادههای قواعد Caveman
`/api/context/caveman/config`	GET/PUT	نام مستعار تنظیمات اختصاصی Caveman
`/api/context/rtk/config`	GET/PUT	تنظیمات اختصاصی RTK، شامل فیلترهای سفارشی و نگهداری خروجی خام
`/api/context/rtk/filters`	GET	کاتالوگ فیلترهای RTK و اطلاعات تشخیصی فیلترهای سفارشی
`/api/context/rtk/test`	POST	اجرای پیشنمایش/آزمایش RTK روی یک محموله متنی
`/api/context/rtk/raw-output/[id]`	GET	خواندن خروجی خام ویرایششده نگهداریشده بر اساس شناسه اشارهگر
`/api/context/combos`	GET/POST	فهرست/ایجاد ترکیبهای فشردهسازی
`/api/context/combos/[id]`	GET/PUT/DELETE	جزئیات/بهروزرسانی/حذف ترکیب فشردهسازی
`/api/context/combos/[id]/assignments`	GET/PUT	تخصیص ترکیبهای فشردهسازی به ترکیبهای مسیریابی
`/api/context/analytics`	GET	نام مستعار تحلیلهای فشردهسازی

پایش

نقطه پایانی	متد	توضیحات
`/api/sessions`	GET	ردیابی نشستهای فعال
`/api/rate-limits`	GET	محدودیتهای نرخ بهازای هر حساب
`/api/monitoring/health`	GET	بررسی سلامت + خلاصه ارائهدهنده (`catalogCount`، `configuredCount`، `activeCount`، `monitoredCount`). نمای مدیریتی شامل `credentialHealth` است: مقادیر اسکالر کشِ وارسی، `failedConnections` در صورت `failed>0`، و `staleDbNonOkCount` (`test_status` ماندگار SQLite، نه سنجه). به MONITORING_GUIDE.md مراجعه کنید.
`/api/cache/stats`	GET/DELETE	آمار کش / پاکسازی
`/api/modality-bridge/stats`	GET	`attempts` درونحافظهای، موفقیتها/`bridged`، شکستها، اصابتهای کش، `totalLatencyMs`، `latencySamples`، `averageLatencyMs` با مخرجِ تعداد نمونهها، و زمان آخرین استفاده (با راهاندازی مجدد بازنشانی میشود؛ احراز هویت مدیریتی)
`/api/modality-bridge/video/runtime`	GET	بررسی سختگیرانه حلقهبازگشت قابلاعتماد پیش از احراز هویت/وارسی مدیریتی؛ دسترسپذیری و نسخههای پاکسازیشده 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/export`	GET	دانلود پایگاه داده بهصورت فایل .sqlite
`/api/db-backups/import`	POST	بارگذاری فایل .sqlite برای جایگزینی پایگاه داده
`/api/db-backups/exportAll`	GET	دانلود نسخه پشتیبان کامل بهصورت آرشیو .tar.gz

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

نقطه پایانی	متد	توضیحات
`/api/sync/cloud`	مختلف	عملیات همگامسازی ابری
`/api/sync/initialize`	POST	راهاندازی همگامسازی
`/api/cloud/*`	مختلف	مدیریت فضای ابری

تونلها

نقطه پایانی	متد	توضیحات
`/api/tunnels/cloudflared`	GET	مشاهده وضعیت نصب/اجرای Cloudflare Quick Tunnel برای داشبورد
`/api/tunnels/cloudflared`	POST	فعال یا غیرفعالکردن Cloudflare Quick Tunnel (`action=enable/disable`)
`/api/tunnels/ngrok`	GET	مشاهده وضعیت اجرای ngrok Tunnel برای داشبورد
`/api/tunnels/ngrok`	POST	فعال یا غیرفعالکردن ngrok Tunnel (`action=enable/disable`)

ابزارهای CLI

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

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

عاملهای ACP

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

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

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

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

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

ارزیابیها

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

سیاستها

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

انطباق

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

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

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

این نقاط پایانی برای کلاینتهایی که انتظار سازگاری بومی با 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

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

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

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

{
  "provider": "claude-code"
}

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

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

رونویسی صوت

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

فایلهای صوتی را با استفاده از هر ارائهدهنده پیکربندیشده STT رونویسی کنید. نخستین بخش مسیر، ارائهدهنده بومی را انتخاب میکند (openai/…، deepgram/…). درگاههایی که مدل یک فروشنده دیگر را مجدداً ارائه میکنند، از یک شناسه واجد شرایط استفاده میکنند (openrouter/deepgram/nova-3).

درخواست:

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

پاسخ:

{
  "text": "سلام، این محتوای صوتی رونویسیشده است.",
  "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 تکمیل میکنند. این یک نقطه پایانی از نوع مدیریتی است (احراز هویت بهصورت مرکزی توسط خط لوله authz اعمال میشود).

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

کلاینت درخواست را به /v1/* ارسال میکند
کنترلکننده مسیر، handleChat، handleEmbedding، handleAudioTranscription یا handleImageGeneration را فراخوانی میکند
مدل تعیین میشود (ارائهدهنده/مدل مستقیم یا نام مستعار/ترکیب)
اعتبارنامهها با فیلتر کردن دسترسپذیری حساب از پایگاه داده محلی انتخاب میشوند
برای چت: handleChatCore کش معنایی/امضا را بررسی و تنظیمات فشردهسازی ترکیب را تعیین میکند
در صورت فعال بودن، فشردهسازی پیشدستانه پیش از ترجمه ارائهدهنده اجرا میشود (lite، Caveman، RTK یا انباشته)
اجراکننده ارائهدهنده، درخواست را به سرویس بالادستی ارسال میکند
پاسخ به قالب کلاینت ترجمه میشود (برای چت) یا بدون تغییر بازگردانده میشود (برای تعبیهها/تصاویر/صوت)
میزان استفاده، تحلیلهای فشردهسازی و گزارشهای درخواست ثبت میشوند
در صورت بروز خطا، مطابق قوانین ترکیب از جایگزین استفاده میشود

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

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

ترکیبهای مسیریابی سطحبالا (که پیشتر در بخش /api/combos* خلاصه شدهاند) همچنین میتوانند بهصورت 1:1 از یک الگوی شناسه مدل نگاشت شوند و تغییر مسیر شفاف یک شناسه مدل به سبک OpenAI به یک ترکیب را امکانپذیر کنند.

متد	مسیر	توضیحات
GET	`/api/model-combo-mappings`	فهرست کردن تمام نگاشتهای مدل→ترکیب
POST	`/api/model-combo-mappings`	ایجاد نگاشت — بدنه: `{pattern, comboId, priority?, enabled?, description?}`
GET	`/api/model-combo-mappings/[id]`	دریافت یک نگاشت
PUT	`/api/model-combo-mappings/[id]`	بهروزرسانی فیلدهای یک نگاشت موجود
DELETE	`/api/model-combo-mappings/[id]`	حذف یک نگاشت

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

وبهوکها

اشتراکهای وبهوک خروجی برای رویدادهای 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 از نوع Bearer (isAuthenticated). همچنین /v1/quotas/check و /v1/issues/report را ببینید.

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

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

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

احراز هویت: احراز هویت مدیریتی برای همه متدها الزامی است (requireCloudAgentManagementAuth). پیش از v3.8.0 این مسیرها بدون احراز هویت بودند — برای مشاهده این تغییر ناسازگار، به کامیت 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 ← «وضعیت زمان اجرای تابآوری» مراجعه کنید.

مهارتها

چارچوب مهارت برای گسترش 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": "این وظیفهٔ برنامهنویسی را مسیریابی کن"}]
  }
}

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

فضای ابری، ارزیابیها و سنجش

متد	مسیر	توضیحات
POST	`/api/cloud/auth`	اعتبارسنجی یک کلید Bearer و بازگرداندن اتصالهای پوشاندهشدهٔ ارائهدهندگان + نامهای مستعار مدل برای کلاینتهای همگامسازی ابری
POST	`/api/cloud/credentials/update`	بهروزرسانی اطلاعات اعتبارسنجی رمزگذاریشده برای یک ارائهدهندهٔ همگامشده با فضای ابری
POST	`/api/cloud/model/resolve`	نگاشت یک شناسهٔ منطقی مدل به یک ارائهدهنده/مدل مشخص با استفاده از جدول مسیریابی محلی
GET	`/api/cloud/models/alias`	فهرستکردن نامهای مستعار مدل، همانگونه که در اختیار همگامسازی ابری قرار میگیرند
GET	`/api/assess`	خواندن آخرین دستهبندیهای سنجش (بهازای هر ارائهدهنده/مدل)
POST	`/api/assess`	اجرای یک سنجش — بدنه: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	`/api/evals`	فهرستکردن مجموعههای ارزیابی داخلی + جدیدترین اجراها
POST	`/api/evals`	آغاز یک اجرای ارزیابی
POST	`/api/evals/suites`	ایجاد یک مجموعهٔ ارزیابی سفارشی — بدنه توسط `evalSuiteSaveSchema` اعتبارسنجی میشود
GET	`/api/evals/suites/[id]`	بازیابی یک مجموعهٔ ارزیابی سفارشی

احراز هویت: /api/cloud/auth یک کلید Bearer را مستقیماً اعتبارسنجی میکند؛ سایر مسیرهای /api/cloud/*، /api/evals/* و /api/assess به نشست مدیریتی/کلید API نیاز دارند. درخواست POST به /api/assess از validateBody بههمراه یک شِمای دامنه از نوع اجتماع متمایزشده استفاده میکند.

مدیریت ACP (Agent Client Protocol)

بهعنوان فرایندهای فرزند. این نقاط پایانی، شناسایی عاملهای ACP و ثبت عاملهای سفارشی را مدیریت میکنند.

متد	مسیر	توضیحات
GET	`/api/acp/agents`	فهرستکردن همه عاملهای CLI شناختهشده (داخلی + سفارشی) همراه با وضعیت نصب، نسخه و فایل اجرایی
POST	`/api/acp/agents`	ثبت یک عامل ACP سفارشی یا تازهسازی حافظه نهان — بدنه: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` یا `{action: "refresh"}`
DELETE	`/api/acp/agents`	حذف یک عامل ACP سفارشی — پارامتر کوئری: `?id=<agentId>`

نمونه پاسخ (GET /api/acp/agents):

{
  "agents": [
    {
      "id": "claude",
      "name": "Claude Code CLI",
      "binary": "claude",
      "version": "1.0.45",
      "installed": true,
      "protocol": "stdio",
      "providerAlias": "claude",
      "isCustom": false
    },
    {
      "id": "my-custom-cli",
      "name": "My Custom CLI",
      "installed": false,
      "protocol": "stdio",
      "providerAlias": "my-provider",
      "isCustom": true
    }
  ],
  "cacheTtlMs": 60000,
  "cacheAge": 1234
}

احراز هویت: به نشست مدیریتی (کوکی 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، chipotle، commandCode، devin-cli و غیره) مدیریت کنید. برای مشاهده فهرست کامل، به مرجع ارائهدهندگان مراجعه کنید.

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

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

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

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

147 KiB Raw Blame History Unescape Escape

API Reference (فارسی)

فهرست مطالب

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

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

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

x-omniroute-compression

تعبیهها

تولید تصویر

OCR اسناد

جریان نظرسنجی Azure Document Intelligence

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

فهرست مدلها

پیشوندهای شناسهٔ مدل (?prefix=)

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

مانیفست افزونه ارائهدهنده

Endpointهای سازگاری

مسیرهای اختصاصی ارائهدهنده

Files API

Batches API

API جستوجو

API واکشی وب

استریم WebSocket

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

شناسه مدل: از شناسه خام ChatGPT استفاده کنید (بدون پیشوند codex/)

پیکربندی OpenAI Codex CLI

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

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

کش معنایی

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

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

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

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

احراز هویت

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

جریانهای OAuth

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

میزان استفاده و تحلیلها

تنظیمات

زمینه و فشردهسازی

پایش

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

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

تونلها

ابزارهای CLI

عاملهای ACP

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

ارزیابیها

سیاستها

انطباق

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

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

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

رونویسی صوت

سازگاری با Ollama

نامهای مستعار توکندار VS Code / بدون هدر

تلهمتری

بودجه

محدودیتهای توکن

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

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

وبهوکها

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

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

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

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

مهارتها

حافظه

سرور MCP

سرور A2A

JSON-RPC

کارت عامل

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

فضای ابری، ارزیابیها و سنجش

مدیریت ACP (Agent Client Protocol)

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

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

تحلیل فشردهسازی

ردیابی تنوع ارائهدهندگان

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

147 KiB

Raw Blame History

`x-omniroute-compression`

پیشوندهای شناسهٔ مدل (`?prefix=`)

شناسه مدل: از شناسه خام ChatGPT استفاده کنید (بدون پیشوند `codex/`)

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