# API Reference (فارسی) 🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇧🇦 [bs](../../../bs/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md) --- 🌐 **زبانها:** 🇺🇸 [English](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇧🇦 [Bosanski](../i18n/bs/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md) مرجع اصلی API مربوط به OmniRoute. این سند سطح عمومی `/v1` و پرکاربردترین نقاط پایانی مدیریتی را پوشش میدهد؛ فایل ماشینخوانِ [`docs/openapi.yaml`](../openapi.yaml) و درخت مسیر زیر `src/app/api/` منابع جامع هستند. برای پروتکل متمرکزِ سازگار با OpenAI و ماتریس قابلیتهای ارائهدهندگان، به [`OPENAI_COMPATIBILITY.md`](./OPENAI_COMPATIBILITY.md) مراجعه کنید. --- ## فهرست مطالب - [تکمیلهای گفتگو](#chat-completions) - [اجارههای انحصاری نشست مدیریتشده](#exclusive-managed-session-leases) - [تعبیهها](#embeddings) - [تولید تصویر](#image-generation) - [OCR اسناد](#document-ocr) - [فهرست مدلها](#list-models) - [مانیفست افزونه ارائهدهنده](#provider-plugin-manifest) - [نقاط پایانی سازگاری](#compatibility-endpoints) - [API فایلها](#files-api) - [API دستهها](#batches-api) - [API جستوجو](#search-api) - [استریم WebSocket](#websocket-streaming) - [گزارش سهمیهها و مشکلات](#quotas--issues-reporting) - [کش معنایی](#semantic-cache) - [داشبورد و مدیریت](#dashboard--management) - [مدیریت ترکیبها](#combo-management) - [وبهوکها](#webhooks) - [کلیدهای ثبتشده (مدیریت خودکار)](#registered-keys-auto-management) - [پروتکل عاملها](#agents-protocol) - [پروکسیهای مدیریتی](#management-proxies) - [تابآوری (توسعهیافته)](#resilience-extended) - [مهارتها](#skills) - [حافظه](#memory) - [سرور MCP](#mcp-server) - [سرور A2A](#a2a-server) - [ابر، ارزیابیها و سنجش](#cloud-evals--assess) - [پردازش درخواست](#request-processing) - [احراز هویت](#authentication) --- ## تکمیلهای گفتگو ```bash POST /v1/chat/completions Authorization: Bearer your-api-key Content-Type: application/json { "model": "cc/claude-opus-4-6", "messages": [ {"role": "user", "content": "Write a function to..."} ], "stream": true } ``` ### هدرهای سفارشی | هدر | جهت | توضیحات | | ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-OmniRoute-No-Cache` | درخواست | برای دور زدن کش، روی `true` تنظیم کنید | | `x-omniroute-no-memory` | درخواست | برای رد کردن تزریق حافظه و مهارتها در این درخواست، روی `true` تنظیم کنید (مشابه حالت بدون کش؛ از سربار توکن/هزینه بهازای هر فراخوانی جلوگیری میکند) | | `X-OmniRoute-Progress` | درخواست | برای رویدادهای پیشرفت، روی `true` تنظیم کنید | | `X-Session-Id` | درخواست | کلید نشست چسبنده برای وابستگی نشست خارجی | | `x_session_id` | درخواست | گونه دارای زیرخط نیز پذیرفته میشود (HTTP مستقیم) | | `X-OmniRoute-Session-Id` | درخواست | برچسب نشست/مکالمه ارائهشده توسط فراخواننده (همچنین حافظه را تغذیه میکند). در صورت وجود، بدون تغییر در `call_logs.session_tag` برای انتساب هزینه بهازای هر نشست (#8249) ذخیره میشود — در صورت نبود هرگز ساخته نمیشود | | `Idempotency-Key` | درخواست | کلید حذف موارد تکراری (بازه ۵ ثانیهای) | | `X-Request-Id` | درخواست | کلید جایگزین حذف موارد تکراری | | `x-omniroute-connection` | درخواست | یک درخواست تکمدلی را با استفاده از شناسه آن به یک اتصال ارائهدهنده (حساب) متصل نگه دارید — به [اتصال درخواست به حساب](#account-pinning-per-request) مراجعه کنید | | `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=; provider=; latency_ms=` (`` راهبرد ترکیب است، یا برای یک درخواست غیرترکیبی `single`) — همیشه در پاسخهای تکمیل وجود دارد | > نکته درباره Nginx: اگر به هدرهای دارای زیرخط متکی هستید (برای مثال `x_session_id`)، گزینه `underscores_in_headers on;` را فعال کنید. #### پینکردن حساب برای هر درخواست هنگامی که یک ارائهدهنده چند اتصال (حساب یا کلید) دارد، OmniRoute معمولاً یکی از آنها را از طریق راهبرد انتخاب حساب خود برمیگزیند. در عوض، یک درخواست میتواند با هدر `x-omniroute-connection` یک اتصال مشخص را پین کند: ```bash curl http://localhost:20128/v1/chat/completions \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "x-omniroute-connection: " \ -d '{"model": "codex/gpt-5.5", "messages": [{"role": "user", "content": "hi"}]}' ``` - **شناسه را کجا پیدا کنیم.** صفحه ارائهدهنده را در داشبورد باز کنید (**داشبورد ← ارائهدهندگان ← **) و روی تراشه شناسه `xxxxxxxx…` در ردیف اتصال کلیک کنید — با این کار شناسه کامل اتصال کپی میشود. - **کدام درخواستها از آن پیروی میکنند.** درخواستهای تکمدلی (`provider/model`) در `/v1/chat/completions`، `/v1/messages` و `/v1/responses`. ترکیبها این هدر را نادیده میگیرند؛ در عوض، برای هر مرحله ترکیب، یک حساب را از طریق اتصال خود آن مرحله پین کنید. - **پین سختگیرانه است، نه صرفاً یک ترجیح.** اتصال پینشده بهصورت انحصاری استفاده میشود. بروز خطا درون درخواست، دوره انتظار حساب را ثبت میکند، اما به یک حساب همرده از همان ارائهدهنده **تغییر مسیر نمیدهد**. - **دوره انتظار و سهمیه، پین را آزاد میکنند.** هنگامی که اتصال پینشده در دوره انتظار است، سهمیهاش تمام شده یا بهدلیل یک خطمشی سهمیه مسدود شده است، درخواستهای بعدی دقیقاً مانند ترافیک پیننشده به سایر اتصالهای ارائهدهنده بازمیگردند. - **شناسههای ناشناخته یا غیرفعال با شکست مواجه میشوند.** شناسهای که در مجموعه فعال ارائهدهنده نیست (حذفشده، غیرفعالشده یا متعلق به ارائهدهندهای دیگر)، هیچ حساب واجد شرایطی باقی نمیگذارد؛ بنابراین درخواست بهجای آنکه بیسروصدا به مسیر دیگری هدایت شود، با شکست مواجه میشود. Claude Code هدرهای سفارشی را از طریق `ANTHROPIC_CUSTOM_HEADERS` ارسال میکند. آن را در بلوک `env` فایل `~/.claude/settings.json` یا در فایل `.claude/settings.json` در سطح پروژه قرار دهید تا برای هر پروژه حساب متفاوتی پین شود: ```jsonc { "env": { "ANTHROPIC_BASE_URL": "http://:20128", "ANTHROPIC_AUTH_TOKEN": "", "ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: ", }, } ``` منبع: `src/sse/handlers/chat.ts` (خواندن هدر)، `src/sse/services/auth.ts` و `src/sse/services/sessionAffinityPin.ts` (آزادسازی پین و بررسی نبودن در مجموعه). > **هدرهای تلهمتری هزینه:** پاسخهای موفقِ غیرجریانی، مجموعه تلهمتری هزینه `X-OmniRoute-*` را نیز در بر دارند — `X-OmniRoute-Response-Cost` (دلار آمریکا، با ۱۰ رقم اعشار ثابت؛ `0.0000000000` برای موارد رایگان یا بدون قیمت)، `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`، `X-OmniRoute-Model`، `X-OmniRoute-Provider`، `X-OmniRoute-Latency-Ms`، `X-OmniRoute-Cache-Hit` و `X-OmniRoute-Fallback-Attempts` (فقط زمانی که > 0 باشد)، بهعلاوه `X-OmniRoute-Request-Id` و `X-OmniRoute-Version`. این هدرها توسط تکمیلهای چت، `/v1/responses`، `/v1/messages` و **نقاط پایانی رسانه** منتشر میشوند — `/v1/embeddings`، `/v1/images/generations`، `/v1/audio/speech`، `/v1/audio/transcriptions`، `/v1/rerank`، `/v1/videos/generations`، `/v1/music/generations` و `/v1/moderations` (هزینه همیشه `0` است). در صورت موجود بودن قیمتگذاری، هزینه رسانه بر اساس هر وجه محاسبه میشود (بهازای هر تصویر، هر ثانیه، هر نویسه یا هر واحد جستوجو)؛ در غیر این صورت `0` است (در صورت خطا، باز میماند). > **معنای هزینه در اصابت کش:** هنگام اصابت به کش معنایی (`X-OmniRoute-Cache-Hit: true`)، هیچ فراخوانی بالادستی انجام نمیشود؛ بنابراین `X-OmniRoute-Response-Cost` برابر با `0.0000000000` است (هزینه **افزایشی** ارائه نتیجه اصابت). هزینه اصلی یا هزینهای که در غیر این صورت ایجاد میشد، بهطور جداگانه در `X-OmniRoute-Cost-Saved` گزارش میشود. مصرفکنندگان صورتحساب باید مجموع `X-OmniRoute-Response-Cost` را محاسبه کنند (اصابتها هزینهای ندارند)؛ سامانههای تحلیل کش میتوانند `X-OmniRoute-Cost-Saved` را تجمیع کنند. ## اجارههای انحصاری نشست مدیریتشده اجاره انحصاری نشست مدیریتشده، یک قرارداد مسیریابی اختیاری و مستقل از کلاینت است: یک مالک فعال، یک اتصال واجد شرایط OmniRoute را در اختیار میگیرد. این سازوکار یک مدل را اجاره نمیدهد، به OAuth نیاز ندارد، کلاینت خاصی را شناسایی نمیکند و به ارائهدهنده خاصی نیاز ندارد. کلید API احراز هویتکننده باید دارای دامنه `lease:exclusive` و یک فهرست صریح و غیرخالی `allowedConnections` باشد. مرز جهش پایگاه داده، وجود همزمان هر دو فیلد را هنگام ایجاد کلید و بهروزرسانیهای جزئی الزامی میکند. ```http POST /api/v1/session-leases Authorization: Bearer Content-Type: application/json X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> {"action":"acquire","model":"glm/glm-4.6"} ``` پاسخهای موفق دریافت، تمدید و آزادسازی، برچسبهای زمانی، `state` و مقدار مثبت دقیق `generation` را نمایش میدهند، اما هرگز اتصال انتخابشده یا اطلاعات اعتبارسنجی را افشا نمیکنند. برای تمدید و آزادسازی، نسل در بدنه JSON ارائه میشود: ```json { "action": "renew", "generation": 1 } ``` ```json { "action": "release", "generation": 1, "reason": "OWNER_EXIT" } ``` مالک یک اجاره فعال میتواند بهطور صریح فراداده نمایشی ایمن از نظر حریم خصوصی را برای اتصال فعلی خود درخواست کند: ```json { "action": "status", "generation": 1 } ``` ```json { "state": "ACTIVE", "generation": 1, "acquiredAt": "2026-08-28T12:00:00.000Z", "renewedAt": "2026-08-28T12:00:30.000Z", "expiresAt": "2026-08-28T12:02:30.000Z", "connection": { "displayName": "Primary Codex", "provider": "codex" } } ``` این کنش اختیاری وضعیت، در یک تراکنش پایگاه داده با مالک مبهم، کلید API مدیریتشده احراز هویتشده و نسل فعال دقیق حصاربندی میشود. `displayName` فقط نام پیکربندیشده و بدون فاصلههای اضافی اتصال است؛ هنگامی که نام پیکربندیشده امنی وجود نداشته باشد، مقدار آن `null` است. OmniRoute هرگز ایمیل یا هویت حساب تولیدشدهای را جایگزین نمیکند. مقدار ارائهدهنده، یک برچسب نمایشی غیرحساس است و هرگز شناسه تولیدشده یک ارائهدهنده سازگار نیست. اطلاعات اعتبارسنجی، توکنها، کوکیها، شناسههای خام اتصال یا کلید API، هشهای مالک، اسرار حصاربندی و دادههای داخلی مسیریابی حذف میشوند. جستوجوهای دارای کلید اشتباه، مالک اشتباه، نسل منقضی، مورد مفقود، منقضیشده، آزادشده یا باطلشده، همگی بدون فراداده اتصال همان خطای `409 LEASE_FENCE_STALE` را برمیگردانند. کلاینتی که پاسخ انتظار برای ظرفیت را دریافت کرده است، هیچ اتصال فعالی برای بررسی ندارد. هنگامی که مسیریابی یک اجاره فعال را منتقل میکند، همان نسل معتبر باقی میماند و وضعیت بهصورت اتمی اتصال جدید را برمیگرداند، نه اتصال قدیمی را. کلاینتهای موجود بدون تغییر باقی میمانند، زیرا پاسخهای دریافت، تمدید، آزادسازی و انتظار، ساختار قبلی خود را حفظ میکنند. این قرارداد سرور، `/status` استاندارد OpenAI Codex را تغییر نمیدهد. Codex استاندارد در حال حاضر ارائهدهنده مدل و وضعیت داخلی احراز هویت/حساب خود را گزارش میکند، اما فراداده دلخواه حساب ارائهدهنده سفارشی را نمایش نمیدهد؛ یک یکپارچهسازی آتی کلاینت باید این کنش را فراخوانی کند و درباره نحوه نمایش `connection.displayName` تصمیم بگیرد. پس از آن، هر درخواست استنتاج مدیریتشده هر دو سرآیند کنترلی را ارائه میکند: ```http X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> X-OmniRoute-Lease-Generation: 1 ``` مالک دقیق، نسل، اتصال فعال و کلید API احراز هویتشده، بلافاصله پیش از هر تلاش بالادستی پشتیبانیشده حصاربندی میشوند. بازپخش مالک و نسل با کلیدی دیگر، حتی زمانی که آن کلید همان اتصال را مجاز میداند، ناموفق خواهد بود. مالکان خام ذخیره، ثبت یا در تصویر لحظهای درخواست نگهداری نمیشوند و به بالادست نیز ارسال نمیشوند. رقابت موقت بر سر منابع، HTTP `429` را همراه با `Retry-After` و محتوای زیر برمیگرداند: ```json { "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:` | در صورت فعال بودن، یک موتور واحد؛ برای مثال `engine:rtk`. فعالسازی اختیاری آن موتور برای هر درخواست. | | `` | یک ترکیب نامگذاریشده که ابتدا بر اساس نام (بدون حساسیت به بزرگی و کوچکی حروف) و سپس بر اساس شناسه تطبیق داده میشود. | نکات: - مقادیر ناشناخته نادیده گرفته میشوند (درخواست هرگز رد نمیشود)؛ فرایند تعیین مقدار به ترتیب اولویت عادی اپراتور ادامه مییابد. - اگر چند ترکیب نام یکسانی دارند، برای تطبیق قطعی، **شناسه** ترکیب را ارسال کنید. - ترکیبی که نام آن `off` یا `default` باشد، با نام قابل انتخاب نیست (این کلیدواژهها ابتدا تفسیر میشوند)؛ برای ارجاع به چنین ترکیبی از شناسه آن استفاده کنید. - کلید اصلی فشردهسازی یک مانع قطعی است: هنگامی که فشردهسازی بهصورت سراسری غیرفعال باشد، این سرآیند نمیتواند آن را فعال کند. طرح اعمالشده در سرآیند پاسخ بازگردانده میشود: ``` X-OmniRoute-Compression: ; source= ``` که در آن `` یکی از مقادیر `request-header`، `routing-override`، `active-profile`، `auto-trigger`، `default` یا `off` است. --- ## تعبیهسازیها ```bash POST /v1/embeddings Authorization: Bearer your-api-key Content-Type: application/json { "model": "nebius/Qwen/Qwen3-Embedding-8B", "input": "The food was delicious" } ``` ارائهدهندگان موجود: Nebius، OpenAI، Mistral، Together AI، Fireworks، NVIDIA، **OpenRouter** و Jina AI. شناسههای کاتالوگ بهشکل `provider/model` هستند (مثال: `jina-ai/jina-embeddings-v5-omni-small`). شناسههای مدل Jina بدون پیشوند که در رجیستری وجود دارند (برای مثال `jina-embeddings-v5-text-small` و `jina-reranker-v3.5`) نیز تفکیک میشوند. عملیات تعبیهسازی/بازرتبهبندی/طبقهبندی/قطعهبندی Jina ابتدا از اعتبارنامههای `jina-ai` در داشبورد استفاده میکنند؛ `JINA_AI_API_KEY` تنها زمانی گزینهٔ جایگزین است که هیچ کلید داشبوردی وجود نداشته باشد. کارت `jina-reader` فقط برای Reader / `r.jina.ai` است (`POST /v1/web/fetch`) و هرگز تعبیهسازی یا بازرتبهبندی ارائه نمیکند. مدلهای رجیستری که پشتیبانی چندوجهی را اعلام میکنند، حداکثر ۳۲ آیتم ساختاریافته و مستقل از ارائهدهنده را نیز میپذیرند. انواع آیتمهای رسانهای عبارتاند از `text`، `image`، `audio`، `video` و `document`. مقدار `source` برای رسانه یا `{"type":"url","url":"https://..."}` است یا `{"type":"base64","data":"...","media_type":"..."}`. Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`، `jina-ai/jina-embeddings-v5-omni-nano` و نام مستعار خانوادهٔ `jina-ai/jina-embeddings-v5-omni` → omni-small) همچنین اسناد بومی EmbeddingsV5Request متعلق به Jina را میپذیرد و آنها را **بدون تغییر** به `https://api.jina.ai/v1/embeddings` ارسال میکند: ```json { "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/`، هر مدلی که سرور محلی بارگذاری کرده باشد): آیتمهای متعارف `text` به رشتههای ساده تبدیل میشوند و هرکدام از `image` / `audio` / `video` به یک شیء `{"content": [part]}` تبدیل میشوند؛ این کار با استفاده از بخشهای محتوای گفتوگوی llama-server (`image_url`، `input_audio` با قالب `wav` / `mp3` / `flac` و `input_video`) و دادههای درونخطی انجام میشود؛ برای هر آیتم سطح بالا یک بردار تولید میشود. سرور باید با `--embedding --mmproj …` اجرا شود؛ بدون پروژکتور، خود سرور رسانه را رد میکند. `document` پشتیبانی نمیشود. - مدلهای ناشناخته/پویا که فرادادهٔ صریحی دربارهٔ وجه ندارند، ورودی ساختاریافته را با HTTP 400 رد میکنند. ```json { "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 برمیگردانند. فیلدهای توسعهای غیرورودی در درخواستهای قدیمی رشتهای/توکنی همچنان بدون تغییر عبور داده میشوند. ```bash # فهرستکردن همهٔ مدلهای تعبیهسازی GET /v1/embeddings ``` --- ## تولید تصویر ```bash POST /v1/images/generations Authorization: Bearer your-api-key Content-Type: application/json { "model": "openai/gpt-image-2", "prompt": "A beautiful sunset over mountains", "size": "1024x1024" } ``` ارائهدهندگان موجود شامل OpenAI (GPT Image 2)، xAI (Grok Image)، Together AI (FLUX)، Fireworks AI، Nebius (FLUX)، Hyperbolic، NanoBanana، **OpenRouter**، **ZenMux**، SD WebUI (محلی) و ComfyUI (محلی) هستند. `n` تعداد `n` تصویر را در `data[]` برمیگرداند. برای ارائهدهندگانی که API بالادستی آنها در هر فراخوانی یک تصویر برمیگرداند (Black Forest Labs، Stability AI، Leonardo، Ideogram، Haiper، Hyperbolic، Magnific/Freepik، NVIDIA NIM، Cloudflare Workers AI)، تعداد `n` فراخوانی جداگانه بالادستی انجام میشود که حداکثر ۴ مورد از آنها بهطور همزمان در حال اجرا خواهند بود. یک `seed` ثابت بر اساس اندیس فراخوانی افزایش مییابد (`seed`، `seed + 1`، …)، بنابراین تصاویر متفاوت هستند اما همچنان قابلیت بازتولید دارند. مقدار `n` حداکثر ۱۰ است. اگر هرکدام از فراخوانیها ناموفق باشد، کل درخواست ناموفق خواهد بود. فهرست قالبهای fan-out در `SINGLE_IMAGE_FANOUT_FORMATS` در `open-sse/handlers/imageGeneration/fanOut.ts` قرار دارد. ZenMux از اتصال موجود مبتنی بر کلید API مجدداً استفاده میکند و پیشوندهای `zenmux/` یا `zm/` را میپذیرد: - `zenmux/openai/gpt-image-2` از OpenAI Images API متعلق به ZenMux استفاده میکند. گزینهها شامل `size`، `quality`، `n`، `output_format`، `output_compression`، `background` و `response_format` هستند. - ناشران دیگر، مانند `zm/meta/muse-image-1.0`، از نقطه پایانی `:predict` مربوط به Vertex AI در ZenMux استفاده میکنند. `n` به `sampleCount`، مقدار `aspect_ratio` به `aspectRatio` و `image_size` (`1K`، `2K`، `4K`) به `sampleImageSize` نگاشت میشود. مقدار پیکسلی `size` فقط نسبت ابعاد را مشخص میکند و ابعاد پیکسلی را تضمین نمیکند. نسبتها، وضوحها و تعدادهای پشتیبانیشده بسته به مدل متفاوت هستند. - `zm/inclusionai/ming-image-0.1-design` ابعاد را بهصورت خودکار انتخاب میکند. `size`، `aspect_ratio` و `image_size` را حذف کنید؛ مقادیر صریح باعث بازگشت HTTP 400 میشوند. میتوان PNG، JPEG و WebP را با `output_format` درخواست کرد. این یکپارچهسازی از تولید تصویر از متن پشتیبانی میکند، نه ویرایش تصویر مرجع. خروجی Vertex به `data[].b64_json` نرمالسازی میشود؛ `response_format: "url"` یک URL بالادستی HTTPS یا، در صورتی که فقط بایتهای تصویر موجود باشند، یک URL دادهای base64 برمیگرداند. خروجیهای خالی یا فیلترشده بهجای یک پاسخ موفق خالی، خطا برمیگردانند. دسترسی به مدل به حساب ZenMux بستگی دارد. به [API مربوط به Vertex در ZenMux](https://docs.zenmux.ai/api/vertexai/generate-images) و [OpenAI Images API](https://docs.zenmux.ai/api/openai/generate-an-image) مراجعه کنید. ```bash # فهرست همه مدلهای تصویر GET /v1/images/generations ``` --- ## OCR سند ```bash 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 برمیگردانند: ```json { "pages": [{ "index": 0, "markdown": "# Extracted text..." }], "model": "mistral-ocr-latest", "usage_info": { "pages_processed": 1 } } ``` ### جریان نظرسنجی Azure Document Intelligence API مربوط به `analyze` در Azure Document Intelligence ناهمگام است: درخواست اولیه بهجای بدنه، یک هدر `Operation-Location` برمیگرداند و برای دریافت نتیجه باید نظرسنجی انجام شود. کنترلگر (`open-sse/handlers/ocr.ts`) آن URL را هر ثانیه و حداکثر طی ۳۰ تلاش نظرسنجی میکند، در صورت دریافت پاسخ نظرسنجی غیر `ok` یا وضعیت `"failed"` بلافاصله شکست میخورد (به نظرسنجی ادامه نمیدهد) و اگر پس از تمامشدن تعداد تلاشهای مجاز، عملیات همچنان در حال اجرا باشد، `504` برمیگرداند. پاسخ نهایی Azure پیش از بازگرداندهشدن به فراخواننده، به همان ساختار `pages`/`markdown` مورد استفاده Mistral نرمالسازی میشود؛ بنابراین کد کلاینت نیازی ندارد برای این ارائهدهنده حالت خاصی در نظر بگیرد. ### احراز هویت و تفکیک نقطه پایانی Vertex AI DeepSeek OCR `vertex-deepseek-ocr` از همان احراز هویت Vertex AI که OmniRoute از قبل برای ترافیک چت/تصویر پشتیبانی میکند، مجدداً استفاده میکند (`open-sse/executors/vertex.ts`): کلید API اتصال یا یک اعتبارنامه JSON حساب سرویس است (که از طریق جریان JWT-bearer با یک توکن دسترسی OAuth کوتاهعمر مبادله میشود) یا یک توکن دسترسی OAuth از قبل صادرشده که بدون تغییر استفاده میشود. URL نقطه پایانی بالادستی، نقطه پایانی عمومی شریک `openapi/chat/completions` در Vertex است که با استفاده از پروژه و منطقه اتصال ساخته میشود — مقدار صریح `providerSpecificData.project`/`providerSpecificData.region` همیشه اولویت دارد؛ در غیر این صورت، پروژه از `project_id` موجود در JSON حساب سرویس استخراج میشود و مقدار پیشفرض منطقه `us-central1` است. هر دو تفکیک در `open-sse/handlers/ocr.ts` (`resolveVertexOcrAccessToken`، `resolveVertexOcrBaseUrl`) انجام میشوند و `src/app/api/v1/ocr/route.ts` پیش از ارسال به `handleOcr` از آنها استفاده میکند. --- ## فهرست مدلها ```bash GET /v1/models Authorization: Bearer your-api-key → همه مدلهای چت، تعبیهسازی و تصویر + ترکیبها را با فرمت OpenAI برمیگرداند ``` ### قیمت مدلها (`pricing`) هنگامی که OmniRoute قیمت مدل را بداند، ورودی مربوطه دارای یک شیء `pricing` خواهد بود. قیمت از جدول قیمتگذاری مورد استفاده برای محاسبه هزینه میآید: مقادیر پیشفرض داخلی، قیمتهای همگامشده و بازنویسیهای تنظیمشده از طریق `/api/pricing`. اینها قیمتهای فهرست هستند، بنابراین ارائهدهندگان اشتراکی نیز قیمت بهازای هر توکن را نمایش میدهند. ```json "pricing": { "prompt": "0.000005", "completion": "0.000025", "input_cache_read": "0.0000005", "input_cache_write": "0.00000625", "input": 5, "output": 25, "cached": 0.5, "cache_creation": 6.25 } ``` | فیلدها | واحد | توضیحات | | --------------------------------------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `prompt`, `completion`, `input_cache_read`, `input_cache_write` | دلار آمریکا بهازای هر توکن، رشته اعشاری | سازگار با OpenRouter و هرگز با نمادگذاری نمایی نمایش داده نمیشود. دو فیلد کش فقط زمانی ظاهر میشوند که قیمتی برای کش وجود داشته باشد. | | `input`, `output`, `cached`, `cache_creation` | دلار آمریکا بهازای ۱ میلیون توکن، عدد | فیلدهایی از نسخههای قبلی کاتالوگ که برای کلاینتهای موجود حفظ شدهاند. هنگامی که ردیف قیمتگذاری شامل `reasoning` و `long_context` باشد، آنها نیز ظاهر میشوند. | - **ترکیبها** قیمت نخستین مقصد قابلمشاهده خود را دارند. ترکیبهای داخلی `auto/*` در زمان درخواست یک مقصد را انتخاب میکنند، بنابراین `pricing` ندارند. - **مدلهای رایگان** هنگامی که قیمتشان صفر باشد، `"0"` (و `0`) را نمایش میدهند. مدلی که ردیف قیمتگذاری ندارد نیز هنگامی `"0"` را نمایش میدهد که کاتالوگ آن را رایگان علامتگذاری کرده باشد (`free: true`) یا کاتالوگ داخلی مدلهای رایگان آن را فهرست کرده باشد. - **قیمت نامشخص:** ورودی فاقد کلید `pricing` است. - **ارائهدهندگان مبتنی بر اعتبار** (مانند Kiro) بهجای هر توکن، بهازای هر درخواست هزینه دریافت میکنند. ورودیهای آنها فیلدهای عددی بهازای ۱ میلیون توکن قبلی را حفظ میکنند و هیچ فیلد رشتهای بهازای هر توکن ندارند. - **گونهها** (شناسههای میزان تلاش استدلال، نامهای مستعار بدون تفکر، آینههای اکتشاف و درگاه) قیمت مدلی را که درخواستها را به آن هدایت میکنند، کپی میکنند. - این فیلدها فقط نرخهای پایه را در بر میگیرند. سطوح زمینه طولانی (فیلد عددی `long_context`) و ضرایب سطح سرویس (برای مثال Codex سریع یا انعطافپذیر) مقدار `prompt` یا `completion` را تغییر نمیدهند. - این شیء برای همه شیوههای احراز هویت یکسان است، از جمله درخواست به سبک Anthropic با `x-api-key` و `anthropic-version` (پاسخ همچنان `{ "object": "list", "data": [...] }` باقی میماند). پیادهسازی: `src/app/api/v1/models/catalogPricing.ts`. ### پیشوندهای شناسه مدل (`?prefix=`) بیشتر مدلها با یک **پیشوند ارائهدهنده** معرفی میشوند. پیشوند دریافتی شما توسط پرچم قابلیت `MODELS_CATALOG_PREFIX_MODE` کنترل میشود و میتوان آن را **برای هر درخواست** با یک پارامتر پرسوجو بازنویسی کرد — این قابلیت برای کلاینتی مفید است که بدون تغییر تنظیم سراسری سرور برای دیگران، فهرستی پاکیزه میخواهد: ```bash 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](../guides/VSCODE-COPILOT.md) انجام میدهد. ### فیلترهای اکتشاف (`?capability=`, `?min_context=`, `?kind=`, `?q=`) `GET /v1/models` فیلترهای اکتشاف اختیاری را میپذیرد. بدون هیچیک از آنها، پاسخ بدون تغییر باقی میماند. این فیلترها کاتالوگی را که فراخواننده از قبل میبیند محدود میکنند (مجوزهای کلید API ابتدا اعمال میشوند) و پیش از صفحهبندی به سبک OpenAI با `limit` / `after` اجرا میشوند: ```bash GET /v1/models?capability=vision&capability=tool_calling # همه قابلیتهای فهرستشده باید درست باشند GET /v1/models?capability=vision,reasoning&min_context=200000 GET /v1/models?kind=embedding # مقدار `type` کاتالوگ؛ ردیفهای بدون آن `chat` هستند GET /v1/models?q=sonnet&limit=10 # تطبیق بدون حساسیت به بزرگی و کوچکی حروف روی شناسه یا نام ``` | پارامتر | مقادیر | | ------------- | --------------------------------------------------------------------------------------------------- | | `capability` | `attachment`، `reasoning`، `structured_output`، `temperature`، `thinking`، `tool_calling`، `vision` | | `min_context` | عدد صحیح نامنفی، که با `context_length` مقایسه میشود | | `kind` | `chat`، `audio`، `embedding`، `image`، `moderation`، `music`، `rerank`، `video` | | `q` | ۱ تا ۲۰۰ نویسه | یک مقدار ناشناخته، یا یک `min_context` که عدد صحیح نامنفی نباشد (برای مثال `1.5`)، HTTP `400` را برمیگرداند و پیام، مقادیر معتبر را فهرست میکند. پیادهسازی: `src/app/api/v1/models/catalogFilters.ts`. ### فهرست کوتاه مدلها (`POST /v1/models/query`) `POST /v1/models/query` یک فهرست کوتاه و قطعی از همان کاتالوگ، با همان احراز هویت و سطح مشاهدهپذیری مختص هر کلید مانند `GET /v1/models`، برمیگرداند: ```bash POST /v1/models/query Authorization: Bearer your-api-key Content-Type: application/json { "capabilities": ["vision", "tool_calling"], "min_context": 128000, "max_output": 16000, "kind": "chat", "q": "gpt", "owned_by": "openai", "exclude": ["openai/gpt-4o"], "limit": 5 } → { "object": "list", "data": [ ...models ] } ``` همهٔ فیلدها اختیاری هستند. `capabilities` و `exclude` یک آرایه یا رشتهای جداشده با ویرگول میپذیرند؛ `max_output` با `max_output_tokens` مقایسه میشود. نتایج ابتدا بر اساس `owned_by` و سپس `id` مرتب میشوند. مقدار پیشفرض `limit` برابر `20` است و مقادیر بیشتر از `100` به `100` محدود میشوند. JSON نامعتبر، یک فیلد ناشناخته یا یک مقدار نامعتبر، HTTP `400` را برمیگرداند. ### مدلهای گفتوگوی پنهانشده بهصورت مجزا مدلی که در صفحهٔ ارائهدهندهٔ خود با علامت **پنهان** مشخص شده باشد، از کاتالوگ حذف میشود و هنگام درخواست صریح، با HTTP `404` / `model_not_found` رد میشود. این بررسی از ارائهدهنده و مدل حلشده استفاده میکند، از جمله نامهای مستعار ارائهدهنده، پیشوندهای گرهٔ ارائهدهندهٔ سازگار و مقادیر پیشفرض اتصال. یک ترکیب، اهداف پنهان را نادیده میگیرد و میتواند از یک مدل همخانوادهٔ قابلمشاهده استفاده کند؛ وقتی هیچ هدف قابلاجرایی باقی نماند، همان کد خطا را برمیگرداند. لغو حالت پنهان از درخواست بعدی اعمال میشود. بازنویسیهای مشاهدهپذیری مختص تصویر، مدل گفتوگویی با همان شناسه را پنهان نمیکنند. این تنظیم مجزای مدل، از [فهرستهای مجاز/غیرمجاز نمایش مدل](../routing/MODEL_EXPOSURE_LIST.md) جدا است؛ این فهرستها نمایش در کاتالوگ و گزینههای مسیریابی خودکار را فیلتر میکنند، در حالی که ارسال صریح را حفظ میکنند. مجوزهای مدل برای کلید API همچنان بهطور مستقل اعمال میشوند. حالت پیشفرض پیشوند کاتالوگ همچنان `dual` است. ### گونههای مدل بدون تفکر برای مدلهای Claude دارای قابلیت تفکر، `/v1/models` یک گونهٔ **بدون تفکر** را نیز نمایش میدهد که شناسهٔ آن با `claude-3-omniroute-no-thinking/` آغاز میشود: ``` claude-3-omniroute-no-thinking// ``` انتخاب این شناسه (برای مثال، در پیکربندی Claude Code که همیشه یک بلوک `thinking` پیوست میکند) با سرکوب استدلال، دوباره به `/` واقعی نگاشت میشود — `thinking:{type:"disabled"}` در مسیر `/v1/messages`، یا حذف فیلدهای `reasoning`/`reasoning_effort` در مسیر `/v1/chat/completions`. این گونه فقط برای مدلهای خانوادهٔ Claude فهرست میشود که از تفکر پشتیبانی میکنند **و** مقدار `disabled` را میپذیرند (بنابراین، برای مثال، مدلهای صرفاً تطبیقی که `disabled` را رد میکنند، مستثنا میشوند). اپراتورها میتوانند این گونه را برای هر مدل از طریق `ModelSpec.noThinkingAlias` بهاجبار فعال یا غیرفعال کنند. --- ## مانیفست افزونه ارائهدهنده ```bash GET /api/v1/provider-plugin-manifest ``` مانیفست JSON-safe افزونه ارائهدهنده را برمیگرداند که توسط Bifrost، CLIProxyAPI و مسیریابهای sidecar آینده استفاده میشود. پاسخ از رجیستری ارائهدهندگان TypeScript تولید میشود و عمداً اسرار کلاینت OAuth، تفکیک محیط زمان اجرا، توابع اجراکننده، هدرهای درخواست و دادههای حساب را شامل نمیشود. زمانی از این نقطه پایانی استفاده کنید که یک sidecar خارج از پردازش اجرا میشود و نمیتواند `open-sse/config/providerPluginManifestRegistry.ts` را مستقیماً import کند. --- ## تولید صوت ElevenLabs یک اتصال ارائهدهنده `elevenlabs` را در OmniRoute با کلید API مربوط به ElevenLabs پیکربندی کنید. کلاینتها با کلید **OmniRoute** خود احراز هویت میکنند (`Authorization: Bearer $OMNIROUTE_API_KEY`)؛ دروازه، کلید ذخیرهشده ارائهدهنده را بهعنوان `xi-api-key` ارسال میکند. هرگز کلید ElevenLabs را بهعنوان توکن bearer دروازه ارسال نکنید. | روش | مسیر | پاسخ | دستهبندی نقطه پایانی کلید API | | ---- | --------------------------- | --------------------------------- | ----------------------------- | | POST | `/v1/sound-generation` | بایتهای صوتی بومی | `elevenlabs` | | POST | `/v1/music` | بایتهای صوتی بومی | `music` | | POST | `/v1/music/stream` | بایتهای صوتی جریانی | `music` | | POST | `/v1/music/detailed` | صوت multipart بومی و طرح آهنگسازی | `music` | | POST | `/v1/music/detailed/stream` | فراداده SSE بومی و قطعههای صوتی | `music` | | POST | `/v1/music/plan` | طرح آهنگسازی JSON | `music` | این نقاط پایانی، مسیرهای موجود `/v1/audio/speech`، `/v1/audio/transcriptions`، `/v1/voices`، `/v1/text-to-speech/{voiceId}` و `/v1/speech-to-text` را تکمیل میکنند. فیلدهای JSON بومی و پارامترهای کوئری مانند `output_format` و `enable_logging` حفظ میشوند. پاسخهای `/v1/music/detailed` مرزهای multipart خود را حفظ میکنند؛ آنها را بهصورت multipart تجزیه کنید. `/v1/music/detailed/stream` نوع `text/event-stream` را با فراداده آهنگسازی و قطعههای صوتی base64 در رویدادهای SSE برمیگرداند. هر شش مسیر از پیشدرخواست CORS پشتیبانی میکنند. ```bash export OMNIROUTE_BASE_URL="http://localhost:20128" export OMNIROUTE_API_KEY="your-omniroute-api-key" # یک جلوه صوتی کوتاه. مدتزمان: ۰٫۵ تا ۳۰ ثانیه. curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/sound-generation?output_format=mp3_44100_128" \ -H "Authorization: Bearer $OMNIROUTE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text":"A single soft bell chime","duration_seconds":1,"model_id":"eleven_text_to_sound_v2"}' \ --output effect.mp3 # مدتزمان موسیقی بر حسب میلیثانیه بیان میشود: ۳۰۰۰ تا ۶۰۰۰۰۰. curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music?output_format=mp3_44100_128" \ -H "Authorization: Bearer $OMNIROUTE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt":"Gentle instrumental piano","music_length_ms":10000,"force_instrumental":true,"model_id":"music_v1"}' \ --output music.mp3 ``` برای تحویل تدریجی صوت، از `/v1/music/stream` با همان بدنه JSON استفاده کنید. آهنگسازی دقیقاً یکی از `prompt` یا `composition_plan` را میپذیرد؛ `/v1/music/plan` به `prompt` نیاز دارد و بهصورت اختیاری `source_composition_plan` را میپذیرد. طرحوارههای بومی، فیلدهای اضافی ارائهدهنده را حفظ میکنند تا نسخههای طرح آهنگسازی و گزینههای تنظیم دقیق به ElevenLabs برسند. نقطه پایانی یکپارچه `/v1/music/generations` نیز `elevenlabs/music_v1`، `elevenlabs/music_v2` و `elevenlabs/music_v2_5` را میپذیرد. با یک اتصال فعال ElevenLabs، این مدلها از طریق کاتالوگ موسیقی ارائه میشوند. این نقطه پایانی `{"created":...,"data":[{"b64_json":"...","format":"mp3"}]}` را برمیگرداند. فیلد `duration` آن بر حسب ثانیه است و به `music_length_ms` نگاشت میشود؛ مقدار صریح `music_length_ms` اولویت دارد. `instrumental` به `force_instrumental` نگاشت میشود و فیلد بومی اولویت دارد. برای استریم از نقاط پایانی استریم بومی و برای درخواستهایی که صرفاً توسط یک طرح آهنگسازی هدایت میشوند، از نقطه پایانی آهنگسازی بومی استفاده کنید. ```bash curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music/generations" \ -H "Authorization: Bearer $OMNIROUTE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"elevenlabs/music_v1","prompt":"Gentle instrumental piano","duration":10,"instrumental":true}' ``` محدودیتهای نقطه پایانی، مدل، بودجه و اتصال پیش از فراخوانی سرویس بالادستی اعمال میشوند. مسیرهای بومی، کدهای وضعیت و بدنههای خطای سرویس بالادستی را بدون تغییر برمیگردانند، از جمله `402` برای یک محدودیت طرح و `429` برای محدودیت سهمیه. هدرهای `character-cost`، `song-id`، `request-id` و `retry-after` در صورت وجود حفظ میشوند. موجودی اعتبار رایگان، دسترسی به همه مدلهای موسیقی، قالبهای خروجی یا قابلیتهای API را تضمین نمیکند: ElevenLabs استحقاق دسترسی هر درخواست را تعیین میکند. نقطه پایانی یکپارچه، کدهای وضعیت خطا را در پوشش خطای نرمالسازیشده OmniRoute حفظ میکند. قراردادهای سرویس بالادستی: [جلوههای صوتی](https://elevenlabs.io/docs/api-reference/text-to-sound-effects/convert)، [آهنگسازی موسیقی](https://elevenlabs.io/docs/api-reference/music/compose) و [جزئیات موسیقی جریانی](https://elevenlabs.io/docs/api-reference/music/compose-detailed-stream). --- ## نقاط پایانی سازگاری | متد | مسیر | قالب | | ---- | ----------------------------------------- | ------------------------------------------------- | | POST | `/v1/chat/completions` | OpenAI | | POST | `/v1/messages` | Anthropic | | POST | `/v1/responses` | پاسخهای OpenAI | | POST | `/v1/embeddings` | OpenAI | | POST | `/v1/images/generations` | تصاویر OpenAI | | POST | `/v1/images/edits` | تصاویر OpenAI (ویرایش/ترمیم) | | POST | `/v1/videos/generations` | تولید ویدئو به سبک OpenAI | | POST | `/v1/music/generations` | تولید موسیقی به سبک OpenAI | | POST | `/v1/audio/transcriptions` | صوت OpenAI (تبدیل گفتار به متن) | | POST | `/v1/audio/speech` | تبدیل متن به گفتار OpenAI (بدنهٔ صوتی برمیگرداند) | | POST | `/v1/rerank` | بازرتبهبندی به سبک Cohere/Voyage | | POST | `/v1/classify` | دستهبندی Jina (`api.jina.ai`) | | POST | `/v1/segment` | قطعهبند Jina (`segment.jina.ai`) | | POST | `/v1/moderations` | تعدیل محتوای OpenAI | | GET | `/v1/models` | OpenAI | | POST | `/v1/models/query` | فهرست کوتاهِ فیلترشدهٔ مدلها | | POST | `/v1/messages/count_tokens` | Anthropic | | GET | `/v1beta/models` | Gemini | | POST | `/v1beta/models/{...path}` | Gemini generateContent | | POST | `/v1/api/chat` | Ollama | | GET | `/api/v1/vscode/{token}/` | نام مستعار کاتالوگ OpenAI | | GET | `/api/v1/vscode/{token}/models` | نام مستعار مدلهای OpenAI | | POST | `/api/v1/vscode/{token}/chat/completions` | نام مستعار توکندار OpenAI | | POST | `/api/v1/vscode/{token}/responses` | نام مستعار توکندار پاسخهای OpenAI | | POST | `/api/v1/vscode/{token}/api/chat` | نام مستعار توکندار Ollama | | GET | `/api/v1/vscode/{token}/api/tags` | نام مستعار توکندار برچسبهای Ollama | همهٔ مسیرهای POST از ساختار یکسانی پیروی میکنند: `Bearer your-api-key` بههمراه بدنهٔ JSON اعتبارسنجیشده توسط Zod (`v1RerankSchema`، `v1ModerationSchema`، `v1AudioSpeechSchema` و غیره؛ به `src/shared/validation/schemas.ts` مراجعه کنید). در صورت شکست اعتبارسنجی طرحواره، 4xx بازگردانده میشود. برای کلاینتهایی که نمیتوانند `Authorization: Bearer ...` را پیوست کنند، OmniRoute همچنین کلیدهای API را در URL میپذیرد؛ یا از طریق سازگاری با رشتهٔ پرسوجو (`?token=...`، `?apiKey=...`، `?api_key=...`، `?key=...`) یا از طریق نقاط پایانی اختصاصی `/api/v1/vscode/{token}/...` که در ادامه مستند شدهاند. ```bash # بازرتبهبندی (ارائهدهندهٔ رجیستری ابری، یا یک گرهٔ ارائهدهندهٔ سازگار با OpenAI بهشکل "/") POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] } # دستهبندی Jina (اعتبارنامههای Foundation API) POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] } # قطعهبند Jina POST /v1/segment { "content": "...", "return_chunks": true } # جستوجوی Jina (s.jina.ai؛ نامهای مستعار ارائهدهنده: jina-search، jina-ai، jina) POST /v1/search { "query": "...", "provider": "jina-search" } # تعدیل محتوا POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." } # تبدیل متن به گفتار — بدنهٔ audio/mpeg (یا قالب درخواستی) را برمیگرداند POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" } # تبدیل متن به گفتار Soniox به یک زبان و یک صدا نیاز دارد: مقدار پیشفرض `language` برابر با "en" است؛ صدای # مشخصنشده یا نام یکی از صداهای استاندارد OpenAI (alloy، nova، …) به "Adrian" تبدیل میشود POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" } # ویرایش تصویر (چندبخشی) POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png # تولید ویدئو / موسیقی (شناسهٔ مدل با پیشوند ارائهدهنده) POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." } POST /v1/music/generations { "model": "kie/suno-v4.0", "prompt": "..." } ``` > **گرههای ارائهدهندهٔ بازرتبهبندی:** `POST /v1/rerank` همچنین درخواستها را به گرههای ارائهدهندهٔ سازگار با OpenAI > (oMLX، vLLM، Infinity، TEI در پشت یک درگاه، …) که با `/` آدرسدهی میشوند، هدایت میکند. گرههای > لوپبک (`localhost`، `127.0.0.1`، `172.16.0.0/12`) همیشه واجد شرایط هستند؛ همین امر دربارهٔ نامهای میزبانی که > اپراتور در `OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS` فهرست میکند نیز صدق میکند (برای مثال، نام یک سرویس Docker/Compose مانند > `http://reranker:8080/v1`؛ این گرهها مستقیماً فراخوانی میشوند و هرگز از طریق `HTTP(S)_PROXY` یا پراکسی > سنجاقشدهٔ یک اتصال فراخوانی نمیشوند). گرههای مستقر روی هر میزبان دیگری > — مانند یک دستگاه در LAN یا یک همتای Tailscale — تنها زمانی واجد شرایط هستند که اپراتور پرچم قابلیت > `RERANK_REMOTE_PROVIDER_NODES` را فعال کند **و** URL پایهٔ گره با سیاست URL خروجی ارائهدهنده > (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`) مطابقت داشته باشد. > مرحلهٔ بازرتبهبندی موتور حافظه، این مسیر را از طریق > لوپبک فراخوانی میکند؛ بنابراین همین قاعده بر `rerankProviderModel` در تنظیمات حافظه نیز حاکم است. > > **ساختارهای سرور محلی:** گره در `/v1/rerank` و در صورت دریافت 404، در `/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` صریح در ردیفی همگامسازیشده یا افزودهشده بهصورت دستی همچنان اولویت دارد. ### مسیرهای اختصاصی ارائهدهنده ```bash POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` اگر پیشوند ارائهدهنده وجود نداشته باشد، بهطور خودکار افزوده میشود. مدلهای ناسازگار خطای `400` برمیگردانند. --- ## API فایلها نقطه پایانی سازگار با OpenAI برای ورودی/خروجی دستهای و بارگذاری فایل با هدف مشخص. | روش | مسیر | توضیحات | | ------ | ------------------------ | -------------------------------------------------------------------------------------------------------------- | | POST | `/v1/files` | بارگذاری فایل (چندبخشی: `file`، `purpose`، `expires_after[anchor]`، `expires_after[seconds]`) — حداکثر 512 MiB | | GET | `/v1/files` | فهرستکردن فایلهای مربوط به کلید API احراز هویتشده | | GET | `/v1/files/[id]` | دریافت فراداده یک فایل | | DELETE | `/v1/files/[id]` | حذف یک فایل | | GET | `/v1/files/[id]/content` | ارسال جریانی بدنه خام فایل به درخواستکننده | **احراز هویت:** کلید API از نوع Bearer — فایلها از طریق `getApiKeyRequestScope` بهازای هر کلید API محدودهبندی میشوند. هر کلید فقط فایلهای متعلق به خودش را میبیند، دانلود و حذف میکند؛ نشست داشبورد بدون کلید، کل نمونه را میخواند؛ دسترسی به فایلی بدون مالک (بارگذاری ناشناس یا از طریق نشست داشبورد) برای هر فراخواننده فاقد نشست رد میشود. `GET /v1/files` درخواست فراخواننده ناشناس — و کلید ارائهشدهای که قابل شناسایی نیست — را حتی زمانی که `REQUIRE_API_KEY=false` باشد، بهجای فهرستکردن فایلهای همه مستأجرها، با `401` رد میکند (GHSA-m3hp-hq9g-fpmv، GHSA-2jm2-mpx8-6523). --- ## API پردازشهای دستهای پردازش دستهای سازگار با OpenAI. | روش | مسیر | توضیحات | | ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | POST | `/v1/batches` | ایجاد پردازش دستهای — بدنه توسط `v1BatchCreateSchema` اعتبارسنجی میشود (`input_file_id`، `endpoint`، `completion_window`) | | GET | `/v1/batches` | فهرستکردن پردازشهای دستهای | | GET | `/v1/batches/[id]` | دریافت وضعیت پردازش دستهای + `request_counts` | | DELETE | `/v1/batches/[id]` | حذف یک پردازش دستهای تکمیلشده/ناموفق | | POST | `/v1/batches/[id]/cancel` | لغو یک پردازش دستهای در حال اجرا | **احراز هویت:** کلید API از نوع Bearer. پردازشهای دستهای با همان قاعده سهگانه فایلها، بهازای هر کلید API محدودهبندی میشوند: فقط کلید خود مالک، دسترسی سراسری نشست داشبورد به نمونه، و رد دسترسی به رکوردهای بدون مالک برای هر فراخواننده فاقد نشست (دریافت، حذف، لغو و بررسی `input_file_id` هنگام ایجاد). `GET /v1/batches` درخواست فراخواننده ناشناس را حتی زمانی که `REQUIRE_API_KEY=false` باشد، با `401` رد میکند. --- ## API جستوجو انتزاع ارائهدهنده وب/جستوجو (Tavily، Brave، Exa، Serper و غیره). | متد | مسیر | توضیحات | | ---- | ---------------------- | ---------------------------------------------------------------------------------------------------------------- | | GET | `/v1/search` | فهرستکردن ارائهدهندگان جستوجوی پیکربندیشده و قابلیتهای آنها | | POST | `/v1/search` | اجرای یک پرسوجوی جستوجو — بدنه توسط `v1SearchSchema` اعتبارسنجی میشود و از کشکردن/ادغام درخواستها پشتیبانی میکند | | GET | `/v1/search/analytics` | آمار برخورد/تأخیر/کش بهتفکیک ارائهدهنده | **احراز هویت:** کلید API از نوع Bearer (`extractApiKey` + `isValidApiKey`). سیاست جستوجو از طریق `enforceApiKeyPolicy` اعمال میشود. ### گزینههای `provider_options` برای Exa و Tavily Exa و Tavily فیلدهای مختص ارائهدهنده را از یک مجموعه نامگذاریشده میخوانند: `provider_options.exa` (یا `provider_options["exa-search"]`) و `provider_options.tavily` (یا `provider_options["tavily-search"]`). فقط کلیدهای زیر ارسال میشوند. هرکدام در `open-sse/handlers/search/providerOptionsPassthrough.ts` با طرحواره Zod مختص خود بررسی میشوند و کلیدی با نوع نادرست حذف میشود. همه کلیدهای دیگر، از جمله احراز هویت، URL پایه، `stream` و `outputSchema` نادیده گرفته میشوند. کلیدهای مسطحی که سایر ارائهدهندگان استفاده میکنند (`cx`، `depth`، ...) مانند قبل کار میکنند. | ارائهدهنده | فیلدهای سطح بالا | تودرتو | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Exa | `type`، `category`، `userLocation`، `moderation`، `additionalQueries`، `objective`، `systemPrompt`، `compliance` (مقادیر اولیه مسطح)، `startPublishedDate`، `endPublishedDate` | `contents.{text, highlights, summary, extras, subpages, subpageTarget, livecrawlTimeout, maxAgeHours}` با مقدار پیشفرض `{ text: true, highlights: true }` ادغام میشود | | Tavily | `search_depth`، `chunks_per_source`، `time_range`، `start_date`، `end_date`، `include_published_date`، `filter_by_published_date`، `include_answer`، `include_raw_content`، `include_images`، `include_image_descriptions`، `include_favicon`، `include_domains_mode`، `language`، `filter_by_language`، `auto_parameters`، `exact_match`، `include_usage`، `safe_search` | — | فیلدهای عمومی همیشه اولویت دارند: `query`، `max_results`، `filters` (دامنهها)، `country` و موضوع مشتقشده از `search_type`. در Exa، `search_type: "news"` مقدار `category: "news"` را حفظ میکند. Tavily همچنین `search_type: "finance"` (`topic: "finance"`) را میپذیرد. اکنون `time_range` عمومی به هر دو ارائهدهنده میرسد: Exa مقدار `startPublishedDate` (مُهر زمانی ISO) و Tavily مقدار `start_date` (`YYYY-MM-DD`) را دریافت میکند. تاریخ صریح در `provider_options` مقدار نگاشتشده را بازنویسی میکند. نتایج Exa مقادیر `id`، `highlight_scores`، `summary`، `subpages`، `entities` و `extras` را در `provider_raw` نگه میدارند. نتایج Tavily مقادیر `images` و `favicon` را نگه میدارند. محاسبه هزینه همچنان از رجیستری مسطح `costPerQuery` استفاده میکند. Tavily برای `search_depth: "advanced"` بهازای هر فراخوانی اعتبار بیشتری دریافت میکند و این تفاوت در `usage.search_cost_usd` منعکس نمیشود. --- ## API واکشی وب محتوا را از یک URL از طریق ارائهدهنده پیکربندیشده واکشی وب (Firecrawl، Jina Reader، Tavily Extract، TinyFish Fetch، Nimble Extract، Parallel Extract) استخراج میکند. Parallel Extract (`parallel-search`، با همان کلید API مربوط به Parallel Search) فقط Markdown برمیگرداند — هر `format` دیگری منجر به `400` میشود — و محتوا را به 100,000 نویسه محدود میکند. وقتی خود صفحه مقصد قابل استخراج نباشد، سرویس بالادستی آن را درون یک HTTP 200 گزارش میکند؛ OmniRoute این وضعیت را بهصورت یک `422` با پیامی ثابت نمایش میدهد. | متد | مسیر | توضیحات | | ---- | --------------- | -------------------------------------------------------------- | | POST | `/v1/web/fetch` | واکشی/خزش یک URL — بدنه با `v1WebFetchSchema` اعتبارسنجی میشود | **احراز هویت:** کلید API از نوع Bearer (`extractApiKey` + `isValidApiKey`). خطمشی از طریق `enforceApiKeyPolicy` اعمال میشود. **بازگشت جایگزین آگاه از سهمیه (#8297):** وقتی `provider` مشخصی ارائه نشده باشد، مخزن (`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search` → `parallel-search`) با ترتیب اولویت ثابت (ابتدا پُر کردن) پیمایش میشود — ارائهدهندهای که پیکربندی شده اما با محدودیت نرخ مواجه است، بهجای متوقفکردن درخواست نادیده گرفته میشود، و خطای قابلتلاشمجدد/مرتبط با سهمیه از سرویس بالادستی (همیشه HTTP 429؛ کدهای 402/403 برای سهمیههای سبک پلن رایگان Firecrawl/Tavily/TinyFish — نه برای Jina Reader، و هرگز برای یک درخواست نامعتبر 400 معمولی) در زمان درخواست به ارائهدهنده بعدیِ امتحاننشده که دارای اعتبارنامه است منتقل میشود. وقتی همه ارائهدهندگان مخزن به پایان برسند، نقطه پایانی بهجای `400` عمومی قبلی، یک `429` واحد (همراه با هدر `Retry-After`) برمیگرداند. وقتی یک `provider` مشخص درخواست شود، **هیچ** بازگشت جایگزین پنهانیای وجود ندارد — ارائهدهنده مشخصی که با محدودیت نرخ یا خرابی مواجه شده باشد، خطای خودش را نمایش میدهد (`429` در صورت محدودیت نرخ، وگرنه وضعیت سرویس بالادستی). --- ## استریم WebSocket ```bash GET /v1/ws?handshake=1 ``` یک هندشیک ارتقای WebSocket را اعتبارسنجی میکند و پیامهای نمونه پروتکل انتقال (`request`، `cancel`) را برمیگرداند. فریمهای واقعی WS توسط سرور WS همراهشده در خارج از جدول مسیرهای Next.js مدیریت میشوند. **احراز هویت:** کلید API از نوع Bearer هنگام هندشیک. ### API پاسخها روی WebSocket (فقط codex) ```bash # همان میزبان:درگاه API مربوط به HTTP (بهطور پیشفرض 20128)؛ اتصال را ارتقا دهید: wscat -c "ws://localhost:20128/v1/responses?api_key=" # (یا: -H "Authorization: Bearer ") # نخستین فریم باید 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//codex/"` استفاده کنید. پیادهسازی در `app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts` قرار دارد. **احراز هویت:** کلید API از نوع Bearer هنگام هندشیک. سرور HTTP همراهشده (`server-ws.mjs`) باید نقطه ورود فعال باشد (وقتی `app/server-ws.mjs` وجود دارد، بهطور پیشفرض همینطور است). #### شناسه مدل: از شناسه خام ChatGPT استفاده کنید (بدون پیشوند `codex/`) **Codex CLI** مربوط به OpenAI، وقتی `supports_websockets = true` باشد، نام مدل را در سمت کلاینت اعتبارسنجی میکند و **شناسههای دارای پیشوند ارائهدهنده را رد میکند**، مانند `codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account`). شناسه **خام** را ارسال کنید (برای مثال `gpt-5.5`). پل OmniRoute فقط مختص codex است، بنابراین پیش از تونلزنی به سرویس بالادستی، یک شناسه خام را دوباره بهعنوان مدل codex تفکیک میکند (`resolveCodexWsModelInfo`) — حتی با اینکه یک `gpt-5.5` خام در غیر این صورت از طریق HTTP به ارائهدهنده دیگری مسیریابی میشد. #### پیکربندی Codex CLI مربوط به OpenAI با افزودن یک ارائهدهنده سفارشی دارای پشتیبانی WebSocket به `~/.codex/config.toml`، Codex CLI را به OmniRoute متصل کنید (برای جلوگیری از تغییر پیکربندی موجود، از یک `CODEX_HOME` جداگانه استفاده کنید): ```toml model = "gpt-5.5" # شناسه خام — نه "codex/gpt-5.5" model_provider = "omniroute" [model_providers.omniroute] name = "OmniRoute (WS)" base_url = "http://localhost:20128/v1" # بدون اسلش پایانی؛ URL مربوط به WS از آن مشتق میشود (در محیط عملیاتی از https/wss استفاده کنید) wire_api = "responses" # تنها مقدار پشتیبانیشده از فوریه 2026 supports_websockets = true # انتقال Responses-over-WS را فعال میکند env_key = "OMNIROUTE_API_KEY" # کلید API مربوط به OmniRoute را نگه میدارد (Bearer) ``` ```bash 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) برای نمایش هزینهکرد دارنده کلید استفاده میکند. ```bash # قالب متنی (قرارداد قدیمی — متن ساده برای ترمینال) curl -H "Authorization: Bearer " \ http://localhost:20128/api/usage/om-usage # قالب ساختاریافته — چیزی که رابط کاربری مصرف میکند curl -H "Authorization: Bearer " \ "http://localhost:20128/api/usage/om-usage?format=json" ``` کلید باید **`allowUsageCommand`** را فعال کرده باشد (بهطور پیشفرض غیرفعال است — مدیر کلید API در داشبورد آن را برای هر کلید تغییر میدهد). بدون آن، نقطه پایانی با `403` پاسخ میدهد. `?format=json` ساختاری تفکیکشده برمیگرداند تا فراخوان هرگز در صورت رد درخواست، فیلد دادهای را نخواند. در صورت موفقیت: ```jsonc { "allowed": true, // فقط زمانی وجود دارد که کلید، محدودیتهای استفاده مختص هر کلید را فعال کرده باشد (دلار روزانه/هفتگی): "personal": { "dailySpentUsd": 1.25, "dailyLimitUsd": 5, "dailyResetAtIso": "…", "weeklySpentUsd": 8, "weeklyLimitUsd": 20, "weeklyResetAtIso": "…" /* … */, }, // نمای فوری سهمیه ارائهدهنده انتخابشده، یا null وقتی هنوز چیزی در حافظه نهان نیست: "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */} }, // نمای فوری همه اتصالها، تا رابط کاربری بتواند چند ارائهدهنده را کنار هم نمایش دهد: "providers": [ { "connectionId": "…", "provider": "claude" /* … */ }, { "provider": "codex" /* … */ }, ], } ``` در صورت رد درخواست (`401` برای کلید نامعتبر / `403` برای نداشتن مجوز)، همین مسیر `{ "allowed": false, "error": { "message": "…" } }` را برمیگرداند — وجود `personal`/`provider` خالی (کلید مجاز است، اما هنوز اطلاعاتی دریافت نشده) حالتی متفاوت از رد درخواست است و فقط قالب JSON این دو را از یکدیگر متمایز میکند. **احراز هویت:** کلید API از نوع Bearer متعلق به خود فراخوان، که با `isValidApiKey` اعتبارسنجی میشود — این سطح مدیریتی (`/api/keys/…`) _نیست_؛ سطح مدیریتی همچنان پشت `requireManagementAuth` باقی میماند. ### درصدهای سهمیه خام در برابر درصدهای تعدیلشده با حد توقف هنگام استفاده از `/api/usage/om-usage`، فراخوانها باید به تفاوت میان درصدهای ارائهشده در **خروجی متن ساده** و **خروجی JSON** ساختاریافته توجه کنند: | جنبه | قالب متن ساده (`/api/usage/om-usage` / `@@om-usage`) | قالب JSON (`?format=json`) | | :-------------------- | :------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- | | **فیلد خروجی** | `NN% left` (برای مثال، `20% left`) | `provider.quotas` / `providers[].quotas` | | **اندازهگیری** | **ظرفیت قابلاستفاده تعدیلشده با حد توقف**: ظرفیت باقیمانده بالاتر از آستانه حد توقف | **سهمیه خام بالادستی**: اندازهگیری تعدیلنشده ارائهدهنده | | **مقیاسبندی حد توقف** | از طریق `effectiveRemainingPercent()` مقیاسبندی میشود تا ذخیره محافظتشده بهصورت `0% left` نمایش داده شود | ندارد (مقادیر خام نمای فوری، همانگونه که ارائهدهنده گزارش کرده است) | | **داده آستانه** | در درصد نمایشدادهشده لحاظ میشود | در `quotaWindowThresholds` هر اتصال (یا مقادیر پیشفرض سرور) ذخیره میشود | | **مصرفکننده اصلی** | CLIهای تعاملی، اعلانهای ترمینال و اپراتورهای انسانی | یکپارچهسازیهای برنامهنویسی، داشبوردها، تحلیلها و ردیابهای صورتحساب | #### فرمول تعدیل حد توقف OmniRoute از حدهای توقف پیشگیرانه سهمیه برای جلوگیری از اتمام منابع بالادستی پشتیبانی میکند (که از طریق `quotaWindowThresholds` اتصال، مقادیر پیشفرض ارائهدهنده یا تنظیمات تابآوری سراسری پیکربندی میشوند). هنگامی که یک آستانه حد توقف (برای مثال، `cutoff = 25%`) در پنجره سهمیه فعال باشد، رندرکننده متن ظرفیت باقیمانده را به این صورت محاسبه میکند: - اگر `remaining <= cutoff` باشد: `0%` را برمیگرداند. - اگر `remaining > cutoff` باشد: `((remaining - cutoff) / (100 - cutoff)) * 100` را برمیگرداند. خروجی متنی قالببندیشده، این مقدار را به نزدیکترین عدد صحیح گرد میکند (`Math.round(...)`). #### مثال توضیحی پنجره یک ارائهدهنده را با **۶۰٪ استفاده خام** (و در نتیجه **۴۰٪ سهمیه خام باقیمانده**) و آستانه **حد توقف ۲۵٪ از سهمیه باقیمانده** در نظر بگیرید: | نمایش | محاسبه | باقیمانده | استفاده ضمنی | | :---------------------------- | :------------------------------------------------- | :-------: | :----------------------------------------: | | **JSON خام (`?format=json`)** | نمای فوری بالادستی (`quotas[window]`) | **۴۰٪** | **۶۰٪** | | **قالب متنی (`NN% left`)** | `((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100` | **۲۰٪** | **۸۰٪** (در صورت محاسبه `100 - remaining`) | - **چرا متن ۲۰٪ باقیمانده را نشان میدهد:** از ۴۰٪ سهمیه فیزیکی باقیمانده حساب، ۲۵٪ توسط سیاست حد توقف رزرو شده است. فراخوان فقط ۱۵٪ از مجموع ۷۵٪ فضای قابلاستفاده را پیش از آنکه مسیریاب هدایت درخواستها به این اتصال را متوقف کند، در اختیار دارد. مقیاسبندی تضمین میکند که اتصال دقیقاً زمانی پایان ظرفیت (`0% left`) را اعلام کند که مسیریابی متوقف خواهد شد. - **چرا JSON مقادیر خام را حفظ میکند:** بار JSON نمای فوری دقیق ارائهدهنده (`UsageSnapshot`) را برمیگرداند تا ابزارهای خارجی بدون مقیاسبندی اتلافی سمت سرور، به میزان بهرهبرداری واقعی بالادستی و `quotaWindowThresholds` در سطح اتصال دسترسی داشته باشند. #### راهنمای مهاجرت مصرفکنندگان اگر یک یکپارچهسازی خارجی (مانند افزونهٔ ویرایشگر یا افزونهٔ عامل) قبلاً endpoint متنی (`NN% left`) را استخراج میکرد و درصد استفادهشده را بهصورت `100 - NN` محاسبه میکرد، مهاجرت به `?format=json` به این معناست: - خواندن مقادیر خام JSON، **مصرف واقعی بالادستی** را منعکس خواهد کرد (در مثال بالا، 60٪ استفادهشده). - اگر یکپارچهسازی بخواهد معناشناسی میزان مجازِ قابلاستفاده در endpoint متنی را حفظ کند، میتواند فرمول مؤثرِ مقدار باقیمانده را در سمت کلاینت و با استفاده از `quotaWindowThresholds` برای بازنویسیهای سطح اتصال ارزیابی کند. --- ## کش معنایی ```bash # دریافت آمار کش GET /api/cache/stats # پاککردن همه کشها DELETE /api/cache/stats ``` نمونه پاسخ: ```json { "semanticCache": { "memorySize": 42, "memoryMaxSize": 500, "dbSize": 128, "hitRate": 0.65 }, "idempotency": { "activeKeys": 3, "windowMs": 5000 } } ``` ### تأثیر بر تأخیر در صورت اصابت به کش معنایی، پاسخ **بدون فراخوانی بالادستی** از کش ارائه میشود؛ بنابراین مقدار گزارششده برای `X-OmniRoute-Response-Latency` نزدیک به صفر است (صرفنظر از تأخیر اصلی بالادستی). کلاینتهای حساس به تأخیر (بنچمارکگیری، پایش p50/p99) باید هدر پاسخ `X-OmniRoute-Cache-Latency` را بررسی کنند: | مقدار | معنی | | -------------- | --------------------------------------------------------- | | `synthetic` | پاسخ از کش ارائه شده است؛ تأخیر، زمان واقعی بالادستی نیست | | _(وجود ندارد)_ | پاسخ از فراخوانی واقعی بالادستی دریافت شده است | ### دور زدن کش برای هر کلید کلیدهای API میتوانند از طریق `cacheDefaultMode` از خواندن کش معنایی انصراف دهند: | مقدار | رفتار | | -------- | ----------------------------------------------------------------- | | `legacy` | رفتار عادی کش (پیشفرض) | | `bypass` | جستوجو در کش را کاملاً رد میکند؛ همیشه بالادستی را فراخوانی میکند | هنگام ایجاد کلید (`POST /api/keys`) تنظیم کنید یا آن را بهروزرسانی کنید (`PATCH /api/keys/[id]`): ```json { "cacheDefaultMode": "bypass" } ``` ### دور زدن کش برای هر درخواست هر درخواستی، صرفنظر از تنظیمات کلید، میتواند کش را دور بزند: ``` X-OmniRoute-No-Cache: true ``` --- ## داشبورد و مدیریت مسیرهای مدیریتی (`/api/*` بهجز احراز هویت/ورود عمومی) با کلیدهای API عادیِ استنتاج **مجاز نمیشوند**. خانوادههای اعتبارنامه، دامنههای دسترسی و نمونههای curl: [احراز هویت مدیریتی](../guides/MANAGEMENT-AUTH.md). ### احراز هویت | نقطه پایانی | متد | توضیحات | | ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/auth/login` | POST | ورود | | `/api/auth/logout` | POST | خروج | | `/api/settings/require-login` | GET/POST | وضعیت ورود (GET، عمومی). POST گذرواژه را تنظیم میکند / وضعیت الزام ورود را تغییر میدهد: پس از وجود گذرواژه، فقط اپراتور مجاز است (نشست داشبورد، CLI محلی، یا ورود غیرفعال — کلیدهای API و توکنهای `oma_` پاسخ `403` دریافت میکنند)؛ نشست داشبورد برای جایگزینی گذرواژه، `currentPassword` را ارسال میکند | ### مدیریت ارائهدهنده | نقطه پایانی | متد | توضیحات | | --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/providers` | GET/POST | فهرستکردن / ایجاد ارائهدهندگان | | `/api/providers/[id]` | GET/PUT/DELETE | مدیریت یک ارائهدهنده | | `/api/providers/[id]/test` | POST | آزمایش اتصال ارائهدهنده | | `/api/providers/[id]/models` | GET | فهرستکردن مدلهای ارائهدهنده | | `/api/providers/validate` | POST | اعتبارسنجی پیکربندی ارائهدهنده | | `/api/providers/bulk` | POST | افزودن گروهی کلیدهای API برای یک ارائهدهنده | | `/api/providers/import` | POST | واردکردن یک فهرست ناهمگون از ارائهدهندگان از فایل CSV/JSON تجزیهشده (#6836)؛ نتایج شکست جزئی برای هر ردیف | | `/api/provider-nodes*` | مختلف | مدیریت گرههای ارائهدهنده | | `/api/provider-models` | GET/POST/PUT/PATCH/DELETE | مدلهای سفارشی و بازنویسیهای مختص هر مدل (افزودن، بهروزرسانی، پنهان/نمایانکردن، حذف) | | `/api/provider-models/validate-and-add` | POST | اعتبارسنجی سختگیرانه و اختیاری اتصال با احراز هویت مدیریتی و ثبت اتمی مدل سفارشی؛ [اعتبارسنجی مدل](../guides/MODEL-VALIDATION.md) را ببینید | برای مدلهای همگامسازیشده/واردشده، `PUT /api/provider-models` مقادیر `provider`، `modelId` و `maxOutputTokenOverride` را میپذیرد: یک عدد صحیح مثبت، سقف دستی توکن خروجی را تنظیم میکند و `null` آن را پاک میکند تا مقدار پیشفرض بازیابی شود. `GET /api/provider-models?provider=` این مقادیر را در `modelOutputOverrides` برمیگرداند، از جمله برای مدلهایی که ردیف مدل سفارشی ندارند. این بازنویسی از قابلیت زمان اجرای `max_output_tokens` استفاده میکند و پس از همگامسازی مجدد مدل نیز باقی میماند. صفحه ارائهدهنده سازگار با OpenAI همان کنترلهای ویرایش/پاککردن را ارائه میدهد و مدلهایی را که صراحتاً از قابلیت بینایی پشتیبانی میکنند علامتگذاری میکند. گرههای سفارشی Chat Completions، انصرافهای صریح از استدلال را با بکاند بالادستی تطبیق میدهند. یک آزمایش اتصال موفق، کنترلهای قالب چت را بهطور خودکار برای هر شناسه دقیق مدلی انتخاب میکند که ورودی `/models` آن یک مقدار شناختهشده `owned_by` را اثبات کند: `vllm`، `sglang` یا `llamacpp`. پوششهای شفاف سازگار با OpenAI ممکن است ورودی اصلی مدل را درون یک شیء تودرتوی `openai` حفظ کنند؛ فرایند تشخیص حداکثر سه لایه از چنین پوششهایی را دنبال میکند. مدلهایی با مالکیت ناموجود، ناشناخته یا متناقض، رفتار عادی OpenAI را حفظ میکنند. تشخیص از درخواست موجود کاتالوگ دوباره استفاده میکند، هیچ توکن تکمیلی تولید نمیکند و با تغییر نقطه پایانی اتصال نامعتبر میشود. برای تثبیت این رفتار در بکاندی که آن فراداده را ارائه نمیدهد، از API موجود برای بهروزرسانی جزئی ارائهدهنده استفاده کنید: ```json { "providerSpecificData": { "reasoningControl": "chat-template" } } ``` این بدنه را با `PUT /api/providers/` ارسال کنید. در آن اتصال، سطح صریح تلاش استدلالی `none` بهشکل `chat_template_kwargs.thinking=false` و `chat_template_kwargs.enable_thinking=false` ارسال میشود. مقادیر صریح و بومی قالب همچنان ملاک نهایی هستند، مگر اینکه یک قانون استدلال سمت سرور سطحی از تلاش را تحمیل کند. این تنظیم فقط زمانی اعمال میشود که یک اتصال سفارشی سازگار با OpenAI بدنه Chat Completions را ارسال کند؛ درخواستهای Responses و ارائهدهندگان عادی ساختار بومی درخواست خود را حفظ میکنند. برای اجبار به عبور عادی `reasoning_effort` در OpenAI، `reasoningControl` را روی `openai` تنظیم کنید؛ یا برای استفاده از تشخیص خودکار، آن را حذف کنید/روی `null` قرار دهید. درخواستهای طبقهبند حالت خودکار Claude Code، هنگامی که فاقد کنترلهای صریح استدلال باشند، حالت بومی تفکر را بهطور پیشفرض غیرفعال میکنند. تشخیص از نشانگر سیستمی طبقهبند در درخواستهای قالب Claude استفاده میکند، نه از نام مدلها یا محدودیتهای تکمیل. کنترلهای صریح بدنه، سرآیندهای پشتیبانیشده تلاش/تفکر، قوانین مسیریابی و سطح تلاش نهایی مدل، اولویت فعلی خود را حفظ میکنند. هر دو مرحله طبقهبند، پرامپتها، محدودیتهای تکمیل، توالیهای توقف و نتایج واقعی مجوزدهی بالادستی خود را حفظ میکنند؛ مرحله دوم همچنان میتواند استدلال قابلمشاهده درخواستی خود را بهصورت متن عادی تولید کند. ### جریانهای OAuth | نقطه پایانی | متد | توضیحات | | -------------------------------- | ----- | --------------------- | | `/api/oauth/[provider]/[action]` | مختلف | OAuth مختص ارائهدهنده | ### مسیریابی و پیکربندی | نقطه پایانی | متد | توضیحات | | --------------------- | -------- | ---------------------------------- | | `/api/models/alias` | GET/POST | نامهای مستعار مدل | | `/api/models/catalog` | GET | همه مدلها بر اساس ارائهدهنده و نوع | | `/api/combos*` | متنوع | مدیریت ترکیبها | | `/api/keys*` | متنوع | مدیریت کلید API | | `/api/pricing` | GET | قیمتگذاری مدل | ### استفاده و تحلیلها | نقطه پایانی | متد | توضیحات | | -------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/usage/history` | GET | تاریخچه استفاده | | `/api/usage/logs` | GET | گزارشهای استفاده | | `/api/usage/request-logs` | GET | گزارشهای سطح درخواست | | `/api/usage/[connectionId]` | GET | میزان استفاده بهازای هر اتصال | | `/api/usage/token-limits` | GET/POST/DELETE | بودجه محدودیت توکن بهازای هر کلید API | | `/api/usage/model-latency-stats` | GET | تجمیع چرخشی تأخیر بهازای هر ارائهدهنده/مدل (میانگین/p50/p95/p99، نرخ موفقیت)؛ فیلترها: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) | | `/api/usage/cache-health` | GET | خلاصه سلامت کش پرامپت بر روی `call_logs` — نسبت نوشتن/خواندن، توزیع اندازه نوشتن در p50/p90/p99، تمرکز نوشتنهای سنگین، تفکیک بر اساس مدل و نتیجه ارزیابی `healthy`/`degraded`/`thrash`/`no-data`؛ پارامترهای کوئری `range` (`1h`\|`24h`\|`7d`\|`30d`، پیشفرض `24h`) و `model` اختیاری (#8827) | ### مجوزهای کلید API `PATCH /api/keys/{id}` مجوزهای یک کلید موجود را بهروزرسانی میکند. مانند همه مسیرهای `/api/keys*`، این مسیر به مجوز مدیریتی نیاز دارد (به [احراز هویت مدیریتی](../guides/MANAGEMENT-AUTH.md) مراجعه کنید)، نه کلید استنتاج. فقط فیلدهایی را ارسال کنید که میخواهید تغییر دهید؛ درخواستی که هیچیک از آنها را نداشته باشد با `No valid fields to update` رد میشود. فیلدهای پذیرفتهشده توسط `updateKeyPermissionsSchema` در `src/shared/validation/schemas/keys.ts` تعریف شدهاند. | فیلد | نوع | توضیحات | | ------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | رشته، ۱ تا ۲۰۰ نویسه | | | `isActive` | بولی | | | `isBanned` | بولی | | | `expiresAt` | تاریخوزمان ISO 8601 یا `null` | `null` تاریخ انقضا را پاک میکند | | `modelAccessMode` | `all` \| `restricted` | وقتی حالت `all` است، `allowedModels` باید خالی باشد | | `allowedModels`, `blockedModels` | آرایهای از رشتهها، حداکثر ۱۰۰۰ مورد | | | `allowedCombos` | آرایهای از رشتهها، حداکثر ۵۰۰ مورد | تعیین میکند کلید مجاز به فراخوانی کدام کمبوها است؛ مدلهای مستقیم توسط `modelAccessMode` / `allowedModels` کنترل میشوند | | `connectionAccessMode` | `all` \| `restricted` | در حالت `restricted`، مقدار `allowedConnections` نباید خالی باشد و در حالت `all` باید خالی باشد | | `allowedConnections` | آرایهای از UUIDها، حداکثر ۱۰۰ مورد | | | `allowAutoCombos` | بولی | مقدار `false` درخواستهای مدلهای `auto/*` با این کلید را رد میکند؛ کلیدهایی که هرگز آن را تنظیم نکردهاند مجاز هستند | | `catalogScope` | `all` \| `combos` \| `models` | مشخص میکند `GET /v1/models` چه مواردی را برای این کلید فهرست کند (فقط کمبوها، فقط مدلها یا هر دو)؛ این گزینه موارد قابل فراخوانی توسط کلید را تغییر نمیدهد | | `forcedModel` | رشتهای با حداکثر ۳۰۰ نویسه، یا `null` | درخواستهای چت را با اولویت بالاتر از `X-Route-Model` و `body.model` به این مدل/کمبو هدایت میکند؛ محدودیتهای کلید همچنان اعمال میشوند | | `noLog`, `autoResolve` | بولی | | | `throttleDelayMs` | عدد صحیح، ۰ تا ۳۰۰۰۰۰ | | | `maxSessions` | عدد صحیح، ۰ تا ۱۰۰۰۰ | | | `rateLimits` | آرایهای از `{ limit, window }` (اعداد صحیح مثبت، حداکثر ۵۰ مورد) یا `null` | `null` محدودیتها را پاک میکند | | `accessSchedule` | شیء زمانبندی یا `null` | `null` زمانبندی را پاک میکند | | `scopes` | آرایهای از رشتهها، حداکثر ۳۲ مورد | | | `allowedEndpoints` | آرایهای از رشتهها، حداکثر ۲۰ مورد | | | `streamDefaultMode` | `legacy` \| `json` | | | `cacheDefaultMode` | `legacy` \| `bypass` | به [دور زدن کش برای هر کلید](#per-key-cache-bypass) مراجعه کنید | | `compressionEnabled` | بولی | | | `codexServiceMode` | یکی از حالتهای سرویس Codex | | | `disableNonPublicModels` | boolean | | | `allowUsageCommand` | boolean | | | `usageLimitEnabled` | boolean | | | `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | number >= 0 یا `null` | | | `chaosModeEnabled` | boolean | | ```bash curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -d '{ "allowAutoCombos": false, "catalogScope": "combos" }' ``` ### تنظیمات | نقطه پایانی | متد | توضیحات | | ------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/settings` | GET/PUT/PATCH | تنظیمات عمومی. کلیدهای سیاست امنیتی (`requireLogin`، `newPassword`، `oidc*`، `corsOrigins`، `bruteForceProtection`) به `currentPassword` و اعتبارنامه اپراتور نیاز دارند — کلیدهای API و توکنهای `oma_` پاسخ `403` دریافت میکنند؛ هر تغییر به حوزه توکن دسترسی `admin` نیاز دارد | | `/api/settings/proxy` | GET/PUT | پیکربندی پروکسی شبکه | | `/api/settings/proxy/test` | POST | آزمایش اتصال پروکسی | | `/api/settings/ip-filter` | GET/PUT | فهرست مجاز/مسدودسازی IP | | `/api/settings/thinking-budget` | GET/PUT | حالت بازنویسی **درخواست** تفکر/استدلال (عبور بدون تغییر / حذف خودکار / سفارشی / تطبیقی). مستقل از فشردهسازی است. [THINKING_BUDGET.md](../guides/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](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status) مراجعه کنید. | | `/api/cache/stats` | GET/DELETE | آمار کش / پاکسازی | | `/api/modality-bridge/stats` | GET | مقادیر درونحافظهای `attempts`، موفقیتها/`bridged`، شکستها، اصابتهای کش، `totalLatencyMs`، `latencySamples`، `averageLatencyMs` با مخرج تعداد نمونهها، و زمان آخرین استفاده (با راهاندازی مجدد بازنشانی میشود؛ نیازمند احراز هویت مدیریتی) | | `/api/modality-bridge/video/runtime` | GET | بررسی سختگیرانه حلقه بازگشتی مورداعتماد پیش از احراز هویت/کاوش مدیریتی؛ وضعیت دسترسپذیری و نسخههای پاکسازیشده FFmpeg/ffprobe (بدون ذخیرهسازی) | | `/api/modality-bridge/video/extract` | POST | کارگزار داخلی و احرازشده بایت روی حلقه بازگشتی مورداعتماد؛ ورودی 50 MiB، صف محدود/خروجی 32 MiB، ظرفیت `503`، قطع اتصال `499`، مهلت زمانی `504`؛ یک API عمومی بارگذاری نیست | ### پشتیبانگیری و برونبری/درونریزی | نقطه پایانی | متد | توضیحات | | --------------------------- | ------ | ------------------------------------------------------------------------------------- | | `/api/db-backups` | GET | فهرستکردن پشتیبانهای موجود | | `/api/db-backups` | PUT | ایجاد پشتیبان دستی | | `/api/db-backups` | POST | بازیابی از یک پشتیبان مشخص | | `/api/db-backups` | PATCH | ذخیره تنظیمات نگهداری پشتیبان (فقط اپراتور) | | `/api/db-backups` | DELETE | حذف پشتیبانهای ذخیرهشده مطابق تنظیمات نگهداری (فقط اپراتور) | | `/api/db-backups/export` | GET | دانلود پایگاه داده بهصورت فایل .sqlite | | `/api/db-backups/import` | POST | بارگذاری فایل .sqlite برای جایگزینی پایگاه داده (`?dryRun=true` فقط اعتبارسنجی میکند) | | `/api/db-backups/exportAll` | GET | دانلود پشتیبان کامل بهصورت بایگانی .tar.gz | `/api/db-backups/export`، `/api/db-backups/exportAll` و `/api/settings/export-json` تمام اطلاعات احراز هویت ذخیرهشده را ارائه میکنند؛ بنابراین به نشست داشبورد یا CLI محلی نیاز دارند (یا ورود باید غیرفعال باشد). کلیدهای API با هر دامنهای و توکنهای دسترسی `oma_` پاسخ `403` دریافت میکنند. عملیات بازیابی نیز همین محدودیت را دارد: `POST /api/db-backups/import` (شامل `dryRun=true`)، `POST /api/db-backups` (بازیابی بر اساس شناسه) و `POST /api/settings/import-json` پایگاه داده یا تنظیمات فعال را جایگزین میکنند؛ بنابراین اعتبارنامه یک ماشین نیز در آنجا پاسخ `403` دریافت میکند؛ `omniroute sync import` اعتبارنامه CLI محلی را ارسال میکند. همین موضوع درباره `DELETE /api/db-backups` (حذف پشتیبانهای ذخیرهشده) و `PATCH /api/db-backups` (تنظیمات نگهداری: مقادیر ذخیرهشده، حذف خودکار پس از هر پشتیبانگیری را کنترل میکنند) نیز صدق میکند. فهرستکردن (`GET`) و ایجاد پشتیبان دستی (`PUT`) همچنان از احراز هویت معمول مدیریتی استفاده میکنند. ### همگامسازی ابری | نقطه پایانی | متد | توضیحات | | ---------------------- | ------- | ------------------------ | | `/api/sync/cloud` | Various | عملیات همگامسازی ابری | | `/api/sync/initialize` | POST | مقداردهی اولیه همگامسازی | | `/api/cloud/*` | Various | مدیریت فضای ابری | ### تونلها | نقطه پایانی | متد | توضیحات | | -------------------------- | ---- | --------------------------------------------------------------------- | | `/api/tunnels/cloudflared` | GET | خواندن وضعیت نصب/اجرای Cloudflare Quick Tunnel برای داشبورد | | `/api/tunnels/cloudflared` | POST | فعال یا غیرفعالکردن Cloudflare Quick Tunnel (`action=enable/disable`) | | `/api/tunnels/ngrok` | GET | خواندن وضعیت اجرای ngrok Tunnel برای داشبورد | | `/api/tunnels/ngrok` | POST | فعال یا غیرفعالکردن ngrok Tunnel (`action=enable/disable`) | ### ابزارهای CLI | نقطه پایانی | متد | توضیحات | | ---------------------------------- | --- | -------------------- | | `/api/cli-tools/claude-settings` | GET | وضعیت Claude CLI | | `/api/cli-tools/codex-settings` | GET | وضعیت Codex CLI | | `/api/cli-tools/droid-settings` | GET | وضعیت Droid CLI | | `/api/cli-tools/openclaw-settings` | GET | وضعیت OpenClaw CLI | | `/api/cli-tools/runtime/[toolId]` | GET | محیط اجرای عمومی CLI | پاسخهای CLI شامل این موارد هستند: `installed`، `runnable`، `command`، `commandPath`، `runtimeMode`، `reason`. ### عاملهای ACP | نقطه پایانی | متد | توضیحات | | ----------------- | ------ | ----------------------------------------------------------------- | | `/api/acp/agents` | GET | فهرستکردن تمام عاملهای شناساییشده (داخلی + سفارشی) همراه با وضعیت | | `/api/acp/agents` | POST | افزودن عامل سفارشی یا تازهسازی حافظه نهان شناسایی | | `/api/acp/agents` | DELETE | حذف عامل سفارشی با پارامتر پرسوجوی `id` | پاسخ GET شامل `agents[]`‏ (id، name، binary، version، installed، protocol، isCustom) و `summary`‏ (total، installed، notFound، builtIn، custom) است. ### تابآوری و محدودیت نرخ | Endpoint | Method | Description | | --------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/resilience` | GET/PATCH | دریافت/بهروزرسانی صف درخواست، دوره انتظار اتصال، قطعکننده ارائهدهنده و تنظیمات انتظار | | `/api/resilience/reset` | POST | بازنشانی قطعکنندههای مدار ارائهدهنده | | `/api/resilience/model-cooldowns` | GET | فهرستکردن قفلهای فعال برای هر ترکیب (ارائهدهنده، اتصال، مدل)، مرتبشده بر اساس زمان باقیمانده | | `/api/resilience/model-cooldowns` | DELETE | پاککردن قفل مدل — بدنه `{provider, model}` یا `{all: true}` برای پاککردن همه موارد | | `/api/rate-limits` | GET/POST | وضعیت محدودیت نرخ برای هر حساب (GET) یا فعال/غیرفعالکردن محافظت در برابر محدودیت نرخ برای یک اتصال (POST با `{connectionId, enabled}`). مسیر نوشتن پشتیبانیشده برای `rateLimitProtection` (هرگز از طریق `PUT /api/providers/[id]` تغییر داده نمیشود). توجه: `enabled: false` محافظت صریح را غیرفعال میکند، اما اتصال فعال مبتنی بر کلید API را از سازوکار ایمنی فعالسازی خودکار سراسری (`autoEnableApiKeyProviders`) خارج نمیکند. | | `/api/rate-limit` | GET | پیکربندی سراسری محدودیت نرخ (منسوخشده؛ نام مستعار `/api/rate-limits`) | > هر چهار مسیر `/api/resilience/*` به **احراز هویت مدیریتی** (`requireManagementAuth`) نیاز دارند. برای شرح کامل تفاوت میان قطعکننده ارائهدهنده، دوره انتظار اتصال و قفل مدل، به [تابآوری (توسعهیافته)](#resilience-extended) مراجعه کنید. ### ارزیابیها | Endpoint | Method | Description | | ------------ | -------- | --------------------------------------- | | `/api/evals` | GET/POST | فهرست مجموعههای ارزیابی / اجرای ارزیابی | ### سیاستها | Endpoint | Method | Description | | --------------- | --------------- | ------------------------ | | `/api/policies` | GET/POST/DELETE | مدیریت سیاستهای مسیریابی | ### انطباق | Endpoint | Method | Description | | --------------------------- | ------ | --------------------------------- | | `/api/compliance/audit-log` | GET | گزارش ممیزی انطباق (آخرین N مورد) | ### v1beta (سازگار با Gemini) | Endpoint | Method | Description | | -------------------------- | ------ | --------------------------------------- | | `/v1beta/models` | GET | فهرست مدلها در قالب Gemini | | `/v1beta/models/{...path}` | POST | نقطه پایانی `generateContent` در Gemini | این نقاط پایانی، قالب API مربوط به Gemini را برای کلاینتهایی که به سازگاری بومی با SDK مربوط به Gemini نیاز دارند، بازتاب میدهند. ### APIهای داخلی / سیستمی | Endpoint | Method | Description | | ------------------------ | ------ | ---------------------------------------------------------- | | `/api/init` | GET | بررسی مقداردهی اولیه برنامه (در نخستین اجرا استفاده میشود) | | `/api/tags` | GET | برچسبهای مدل سازگار با Ollama (برای کلاینتهای Ollama) | | `/api/restart` | POST | راهاندازی مجدد کنترلشده سرور | | `/api/shutdown` | POST | خاموشکردن کنترلشده سرور | | `/api/system/env/repair` | POST | ترمیم متغیرهای محیطی ارائهدهنده OAuth | | `/api/system/version` | GET | نسخه فعلی/جدیدترین، وضعیت بهروزرسانی و کانال انتشار | | `/api/system/version` | POST | آغاز بهروزرسانی آگاه از استقرار به جدیدترین نسخه | > **توجه:** این نقاط پایانی بهصورت داخلی توسط سیستم یا برای سازگاری با کلاینت Ollama استفاده میشوند. معمولاً کاربران نهایی آنها را فراخوانی نمیکنند. ### ترمیم محیط OAuth _(v3.6.1+)_ ```bash POST /api/system/env/repair Content-Type: application/json { "provider": "claude-code" } ``` متغیرهای محیطی OAuth مفقود یا خراب را برای یک ارائهدهنده مشخص ترمیم میکند. خروجی: ```json { "success": true, "repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"], "backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak" } ``` ### نسخه و کانال انتشار ```bash GET /api/system/version ``` مسیر مدیریتی مختص loopback (با احراز هویت مدیر). نسخه در حال اجرا، جدیدترین نسخه منتشرشده و وضعیت بهروزرسانی خودکار را برمیگرداند. `releaseChannel` و `channels` فیلدهای افزودهشده هستند (ریل 3.8.54)؛ `channel` معنای خود را حفظ میکند — حالت استقراری که بهروزرسان داشبورد استفاده میکند (`npm`، `source` یا `docker-compose`). ```json { "current": "3.8.52", "latest": "3.8.52", "updateAvailable": false, "channel": "npm", "autoUpdateSupported": true, "autoUpdateError": null, "news": null, "releaseChannel": "latest", "channels": { "latest": "3.8.52", "next": "3.8.53-rc.1" } } ``` - `releaseChannel` — کانال npm مربوط به بیلد در حال اجرا: `nightly` برای نسخههای `-nightly.*`، `next` برای سایر پیشانتشارها (`-rc.*`، `-beta.*`، `-alpha.*`)، `lts` برای نسخه پایدارِ یک نسخه اصلی قدیمیتر از `channels.latest` و در غیر این صورت `latest`. این قواعد با `scripts/release/dist-tag.mjs` یکساناند که هنگام انتشار، dist-tag مربوط به npm را انتخاب میکند. - `channels` — جدیدترین نسخه منتشرشده برای هر dist-tag، از `npm view omniroute dist-tags` (با HTTP fallback رجیستری)، که با همان TTL دهدقیقهای `latest` کش میشود. `latest` همیشه وجود دارد (ابتدا به فیلد `latest` و سپس به `"unavailable"` برمیگردد)؛ `next`، `nightly` و `lts` تنها زمانی ظاهر میشوند که آن dist-tag وجود داشته باشد. درخواست `Cache-Control: no-cache` هر دو جستوجو را تازهسازی میکند. مدل کانال (`latest` = v3 تا انتشار عمومی 4.0، `next` = rc، `nightly` = بیلدهای `develop`، `lts` = وصلههای v3 پس از انتشار عمومی 4.0) در `docs/ops/RELEASE_STRATEGY.md` توضیح داده شده است. --- ## رونویسی صوت ```bash POST /v1/audio/transcriptions Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` فایلهای صوتی را با استفاده از هر ارائهدهنده STT پیکربندیشده رونویسی کنید. نخستین بخش مسیر، ارائهدهنده بومی را انتخاب میکند (`openai/…`، `deepgram/…`). درگاههایی که مدل یک فروشنده دیگر را مجدداً ارائه میکنند، از یک شناسه واجد شرایط استفاده میکنند (`openrouter/deepgram/nova-3`). **درخواست:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ -H "Authorization: Bearer your-api-key" \ -F "file=@recording.mp3" \ -F "model=openai/whisper-1" ``` **پاسخ:** ```json { "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 استفاده میکنند: ```bash # نقطه پایانی چت (قالب Ollama) POST /v1/api/chat # فهرست مدلها (قالب Ollama) GET /api/tags ``` درخواستها بهطور خودکار میان قالب Ollama و قالبهای داخلی ترجمه میشوند. ## نامهای مستعار توکندار VS Code / بدون هدر زمانی از این نامهای مستعار استفاده کنید که یک یکپارچهسازی نمیتواند هدر `Authorization` را درج کند و لازم است کلید API در URL پایه تعبیه شود. ```bash # نام مستعار کاتالوگ به سبک 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 ``` مثال: ```bash 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 ظاهر شوند. آنها را بهعنوان یک گزینه سازگاری در نظر بگیرید، نه روش احراز هویت پیشفرض. --- ## تلهمتری ```bash # دریافت خلاصه تلهمتری تأخیر (p50/p95/p99 برای هر ارائهدهنده) GET /api/telemetry/summary ``` **پاسخ:** ```json { "providers": { "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } } } ``` --- ## بودجه ```bash # دریافت وضعیت بودجه برای همه کلیدهای 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` در سراسر کلید اعمال شوند؛ هنگامی که چند محدودیت با یک درخواست مطابقت داشته باشند، محدودکنندهترین مورد اعمال میشود. ```bash # فهرستکردن محدودیتهای توکن یک کلید (شامل میزان استفاده زنده در پنجره) GET /api/usage/token-limits?apiKeyId=key-123 # ایجاد یا بهروزرسانی یک محدودیت توکن POST /api/usage/token-limits Content-Type: application/json { "apiKeyId": "key-123", "scopeType": "model", "scopeValue": "openai/gpt-4o", "tokenLimit": 1000000, "resetInterval": "monthly", "enabled": true } # حذف یک محدودیت توکن بر اساس شناسه DELETE /api/usage/token-limits?id=tl-abc ``` > **نکات طرحواره** (`setTokenLimitSchema`): `apiKeyId` و `scopeType` (`model` | `provider` | `global`) الزامی هستند. `scopeValue` الزامی است، مگر اینکه `scopeType` برابر با `global` باشد (برای مثال، شناسه مدل برای محدوده `model` یا شناسه ارائهدهنده برای محدوده `provider`). `tokenLimit` باید یک عدد صحیح مثبت باشد (از رشته تبدیل میشود). اختیاری: `id` (برای ایجاد آن را حذف کنید و برای بهروزرسانی ارائه دهید)، `resetInterval` (`daily` | `weekly` | `monthly`، مقدار پیشفرض `monthly`)، `resetTime` (`HH:MM`)، `enabled` (مقدار پیشفرض `true`). پاسخهای `GET` هر محدودیت را با `tokensUsed`، `remaining`، `windowStart`، `periodStartAt` و `nextResetAt` غنی میکنند. این یک نقطه پایانی از نوع مدیریتی است (احراز هویت بهصورت مرکزی توسط خط لوله مجوزدهی اعمال میشود). ## پردازش درخواست 1. کلاینت درخواست را به `/v1/*` ارسال میکند 2. کنترلکننده مسیر `handleChat`، `handleEmbedding`، `handleAudioTranscription` یا `handleImageGeneration` را فراخوانی میکند 3. مدل تعیین میشود (ارائهدهنده/مدل مستقیم یا نام مستعار/ترکیب) 4. اعتبارنامهها از پایگاه داده محلی و با فیلترکردن دسترسپذیری حساب انتخاب میشوند 5. برای چت: `handleChatCore` کش معنایی/امضا را بررسی و تنظیمات فشردهسازی ترکیب را تعیین میکند 6. در صورت فعالبودن، فشردهسازی پیشدستانه پیش از ترجمه ارائهدهنده اجرا میشود (`lite`، Caveman، RTK یا حالت انباشته) 7. اجراکننده ارائهدهنده، درخواست بالادستی را ارسال میکند 8. پاسخ به قالب کلاینت برگردانده میشود (برای چت) یا همانگونه بازگردانده میشود (برای تعبیهها/تصاویر/صوت) 9. میزان استفاده، تحلیلهای فشردهسازی و گزارشهای درخواست ثبت میشوند 10. در صورت بروز خطا، بازگشت جایگزین بر اساس قواعد ترکیب اعمال میشود مرجع کامل معماری: [`ARCHITECTURE.md`](../architecture/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` | فهرست وبهوکها (مقادیر محرمانه بهشکل `...` پوشانده میشوند) | | POST | `/api/webhooks` | ایجاد وبهوک — بدنه: `{url, events?: ["*"], secret?, description?}` | | GET | `/api/webhooks/[id]` | بازیابی یک وبهوک | | PUT | `/api/webhooks/[id]` | بهروزرسانی url/events/secret/description | | DELETE | `/api/webhooks/[id]` | حذف یک وبهوک | | POST | `/api/webhooks/[id]/test` | ارسال یک payload آزمایشی به URL وبهوک و بازگرداندن وضعیت تحویل | **احراز هویت:** نشست مدیریت/کلید API (`requireManagementAuth`). --- ## کلیدهای ثبتشده (مدیریت خودکار) زیرسامانه مدیریت خودکار کلید از این موارد برای صدور و چرخش کلیدهای API در یک ارائهدهنده/حساب پشتیبان، با سهمیههای روزانه/ساعتی استفاده میکند. | متد | مسیر | توضیحات | | ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/registered-keys` | فهرست کلیدهای ثبتشده (فقط پیشوند پوشاندهشده) | | POST | `/api/v1/registered-keys` | صدور یک کلید ثبتشده جدید — بدنه: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. کلید خام را فقط **یکبار** بازمیگرداند. در صورت رد بهدلیل سهمیه، `429` بازمیگرداند. | | GET | `/api/v1/registered-keys/[id]` | بازیابی فراداده یک کلید ثبتشده (بدون داده خام) | | DELETE | `/api/v1/registered-keys/[id]` | لغو یک کلید ثبتشده | | POST | `/api/v1/registered-keys/[id]/revoke` | نقطه پایانی صریح برای لغو (با اثری یکسان با DELETE) | **احراز هویت:** نشست مدیریت/کلید API (`requireManagementAuth`) — همان محافظ `/api/keys`: یک نشست داشبورد، توکن محلی CLI، یا یک کلید API با دامنه `manage`/`admin`؛ کلیدهای API مختص استنتاج، `403` دریافت میکنند. همچنین `/v1/quotas/check` و `/v1/issues/report` را ببینید. --- ## پروتکل عاملها وظایف عامل ابری (Claude Code، Codex Cloud، OpenHands و غیره) که از راه دور و از طرف کاربران OmniRoute اجرا میشوند. | متد | مسیر | توضیحات | | ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/agents/tasks` | فهرست وظایف — پارامترهای اختیاری `?provider=`، `?status=`، `?limit=` (از 1 تا 500، پیشفرض 50) | | POST | `/api/v1/agents/tasks` | ایجاد وظیفه — بدنه توسط `CreateCloudAgentTaskSchema` اعتبارسنجی میشود (`providerId`، `prompt`، `source`، `options?`). پاکت وظیفه را با وضعیت `201` برمیگرداند | | DELETE | `/api/v1/agents/tasks?id=...` | حذف یک وظیفه | | GET | `/api/v1/agents/tasks/[id]` | خواندن وظیفه — هنگامی که `external_id` تنظیم شده باشد، وضعیت را بهصورت همگام از عامل ابری بالادستی بهروزرسانی میکند | | POST | `/api/v1/agents/tasks/[id]` | اقدام تفکیکشده: `{action: "approve"}`، `{action: "message", message}` یا `{action: "cancel"}` | | DELETE | `/api/v1/agents/tasks/[id]` | حذف یک وظیفه مشخص بر اساس شناسه | > **احراز هویت:** احراز هویت مدیریتی برای همه متدها الزامی است (`requireCloudAgentManagementAuth`). پیش از v3.8.0 این مسیرها بدون احراز هویت بودند — برای مشاهده تغییر ناسازگار، به کامیت `588a0333` مراجعه کنید. ```bash # ایجاد یک وظیفه ابری 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=` را ارسال کنید | | 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` پشتیبانی میکند؛ همین فیلدها در داشبورد ← تنظیمات ← تابآوری نیز ارائه شدهاند. ```bash # پاکسازی قفل یک مدل 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`](../../CLAUDE.md) ← «وضعیت زمان اجرای تابآوری» و [`docs/architecture/RESILIENCE_GUIDE.md`](../architecture/RESILIENCE_GUIDE.md) مراجعه کنید. ### صف محدودیت نرخ و شبکه ایمنی فعالسازی خودکار - **مسیر نوشتن پشتیبانیشده**: `POST /api/rate-limits` با بدنه `{"connectionId": "", "enabled": true|false}` نقطه پایانی مدیریتی پشتیبانیشده برای فعال یا غیرفعالکردن محافظت در برابر محدودیت نرخ برای یک اتصال است. `PUT /api/providers/[id]` عمداً `rateLimitProtection` را تغییر نمیدهد یا وارونه نمیکند (#11278). - **معنای `enabled: false`**: تنظیم `enabled: false` محافظت صریح اتصال را حذف میکند، اما یک اتصال فعال مبتنی بر کلید API را از شبکه ایمنی سراسری فعالسازی خودکار (`autoEnableApiKeyProviders = true`) خارج **نمیکند**. در `reconcileEnabledConnections` (`open-sse/services/rateLimitManager.ts`)، مقادیر `false` و `undefined` معادلاند؛ اتصالهای فعال مبتنی بر کلید API که محافظت صریح ندارند، همچنان تحت شبکه ایمنی فعالسازی خودکار محافظت میشوند. - **غیرفعالسازی سراسری**: برای اجرای اتصالهای مبتنی بر کلید API بدون صفهای محدودیت نرخ، شبکه ایمنی را بهصورت سراسری از طریق `RATE_LIMIT_AUTO_ENABLE=false` (متغیر محیطی) یا `resilienceSettings.requestQueue.autoEnableApiKeyProviders = false` (تنظیمات ← تابآوری / `PATCH /api/resilience`) غیرفعال کنید. --- ## مهارتها چارچوب مهارت برای گسترش OmniRoute با کنترلکنندههای اجرایی سفارشی، بههمراه یکپارچهسازیهای بازارچه. | متد | مسیر | توضیحات | | ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/skills` | فهرست مهارتهای نصبشده — قابل فیلتر با `?q=`، `?mode=on\|off\|auto`، `?source=skillsmp\|skillssh\|local` و دارای صفحهبندی | | GET | `/api/skills/[id]` | دریافت یک مهارت | | PUT | `/api/skills/[id]` | بهروزرسانی مهارت (نام، توضیحات، حالت، طرحواره، کنترلکننده، برچسبها) | | DELETE | `/api/skills/[id]` | حذف نصب یک مهارت | | POST | `/api/skills/install` | نصب مهارت از مانیفست خام — بدنه: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` | | GET | `/api/skills/executions` | فهرست اجرای اخیر مهارتها (ردپای ممیزی شامل ورودیها/خروجیها/مدتزمان) | | GET | `/api/skills/marketplace?q=...` | جستوجو/فهرست محبوب از بازارچه SkillsMP (نیازمند تنظیم `skillsmpApiKey`) | | POST | `/api/skills/marketplace/install` | نصب یک مهارت با شناسه از SkillsMP | | GET | `/api/skills/skillssh?q=&limit=` | جستوجوی رجیستری skills.sh | | POST | `/api/skills/skillssh/install` | نصب یک مهارت با شناسه از skills.sh | **احراز هویت:** نشست مدیریتی/کلید API. مسیرهای جستوجوی بازارچه، احراز هویت مدیریتی یا کلید API از نوع Bearer (`isAuthenticated`) را میپذیرند. --- ## حافظه مخزن پایدار حافظهٔ مکالمهای/واقعی که بهازای هر کلید API / نشست تفکیک میشود. | متد | مسیر | توضیحات | | ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------- | | GET | `/api/memory` | فهرست حافظهها — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`، با صفحهبندی `offset/limit` یا `page/limit` | | POST | `/api/memory` | ایجاد حافظه — بدنه توسط Zod اعتبارسنجی میشود: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` | | GET | `/api/memory/[id]` | بازیابی یک حافظه | | DELETE | `/api/memory/[id]` | حذف یک حافظه | | GET | `/api/memory/health` | سلامت زیرسامانهٔ حافظه (اتصال پایگاه داده، بکاند تعبیهها، وضعیت ایندکس برداری) | **احراز هویت:** نشست مدیریتی/کلید API (`requireManagementAuth`). مقادیر enum برای `type`:‏ `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (به `MemoryType` در `src/lib/memory/types.ts` مراجعه کنید). --- ## سرور MCP OmniRoute همراه با یک سرور داخلی Model Context Protocol با ۳ انتقال (stdio، SSE، streamable-http) و ابزارهای دارای محدوده ارائه میشود. نقاط پایانی داشبورد در زیر، دادههای وضعیت/ممیزی را میخوانند و انتقالهای HTTP را پروکسی میکنند. | متد | مسیر | توضیحات | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- | | GET | `/api/mcp/status` | ضربان حیات، انتقال، وضعیت آنلاین، آخرین فراخوانی، ابزارهای برتر، نرخ موفقیت ۲۴ ساعته | | GET | `/api/mcp/tools` | فهرست ابزارهای MCP بههمراه `name`، `description`، `scopes`، `phase`، `auditLevel`، `sourceEndpoints` | | GET | `/api/mcp/sse` | باز کردن جریان SSE برای انتقال SSE (اگر MCP غیرفعال باشد یا انتقال مطابقت نداشته باشد، `503` برمیگرداند) | | POST | `/api/mcp/sse` | ارسال فریم JSON-RPC روی انتقال SSE | | GET | `/api/mcp/stream` | باز کردن سمت SSE انتقال Streamable HTTP (پیامهای آغازشده از سوی سرور) | | POST | `/api/mcp/stream` | ارسال فریم JSON-RPC روی انتقال Streamable HTTP | | DELETE | `/api/mcp/stream` | پایان دادن به یک نشست Streamable HTTP | | GET | `/api/mcp/audit` | جستوجوی گزارش ممیزی — `?limit=`، `?offset=`، `?tool=`، `?success=true | false`، `?apiKeyId=` | | GET | `/api/mcp/audit/stats` | آمار تجمیعی ممیزی (مجموعها، نرخ موفقیت، میانگین مدتزمان، ابزارهای برتر) | **احراز هویت:** انتقالهای `sse`/`stream` از سطح احراز هویت ویژهٔ MCP پیروی میکنند (کلید API از نوع Bearer با محدودهٔ `mcp`)؛ مسیرهای `status`/`tools`/`audit*` از داشبورد قابل خواندن هستند (فراتر از امکان دسترسی به میزبان داشبورد، احراز هویت اضافی لازم نیست). > هر دو انتقال HTTP توسط `settings.mcpEnabled` و `settings.mcpTransport` کنترل میشوند — عدم تطابق انتقال، `400` و غیرفعال بودن MCP، `503` برمیگرداند. --- ## سرور A2A OmniRoute یک نقطه پایانی A2A (عاملبهعامل) مبتنی بر JSON-RPC 2.0، بههمراه یک پوشش REST برای بازرسی و استفاده در داشبورد ارائه میکند. ### JSON-RPC ```bash 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`. ### کارت عامل ```bash GET /.well-known/agent.json ``` کارت عمومی عامل A2A (نام، توضیحات، قابلیتها، کاتالوگ مهارتها و طرح احراز هویت) را برمیگرداند — این کارت بهمدت 1h بهصورت عمومی کش میشود. نیازی به احراز هویت نیست. ### ابزارهای کمکی REST | متد | مسیر | توضیحات | | ---- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- | | GET | `/api/a2a/status` | وضعیت فعال بودن A2A + آمار وظایف + خلاصه کارت عامل کششده | | GET | `/api/a2a/tasks` | فهرست وظایف — `?state=submitted\|working\|completed\|failed\|cancelled`، `?skill=`، `?limit=` (≤200)، `?offset=` | | POST | `/api/a2a/tasks` | (بهعنوان ابزار کمکی REST پیادهسازی نشده است — از طریق JSON-RPC و `message/send` ایجاد کنید) | | GET | `/api/a2a/tasks/[id]` | بازیابی یک وظیفه | | POST | `/api/a2a/tasks/[id]/cancel` | لغو یک وظیفه | **احراز هویت:** ابزارهای کمکی REST بدون احراز هویت مدیریتی اجرا میشوند (قابل خواندن توسط داشبورد)؛ مسیر JSON-RPC یعنی `/a2a`، در صورت پیکربندی، از Bearer `OMNIROUTE_API_KEY` استفاده میکند. --- ## Cloud، Evals و Assess | متد | مسیر | توضیحات | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | POST | `/api/cloud/auth` | اعتبارسنجی یک کلید Bearer و بازگرداندن اتصالهای ماسکشده ارائهدهندگان + نامهای مستعار مدل برای کلاینتهای همگامسازی ابری | | POST | `/api/cloud/credentials/update` | بهروزرسانی اعتبارنامههای رمزگذاریشده برای یک ارائهدهنده همگامشده با فضای ابری | | POST | `/api/cloud/model/resolve` | نگاشت شناسه منطقی مدل به یک ارائهدهنده/مدل مشخص با استفاده از جدول مسیریابی محلی | | GET | `/api/cloud/models/alias` | فهرست نامهای مستعار مدل، همانگونه که برای همگامسازی ابری ارائه میشوند | | GET | `/api/assess` | خواندن جدیدترین دستهبندیهای ارزیابی (برای هر ارائهدهنده/مدل) | | POST | `/api/assess` | اجرای یک ارزیابی — بدنه: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` | | GET | `/api/evals` | فهرست مجموعههای ارزیابی داخلی + جدیدترین اجراها | | POST | `/api/evals` | آغاز یک اجرای ارزیابی | | POST | `/api/evals/suites` | ایجاد یک مجموعه ارزیابی سفارشی — بدنه توسط `evalSuiteSaveSchema` اعتبارسنجی میشود | | GET | `/api/evals/suites/[id]` | بازیابی یک مجموعه ارزیابی سفارشی | **احراز هویت:** `/api/cloud/auth` مستقیماً یک کلید Bearer را اعتبارسنجی میکند و فقط برای کلیدی با دامنه `manage` / `admin`، کلید ماسکشده و `projectId` هر اتصال را برمیگرداند؛ سایر مسیرهای `/api/cloud/*`، `/api/evals/*` و `/api/assess` به نشست مدیریتی/کلید API نیاز دارند. درخواست POST به `/api/assess` از `validateBody` همراه با یک شِمای دامنه از نوع اجتماع متمایزشده استفاده میکند. --- ## مدیریت ACP (Agent Client Protocol) بهعنوان فرایندهای فرزند. این نقاط پایانی، شناسایی عاملهای ACP و ثبت عاملهای سفارشی را مدیریت میکنند. | متد | مسیر | توضیحات | | ------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/acp/agents` | فهرستکردن تمام عاملهای CLI شناختهشده (داخلی + سفارشی) همراه با وضعیت نصب، نسخه و فایل اجرایی | | POST | `/api/acp/agents` | ثبت یک عامل ACP سفارشی یا تازهسازی حافظهٔ نهان — بدنه: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` یا `{action: "refresh"}` | | DELETE | `/api/acp/agents` | حذف یک عامل ACP سفارشی — پارامتر کوئری: `?id=` | **نمونه پاسخ** (`GET /api/acp/agents`): ```json { "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](../frameworks/ACP.md) مراجعه کنید. --- ## تحلیل و مشاهدهپذیری نقاط پایانی تحلیل بلادرنگ برای نظارت بر مسیریابی، فشردهسازی و تنوع ارائهدهندگان. این نقاط پایانی، صفحات `/dashboard/analytics/*` را پشتیبانی میکنند. ### تحلیل مسیریابی خودکار | متد | مسیر | توضیحات | | --- | ------------------------------------ | ------------------------------------------------------------------------------------------------ | | GET | `/api/analytics/auto-routing` | آمار تجمیعی مسیریابی خودکار: مجموع فراخوانیها، توزیع راهبردها، توزیع سطحها و برترین ارائهدهندگان | | GET | `/api/analytics/auto-routing?days=7` | آمار محدودشده به بازهٔ زمانی (پیشفرض ۲۴ ساعت) | **نمونه پاسخ**: ```json { "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` | آمار تجمیعی فشردهسازی: توکنهای ذخیرهشده، درصد صرفهجویی، توزیع حالتها و میزان استفاده از موتور | **نمونه پاسخ**: ```json { "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` | ردیابی تنوع مبتنی بر آنتروپی شانون: با اندازهگیری پراکندگی ارائهدهندگان، از نقاط شکست منفرد جلوگیری میکند | **نمونه پاسخ**: ```json { "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}` | **احراز هویت:** به نشست مدیریتی با محدوده دسترسی مدیر نیاز دارد. --- ## مدیریت ابزارهای CLI ابزارهای CLI را که با OmniRoute یکپارچه میشوند (antigravity، commandCode، devin-cli و غیره) مدیریت کنید. برای مشاهده فهرست کامل، به [مرجع ارائهدهندگان](./PROVIDER_REFERENCE.md) مراجعه کنید. | متد | مسیر | توضیحات | | ---- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/cli-tools/all-statuses` | وضعیت همه ابزارهای CLI (نصبشده، نسخه، آخرین مشاهده) | | GET | `/api/cli-tools/status` | جزئیات وضعیت یک ابزار CLI (`?tool=` query) | | POST | `/api/cli-tools/apply` | نوشتن پیکربندی تولیدشده ابزار (`dryRun` پیشنمایش ارائه میدهد؛ هنگام اجرا در کانتینر، `422` + `containerEphemeralTarget`؛ `migration` وجود YAML قدیمی Codex را اعلام میکند) | | GET | `/api/cli-tools/backups` | فهرستکردن نسخههای پشتیبان پیکربندی ابزارهای CLI | | POST | `/api/cli-tools/backups` | ایجاد نسخه پشتیبان از پیکربندی همه ابزارهای CLI | | POST | `/api/cli-tools/backups` | بازیابی: همین نقطه پایانی با `{tool, backupId}` در بدنه، آن نسخه پشتیبان را بازیابی میکند | | GET | `/api/cli-tools/antigravity-mitm` | وضعیت پروکسی MITM مربوط به Antigravity (ابزار CLI با نام "antigravity-mitm") | | POST | `/api/cli-tools/antigravity-mitm/alias` | پیکربندی نامهای مستعار antigravity-mitm | **احراز هویت:** به نشست مدیریتی نیاز دارد. --- ## مهارتهای عامل مهارتهای عامل هوش مصنوعی را مدیریت کنید (مشابه GPTهای سفارشی OpenAI، اما برای عاملها). | متد | مسیر | توضیحات | | ------ | ---------------------------- | -------------------------------------------------------------------------------------- | | GET | `/api/agent-skills` | فهرستکردن همه مهارتهای عامل (داخلی + سفارشی) | | GET | `/api/agent-skills/[id]` | دریافت یک مهارت عامل مشخص | | POST | `/api/agent-skills` | ایجاد یک مهارت عامل سفارشی — بدنه: `{name, description, prompt, model?, temperature?}` | | PUT | `/api/agent-skills/[id]` | بهروزرسانی یک مهارت عامل سفارشی | | DELETE | `/api/agent-skills/[id]` | حذف یک مهارت عامل سفارشی | | GET | `/api/agent-skills/[id]/raw` | دریافت پرامپت خام + فراداده (بدون اجرا) | | POST | `/api/agent-skills/generate` | تولید یک مهارت جدید با هوش مصنوعی از روی توضیحی به زبان طبیعی | **احراز هویت:** به نشست مدیریتی یا کلید API با محدوده دسترسی مدیریتی نیاز دارد. --- ## مدیریت کش کش معنایی و کش استدلال را مدیریت کنید. | متد | مسیر | توضیحات | | ------ | ---------------------- | -------------------------------------------------------------------------------------------------------- | | GET | `/api/cache` | نمای کلی کش: تعداد کل ورودیها، نرخ برخورد، اندازه روی دیسک | | GET | `/api/cache/entries` | فهرست ورودیهای ذخیرهشده در کش (همراه با صفحهبندی) | | DELETE | `/api/cache/entries` | حذف ورودیهای کش (فیلتر بر اساس پارامترهای کوئری) | | GET | `/api/cache/stats` | آمار تفصیلی کش (به تفکیک ارائهدهنده و مدل) | | GET | `/api/cache/reasoning` | وضعیت کش استدلال (برای بازپخش استدلال) | | DELETE | `/api/cache/reasoning` | پاکسازی کش استدلال — پارامترهای کوئری: `?toolCallId=` (تکی) یا `?provider=

