# 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) · 🇮🇷 [fa](../../../fa/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) · 🇺🇿 [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) --- 🌐 **زبانیں:** 🇺🇸 [انگریزی](./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) OmniRoute API کا بنیادی حوالہ۔ اس میں عوامی `/v1` سطح اور سب سے زیادہ استعمال ہونے والے انتظامی endpoints شامل ہیں؛ مشین کے لیے قابلِ مطالعہ [`docs/openapi.yaml`](../openapi.yaml) اور `src/app/api/` کے تحت موجود route tree جامع ماخذ ہیں۔ OpenAI سے مطابقت رکھنے والے مخصوص protocol اور provider capability matrix کے لیے، [`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) - [کلاؤڈ، Evals اور Assess](#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` پر سیٹ کریں (no-cache کی عکاسی کرتا ہے؛ ہر کال کے ٹوکن/لاگت کے اضافی بوجھ سے بچاتا ہے) | | `X-OmniRoute-Progress` | درخواست | پیش رفت کے ایونٹس کے لیے `true` پر سیٹ کریں | | `X-Session-Id` | درخواست | بیرونی سیشن وابستگی کے لیے مستقل سیشن کلید | | `x_session_id` | درخواست | انڈر اسکور والی قسم بھی قبول کی جاتی ہے (براہِ راست HTTP) | | `X-OmniRoute-Session-Id` | درخواست | کالر کی فراہم کردہ سیشن/گفتگو ٹیگ (جو میموری کو بھی فراہم کی جاتی ہے)۔ موجود ہونے پر، فی سیشن لاگت کی نسبت کے لیے `call_logs.session_tag` میں من و عن محفوظ کی جاتی ہے (#8249) — غیر موجود ہونے پر کبھی خود نہیں بنائی جاتی | | `Idempotency-Key` | درخواست | نقل ختم کرنے کی کلید (5s کی مدت) | | `X-Request-Id` | درخواست | نقل ختم کرنے کی متبادل کلید | | `X-OmniRoute-Cache` | جواب | `HIT` یا `MISS` (غیر اسٹریمنگ) | | `X-OmniRoute-Idempotent` | جواب | اگر نقل ختم کی گئی ہو تو `true` | | `X-OmniRoute-Progress` | جواب | اگر پیش رفت کی ٹریکنگ فعال ہو تو `enabled` | | `X-OmniRoute-Session-Id` | جواب | OmniRoute کے زیرِ استعمال مؤثر سیشن ID | | `X-OmniRoute-Request-Id` | جواب | درخواست کا باہمی ربط ID (جب معلوم ہو) | | `X-OmniRoute-Version` | جواب | OmniRoute بلڈ ورژن (ہمیشہ موجود) | | `X-OmniRoute-Cost-Saved` | جواب | کیش نے HIT پر جتنی USD لاگت بچائی (صرف کیش ہٹس) | | `X-OmniRoute-Decision` | جواب | روٹنگ ٹریس: `strategy=; provider=; latency_ms=` (`` کومبو حکمتِ عملی ہے، یا غیر کومبو درخواست کے لیے `single`) — تکمیل کے جوابات میں ہمیشہ موجود ہوتا ہے | > Nginx نوٹ: اگر آپ انڈر اسکور ہیڈرز (مثلاً `x_session_id`) پر انحصار کرتے ہیں تو `underscores_in_headers on;` فعال کریں۔ > **لاگت کی ٹیلی میٹری ہیڈرز:** نان اسٹریمنگ کامیاب جوابات میں `X-OmniRoute-*` لاگت کی ٹیلی میٹری کا مجموعہ بھی شامل ہوتا ہے — `X-OmniRoute-Response-Cost` (USD، مقررہ 10 اعشاریہ مقامات؛ مفت/بلا قیمت کے لیے `0.0000000000`)، `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`، `X-OmniRoute-Model`، `X-OmniRoute-Provider`، `X-OmniRoute-Latency-Ms`، `X-OmniRoute-Cache-Hit`، اور `X-OmniRoute-Fallback-Attempts` (صرف اس وقت جب > 0 ہو)، نیز `X-OmniRoute-Request-Id` اور `X-OmniRoute-Version`۔ یہ چیٹ کمپلیشنز، `/v1/responses`، `/v1/messages`، **اور میڈیا اینڈ پوائنٹس** — `/v1/embeddings`، `/v1/images/generations`، `/v1/audio/speech`، `/v1/audio/transcriptions`، `/v1/rerank`، `/v1/videos/generations`، `/v1/music/generations`، اور `/v1/moderations` (لاگت ہمیشہ `0`) — کے ذریعے بھیجے جاتے ہیں۔ قیمت دستیاب ہونے پر میڈیا کی لاگت کا حساب ہر موڈیلٹی کے لحاظ سے (فی تصویر، فی سیکنڈ، فی کریکٹر، فی سرچ یونٹ) کیا جاتا ہے، بصورت دیگر `0` (فیل اوپن)۔ > **کیش ہِٹ کی لاگت کی معنویات:** سیمنٹک کیش HIT (`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` خرابی واپس کرتی ہیں۔ ایک کلائنٹ جس نے صلاحیت-انتظار کا جواب حاصل کیا ہے اس کے پاس معائنہ کرنے کے لیے کوئی فعال بائنڈنگ نہیں ہے۔ جب روٹنگ ایک فعال لیز کو منتقل کرتی ہے، تو وہی جنریشن درست رہتی ہے اور اسٹیٹس جوہری طور پر نئی بائنڈنگ واپس کرتا ہے، کبھی بھی پرانی نہیں۔ موجودہ کلائنٹس غیر تبدیل شدہ رہتے ہیں کیونکہ حصول، تجدید، ریلیز، اور انتظار کے جوابات اپنی پچھلی شکلیں برقرار رکھتے ہیں۔ یہ سرور معاہدہ اسٹاک OpenAI Codex `/status` کو تبدیل نہیں کرتا۔ اسٹاک 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`۔ اس انجن کے لیے فی درخواست آپٹ-ان۔ | | `` | ایک نامزد کومبو، پہلے نام سے (کیس-غیر حساس) پھر ID سے مماثل۔ | نوٹس: - نامعلوم اقدار کو نظر انداز کر دیا جاتا ہے (درخواست کبھی مسترد نہیں کی جاتی)؛ ریزولوشن عام آپریٹر کی ترجیح پر آ جاتا ہے۔ - اگر متعدد کومبوز ایک نام کا اشتراک کرتے ہیں، تو ایک متعین میچ کے لیے کومبو **id** پاس کریں۔ - ایک کومبو جس کا نام `off` یا `default` ہے اسے نام سے منتخب نہیں کیا جا سکتا (ان کلیدی الفاظ کی پہلے تشریح کی جاتی ہے)؛ ایسے کومبو کو اس کی ID سے حوالہ دیں۔ - ماسٹر کمپریشن سوئچ ایک سخت گیٹ ہے: جب کمپریشن عالمی سطح پر غیر فعال ہو، تو یہ ہیڈر اسے فعال نہیں کر سکتا۔ لاگو شدہ پلان کو رسپانس ہیڈر میں واپس گونجایا جاتا ہے: ``` 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۔ کیٹلاگ IDs کی شکل `provider/model` ہے (مثال: `jina-ai/jina-embeddings-v5-omni-small`)۔ رجسٹری میں موجود مختصر Jina ماڈل IDs (مثلاً `jina-embeddings-v5-text-small`، `jina-reranker-v3.5`) بھی ریزولو ہو جاتے ہیں۔ Jina embed/rerank/classify/segment پہلے ڈیش بورڈ کی `jina-ai` اسناد استعمال کرتے ہیں؛ `JINA_AI_API_KEY` صرف اس صورت میں متبادل ہے جب ڈیش بورڈ کلید موجود نہ ہو۔ `jina-reader` کارڈ صرف Reader / `r.jina.ai` کے لیے ہے (`POST /v1/web/fetch`) اور کبھی بھی embeddings یا rerank فراہم نہیں کرتا۔ رجسٹری کے وہ ماڈلز جو ملٹی موڈل معاونت ظاہر کرتے ہیں، فراہم کنندہ سے غیر جانب دار، ساخت یافتہ زیادہ سے زیادہ 32 آئٹمز بھی قبول کرتے ہیں۔ میڈیا آئٹم کی اقسام `text`، `image`، `audio`، `video`، اور `document` ہیں۔ ان کا میڈیا `source` یا تو `{"type":"url","url":"https://..."}` ہوتا ہے یا `{"type":"base64","data":"...","media_type":"..."}`۔ Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`، `jina-ai/jina-embeddings-v5-omni-nano`، اور فیملی عرف `jina-ai/jina-embeddings-v5-omni` → omni-small) Jina کی مقامی EmbeddingsV5Request دستاویزات بھی قبول کرتا ہے اور انہیں **بغیر کسی تبدیلی کے فارورڈ کرتا ہے** `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 }` اقدار ایک عوامی HTTPS URL، ایک `data:` URI، یا خام base64 ہو سکتی ہیں۔ OmniRoute ان آبجیکٹس کو اسٹرنگ میں تبدیل نہیں کرتا اور نہ ہی مقامی image URLs کو حاصل کرتا ہے — Jina عوامی میڈیا خود حاصل کرتا ہے۔ اضافی Jina فیلڈز (`task`، `normalized`، `truncate`، `embedding_type`) فارورڈ کیے جاتے ہیں۔ صرف متن والے Jina SKUs اب بھی غیر متنی دستاویزات کو مسترد کرتے ہیں۔ سکیورٹی اور ٹرانسپورٹ کی حدود: - ریموٹ میڈیا URLs لازماً عوامی HTTPS ہونے چاہییں۔ معیاری `{type,source:url}` آئٹمز سرور کی جانب سے حاصل کیے جاتے ہیں (ری ڈائریکٹ کی دوبارہ توثیق، ٹائم آؤٹ، سائز کی حدود، عوامی DNS، کنکشن پننگ) اور فراہم کنندہ کی کال سے پہلے اِن لائن کر دیے جاتے ہیں۔ Jina کے مقامی `{image:"https://..."}` آئٹمز اسی عوامی HTTPS جانچ کے بعد جوں کے توں فارورڈ کیے جاتے ہیں؛ Jina URL حاصل کرتا ہے۔ - اِن لائن base64 میڈیا کی حد فی آئٹم ڈی کوڈ شدہ 8 MiB اور پوری درخواست میں مجموعی طور پر ڈی کوڈ شدہ 16 MiB ہے۔ فراہم کنندہ کے لیے ترجمہ (معیاری آئٹمز کبھی بھی بغیر تبدیلی کے فارورڈ نہیں کیے جاتے): - Jina ملٹی موڈل ماڈلز: ہر اعلیٰ سطحی آئٹم ایک موڈیلٹی کلید والا آبجیکٹ بن جاتا ہے (`text` / `image` / `audio` / `video` / `pdf`)، جس میں اِن لائن میڈیا کے لیے data URIs استعمال ہوتے ہیں؛ فی اعلیٰ سطحی آئٹم ایک ویکٹر۔ - Gemini Embedding 2 فیملی: ایک اعلیٰ سطحی array، `content.parts` (`text` یا `inline_data`) کے ساتھ، ایک واحد مقامی `models/{model}:embedContent` درخواست بن جاتا ہے۔ - 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": "پہاڑوں کے اوپر ایک خوبصورت غروبِ آفتاب", "size": "1024x1024" } ``` دستیاب فراہم کنندگان میں OpenAI (GPT Image 2)، xAI (Grok Image)، Together AI (FLUX)، Fireworks AI، Nebius (FLUX)، Hyperbolic، NanoBanana، **OpenRouter**، **ZenMux**، SD WebUI (مقامی)، ComfyUI (مقامی) شامل ہیں۔ `n`، `data[]` میں `n` تصاویر واپس کرتا ہے۔ جن فراہم کنندگان کا اپ اسٹریم API ہر کال پر ایک تصویر واپس کرتا ہے (Black Forest Labs، Stability AI، Leonardo، Ideogram، Haiper، Hyperbolic، Magnific/Freepik، NVIDIA NIM، Cloudflare Workers AI)، ان کے لیے `n` علیحدہ اپ اسٹریم کالز کی جاتی ہیں، جن میں بیک وقت زیادہ سے زیادہ 4 زیرِ عمل ہوتی ہیں۔ ایک مقررہ `seed` کو کال انڈیکس کے مطابق بڑھایا جاتا ہے (`seed`، `seed + 1`، …)، لہٰذا تصاویر مختلف ہوتی ہیں مگر دوبارہ قابلِ تخلیق رہتی ہیں۔ `n` کی زیادہ سے زیادہ حد 10 ہے۔ اگر کوئی بھی کال ناکام ہو جائے تو پوری درخواست ناکام ہو جاتی ہے۔ فین آؤٹ فارمیٹس کی فہرست `SINGLE_IMAGE_FANOUT_FORMATS` میں `open-sse/handlers/imageGeneration/fanOut.ts` پر موجود ہے۔ ZenMux موجودہ API کلید کنکشن کو دوبارہ استعمال کرتا ہے اور `zenmux/` یا `zm/` سابقے قبول کرتا ہے: - `zenmux/openai/gpt-image-2`، ZenMux کا OpenAI Images API استعمال کرتا ہے۔ اختیارات میں `size`، `quality`، `n`، `output_format`، `output_compression`، `background`، اور `response_format` شامل ہیں۔ - دیگر ناشرین، جیسے `zm/meta/muse-image-1.0`، ZenMux کا Vertex AI `:predict` اینڈ پوائنٹ استعمال کرتے ہیں۔ `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"` ایک اپ اسٹریم HTTPS URL واپس کرتا ہے، یا جب صرف تصویری بائٹس دستیاب ہوں تو base64 ڈیٹا URL واپس کرتا ہے۔ خالی/فلٹر شدہ آؤٹ پٹس خالی کامیاب جواب کے بجائے خرابی واپس کرتے ہیں۔ ماڈل تک رسائی ZenMux اکاؤنٹ پر منحصر ہے۔ [ZenMux کا Vertex API](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` ایک `provider/model` سابقے کے ذریعے OCR فراہم کنندہ منتخب کرتا ہے؛ صرف ماڈل id (مثلاً `mistral-ocr-latest`) اپنے رجسٹرڈ فراہم کنندہ سے منسلک ہو جاتی ہے، اور اگر `model` فراہم نہ کیا جائے تو پہلے سے طے شدہ Mistral (`mistral-ocr-latest`) استعمال ہوتا ہے۔ رجسٹرڈ فراہم کنندگان (`open-sse/config/ocrRegistry.ts`): | فراہم کنندہ id | ماڈل id | `model` کی قدر | نوٹس | | ----------------------------- | -------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (یا صرف `mistral-ocr-latest`) | ہم وقت — واحد upstream کال سے جواب براہِ راست واپس کیا جاتا ہے۔ | | `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | غیر ہم وقت upstream (`analyze` + پولنگ) — ذیل میں دیکھیں۔ | | `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | ہم وقت، Vertex AI کے `openapi/chat/completions` پارٹنر endpoint کے ذریعے — توثیق/URL کے لیے ذیل میں دیکھیں۔ | تینوں فراہم کنندگان ایک ہی Mistral طرز کی باڈی میں جواب دیتے ہیں: ```json { "pages": [{ "index": 0, "markdown": "# Extracted text..." }], "model": "mistral-ocr-latest", "usage_info": { "pages_processed": 1 } } ``` ### Azure Document Intelligence کی پولنگ کا بہاؤ Azure Document Intelligence کی `analyze` API غیر ہم وقت ہے: ابتدائی درخواست باڈی کے بجائے ایک `Operation-Location` ہیڈر واپس کرتی ہے، اور نتیجے کے لیے پولنگ کرنا ضروری ہوتا ہے۔ ہینڈلر (`open-sse/handlers/ocr.ts`) اس URL کو ہر سیکنڈ میں زیادہ سے زیادہ 30 کوششوں تک پول کرتا ہے، کسی غیر-`ok` پول جواب یا `"failed"` اسٹیٹس پر فوراً ناکام ہو جاتا ہے (پولنگ جاری نہیں رکھتا)، اور اگر کوششوں کی حد ختم ہونے کے بعد بھی کارروائی جاری ہو تو `504` واپس کرتا ہے۔ حتمی Azure جواب کو کال کرنے والے کو واپس کرنے سے پہلے Mistral میں استعمال ہونے والی اسی `pages`/`markdown` ساخت میں معمول پر لایا جاتا ہے، لہٰذا کلائنٹ کوڈ کو فراہم کنندہ کے لیے الگ خصوصی صورت سنبھالنے کی ضرورت نہیں ہوتی۔ ### Vertex AI DeepSeek OCR کی توثیق اور endpoint کا تعین `vertex-deepseek-ocr` اسی Vertex AI توثیق کو دوبارہ استعمال کرتا ہے جس کی OmniRoute پہلے ہی چیٹ/تصویری ٹریفک (`open-sse/executors/vertex.ts`) کے لیے معاونت کرتا ہے: کنکشن کی API کلید یا تو Service Account JSON اسناد ہوتی ہے (جسے JWT-bearer بہاؤ کے ذریعے مختصر مدت کے OAuth رسائی ٹوکن سے تبدیل کیا جاتا ہے) یا پہلے سے جاری کردہ OAuth رسائی ٹوکن، جسے جوں کا توں استعمال کیا جاتا ہے۔ upstream endpoint URL، Vertex کا عمومی `openapi/chat/completions` پارٹنر endpoint ہے، جو کنکشن کے پروجیکٹ اور خطے سے بنایا جاتا ہے — واضح `providerSpecificData.project`/`providerSpecificData.region` کو ہمیشہ ترجیح دی جاتی ہے؛ بصورتِ دیگر پروجیکٹ Service Account JSON کے `project_id` سے اخذ کیا جاتا ہے اور خطے کی پہلے سے طے شدہ قدر `us-central1` ہوتی ہے۔ دونوں کا تعین `open-sse/handlers/ocr.ts` (`resolveVertexOcrAccessToken`، `resolveVertexOcrBaseUrl`) میں ہوتا ہے، جنہیں `handleOcr` کو بھیجنے سے پہلے `src/app/api/v1/ocr/route.ts` استعمال کرتا ہے۔ --- ## ماڈلز کی فہرست ```bash GET /v1/models Authorization: Bearer your-api-key → OpenAI فارمیٹ میں تمام چیٹ، ایمبیڈنگ، اور امیج ماڈلز + کومبوز واپس کرتا ہے ``` ### ماڈل id کے سابقے (`?prefix=`) زیادہ تر ماڈلز کی تشہیر ایک **provider prefix** کے تحت کی جاتی ہے۔ آپ کو کون سا سابقہ ملتا ہے، یہ `MODELS_CATALOG_PREFIX_MODE` فیچر فلیگ کے ذریعے کنٹرول ہوتا ہے، اور اسے ایک query parameter کے ذریعے **ہر درخواست کے لیے** اوور رائیڈ کیا جا سکتا ہے — یہ ایسے کلائنٹ کے لیے مفید ہے جو باقی سب کے لیے سرور کی عمومی ترتیب تبدیل کیے بغیر ایک صاف فہرست چاہتا ہو: ```bash GET /v1/models?prefix=alias # ہر ماڈل کے لیے ایک id — مختصر alias سابقہ GET /v1/models?prefix=dual # دونوں صورتیں (سرور کا ڈیفالٹ) GET /v1/models?prefix=canonical # صرف مکمل provider-id سابقہ ``` | موڈ | اخراج | نوٹس | | ----------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dual` | `cc/claude-sonnet-4-6` **اور** `claude/claude-sonnet-4-6` | **ڈیفالٹ۔** دونوں ids ایک ہی ماڈل کی طرف روٹ ہوتے ہیں؛ اسے برقرار رکھا گیا ہے تاکہ کسی بھی صورت کو hardcode کرنے والی کلائنٹ کنفیگریشنز کام کرتی رہیں۔ یہ تقریباً کیٹلاگ کو دوگنا کر دیتا ہے۔ | | `alias` | `cc/claude-sonnet-4-6` | ہر ماڈل کے لیے ایک اندراج۔ الگ alias نہ رکھنے والے providers بھی اپنا اندراج خارج کرتے ہیں، اس لیے کچھ بھی ضائع نہیں ہوتا۔ | | `canonical` | `claude/claude-sonnet-4-6` | مکمل provider-id سابقے کے تحت ہر ماڈل کے لیے ایک اندراج۔ الگ alias نہ رکھنے والے providers (مثلاً `antigravity/…`، `agy/…`) بھی یہاں اپنی واحد id خارج کرتے ہیں، اس لیے کچھ بھی ضائع نہیں ہوتا۔ | `dual` موڈ کے mirror کو query parameter کے بغیر بھی پہچانا جا سکتا ہے: اس میں بنیادی id کی طرف اشارہ کرنے والی `parent` فیلڈ ہوتی ہے۔ ماڈل picker دکھانے والے کلائنٹس کو `?prefix=alias` کی درخواست کرنی چاہیے — یہی کام [OmniCopilot VS Code extension](../guides/VSCODE-COPILOT.md) کرتی ہے۔ ### انفرادی طور پر پوشیدہ چیٹ ماڈلز اپنے provider صفحے پر **Hidden** کے طور پر نشان زد ماڈل کو کیٹلاگ سے خارج کر دیا جاتا ہے اور اسے واضح طور پر طلب کیے جانے پر HTTP `404` / `model_not_found` کے ساتھ مسترد کر دیا جاتا ہے۔ یہ جانچ resolve شدہ provider اور ماڈل کو استعمال کرتی ہے، بشمول provider aliases، compatible-provider node prefixes، اور connection defaults۔ کوئی combo پوشیدہ targets کو چھوڑ دیتا ہے اور ایک مرئی sibling استعمال کر سکتا ہے؛ جب کوئی قابلِ عمل target باقی نہ رہے تو یہ وہی error code واپس کرتا ہے۔ پوشیدگی ختم کرنے کا اثر اگلی درخواست پر ہوتا ہے۔ صرف امیج کے visibility overrides اسی ID والے چیٹ ماڈل کو پوشیدہ نہیں کرتے۔ یہ انفرادی ماڈل ترتیب [model exposure allow/deny lists](../routing/MODEL_EXPOSURE_LIST.md) سے الگ ہے، جو explicit dispatch کو برقرار رکھتے ہوئے کیٹلاگ اشتہار اور auto-routing candidates کو فلٹر کرتی ہیں۔ API-key ماڈل permissions بدستور آزادانہ طور پر لاگو ہوتی ہیں۔ ڈیفالٹ کیٹلاگ prefix mode `dual` ہی رہتا ہے۔ ### بغیر سوچنے والے ماڈل کی اقسام سوچنے کی صلاحیت رکھنے والے Claude ماڈلز کے لیے، `/v1/models` ایک **no-thinking** variant کی بھی تشہیر کرتا ہے جس کی id کے شروع میں `claude-3-omniroute-no-thinking/` لگایا جاتا ہے: ``` claude-3-omniroute-no-thinking// ``` اس id کو منتخب کرنا (مثلاً ایسی Claude Code کنفیگریشن میں جو ہمیشہ `thinking` بلاک منسلک کرتی ہے) reasoning کو دبا کر واپس اصل `/` پر resolve کرتا ہے — `/v1/messages` path پر `thinking:{type:"disabled"}`، یا `/v1/chat/completions` path پر `reasoning`/`reasoning_effort` فیلڈز کو ہٹا کر۔ یہ variant صرف Claude-family کے ان ماڈلز کے لیے درج ہوتا ہے جو thinking کی معاونت کرتے **اور** `disabled` کو تسلیم کرتے ہیں (لہٰذا مثلاً adaptive-only ماڈلز جو `disabled` کو مسترد کرتے ہیں، خارج رہتے ہیں)۔ آپریٹرز `ModelSpec.noThinkingAlias` کے ذریعے ہر ماڈل کے لیے variant کو لازماً فعال یا غیر فعال کر سکتے ہیں۔ --- ## فراہم کنندہ پلگ اِن مینی فیسٹ ```bash GET /api/v1/provider-plugin-manifest ``` یہ Bifrost، CLIProxyAPI، اور مستقبل کے سائڈ کار راؤٹرز کے زیرِ استعمال JSON-محفوظ فراہم کنندہ پلگ اِن مینی فیسٹ واپس کرتا ہے۔ جواب TypeScript فراہم کنندہ رجسٹری سے تیار کیا جاتا ہے اور دانستہ طور پر OAuth کلائنٹ سیکرٹس، رن ٹائم ماحول کی ریزولیوشن، ایگزیکیوٹر فنکشنز، درخواست کے ہیڈرز، اور اکاؤنٹ ڈیٹا کو شامل نہیں کرتا۔ اس اینڈ پوائنٹ کو اس وقت استعمال کریں جب کوئی سائڈ کار عمل سے باہر چلتا ہو اور براہِ راست `open-sse/config/providerPluginManifestRegistry.ts` درآمد نہ کر سکتا ہو۔ --- ## مطابقتی اینڈپوائنٹس | طریقہ | راستہ | فارمیٹ | | ----- | ----------------------------------------- | ------------------------------------- | | POST | `/v1/chat/completions` | OpenAI | | POST | `/v1/messages` | Anthropic | | POST | `/v1/responses` | OpenAI Responses | | POST | `/v1/embeddings` | OpenAI | | POST | `/v1/images/generations` | OpenAI Images | | POST | `/v1/images/edits` | OpenAI Images (ترمیم/inpaint) | | POST | `/v1/videos/generations` | OpenAI طرز کی ویڈیو جنریشن | | POST | `/v1/music/generations` | OpenAI طرز کی موسیقی جنریشن | | POST | `/v1/audio/transcriptions` | OpenAI Audio (STT) | | POST | `/v1/audio/speech` | OpenAI TTS (آڈیو باڈی لوٹاتا ہے) | | POST | `/v1/rerank` | Cohere/Voyage طرز کی دوبارہ درجہ بندی | | POST | `/v1/classify` | Jina درجہ بندی (`api.jina.ai`) | | POST | `/v1/segment` | Jina سیگمنٹر (`segment.jina.ai`) | | POST | `/v1/moderations` | OpenAI Moderations | | GET | `/v1/models` | OpenAI | | POST | `/v1/messages/count_tokens` | Anthropic | | GET | `/v1beta/models` | Gemini | | POST | `/v1beta/models/{...path}` | Gemini generateContent | | POST | `/v1/api/chat` | Ollama | | GET | `/api/v1/vscode/{token}/` | OpenAI کیٹلاگ عرف | | GET | `/api/v1/vscode/{token}/models` | OpenAI ماڈلز عرف | | POST | `/api/v1/vscode/{token}/chat/completions` | OpenAI ٹوکنائزڈ عرف | | POST | `/api/v1/vscode/{token}/responses` | OpenAI Responses ٹوکنائزڈ عرف | | POST | `/api/v1/vscode/{token}/api/chat` | Ollama ٹوکنائزڈ عرف | | GET | `/api/v1/vscode/{token}/api/tags` | Ollama ٹیگز ٹوکنائزڈ عرف | تمام POST روٹس ایک ہی ساخت کی پیروی کرتے ہیں: `Bearer your-api-key` + Zod سے توثیق شدہ JSON باڈی (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` وغیرہ، `src/shared/validation/schemas.ts` دیکھیں)۔ اسکیما کی ناکامی پر 4xx واپس کیا جاتا ہے۔ جو کلائنٹس `Authorization: Bearer ...` منسلک نہیں کر سکتے، ان کے لیے OmniRoute یو آر ایل میں API کلیدیں بھی قبول کرتا ہے، یا تو کوئری اسٹرنگ مطابقت (`?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": "..." } # TTS — audio/mpeg (یا مطلوبہ فارمیٹ) باڈی لوٹاتا ہے POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" } # Soniox TTS کے لیے زبان اور آواز درکار ہیں: `language` کی ڈیفالٹ قدر "en" ہے؛ غائب # آواز یا OpenAI کی اسٹاک آواز کا نام (alloy, nova, …) "Adrian" بن جاتا ہے POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" } # تصویر میں ترمیم (multipart) POST /v1/images/edits -F 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` فیچر فلیگ فعال کرے **اور** نوڈ کا بنیادی یو آر ایل فراہم کنندہ کی > آؤٹ باؤنڈ یو آر ایل پالیسی (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`) پر پورا اترے۔ > میموری انجن کا دوبارہ درجہ بندی کا مرحلہ اس روٹ کو > لوپ بیک کے ذریعے کال کرتا ہے، لہٰذا یہی اصول Memory کی ترتیبات میں `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` واپس کرتے ہیں۔ --- ## Files API بیچ اِن پٹ/آؤٹ پٹ اور فائل کے مقصد کے مطابق اپ لوڈز کے لیے OpenAI سے مطابقت رکھنے والا فائلز اینڈ پوائنٹ۔ | طریقہ | راستہ | تفصیل | | ------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------- | | POST | `/v1/files` | فائل اپ لوڈ کریں (ملٹی پارٹ: `file`، `purpose`، `expires_after[anchor]`، `expires_after[seconds]`) — زیادہ سے زیادہ 512 MiB | | GET | `/v1/files` | توثیق شدہ API کلید کی فائلوں کی فہرست حاصل کریں | | GET | `/v1/files/[id]` | فائل کا میٹا ڈیٹا حاصل کریں | | DELETE | `/v1/files/[id]` | فائل حذف کریں | | GET | `/v1/files/[id]/content` | خام فائل باڈی کو واپس اسٹریم کریں | **توثیق:** بیئرر API کلید — فائلیں `getApiKeyRequestScope` کے ذریعے ہر API کلید کے لیے الگ دائرۂ کار میں ہوتی ہیں۔ کوئی کلید صرف اپنی فائلیں دیکھ، ڈاؤن لوڈ اور حذف کر سکتی ہے؛ کلید کے بغیر ڈیش بورڈ سیشن پوری انسٹینس کو پڑھ سکتا ہے؛ بغیر مالک والی فائل (گمنام یا ڈیش بورڈ سیشن سے اپ لوڈ کردہ) تک ہر غیر سیشن کالر کی رسائی مسترد کر دی جاتی ہے۔ `GET /v1/files` کسی گمنام کالر — اور ایسی فراہم کردہ کلید کو جس کی شناخت نہ ہو سکے — `401` کے ساتھ مسترد کرتا ہے، خواہ `REQUIRE_API_KEY=false` ہو، بجائے اس کے کہ ہر ٹیننٹ کی فائلیں فہرست میں دکھائے (GHSA-m3hp-hq9g-fpmv، GHSA-2jm2-mpx8-6523)۔ --- ## Batches API OpenAI سے مطابقت رکھنے والی بیچ پروسیسنگ۔ | طریقہ | راستہ | تفصیل | | ------ | ------------------------- | -------------------------------------------------------------------------------------------------------------------- | | POST | `/v1/batches` | بیچ بنائیں — باڈی کی توثیق `v1BatchCreateSchema` کے ذریعے ہوتی ہے (`input_file_id`، `endpoint`، `completion_window`) | | GET | `/v1/batches` | بیچز کی فہرست حاصل کریں | | GET | `/v1/batches/[id]` | بیچ کی حالت + `request_counts` حاصل کریں | | DELETE | `/v1/batches/[id]` | مکمل/ناکام بیچ حذف کریں | | POST | `/v1/batches/[id]/cancel` | زیرِ عمل بیچ منسوخ کریں | **توثیق:** بیئرر API کلید۔ بیچز اسی سہ رخی اصول کے تحت ہر API کلید کے لیے الگ دائرۂ کار میں ہوتے ہیں جو فائلوں پر لاگو ہے: صرف اپنی کلید، ڈیش بورڈ سیشن کے لیے پوری انسٹینس، اور بغیر مالک والے ریکارڈز تک ہر غیر سیشن کالر کی رسائی مسترد (حاصل کرنے، حذف کرنے، منسوخ کرنے، اور تخلیق کے وقت `input_file_id` کی جانچ کے لیے)۔ `GET /v1/batches` کسی گمنام کالر کو `401` کے ساتھ مسترد کرتا ہے، خواہ `REQUIRE_API_KEY=false` ہو۔ --- ## تلاش API ویب/تلاش فراہم کنندہ کی تجرید (Tavily، Brave، Exa، Serper، وغیرہ)۔ | طریقہ | راستہ | وضاحت | | ----- | ---------------------- | --------------------------------------------------------------------------------------------------- | | GET | `/v1/search` | ترتیب شدہ تلاش فراہم کنندگان اور ان کی صلاحیتوں کی فہرست | | POST | `/v1/search` | تلاش کی استفسار چلائیں — باڈی کی توثیق `v1SearchSchema` سے ہوتی ہے، کیشنگ/یکجائی کی معاونت موجود ہے | | GET | `/v1/search/analytics` | ہر فراہم کنندہ کے ہٹ/تاخیر/کیش کے اعدادوشمار | **توثیق:** Bearer API کلید (`extractApiKey` + `isValidApiKey`)۔ تلاش کی پالیسی `enforceApiKeyPolicy` کے ذریعے نافذ کی جاتی ہے۔ --- ## ویب بازیافت API کسی ترتیب شدہ ویب بازیافت فراہم کنندہ (Firecrawl، Jina Reader، Tavily Extract، TinyFish Fetch، Nimble Extract) کے ذریعے URL سے مواد اخذ کریں۔ | طریقہ | راستہ | وضاحت | | ----- | --------------- | --------------------------------------------------------------------- | | POST | `/v1/web/fetch` | URL بازیافت/اسکریپ کریں — باڈی کی توثیق `v1WebFetchSchema` سے ہوتی ہے | **توثیق:** Bearer API کلید (`extractApiKey` + `isValidApiKey`)۔ پالیسی `enforceApiKeyPolicy` کے ذریعے نافذ کی جاتی ہے۔ **کوٹہ سے آگاہ متبادل (#8297):** جب کوئی واضح `provider` نہ دیا گیا ہو تو پول (`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) کو مقررہ ترجیحی ترتیب (پہلے پُر کریں) میں آزمایا جاتا ہے — شرح کی حد سے محدود مگر ترتیب شدہ فراہم کنندہ کو درخواست فوراً ختم کرنے کے بجائے چھوڑ دیا جاتا ہے، اور قابلِ دوبارہ کوشش/کوٹہ سے متعلق بالائی سروس کی ناکامی (HTTP 429 ہمیشہ؛ Firecrawl/Tavily/TinyFish کے کوٹہ طرز کے مفت درجوں کے لیے 402/403 — Jina Reader کے لیے نہیں، اور سادہ 400 ناقص درخواست کے لیے کبھی نہیں) درخواست کے وقت اگلے غیر آزمودہ، اسناد رکھنے والے فراہم کنندہ کی طرف منتقل ہو جاتی ہے۔ جب پول میں موجود ہر فراہم کنندہ ختم ہو جائے تو اینڈپوائنٹ سابقہ عمومی `400` کے بجائے ایک واحد `429` (`Retry-After` ہیڈر کے ساتھ) واپس کرتا ہے۔ جب واضح `provider` کی درخواست کی جائے تو **کوئی** خاموش متبادل نہیں ہوتا — شرح کی حد سے محدود یا ناکام واضح فراہم کنندہ اپنی ہی خرابی ظاہر کرتا ہے (شرح کی حد کی صورت میں `429`، بصورتِ دیگر بالائی سروس کا اسٹیٹس)۔ --- ## WebSocket اسٹریمنگ ```bash GET /v1/ws?handshake=1 ``` WebSocket اپ گریڈ ہینڈ شیک کی توثیق کرتا ہے اور وائر پروٹوکول کے مثالی پیغامات (`request`، `cancel`) واپس کرتا ہے۔ اصل WS فریمز کو Next.js روٹ ٹیبل سے باہر شامل شدہ WS سرور سنبھالتا ہے۔ **توثیق:** ہینڈ شیک کے دوران Bearer API کلید۔ ### WebSocket کے ذریعے Responses API (صرف codex) ```bash # HTTP API کے طور پر وہی host:port (ڈیفالٹ 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` برج کے ذریعے توثیق اور تیاری کرتی ہے، ایک codex OAuth کنکشن منتخب کرتی ہے، اور `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` میں ہے۔ **توثیق:** ہینڈ شیک کے دوران Bearer API کلید۔ شامل شدہ HTTP سرور (`server-ws.mjs`) کا فعال نقطۂ آغاز ہونا ضروری ہے (جب `app/server-ws.mjs` موجود ہو تو بطور ڈیفالٹ یہی ہوتا ہے)۔ #### ماڈل id: سادہ ChatGPT id استعمال کریں (`codex/` سابقے کے بغیر) OpenAI **Codex CLI** اس وقت ماڈل کے نام کی کلائنٹ سائیڈ پر توثیق کرتا ہے جب `supports_websockets = true` ہو، اور `codex/gpt-5.5` جیسے **فراہم کنندہ کے سابقے والے ids مسترد کرتا ہے** (`The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account`)۔ **سادہ** id بھیجیں (مثلاً `gpt-5.5`)۔ OmniRoute کا برج صرف codex کے لیے ہے، اس لیے بالائی سروس تک ٹنل بنانے سے پہلے یہ سادہ id کو codex ماڈل کے طور پر دوبارہ حل کرتا ہے (`resolveCodexWsModelInfo`) — اگرچہ سادہ `gpt-5.5` بصورتِ دیگر HTTP کے ذریعے کسی دوسرے فراہم کنندہ کی طرف روٹ ہوتا۔ #### OpenAI Codex CLI کی ترتیب `~/.codex/config.toml` میں WebSocket معاونت کے ساتھ ایک حسبِ ضرورت فراہم کنندہ شامل کر کے Codex CLI کو OmniRoute کی طرف متوجہ کریں (موجودہ ترتیب کو متاثر کرنے سے بچنے کے لیے علیحدہ `CODEX_HOME` استعمال کریں): ```toml model = "gpt-5.5" # سادہ id — "codex/gpt-5.5" نہیں model_provider = "omniroute" [model_providers.omniroute] name = "OmniRoute (WS)" base_url = "http://localhost:20128/v1" # آخر میں سلیش نہیں؛ WS URL اخذ کیا جاتا ہے (پروڈکشن میں https/wss استعمال کریں) wire_api = "responses" # فروری 2026 سے واحد معاون قدر supports_websockets = true # Responses-over-WS ٹرانسپورٹ فعال کرتا ہے env_key = "OMNIROUTE_API_KEY" # OmniRoute API کلید (Bearer) رکھتا ہے ``` ```bash export OMNIROUTE_API_KEY=sk-... # ایک OmniRoute API کلید (اگر REQUIRE_API_KEY=false ہو تو کوئی بھی کلید) codex exec "Responda apenas: PONG" ``` CLI، `base_url + /responses` کو WebSocket میں اپ گریڈ کرتا ہے اور OmniRoute اسے منتخب کردہ codex OAuth کنکشن تک ٹنل کرتا ہے۔ مقامی سرور کے خلاف ابتدا سے انتہا تک توثیق شدہ: ChatGPT، `codex.rate_limits` + `response.created` واپس کرتا ہے اور تکمیل کو اسٹریم کرتا ہے۔ --- ## کوٹاز اور مسائل کی رپورٹنگ | طریقہ | راستہ | تفصیل | | ----- | ------------------- | ----------------------------------------------------------------------------------------- | | GET | `/v1/quotas/check` | رجسٹرڈ کلید جاری کرنے سے پہلے `provider` + `accountId` کے لیے کوٹے کی پیشگی توثیق کریں | | POST | `/v1/issues/report` | کوٹے/کلید کے اجرا کی ناکامی کی GitHub کو اطلاع دیں (`GITHUB_ISSUES_REPO` + ٹوکن درکار ہے) | **تصدیق:** Bearer API کلید (`isAuthenticated`)۔ --- ## سیلف سروس استعمال (`/api/usage/om-usage`) کوئی بھی API کلید **اپنا** استعمال اور کوٹے پڑھ سکتی ہے — انتظامی توثیق کی ضرورت نہیں۔ یہ وہ اینڈ پوائنٹ ہے جسے کوئی کلائنٹ (CLI، OmniCopilot پینل) کلید کے حامل شخص کو اس کا خرچ دکھانے کے لیے استعمال کرتا ہے۔ ```bash # متنی صورت (تاریخی معاہدہ — ٹرمینل کے لیے سادہ متن) curl -H "Authorization: Bearer " \ http://localhost:20128/api/usage/om-usage # ساختی صورت — جسے UI استعمال کرتا ہے curl -H "Authorization: Bearer " \ "http://localhost:20128/api/usage/om-usage?format=json" ``` کلید کے لیے **`allowUsageCommand`** فعال ہونا ضروری ہے (یہ بطور ڈیفالٹ غیر فعال ہوتا ہے — ڈیش بورڈ کا API-key مینیجر اسے ہر کلید کے لیے الگ سے تبدیل کرتا ہے)۔ اس کے بغیر اینڈ پوائنٹ `403` کے ساتھ جواب دیتا ہے۔ `?format=json` ایک امتیازی ساخت واپس کرتا ہے تاکہ کالر کبھی بھی انکار کی صورت میں ڈیٹا فیلڈ نہ پڑھے۔ کامیابی کی صورت میں: ```jsonc { "allowed": true, // صرف اس وقت موجود ہوتا ہے جب کلید نے فی کلید استعمال کی حدود (یومیہ/ہفتہ وار USD) اختیار کی ہوں: "personal": { "dailySpentUsd": 1.25, "dailyLimitUsd": 5, "dailyResetAtIso": "…", "weeklySpentUsd": 8, "weeklyLimitUsd": 20, "weeklyResetAtIso": "…" /* … */, }, // منتخب فراہم کنندہ کے کوٹے کا اسنیپ شاٹ، یا اگر ابھی تک کچھ کیش نہ ہوا ہو تو null: "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */}, }, // ہر کنکشن کا اسنیپ شاٹ، تاکہ UI متعدد فراہم کنندگان کو ساتھ ساتھ دکھا سکے: "providers": [ { "connectionId": "…", "provider": "claude" /* … */ }, { "provider": "codex" /* … */ }, ], } ``` انکار کی صورت میں (`401` ناقص کلید / `403` اجازت نہیں) یہی روٹ `{ "allowed": false, "error": { "message": "…" } }` واپس کرتا ہے — موجود مگر خالی `personal`/`provider` (کلید کو اجازت ہے، مگر ابھی تک کچھ معلوم نہیں ہوا) انکار سے مختلف حالت ہے، اور صرف JSON صورت ان دونوں میں فرق کرتی ہے۔ **توثیق:** کالر کی اپنی Bearer API کلید، جس کی `isValidApiKey` کے ذریعے توثیق کی جاتی ہے — یہ انتظامی سطح (`/api/keys/…`) _نہیں_ ہے، جو `requireManagementAuth` کے پیچھے ہی رہتی ہے۔ ### خام بمقابلہ کٹ آف کے مطابق ایڈجسٹ شدہ کوٹے کے فیصد `/api/usage/om-usage` استعمال کرتے وقت کالرز کو **سادہ متنی آؤٹ پٹ** اور ساختی **JSON آؤٹ پٹ** میں پیش کیے گئے فیصد کے درمیان فرق کو مدِنظر رکھنا چاہیے: | پہلو | سادہ متنی فارمیٹ (`/api/usage/om-usage` / `@@om-usage`) | JSON فارمیٹ (`?format=json`) | | :---------------- | :---------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- | | **آؤٹ پٹ فیلڈ** | `NN% left` (مثلاً، `20% left`) | `provider.quotas` / `providers[].quotas` | | **پیمائش** | **کٹ آف کے مطابق ایڈجسٹ شدہ قابلِ استعمال گنجائش**: کٹ آف حد سے زیادہ باقی صلاحیت | **خام اپ اسٹریم کوٹا**: فراہم کنندہ کی غیر ایڈجسٹ شدہ پیمائش | | **کٹ آف اسکیلنگ** | `effectiveRemainingPercent()` کے ذریعے اسکیل کی جاتی ہے تاکہ محفوظ ذخیرہ `0% left` دکھائے | کوئی نہیں (فراہم کنندہ کی اطلاع کے مطابق خام اسنیپ شاٹ اقدار) | | **حد کا ڈیٹا** | دکھائے گئے فیصد میں شامل ہوتا ہے | ہر کنکشن کے `quotaWindowThresholds` میں محفوظ ہوتا ہے (یا سرور ڈیفالٹس) | | **بنیادی صارف** | انٹرایکٹو CLIs، ٹرمینل پرامپٹس، انسانی آپریٹرز | پروگراماتی انٹیگریشنز، ڈیش بورڈز، تجزیات، بلنگ ٹریکرز | #### کٹ آف ایڈجسٹمنٹ کا فارمولا OmniRoute اپ اسٹریم کوٹے کے خاتمے کو روکنے کے لیے پیشگی کوٹا کٹ آف کی معاونت کرتا ہے (جو کنکشن کے `quotaWindowThresholds`، فراہم کنندہ کے ڈیفالٹس، یا عالمی ریزیلینس ترتیبات کے ذریعے ترتیب دیے جاتے ہیں)۔ جب کسی کوٹا ونڈو پر کٹ آف حد (مثلاً، `cutoff = 25%`) فعال ہو، تو متنی رینڈرر باقی گنجائش کا حساب یوں کرتا ہے: - اگر `remaining <= cutoff` ہو: `0%` واپس کرتا ہے۔ - اگر `remaining > cutoff` ہو: `((remaining - cutoff) / (100 - cutoff)) * 100` واپس کرتا ہے۔ فارمیٹ شدہ متنی آؤٹ پٹ اسے قریب ترین صحیح عدد تک راؤنڈ کرتا ہے (`Math.round(...)`)۔ #### توضیحی مثال ایک فراہم کنندہ ونڈو پر غور کریں جس کا **خام استعمال 60%** ہو (لہٰذا **خام باقی کوٹا 40%**) اور **باقی کوٹے کی 25% کٹ آف** حد ترتیب دی گئی ہو: | نمائندگی | حساب | باقی | اخذ شدہ استعمال | | :---------------------------- | :------------------------------------------------- | :-----: | :----------------------------------------------: | | **خام JSON (`?format=json`)** | اپ اسٹریم اسنیپ شاٹ (`quotas[window]`) | **40%** | **60%** | | **متنی فارمیٹ (`NN% left`)** | `((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100` | **20%** | **80%** (اگر `100 - remaining` کا حساب کیا جائے) | - **متن میں 20% باقی کیوں دکھایا جاتا ہے:** اکاؤنٹ پر باقی 40% حقیقی کوٹے میں سے 25% کٹ آف پالیسی کے تحت محفوظ ہے۔ روٹر کے اس کنکشن کو روٹنگ بند کرنے سے پہلے کالر کے پاس قابلِ استعمال 75% گنجائش میں سے صرف 15% باقی ہے۔ اسکیلنگ یقینی بناتی ہے کہ کنکشن ٹھیک اسی وقت ختم ہونے کا اشارہ (`0% left`) دے جب روٹنگ رک جائے گی۔ - **JSON خام اقدار کیوں برقرار رکھتا ہے:** JSON پے لوڈ فراہم کنندہ کا عین اسنیپ شاٹ (`UsageSnapshot`) واپس کرتا ہے تاکہ بیرونی ٹولز کو سرور سائیڈ پر نقصان دہ اسکیلنگ کے بغیر حقیقی اپ اسٹریم استعمال اور کنکشن کی سطح کے `quotaWindowThresholds` تک رسائی حاصل ہو۔ #### صارفین کے لیے منتقلی کی رہنمائی اگر کوئی بیرونی انٹیگریشن (جیسے ایڈیٹر پلگ اِن یا ایجنٹ ایکسٹینشن) پہلے متنی اینڈ پوائنٹ (`NN% left`) کو اسکریپ کرتا تھا اور استعمال شدہ فیصد کا حساب `100 - NN` کے طور پر لگاتا تھا، تو `?format=json` پر منتقلی کا مطلب یہ ہے: - خام JSON اقدار پڑھنے سے **اصل اپ اسٹریم کھپت** ظاہر ہوگی (اوپر دی گئی مثال میں 60% استعمال)۔ - اگر انٹیگریشن متنی اینڈ پوائنٹ کے قابلِ استعمال گنجائش والے مفہوم کو برقرار رکھنا چاہے، تو وہ کنکشن کی سطح کے اوور رائیڈز کے لیے `quotaWindowThresholds` استعمال کرتے ہوئے مؤثر باقی ماندہ گنجائش کے فارمولے کا کلائنٹ سائیڈ پر جائزہ لے سکتا ہے۔ --- ## سیمنٹک کیش ```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 } } ``` ### تاخیر پر اثر سیمنٹک کیش HIT جواب کو **upstream کال کے بغیر** کیش سے فراہم کرتا ہے، اس لیے رپورٹ کردہ `X-OmniRoute-Response-Latency` تقریباً صفر ہوتا ہے (اصل upstream تاخیر سے قطع نظر)۔ تاخیر کے حوالے سے حساس کلائنٹس (بینچ مارکنگ، p50/p99 مانیٹرنگ) کو `X-OmniRoute-Cache-Latency` ریسپانس ہیڈر چیک کرنا چاہیے: | قدر | مطلب | | ------------- | ----------------------------------------------------------- | | `synthetic` | جواب کیش سے فراہم کیا گیا؛ تاخیر حقیقی upstream وقت نہیں ہے | | _(غیر موجود)_ | حقیقی upstream کال سے حاصل کردہ جواب | ### فی کلید کیش بائی پاس API کلیدیں `cacheDefaultMode` کے ذریعے سیمنٹک کیش سے پڑھنے کو ترک کر سکتی ہیں: | قدر | طرزِ عمل | | -------- | ----------------------------------------------------------- | | `legacy` | کیش کا معمول کا طرزِ عمل (ڈیفالٹ) | | `bypass` | کیش lookup مکمل طور پر چھوڑ دیں؛ ہمیشہ upstream کو کال کریں | کلید بناتے وقت (`POST /api/keys`) سیٹ کریں یا (`PATCH /api/keys/[id]`) کے ذریعے اپ ڈیٹ کریں: ```json { "cacheDefaultMode": "bypass" } ``` ### فی درخواست بائی پاس کوئی بھی درخواست کلید کی ترتیبات سے قطع نظر کیش کو بائی پاس کر سکتی ہے: ``` X-OmniRoute-No-Cache: true ``` --- ## ڈیش بورڈ اور انتظام انتظامی روٹس (`/api/*`، سوائے عوامی auth/login کے) عام inference API کلیدوں کے ذریعے **مجاز نہیں** ہوتے۔ اسناد کی اقسام، scopes، اور curl کی مثالیں: [انتظامی توثیق](../guides/MANAGEMENT-AUTH.md)۔ ### توثیق | Endpoint | طریقہ | وضاحت | | ----------------------------- | ------- | -------------------------- | | `/api/auth/login` | POST | لاگ اِن | | `/api/auth/logout` | POST | لاگ آؤٹ | | `/api/settings/require-login` | GET/PUT | لازمی لاگ اِن کو ٹوگل کریں | ### فراہم کنندہ کا انتظام | Endpoint | طریقہ | وضاحت | | --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/providers` | GET/POST | فراہم کنندگان کی فہرست دیکھیں / بنائیں | | `/api/providers/[id]` | GET/PUT/DELETE | فراہم کنندہ کا انتظام کریں | | `/api/providers/[id]/test` | POST | فراہم کنندہ کے کنکشن کی جانچ کریں | | `/api/providers/[id]/models` | GET | فراہم کنندہ کے ماڈلز کی فہرست دیکھیں | | `/api/providers/validate` | POST | فراہم کنندہ کی config کی توثیق کریں | | `/api/providers/bulk` | POST | ایک فراہم کنندہ کے لیے API کلیدیں بڑی تعداد میں شامل کریں | | `/api/providers/import` | POST | پارس شدہ CSV/JSON فائل سے مختلف اقسام کے فراہم کنندگان کی فہرست درآمد کریں (#6836)؛ ہر قطار کے جزوی ناکامی کے نتائج | | `/api/provider-nodes*` | مختلف | فراہم کنندہ کے نوڈز کا انتظام | | `/api/provider-models` | GET/POST/PUT/PATCH/DELETE | حسبِ ضرورت ماڈلز اور ہر ماڈل کے لیے overrides (شامل کرنا، اپ ڈیٹ کرنا، چھپانا/دکھانا، حذف کرنا) | | `/api/provider-models/validate-and-add` | POST | انتظامی طور پر توثیق شدہ، اختیاری سخت کنکشن توثیق اور ایٹمی حسبِ ضرورت ماڈل رجسٹریشن؛ [ماڈل کی توثیق](../guides/MODEL-VALIDATION.md) دیکھیں | ہم وقت ساز/درآمد شدہ ماڈلز کے لیے، `PUT /api/provider-models`، `provider`، `modelId`، اور `maxOutputTokenOverride` قبول کرتا ہے: ایک مثبت صحیح عدد دستی output-token حد مقرر کرتا ہے، اور `null` اسے صاف کر کے طے شدہ قدر بحال کرتا ہے۔ `GET /api/provider-models?provider=` یہ اقدار `modelOutputOverrides` میں واپس کرتا ہے، بشمول ان ماڈلز کے جن کی حسبِ ضرورت ماڈل قطار موجود نہیں ہوتی۔ یہ override runtime کی `max_output_tokens` صلاحیت استعمال کرتا ہے اور ماڈل کی دوبارہ ہم وقت سازی کے بعد بھی برقرار رہتا ہے۔ OpenAI-compatible فراہم کنندہ کا صفحہ یہی ترمیم/صاف کرنے کے کنٹرولز فراہم کرتا ہے اور واضح vision معاونت والے ماڈلز کو نشان زد کرتا ہے۔ حسبِ ضرورت Chat Completions نوڈز، reasoning سے واضح طور پر دست بردار ہونے کی درخواستوں کو upstream backend کے مطابق ڈھالتے ہیں۔ ایک کامیاب کنکشن ٹیسٹ ہر اس عین model ID کے لیے خودکار طور پر chat-template کنٹرولز منتخب کرتا ہے جس کی `/models` اندراج کسی تسلیم شدہ `owned_by` قدر کو ثابت کرتی ہے: `vllm`، `sglang`، یا `llamacpp`۔ شفاف OpenAI-compatible wrappers اصل ماڈل اندراج کو nested `openai` object کے اندر محفوظ رکھ سکتے ہیں؛ شناخت ایسے زیادہ سے زیادہ تین envelopes کی پیروی کرتی ہے۔ غائب، نامعلوم، یا متضاد ملکیت والے ماڈلز عام OpenAI طرزِ عمل برقرار رکھتے ہیں۔ شناخت موجودہ catalog درخواست کو دوبارہ استعمال کرتی ہے، کوئی completion tokens تخلیق نہیں کرتی، اور کنکشن endpoint تبدیل ہونے پر منسوخ ہو جاتی ہے۔ ایسے backend کے لیے اس طرزِ عمل کو مقرر کرنے کی خاطر جو یہ metadata ظاہر نہیں کرتا، موجودہ جزوی فراہم کنندہ update API استعمال کریں: ```json { "providerSpecificData": { "reasoningControl": "chat-template" } } ``` اس body کو `PUT /api/providers/` کے ساتھ بھیجیں۔ اس کنکشن پر، `none` کی واضح reasoning effort کو `chat_template_kwargs.thinking=false` اور `chat_template_kwargs.enable_thinking=false` کے طور پر بھیجا جاتا ہے۔ واضح native template اقدار حتمی اختیار رکھتی ہیں، الا یہ کہ server-side reasoning اصول کسی effort کو لازمی قرار دے۔ یہ ترتیب صرف اس وقت لاگو ہوتی ہے جب کوئی حسبِ ضرورت OpenAI-compatible کنکشن Chat Completions body بھیجتا ہے؛ Responses درخواستیں اور عام فراہم کنندگان اپنی native درخواست کی ساخت برقرار رکھتے ہیں۔ عام OpenAI `reasoning_effort` passthrough کو لازمی بنانے کے لیے `reasoningControl` کو `openai` پر مقرر کریں، یا خودکار شناخت استعمال کرنے کے لیے اسے چھوڑ دیں/`null` پر مقرر کریں۔ Claude Code آٹو موڈ کلاسیفائر کی درخواستوں میں، جب کوئی واضح reasoning controls موجود نہ ہوں، تو مقامی thinking بطور ڈیفالٹ غیر فعال ہوتی ہے۔ شناخت ماڈل کے ناموں یا completion limits کے بجائے Claude فارمیٹ کی درخواستوں میں موجود کلاسیفائر کے system marker کو استعمال کرتی ہے۔ باڈی کے واضح controls، معاون effort/thinking ہیڈرز، routing rules، اور حل شدہ model effort کی موجودہ ترجیح برقرار رہتی ہے۔ کلاسیفائر کے دونوں مراحل اپنے prompts، completion limits، stop sequences، اور حقیقی upstream اجازت کے فیصلے برقرار رکھتے ہیں؛ دوسرا مرحلہ اب بھی اپنی مطلوبہ نظر آنے والی reasoning کو عام متن کے طور پر پیش کر سکتا ہے۔ ### 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 | فی پرووائیڈر/ماڈل rolling latency aggregate (avg/p50/p95/p99، کامیابی کی شرح)؛ فلٹرز: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) | | `/api/usage/cache-health` | GET | `call_logs` پر prompt-cache کی صحت کا خلاصہ — لکھنے/پڑھنے کا تناسب، p50/p90/p99 write-size distribution، heavy-write concentration، فی ماڈل تقسیم، اور `healthy`/`degraded`/`thrash`/`no-data` فیصلہ؛ query params `range` (`1h`\|`24h`\|`7d`\|`30d`، ڈیفالٹ `24h`) اور اختیاری `model` (#8827) | ### API کلید کی اجازتیں `PATCH /api/keys/{id}` کسی موجودہ کلید کی اجازتوں کو اپ ڈیٹ کرتا ہے۔ ہر `/api/keys*` روٹ کی طرح، اسے inference کلید کے بجائے انتظامی اجازت درکار ہوتی ہے (دیکھیے [انتظامی توثیق](../guides/MANAGEMENT-AUTH.md))۔ صرف وہی فیلڈز بھیجیں جنہیں آپ تبدیل کرنا چاہتے ہیں؛ ان میں سے کسی بھی فیلڈ کے بغیر درخواست `No valid fields to update` کے ساتھ مسترد کر دی جاتی ہے۔ قبول شدہ فیلڈز کی تعریف `src/shared/validation/schemas/keys.ts` میں `updateKeyPermissionsSchema` کے ذریعے کی گئی ہے۔ | فیلڈ | قسم | نوٹس | | ------------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | اسٹرنگ، 1-200 حروف | | | `isActive` | بولین | | | `isBanned` | بولین | | | `expiresAt` | ISO 8601 تاریخ و وقت یا `null` | `null` میعاد ختم ہونے کی ترتیب صاف کر دیتا ہے | | `modelAccessMode` | `all` \| `restricted` | جب موڈ `all` ہو تو `allowedModels` خالی ہونا چاہیے | | `allowedModels`, `blockedModels` | اسٹرنگز کی صف، زیادہ سے زیادہ 1000 | | | `allowedCombos` | اسٹرنگز کی صف، زیادہ سے زیادہ 500 | یہ کنٹرول کرتا ہے کہ کلید کن کومبوز کو کال کر سکتی ہے؛ براہِ راست ماڈلز `modelAccessMode` / `allowedModels` کے تحت کنٹرول ہوتے ہیں | | `connectionAccessMode` | `all` \| `restricted` | `restricted` کی صورت میں `allowedConnections` غیر خالی اور `all` کی صورت میں خالی ہونا چاہیے | | `allowedConnections` | UUIDs کی صف، زیادہ سے زیادہ 100 | | | `allowAutoCombos` | بولین | `false` اس کلید کے ساتھ `auto/*` ماڈلز کی درخواستوں کو مسترد کرتا ہے؛ جن کلیدوں نے اسے کبھی سیٹ نہیں کیا، انہیں اجازت ہوتی ہے | | `catalogScope` | `all` \| `combos` \| `models` | اس کلید کے لیے `GET /v1/models` کیا درج کرتا ہے (صرف کومبوز، صرف ماڈلز، یا دونوں)؛ یہ اس بات کو تبدیل نہیں کرتا کہ کلید کن چیزوں کو کال کر سکتی ہے | | `noLog`, `autoResolve` | بولین | | | `throttleDelayMs` | عددِ صحیح، 0-300000 | | | `maxSessions` | عددِ صحیح، 0-10000 | | | `rateLimits` | `{ limit, window }` کی صف (مثبت اعدادِ صحیح، زیادہ سے زیادہ 50) یا `null` | `null` حدود صاف کر دیتا ہے | | `accessSchedule` | شیڈول آبجیکٹ یا `null` | `null` شیڈول صاف کر دیتا ہے | | `scopes` | اسٹرنگز کی صف، زیادہ سے زیادہ 32 | | | `allowedEndpoints` | اسٹرنگز کی صف، زیادہ سے زیادہ 20 | | | `streamDefaultMode` | `legacy` \| `json` | | | `cacheDefaultMode` | `legacy` \| `bypass` | [فی کلید کیش بائی پاس](#per-key-cache-bypass) دیکھیں | | `compressionEnabled` | بولین | | | `codexServiceMode` | Codex سروس موڈز میں سے ایک | | | `disableNonPublicModels` | بولین | | | `allowUsageCommand` | boolean | | | `usageLimitEnabled` | boolean | | | `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | 0 یا اس سے زیادہ number، یا `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 | عمومی ترتیبات | | `/api/settings/proxy` | GET/PUT | نیٹ ورک پراکسی کی تشکیل | | `/api/settings/proxy/test` | POST | پراکسی کنکشن کی جانچ | | `/api/settings/ip-filter` | GET/PUT | IP اجازت فہرست/بلاک فہرست | | `/api/settings/thinking-budget` | GET/PUT | سوچ/استدلال کی **درخواست** کو دوبارہ لکھنے کا موڈ (passthrough / auto-strip / custom / adaptive)۔ کمپریشن سے آزاد۔ [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 | پوائنٹر id کے ذریعے برقرار رکھا گیا مخفی خام آؤٹ پٹ پڑھیں | | `/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` شامل ہے: پروب کیش اسکیلرز، جب `failed>0` ہو تو `failedConnections`، اور `staleDbNonOkCount` (SQLite کا مستقل `test_status`، گیج نہیں)۔ [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/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` ملتا ہے۔ `/api/db-backups/export`, `/api/db-backups/exportAll` and `/api/settings/export-json` hand out every stored credential, so they require the dashboard session or the local CLI (or login disabled). API keys of any scope and `oma_` access tokens get `403`. The restores hold the same boundary: `POST /api/db-backups/import` (`dryRun=true` included), `POST /api/db-backups` (restore by id) and `POST /api/settings/import-json` replace the live database or settings, so a machine credential gets `403` there too; `omniroute sync import` sends the local CLI credential. ### کلاؤڈ ہم وقت سازی | اینڈ پوائنٹ | طریقہ | تفصیل | | ---------------------- | ----- | ------------------------------- | | `/api/sync/cloud` | مختلف | کلاؤڈ ہم وقت سازی کی کارروائیاں | | `/api/sync/initialize` | POST | ہم وقت سازی شروع کریں | | `/api/cloud/*` | مختلف | کلاؤڈ مینجمنٹ | ### ٹنلز | اینڈ پوائنٹ | طریقہ | تفصیل | | -------------------------- | ----- | -------------------------------------------------------------------------- | | `/api/tunnels/cloudflared` | GET | ڈیش بورڈ کے لیے Cloudflare Quick Tunnel کی انسٹالیشن/رن ٹائم کی حالت پڑھیں | | `/api/tunnels/cloudflared` | POST | Cloudflare Quick Tunnel کو فعال یا غیر فعال کریں (`action=enable/disable`) | | `/api/tunnels/ngrok` | GET | ڈیش بورڈ کے لیے ngrok Tunnel کی رن ٹائم حالت پڑھیں | | `/api/tunnels/ngrok` | POST | ngrok Tunnel کو فعال یا غیر فعال کریں (`action=enable/disable`) | ### CLI ٹولز | اینڈ پوائنٹ | طریقہ | تفصیل | | ---------------------------------- | ----- | -------------------- | | `/api/cli-tools/claude-settings` | GET | Claude CLI کی حالت | | `/api/cli-tools/codex-settings` | GET | Codex CLI کی حالت | | `/api/cli-tools/droid-settings` | GET | Droid CLI کی حالت | | `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI کی حالت | | `/api/cli-tools/runtime/[toolId]` | GET | عمومی CLI رن ٹائم | CLI جوابات میں یہ شامل ہوتے ہیں: `installed`، `runnable`، `command`، `commandPath`، `runtimeMode`، `reason`۔ ### ACP ایجنٹس | اینڈ پوائنٹ | طریقہ | تفصیل | | ----------------- | ------ | ---------------------------------------------------------- | | `/api/acp/agents` | GET | حالت سمیت تمام دریافت شدہ ایجنٹس (بلٹ اِن + کسٹم) کی فہرست | | `/api/acp/agents` | POST | کسٹم ایجنٹ شامل کریں یا تشخیصی کیش ریفریش کریں | | `/api/acp/agents` | DELETE | `id` کوئری پیرامیٹر کے ذریعے کسٹم ایجنٹ ہٹائیں | GET جواب میں `agents[]` (id، name، binary، version، installed، protocol، isCustom) اور `summary` (total، installed، notFound، builtIn، custom) شامل ہوتے ہیں۔ ### بحالی پذیری اور شرح کی حدود | اینڈ پوائنٹ | طریقہ | تفصیل | | --------------------------------- | --------- | ------------------------------------------------------------------------------------------ | | `/api/resilience` | GET/PATCH | درخواست کی قطار، کنکشن کول ڈاؤن، فراہم کنندہ بریکر، اور انتظار کی ترتیبات حاصل/اپ ڈیٹ کریں | | `/api/resilience/reset` | POST | فراہم کنندہ سرکٹ بریکرز ری سیٹ کریں | | `/api/resilience/model-cooldowns` | GET | فعال فی-(فراہم کنندہ، کنکشن، ماڈل) لاک آؤٹس کو باقی وقت کے لحاظ سے مرتب کرکے فہرست بنائیں | | `/api/resilience/model-cooldowns` | DELETE | ماڈل لاک آؤٹ صاف کریں — باڈی `{provider, model}` یا سب کچھ مٹانے کے لیے `{all: true}` | | `/api/rate-limits` | GET | فی اکاؤنٹ شرح کی حد کی حالت | | `/api/rate-limit` | GET | عالمی شرح کی حد کی کنفیگریشن | > تمام چار `/api/resilience/*` روٹس کے لیے **انتظامی توثیق** (`requireManagementAuth`) درکار ہے۔ فراہم کنندہ بریکر بمقابلہ کنکشن کول ڈاؤن بمقابلہ ماڈل لاک آؤٹ کی مکمل تفصیل کے لیے [بحالی پذیری (توسیعی)](#resilience-extended) دیکھیں۔ ### تشخیصات | اینڈ پوائنٹ | طریقہ | تفصیل | | ------------ | -------- | ------------------------------------ | | `/api/evals` | GET/POST | تشخیصی سویٹس کی فہرست / تشخیص چلائیں | ### پالیسیاں | اینڈ پوائنٹ | طریقہ | تفصیل | | --------------- | --------------- | ------------------------ | | `/api/policies` | GET/POST/DELETE | روٹنگ پالیسیاں منظم کریں | ### تعمیل | اینڈ پوائنٹ | طریقہ | تفصیل | | --------------------------- | ----- | ---------------------- | | `/api/compliance/audit-log` | GET | تعمیل آڈٹ لاگ (آخری N) | ### v1beta (Gemini سے ہم آہنگ) | اینڈ پوائنٹ | طریقہ | تفصیل | | -------------------------- | ----- | --------------------------------------- | | `/v1beta/models` | GET | Gemini فارمیٹ میں ماڈلز کی فہرست | | `/v1beta/models/{...path}` | POST | Gemini کا `generateContent` اینڈ پوائنٹ | یہ اینڈ پوائنٹس ان کلائنٹس کے لیے Gemini کے API فارمیٹ کی عکاسی کرتے ہیں جنہیں مقامی Gemini SDK مطابقت درکار ہوتی ہے۔ ### داخلی / سسٹم APIs | اینڈ پوائنٹ | طریقہ | تفصیل | | ------------------------ | ----- | ------------------------------------------------------------- | | `/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 ``` صرف لوپ بیک مینجمنٹ روٹ (ایڈمن توثیق)۔ یہ زیرِ استعمال ورژن، تازہ ترین شائع شدہ ورژن اور خودکار اپ ڈیٹ کی حالت واپس کرتا ہے۔ `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`، دیگر قبل از اجرا ورژنز (`-rc.*`، `-beta.*`، `-alpha.*`) کے لیے `next`، `channels.latest` سے پرانے میجر کے مستحکم ورژن کے لیے `lts`، بصورتِ دیگر `latest`۔ وہی اصول جو `scripts/release/dist-tag.mjs` میں ہیں، جو اشاعت کے وقت npm dist-tag منتخب کرتا ہے۔ - `channels` — ہر dist-tag کا شائع شدہ تازہ ترین ورژن، جو `npm view omniroute dist-tags` سے حاصل ہوتا ہے (رجسٹری HTTP متبادل کے ساتھ)، اور `latest` ہی کی طرح 10 منٹ کی TTL کے ساتھ کیش کیا جاتا ہے۔ `latest` ہمیشہ موجود ہوتا ہے (پہلے `latest` فیلڈ، پھر `"unavailable"` کو متبادل کے طور پر استعمال کرتا ہے)؛ `next`، `nightly` اور `lts` صرف اسی وقت ظاہر ہوتے ہیں جب متعلقہ dist-tag موجود ہو۔ `Cache-Control: no-cache` درخواست دونوں تلاشوں کو تازہ کرتی ہے۔ چینل ماڈل (`latest` = 4.0 GA تک v3، `next` = rc، `nightly` = `develop` بلڈز، `lts` = 4.0 GA کے بعد v3 پیچز) کی وضاحت `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 } ``` **مثالی ماڈل IDs:** `openai/whisper-1` (اس کے لیے OpenAI کلید درکار ہے)، `openrouter/deepgram/nova-3` (اس کے لیے OpenRouter کلید درکار ہے)، `deepgram/nova-3` (اس کے لیے مقامی Deepgram کلید درکار ہے)۔ براہِ راست `deepgram/nova-3` درخواست OpenRouter استعمال **نہیں** کرتی۔ **معاونت یافتہ فارمیٹس:** `mp3`، `wav`، `m4a`، `flac`، `ogg`، `webm`۔ --- ## Ollama مطابقت ان کلائنٹس کے لیے جو Ollama کا API فارمیٹ استعمال کرتے ہیں: ```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 } # id کے ذریعے ٹوکن کی حد حذف کریں DELETE /api/usage/token-limits?id=tl-abc ``` > **اسکیما کے نوٹس** (`setTokenLimitSchema`): `apiKeyId` اور `scopeType` (`model` | `provider` | `global`) لازمی ہیں۔ `scopeValue` لازمی ہے، سوائے اس صورت کے جب `scopeType` کی قدر `global` ہو (مثلاً `model` اسکوپ کے لیے ماڈل id، یا `provider` اسکوپ کے لیے پرووائیڈر id)۔ `tokenLimit` لازماً مثبت صحیح عدد ہونا چاہیے (اسٹرنگ سے تبدیل کیا جاتا ہے)۔ اختیاری: `id` (بنانے کے لیے شامل نہ کریں، اپ ڈیٹ کرنے کے لیے فراہم کریں)، `resetInterval` (`daily` | `weekly` | `monthly`، ڈیفالٹ `monthly`)، `resetTime` (`HH:MM`)، `enabled` (ڈیفالٹ `true`)۔ `GET` جوابات ہر حد میں `tokensUsed`، `remaining`، `windowStart`، `periodStartAt`، اور `nextResetAt` شامل کرتے ہیں۔ یہ انتظامی درجے کا endpoint ہے (توثیق مرکزی طور پر authz پائپ لائن کے ذریعے نافذ کی جاتی ہے)۔ ## درخواست کی پراسیسنگ 1. کلائنٹ `/v1/*` کو درخواست بھیجتا ہے 2. روٹ ہینڈلر `handleChat`، `handleEmbedding`، `handleAudioTranscription`، یا `handleImageGeneration` کو کال کرتا ہے 3. ماڈل متعین کیا جاتا ہے (براہِ راست provider/model یا alias/combo) 4. اکاؤنٹ کی دستیابی کی فلٹرنگ کے ساتھ مقامی DB سے اسناد منتخب کی جاتی ہیں 5. چیٹ کے لیے: `handleChatCore` semantic/signature کیش کی جانچ کرتا ہے اور combo کمپریشن کی ترتیبات متعین کرتا ہے 6. فعال ہونے کی صورت میں، provider ترجمے سے پہلے پیشگی کمپریشن چلتی ہے (`lite`، Caveman، RTK، یا stacked) 7. Provider executor upstream درخواست بھیجتا ہے 8. جواب کو واپس کلائنٹ فارمیٹ میں ترجمہ کیا جاتا ہے (چیٹ)، یا جوں کا توں واپس کیا جاتا ہے (embeddings/images/audio) 9. استعمال، کمپریشن analytics، اور درخواست کے لاگز ریکارڈ کیے جاتے ہیں 10. خرابیوں کی صورت میں combo قواعد کے مطابق fallback لاگو ہوتا ہے مکمل آرکیٹیکچر کا حوالہ: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md) --- ## Combo کا انتظام اعلیٰ سطح کے routing combos (جن کا خلاصہ پہلے ہی `/api/combos*` کے تحت دیا گیا ہے) کو ماڈل id پیٹرن سے 1:1 بھی میپ کیا جا سکتا ہے، جس سے OpenAI طرز کی ماڈل id کو شفاف طور پر کسی combo کی جانب ری ڈائریکٹ کیا جا سکتا ہے۔ | طریقہ | راستہ | وضاحت | | ------ | -------------------------------- | ---------------------------------------------------------------------------- | | GET | `/api/model-combo-mappings` | تمام model→combo میپنگز کی فہرست دکھائیں | | 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` | ویب ہُک 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 ٹوکن، یا `manage`/`admin` اسکوپ والی API کلید؛ صرف استنتاج کے لیے API کلیدوں کو `403` ملتا ہے۔ `/v1/quotas/check` اور `/v1/issues/report` بھی دیکھیں۔ --- ## ایجنٹس پروٹوکول OmniRoute صارفین کی جانب سے ریموٹ طور پر انجام دیے جانے والے کلاؤڈ ایجنٹ ٹاسکس (Claude Code، Codex Cloud، OpenHands، وغیرہ)۔ | طریقہ | راستہ | تفصیل | | ------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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]` | id کے ذریعے ایک مخصوص ٹاسک حذف کریں | > **توثیق:** ہر طریقے پر مینجمنٹ توثیق درکار ہے (`requireCloudAgentManagementAuth`)۔ v3.8.0 سے پہلے یہ غیر توثیق شدہ تھے — اس بریکنگ تبدیلی کے لیے commit `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` روٹس کے ذریعے فراہم کیے جاتے ہیں — کوڈ بیس میں فی-id ذیلی روٹس موجود نہیں ہیں۔ --- ## لچک پذیری (توسیعی) OmniRoute عارضی ناکامی سے نمٹنے کے تین آزاد طریقۂ کار فراہم کرتا ہے؛ ذیل میں دیے گئے انتظامی endpoints آپریٹرز کو ان کی حالت پڑھنے اور انہیں override کرنے کی سہولت دیتے ہیں: | دائرہ | حالت کا ذخیرہ | پڑھنا | ری سیٹ / صاف کرنا | | ------------------- | ------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------- | | فراہم کنندہ breaker | `domain_circuit_breakers` + in-memory | `/api/monitoring/health` | `POST /api/resilience/reset` | | کنکشن cooldown | فراہم کنندہ کے کنکشنز پر `rateLimitedUntil` | `/api/rate-limits`, `/api/providers/[id]` | (ضرورت پڑنے پر دوبارہ فعال ہوتا ہے؛ فراہم کنندہ کے PUT کے ذریعے صاف کریں) | | ماڈل lockout | in-memory ماڈل دستیابی رجسٹری | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` | `PATCH /api/resilience`، `providerBreaker.oauth` اور `providerBreaker.apikey` کے تحت فراہم کنندہ breaker overrides قبول کرتا ہے۔ ہر پروفائل `degradationThreshold`، `failureThreshold`، اور `resetTimeoutMs` کی معاونت کرتا ہے؛ یہی فیلڈز Dashboard → Settings → Resilience میں بھی دستیاب ہیں۔ ```bash # کسی ایک ماڈل کا lockout صاف کریں 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"}' # تمام lockouts صاف کریں curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \ -H "Cookie: auth_token=..." \ -d '{"all":true}' ``` مکمل تصوراتی حوالہ اور breaker کی طے شدہ اقدار کے لیے: [`CLAUDE.md`](../../CLAUDE.md) → "لچک پذیری کی runtime حالت" دیکھیں۔ --- ## مہارتیں OmniRoute کو حسبِ ضرورت قابلِ عمل handlers کے ذریعے وسعت دینے کے لیے مہارتوں کا فریم ورک، نیز marketplace integrations۔ | طریقہ | راستہ | تفصیل | | ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/skills` | نصب شدہ مہارتوں کی فہرست — `?q=`، `?mode=on\|off\|auto`، `?source=skillsmp\|skillssh\|local` کے ذریعے قابلِ فلٹر، اور صفحات میں منقسم | | GET | `/api/skills/[id]` | ایک مہارت حاصل کریں | | PUT | `/api/skills/[id]` | مہارت اپ ڈیٹ کریں (نام، تفصیل، mode، schema، handler، tags) | | DELETE | `/api/skills/[id]` | ایک مہارت اَن انسٹال کریں | | POST | `/api/skills/install` | raw manifest سے مہارت نصب کریں — body: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` | | GET | `/api/skills/executions` | حالیہ مہارت executions کی فہرست (inputs/outputs/duration کے ساتھ audit trail) | | GET | `/api/skills/marketplace?q=...` | SkillsMP marketplace سے تلاش/مقبول فہرست (`skillsmpApiKey` setting درکار ہے) | | POST | `/api/skills/marketplace/install` | SkillsMP سے id کے ذریعے مہارت نصب کریں | | GET | `/api/skills/skillssh?q=&limit=` | skills.sh رجسٹری میں تلاش کریں | | POST | `/api/skills/skillssh/install` | skills.sh سے id کے ذریعے مہارت نصب کریں | **توثیق:** انتظامی session/API key۔ Marketplace تلاش کے routes انتظامی توثیق یا Bearer API key (`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` | میموری ذیلی نظام کی صحت (DB کنیکٹیویٹی، embeddings بیک اینڈ، vector index کی حالت) | **توثیق:** مینجمنٹ سیشن/API کلید (`requireManagementAuth`)۔ `type` enum: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (`src/lib/memory/types.ts` میں `MemoryType` دیکھیں)۔ --- ## MCP سرور OmniRoute ایک ایمبیڈڈ Model Context Protocol سرور کے ساتھ فراہم ہوتا ہے، جس میں 3 ٹرانسپورٹس (stdio، SSE، streamable-http) اور محدود دائرۂ کار والے ٹولز شامل ہیں۔ ذیل کے ڈیش بورڈ اینڈ پوائنٹس اسٹیٹس/آڈٹ ڈیٹا پڑھتے ہیں اور HTTP ٹرانسپورٹس کو پراکسی کرتے ہیں۔ | طریقہ | راستہ | وضاحت | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- | | GET | `/api/mcp/status` | ہارٹ بیٹ، ٹرانسپورٹ، آن لائن حالت، آخری کال، سرفہرست ٹولز، 24 گھنٹوں کی کامیابی کی شرح | | GET | `/api/mcp/tools` | `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` کے ساتھ MCP ٹولز کی فہرست | | GET | `/api/mcp/sse` | SSE ٹرانسپورٹ کے لیے کھلی SSE اسٹریم (اگر MCP غیر فعال ہو یا ٹرانسپورٹ مماثل نہ ہو تو `503` لوٹاتا ہے) | | POST | `/api/mcp/sse` | SSE ٹرانسپورٹ پر JSON-RPC فریم بھیجیں | | GET | `/api/mcp/stream` | Streamable HTTP ٹرانسپورٹ کا SSE رخ کھولیں (سرور کی جانب سے شروع کیے گئے پیغامات) | | POST | `/api/mcp/stream` | Streamable HTTP ٹرانسپورٹ پر JSON-RPC فریم بھیجیں | | 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 کے مخصوص توثیقی انٹرفیس کی پابندی کرتے ہیں (`mcp` اسکوپ والی Bearer API کلید)؛ `status`/`tools`/`audit*` روٹس ڈیش بورڈ سے قابلِ مطالعہ ہیں (ڈیش بورڈ ہوسٹ تک رسائی کے علاوہ کسی اضافی توثیق کی ضرورت نہیں)۔ > دونوں HTTP ٹرانسپورٹس `settings.mcpEnabled` اور `settings.mcpTransport` کے ذریعے محدود ہیں — ٹرانسپورٹ کی عدم مماثلت `400` لوٹاتی ہے، جبکہ MCP کی غیر فعال حالت `503` لوٹاتی ہے۔ --- ## A2A سرور OmniRoute معائنے/ڈیش بورڈ کے استعمال کے لیے REST ریپر کے ساتھ ایک A2A (Agent-to-Agent) JSON-RPC 2.0 اینڈ پوائنٹ فراہم کرتا ہے۔ ### 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": "اس کوڈنگ کام کو روٹ کریں"}] } } ``` معاونت یافتہ میتھڈز (سبھی `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` استعمال کرتا ہے۔ --- ## کلاؤڈ، Evals اور Assess | طریقہ | راستہ | تفصیل | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | POST | `/api/cloud/auth` | بیئرر کلید کی توثیق کریں اور کلاؤڈ سنک کلائنٹس کے لیے مخفی فراہم کنندہ کنکشنز + ماڈل عرف واپس کریں | | POST | `/api/cloud/credentials/update` | کلاؤڈ سے ہم وقت فراہم کنندہ کی خفیہ کردہ اسناد اپ ڈیٹ کریں | | POST | `/api/cloud/model/resolve` | مقامی روٹنگ ٹیبل استعمال کرتے ہوئے ایک منطقی ماڈل id کو کسی ٹھوس فراہم کنندہ/ماڈل سے حل کریں | | GET | `/api/cloud/models/alias` | کلاؤڈ سنک کے لیے ظاہر کیے گئے ماڈل عرف کی فہرست دکھائیں | | GET | `/api/assess` | تازہ ترین اسیسمنٹ زمرہ بندیاں پڑھیں (فی فراہم کنندہ/ماڈل) | | POST | `/api/assess` | ایک اسیسمنٹ چلائیں — باڈی: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` | | GET | `/api/evals` | بلٹ اِن eval سویٹس + تازہ ترین رنز کی فہرست دکھائیں | | POST | `/api/evals` | ایک eval رن شروع کریں | | POST | `/api/evals/suites` | ایک حسبِ ضرورت eval سویٹ بنائیں — باڈی کی توثیق `evalSuiteSaveSchema` کے ذریعے کی جاتی ہے | | GET | `/api/evals/suites/[id]` | ایک حسبِ ضرورت eval سویٹ بازیافت کریں | **توثیق:** `/api/cloud/auth` براہِ راست بیئرر کلید کی توثیق کرتا ہے اور صرف `manage` / `admin` اسکوپ والی کلید کے لیے ہر کنکشن کی مخفی کلید اور `projectId` واپس کرتا ہے؛ دیگر `/api/cloud/*`، `/api/evals/*`، اور `/api/assess` روٹس کے لیے مینجمنٹ سیشن/API کلید درکار ہوتی ہے۔ `/api/assess` POST ایک امتیازی-یونین اسکوپ اسکیما کے ساتھ `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` | وقت کی مدت کے مطابق اعداد و شمار (طے شدہ 24h) | **جواب کی مثال**: ```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` | Shannon entropy پر مبنی تنوع کی ٹریکنگ: پرووائیڈر کے پھیلاؤ کی پیمائش کرکے ناکامی کے واحد نقاط کو روکتی ہے | **جواب کی مثال**: ```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 ٹولز کا نظم OmniRoute کے ساتھ ضم ہونے والے CLI ٹولز (antigravity، commandCode، devin-cli وغیرہ) کا نظم کریں۔ مکمل فہرست کے لیے [فراہم کنندہ کا حوالہ](./PROVIDER_REFERENCE.md) دیکھیں۔ | طریقہ | پاتھ | وضاحت | | ----- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/cli-tools/all-statuses` | تمام CLI ٹولز کی حالت (انسٹال شدہ، ورژن، آخری بار دیکھے جانے کا وقت) | | GET | `/api/cli-tools/status` | ایک CLI ٹول کی حالت کی تفصیل (`?tool=` کوئری) | | POST | `/api/cli-tools/apply` | کسی ٹول کی تیار کردہ کنفیگریشن لکھیں (`dryRun` پیش منظر دکھاتا ہے؛ کنٹینرائزڈ ہونے پر `422` + `containerEphemeralTarget`؛ `migration` کسی پرانی Codex YAML کی نشاندہی کرتا ہے) | | GET | `/api/cli-tools/backups` | CLI ٹول کی کنفیگریشن کے بیک اپس کی فہرست | | POST | `/api/cli-tools/backups` | تمام CLI ٹول کنفیگریشنز کا بیک اپ بنائیں | | POST | `/api/cli-tools/backups` | بحال کریں: باڈی میں `{tool, backupId}` کے ساتھ یہی اینڈ پوائنٹ اس بیک اپ کو بحال کرتا ہے | | GET | `/api/cli-tools/antigravity-mitm` | Antigravity MITM پراکسی کی حالت ("antigravity-mitm" CLI ٹول) | | POST | `/api/cli-tools/antigravity-mitm/alias` | antigravity-mitm عرفیات کنفیگر کریں | **توثیق:** انتظامی سیشن درکار ہے۔ --- ## ایجنٹ اسکلز AI ایجنٹ اسکلز کا انتظام کریں (OpenAI کے کسٹم GPTs سے مماثل، لیکن ایجنٹس کے لیے)۔ | طریقہ | پاتھ | تفصیل | | ------ | ---------------------------- | ---------------------------------------------------------------------------------- | | GET | `/api/agent-skills` | تمام ایجنٹ اسکلز کی فہرست دکھائیں (بلٹ اِن + کسٹم) | | GET | `/api/agent-skills/[id]` | ایک مخصوص ایجنٹ اسکل حاصل کریں | | POST | `/api/agent-skills` | کسٹم ایجنٹ اسکل بنائیں — باڈی: `{name, description, prompt, model?, temperature?}` | | PUT | `/api/agent-skills/[id]` | کسٹم ایجنٹ اسکل اپ ڈیٹ کریں | | DELETE | `/api/agent-skills/[id]` | کسٹم ایجنٹ اسکل حذف کریں | | GET | `/api/agent-skills/[id]/raw` | خام پرامپٹ + میٹا ڈیٹا حاصل کریں (بغیر نفاذ کے) | | POST | `/api/agent-skills/generate` | قدرتی زبان کی وضاحت سے AI کے ذریعے نیا اسکل تیار کریں | **توثیق:** مینجمنٹ سیشن یا مینجمنٹ اسکوپ والی API کلید درکار ہے۔ --- ## کیش مینجمنٹ سیمینٹک کیش اور ریزننگ کیش کا نظم کریں۔ | طریقہ | پاتھ | وضاحت | | ------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------- | | GET | `/api/cache` | کیش کا جائزہ: کل اندراجات، ہِٹ ریٹ، ڈسک پر حجم | | GET | `/api/cache/entries` | کیش شدہ اندراجات کی فہرست (صفحہ بندی کے ساتھ) | | DELETE | `/api/cache/entries` | کیش اندراجات حذف کریں (کوئری پیرامیٹرز کے ذریعے فلٹر کریں) | | GET | `/api/cache/stats` | کیش کے تفصیلی اعداد و شمار (فی پرووائیڈر، فی ماڈل) | | GET | `/api/cache/reasoning` | ریزننگ کیش کی حالت (ریزننگ ری پلے کے لیے) | | DELETE | `/api/cache/reasoning` | ریزننگ کیش صاف کریں — کوئری پیرامیٹرز: `?toolCallId=` (واحد) یا `?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_…` رسائی ٹوکن، manage دائرۂ کار والی API کلید) اور یہ inference کلیدوں سے کیسے مختلف ہیں، جاننے کے لیے [انتظامی توثیق](../guides/MANAGEMENT-AUTH.md) دیکھیں۔ - ڈیش بورڈ روٹس (`/dashboard/*`) `auth_token` کوکی استعمال کرتے ہیں - لاگ اِن محفوظ کردہ پاس ورڈ ہیش استعمال کرتا ہے؛ بصورتِ دیگر `INITIAL_PASSWORD` استعمال ہوتا ہے - `requireLogin` کو `/api/settings/require-login` کے ذریعے فعال یا غیر فعال کیا جا سکتا ہے - `REQUIRE_API_KEY=true` ہونے پر `/v1/*` روٹس اختیاری طور پر Bearer API کلید کا تقاضا کرتے ہیں - اس حوالہ میں "انتظامی ٹوکن" / "انتظامی دائرۂ کار والی API کلید" سے مراد اس رہنما میں بیان کردہ اقسام میں سے ایک ہے — کوئی غیر معیّن اضافی خفیہ قسم نہیں > **اہم تبدیلی (v3.8.0)** — `/api/v1/agents/tasks/*` اور cooldown انتظامی endpoints کے لیے اب **انتظامی توثیق** (ڈیش بورڈ `auth_token` کوکی یا انتظامی دائرۂ کار والی API کلید) درکار ہے۔ وہ کلائنٹس جو پہلے ان روٹس کو بغیر توثیق کے کال کرتے تھے، اب `401 Unauthorized` وصول کریں گے۔ commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`) دیکھیں۔