` یا بدون پارامتر (همه) | **احراز هویت:** به نشست مدیریتی نیاز دارد. --- ## سیستم حافظه حافظه پایدار (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` | ارسال یک رویداد آزمایشی به یک وبهوک | **احراز هویت:** به نشست مدیریتی نیاز دارد. برای مشاهده همه انواع رویدادها، به [چارچوب وبهوکها](../frameworks/WEBHOOKS.md) مراجعه کنید. --- ## چارچوب مهارتها مهارتها (چارچوب افزونههای عاملمحور) را مدیریت کنید. | متد | مسیر | توضیحات | | ------ | ------------------------ | ------------------------------------------------------------------------------------------ | | 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 با دامنه مدیریتی نیاز دارد. برای جزئیات کامل، به [چارچوب مهارتها](../frameworks/SKILLS.md) مراجعه کنید. --- ## افزونهها افزونههای 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` | بهروزرسانی پیکربندی افزونه | **احراز هویت:** به نشست مدیریتی نیاز دارد. برای جزئیات کامل، به [چارچوب افزونهها](../frameworks/PLUGIN_SDK.md) مراجعه کنید. --- ## مسیریابی سایه مقایسه سایه / A-B ارائهدهندگان **یک سطح REST مستقل نیست** — این قابلیت از طریق مسیریابی ترکیبی پیکربندی میشود (به [ترکیب خودکار](../routing/AUTO-COMBO.md) مراجعه کنید). معیارهای مقایسه هر ترکیب از طریق `GET /api/combos/metrics` ارائه میشوند. --- ## حفاظها حفاظهای زمان اجرا (تشخیص PII، تشخیص تزریق پرامپت، پلزنی بینایی) را بررسی کنید. حفاظها در هر درخواست اجرا میشوند؛ انصراف برای هر فراخوانی از طریق هدر درخواست `x-omniroute-disabled-guardrails` انجام میشود — هیچ سطح ماندگاری برای فعال/غیرفعالسازی وجود ندارد. | متد | مسیر | توضیحات | | ---- | ---------------------- | ----------------------------------------------------------------------------------------------- | | GET | `/api/guardrails` | فهرستکردن حفاظهای ثبتشده و وضعیت آنها (نام / فعال / اولویت) | | POST | `/api/guardrails/test` | اجرای آزمایشی خط لوله پیش از فراخوانی روی یک ورودی نمونه — بدنه: `{input, disabledGuardrails?}` | **احراز هویت:** به نشست مدیریتی نیاز دارد. برای جزئیات کامل، به [امنیت > حفاظها](../security/GUARDRAILS.md) مراجعه کنید. --- --- ## احراز هویت برای آشنایی با چهار خانوادهٔ اعتبارنامه (نشست داشبورد، توکن CLI محلی، توکن دسترسی `oma_live_…` و کلید API با دامنهٔ مدیریتی) و تفاوت آنها با کلیدهای استنتاج، به [احراز هویت مدیریتی](../guides/MANAGEMENT-AUTH.md) مراجعه کنید. - مسیرهای داشبورد (`/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`) مراجعه کنید.