# 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) · 🇨🇿 [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) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md) --- 🌐 **ভাষাসমূহ:** 🇺🇸 [English](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇨🇿 [Č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` সারফেস এবং সর্বাধিক ব্যবহৃত ব্যবস্থাপনা এন্ডপয়েন্টগুলো অন্তর্ভুক্ত রয়েছে; মেশিন-পাঠযোগ্য [`docs/openapi.yaml`](../openapi.yaml) এবং `src/app/api/`-এর অধীনে থাকা রুট ট্রি হলো পূর্ণাঙ্গ উৎস। --- ## সূচিপত্র - [চ্যাট কমপ্লিশন](#chat-completions) - [এক্সক্লুসিভ ম্যানেজড সেশন লিজ](#exclusive-managed-session-leases) - [এম্বেডিং](#embeddings) - [ছবি তৈরি](#image-generation) - [ডকুমেন্ট OCR](#document-ocr) - [মডেলের তালিকা](#list-models) - [প্রোভাইডার প্লাগইন ম্যানিফেস্ট](#provider-plugin-manifest) - [কম্প্যাটিবিলিটি এন্ডপয়েন্ট](#compatibility-endpoints) - [ফাইল API](#files-api) - [ব্যাচ API](#batches-api) - [সার্চ API](#search-api) - [WebSocket স্ট্রিমিং](#websocket-streaming) - [কোটা ও সমস্যা প্রতিবেদন](#quotas--issues-reporting) - [সেমান্টিক ক্যাশ](#semantic-cache) - [ড্যাশবোর্ড ও ব্যবস্থাপনা](#dashboard--management) - [কম্বো ব্যবস্থাপনা](#combo-management) - [ওয়েবহুক](#webhooks) - [নিবন্ধিত কী (স্বয়ংক্রিয় ব্যবস্থাপনা)](#registered-keys-auto-management) - [এজেন্ট প্রোটোকল](#agents-protocol) - [ম্যানেজমেন্ট প্রক্সি](#management-proxies) - [স্থিতিস্থাপকতা (বর্ধিত)](#resilience-extended) - [স্কিল](#skills) - [মেমোরি](#memory) - [MCP সার্ভার](#mcp-server) - [A2A সার্ভার](#a2a-server) - [ক্লাউড, ইভাল ও অ্যাসেস](#cloud-evals--assess) - [অনুরোধ প্রক্রিয়াকরণ](#request-processing) - [প্রমাণীকরণ](#authentication) --- ## চ্যাট কমপ্লিশন ```bash POST /v1/chat/completions Authorization: Bearer your-api-key Content-Type: application/json { "model": "cc/claude-opus-4-6", "messages": [ {"role": "user", "content": "Write a function to..."} ], "stream": true } ``` ### কাস্টম হেডার | হেডার | দিক | বিবরণ | | ------------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-OmniRoute-No-Cache` | অনুরোধ | ক্যাশ এড়িয়ে যেতে `true` হিসেবে সেট করুন | | `x-omniroute-no-memory` | অনুরোধ | এই অনুরোধের জন্য মেমোরি + স্কিল ইনজেকশন বাদ দিতে `true` হিসেবে সেট করুন (no-cache-এর অনুরূপ; প্রতিটি কলের টোকেন/খরচের অতিরিক্ত ব্যয় এড়ায়) | | `X-OmniRoute-Progress` | অনুরোধ | অগ্রগতি ইভেন্টের জন্য `true` হিসেবে সেট করুন | | `X-Session-Id` | অনুরোধ | বাহ্যিক সেশন অ্যাফিনিটির জন্য স্টিকি সেশন কী | | `x_session_id` | অনুরোধ | আন্ডারস্কোর ভ্যারিয়েন্টও গৃহীত হয় (সরাসরি HTTP) | | `X-OmniRoute-Session-Id` | অনুরোধ | কলকারী-সরবরাহকৃত সেশন/কথোপকথন ট্যাগ (মেমোরিতেও প্রদান করা হয়)। উপস্থিত থাকলে, প্রতি-সেশন খরচ আরোপের জন্য `call_logs.session_tag`-এ অবিকল সংরক্ষণ করা হয় (#8249) — অনুপস্থিত থাকলে কখনো তৈরি করা হয় না | | `Idempotency-Key` | অনুরোধ | ডিডুপ কী (৫ সেকেন্ডের উইন্ডো) | | `X-Request-Id` | অনুরোধ | বিকল্প ডিডুপ কী | | `X-OmniRoute-Cache` | প্রতিক্রিয়া | `HIT` অথবা `MISS` (নন-স্ট্রিমিং) | | `X-OmniRoute-Idempotent` | প্রতিক্রিয়া | ডিডুপ্লিকেট করা হলে `true` | | `X-OmniRoute-Progress` | প্রতিক্রিয়া | অগ্রগতি ট্র্যাকিং চালু থাকলে `enabled` | | `X-OmniRoute-Session-Id` | প্রতিক্রিয়া | OmniRoute দ্বারা ব্যবহৃত কার্যকর সেশন 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"} ``` সফল acquire, renew এবং release প্রতিক্রিয়াগুলো টাইমস্ট্যাম্প, `state` এবং সঠিক ধনাত্মক `generation` প্রকাশ করে, কিন্তু নির্বাচিত সংযোগ বা ক্রেডেনশিয়াল কখনোই প্রকাশ করে না। Renew এবং release-এর ক্ষেত্রে JSON বডিতে generation সরবরাহ করা হয়: ```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" } } ``` এই ঐচ্ছিক status অ্যাকশনটি একটি একক ডেটাবেস ট্রানজ্যাকশনের মধ্যে অস্বচ্ছ মালিক, প্রমাণীকৃত ম্যানেজড API কী এবং সঠিক সক্রিয় generation দ্বারা ফেন্স করা হয়। `displayName` কেবল ট্রিম করা কনফিগার্ড সংযোগের নাম; কোনো নিরাপদ কনফিগার্ড নাম না থাকলে এটি `null` হয়। OmniRoute কখনোই এর পরিবর্তে কোনো ইমেইল বা জেনারেট করা অ্যাকাউন্ট পরিচয় ব্যবহার করে না। provider মানটি একটি অসংবেদনশীল প্রদর্শন লেবেল এবং কখনোই জেনারেট করা সামঞ্জস্যপূর্ণ-প্রোভাইডার শনাক্তকারী নয়। ক্রেডেনশিয়াল, টোকেন, কুকি, কাঁচা সংযোগ বা API কী আইডি, মালিকের হ্যাশ, ফেন্সিং সিক্রেট এবং অভ্যন্তরীণ রাউটিং ডেটা বাদ দেওয়া হয়। ভুল-কী, ভুল-মালিক, পুরোনো-generation, অনুপস্থিত, মেয়াদোত্তীর্ণ, রিলিজ করা এবং অবৈধ করা লুকআপগুলো সংযোগ মেটাডেটা ছাড়াই একই `409 LEASE_FENCE_STALE` ত্রুটি ফেরত দেয়। capacity-wait প্রতিক্রিয়া পাওয়া কোনো ক্লায়েন্টের পরিদর্শন করার মতো সক্রিয় বাইন্ডিং থাকে না। রাউটিং যখন কোনো সক্রিয় লিজকে স্থানান্তর করে, তখন একই generation বৈধ থাকে এবং status পারমাণবিকভাবে নতুন বাইন্ডিং ফেরত দেয়, পুরোনোটি কখনোই নয়। বিদ্যমান ক্লায়েন্টগুলো অপরিবর্তিত থাকে, কারণ acquire, renew, release এবং waiting প্রতিক্রিয়াগুলো তাদের আগের আকৃতি বজায় রাখে। এই সার্ভার চুক্তি স্টক OpenAI Codex `/status` পরিবর্তন করে না। স্টক Codex বর্তমানে এর মডেল প্রোভাইডার এবং বিল্ট-ইন প্রমাণীকরণ/অ্যাকাউন্ট অবস্থা রিপোর্ট করে, কিন্তু ইচ্ছামতো কাস্টম প্রোভাইডার অ্যাকাউন্ট মেটাডেটা রেন্ডার করে না; ভবিষ্যতের কোনো ক্লায়েন্ট ইন্টিগ্রেশনকে এই অ্যাকশন কল করতে হবে এবং `connection.displayName` কীভাবে প্রদর্শন করা হবে তা নির্ধারণ করতে হবে। এরপর প্রতিটি ম্যানেজড ইনফারেন্স অনুরোধ উভয় কন্ট্রোল হেডার সরবরাহ করে: ```http X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> X-OmniRoute-Lease-Generation: 1 ``` প্রতিটি সমর্থিত আপস্ট্রিম প্রচেষ্টার ঠিক আগে সঠিক মালিক, generation, সক্রিয় সংযোগ এবং প্রমাণীকৃত API কী ফেন্স করা হয়। অন্য কোনো কী দিয়ে মালিক ও generation পুনরায় ব্যবহার করলে সেটি ব্যর্থ হয়, এমনকি সেই কী একই সংযোগ অনুমোদন করলেও। কাঁচা মালিকের মান সংরক্ষণ, লগ বা অনুরোধের স্ন্যাপশটে ধরে রাখা হয় না এবং আপস্ট্রিমেও ফরোয়ার্ড করা হয় না। সাময়িক প্রতিযোগিতার ক্ষেত্রে 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` প্রতি-অনুরোধ ভিত্তিতে কম্প্রেশন প্ল্যান ওভাররাইড। এর অগ্রাধিকার সর্বোচ্চ — এটি routing-combo ওভাররাইড, সক্রিয় প্রোফাইল, auto-trigger এবং প্যানেলের Default-কে অগ্রাহ্য করে। মানসমূহ: | মান | প্রভাব | | ------------- | ------------------------------------------------------------------------------------------- | | `off` | এই অনুরোধের জন্য কোনো কম্প্রেশন নয়। | | `default` | প্যানেল থেকে প্রাপ্ত Default প্রোফাইল (সক্রিয় প্রোফাইল উপেক্ষা করে)। | | `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। ক্যাটালগ আইডিগুলো হলো `provider/model` (উদাহরণ: `jina-ai/jina-embeddings-v5-omni-small`)। রেজিস্ট্রিতে থাকা শুধু Jina মডেল আইডিগুলোও (যেমন `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 ওই অবজেক্টগুলোকে স্ট্রিংয়ে রূপান্তর করে না বা নেটিভ ইমেজ URL ফেচ করে না — Jina নিজেই পাবলিক মিডিয়া নিয়ে আসে। অতিরিক্ত Jina ফিল্ড (`task`, `normalized`, `truncate`, `embedding_type`) ফরওয়ার্ড করা হয়। শুধু টেক্সট-ভিত্তিক Jina SKU এখনো নন-টেক্সট ডক প্রত্যাখ্যান করে। নিরাপত্তা ও ট্রান্সপোর্টের সীমা: - রিমোট মিডিয়া URL অবশ্যই পাবলিক HTTPS হতে হবে। ক্যানোনিক্যাল `{type,source:url}` আইটেমগুলো সার্ভার-সাইডে ফেচ করা হয় (রিডাইরেক্ট পুনরায় যাচাইকরণ, টাইমআউট, আকারের সীমা, পাবলিক DNS, সংযোগ পিনিং) এবং প্রোভাইডার কলের আগে ইনলাইন করা হয়। Jina-নেটিভ `{image:"https://..."}` আইটেমগুলো একই পাবলিক-HTTPS যাচাইয়ের পর অপরিবর্তিত অবস্থায় ফরওয়ার্ড করা হয়; Jina URL-টি ফেচ করে। - ইনলাইন base64 মিডিয়ার সীমা প্রতিটি আইটেমে ডিকোড করা অবস্থায় 8 MiB এবং সম্পূর্ণ রিকোয়েস্টজুড়ে ডিকোড করা অবস্থায় 16 MiB। প্রোভাইডার অনুবাদ (ক্যানোনিক্যাল আইটেম কখনোই অপরিবর্তিত অবস্থায় ফরওয়ার্ড করা হয় না): - Jina মাল্টিমোডাল মডেল: প্রতিটি টপ-লেভেল আইটেম একটি মোডালিটি-কীযুক্ত অবজেক্টে পরিণত হয় (`text` / `image` / `audio` / `video` / `pdf`), যেখানে ইনলাইন মিডিয়ার জন্য data URI ব্যবহৃত হয়; প্রতিটি টপ-লেভেল আইটেমের জন্য একটি ভেক্টর। - Gemini Embedding 2 ফ্যামিলি: একটি টপ-লেভেল অ্যারে `content.parts` (`text` অথবা `inline_data`) সহ একটি একক নেটিভ `models/{model}:embedContent` রিকোয়েস্টে পরিণত হয়। - সুস্পষ্ট মোডালিটি মেটাডেটা ছাড়া অজানা/ডায়নামিক মডেলগুলো HTTP 400 দিয়ে স্ট্রাকচার্ড ইনপুট প্রত্যাখ্যান করে। ```json { "model": "jina-ai/jina-embeddings-v5-omni-small", "input": [ { "type": "text", "text": "A red bicycle" }, { "type": "image", "source": { "type": "url", "url": "https://example.com/bicycle.png" } } ], "dimensions": 512, "encoding_format": "float" } ``` অসমর্থিত মডেল/মোডালিটি সমন্বয় আইটেমটিকে কোয়ার্স করার পরিবর্তে HTTP 400 ফেরত দেয়। লিগ্যাসি স্ট্রিং/টোকেন রিকোয়েস্টের নন-ইনপুট এক্সটেনশন ফিল্ডগুলো আগের মতোই অপরিবর্তিত অবস্থায় পাস-থ্রু হয়। ```bash # সব এমবেডিং মডেলের তালিকা দেখান GET /v1/embeddings ``` --- ## ছবি তৈরি ```bash POST /v1/images/generations Authorization: Bearer your-api-key Content-Type: application/json { "model": "openai/gpt-image-2", "prompt": "A beautiful sunset over mountains", "size": "1024x1024" } ``` উপলভ্য প্রোভাইডারসমূহ: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (লোকাল), ComfyUI (লোকাল)। ```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`) | সিঙ্ক্রোনাস — একক আপস্ট্রিম কল থেকে রেসপন্স সরাসরি ফেরত দেওয়া হয়। | | `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | অ্যাসিঙ্ক্রোনাস আপস্ট্রিম (`analyze` + পোল) — নিচে দেখুন। | | `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Vertex AI-এর `openapi/chat/completions` পার্টনার এন্ডপয়েন্টের মাধ্যমে সিঙ্ক্রোনাস — প্রমাণীকরণ/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 পোল করে, কোনো non-`ok` পোল রেসপন্স বা `"failed"` স্ট্যাটাস পেলে তাৎক্ষণিকভাবে ব্যর্থ হয় (পোলিং চালিয়ে যায় না), এবং প্রচেষ্টার সীমা শেষ হওয়ার পরও অপারেশন চলতে থাকলে `504` ফেরত দেয়। কলারের কাছে ফেরত দেওয়ার আগে চূড়ান্ত Azure রেসপন্সকে Mistral-এ ব্যবহৃত একই `pages`/`markdown` আকৃতিতে স্বাভাবিকীকরণ করা হয়, ফলে ক্লায়েন্ট কোডে প্রোভাইডারভেদে বিশেষ ব্যবস্থা নেওয়ার প্রয়োজন হয় না। ### Vertex AI DeepSeek OCR প্রমাণীকরণ ও এন্ডপয়েন্ট রিজল্যুশন `vertex-deepseek-ocr` চ্যাট/ইমেজ ট্রাফিকের জন্য OmniRoute ইতিমধ্যেই সমর্থন করে এমন একই Vertex AI প্রমাণীকরণ পুনরায় ব্যবহার করে (`open-sse/executors/vertex.ts`): কানেকশনের API key হয় একটি Service Account JSON ক্রেডেনশিয়াল (JWT-bearer প্রবাহের মাধ্যমে স্বল্পমেয়াদি OAuth access token-এর বিনিময়ে ব্যবহৃত), অথবা আগে থেকেই তৈরি করা একটি OAuth access token, যা অপরিবর্তিত অবস্থায় ব্যবহৃত হয়। আপস্ট্রিম এন্ডপয়েন্ট URL হলো Vertex-এর জেনেরিক `openapi/chat/completions` পার্টনার এন্ডপয়েন্ট, যা কানেকশনের project ও region থেকে তৈরি করা হয় — স্পষ্টভাবে দেওয়া `providerSpecificData.project`/ `providerSpecificData.region` সর্বদা অগ্রাধিকার পায়; অন্যথায় project-টি Service Account JSON-এর `project_id` থেকে নির্ধারিত হয় এবং region ডিফল্ট হিসেবে `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 ফরম্যাটে সব চ্যাট, এম্বেডিং ও ইমেজ মডেল + কম্বো প্রদান করে ``` ### মডেল আইডি প্রিফিক্স (`?prefix=`) বেশিরভাগ মডেল একটি **প্রোভাইডার প্রিফিক্সের** অধীনে প্রদর্শিত হয়। আপনি কোন প্রিফিক্স পাবেন তা `MODELS_CATALOG_PREFIX_MODE` ফিচার ফ্ল্যাগ দ্বারা নিয়ন্ত্রিত হয় এবং একটি কোয়েরি প্যারামিটারের মাধ্যমে **প্রতিটি অনুরোধের জন্য** ওভাররাইড করা যায় — এটি এমন ক্লায়েন্টের জন্য উপযোগী, যে অন্য সবার জন্য সার্ভারব্যাপী সেটিং পরিবর্তন না করেই একটি পরিচ্ছন্ন তালিকা চায়: ```bash GET /v1/models?prefix=alias # প্রতি মডেলে একটি আইডি — সংক্ষিপ্ত অ্যালিয়াস প্রিফিক্স GET /v1/models?prefix=dual # উভয় রূপ (সার্ভারের ডিফল্ট) GET /v1/models?prefix=canonical # কেবল সম্পূর্ণ প্রোভাইডার-আইডি প্রিফিক্স ``` | মোড | যা প্রদান করে | নোট | | ----------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dual` | `cc/claude-sonnet-4-6` **এবং** `claude/claude-sonnet-4-6` | **ডিফল্ট।** উভয় আইডি একই মডেলে রাউট করে; যেসব ক্লায়েন্ট কনফিগে যেকোনো একটি রূপ হার্ডকোড করা আছে, সেগুলো যেন কাজ করতে থাকে তাই এটি রাখা হয়েছে। এতে ক্যাটালগের আকার প্রায় দ্বিগুণ হয়। | | `alias` | `cc/claude-sonnet-4-6` | প্রতি মডেলে একটি এন্ট্রি। স্বতন্ত্র অ্যালিয়াসবিহীন প্রোভাইডারগুলোও তাদের এন্ট্রি প্রদান করে, তাই কিছুই হারায় না। | | `canonical` | `claude/claude-sonnet-4-6` | সম্পূর্ণ প্রোভাইডার-আইডি প্রিফিক্সের অধীনে প্রতি মডেলে একটি এন্ট্রি। স্বতন্ত্র অ্যালিয়াসবিহীন প্রোভাইডারগুলোও (যেমন `antigravity/…`, `agy/…`) এখানে তাদের একক আইডি প্রদান করে, তাই কিছুই হারায় না। | কোয়েরি প্যারামিটার ছাড়াও একটি `dual`-মোড মিরর শনাক্ত করা যায়: এতে প্রাথমিক আইডির দিকে নির্দেশকারী একটি `parent` ফিল্ড থাকে। যেসব ক্লায়েন্ট মডেল পিকার রেন্ডার করে, তাদের `?prefix=alias` অনুরোধ করা উচিত — [OmniCopilot VS Code extension](../guides/VSCODE-COPILOT.md) এটিই করে। ### নো-থিংকিং মডেল ভ্যারিয়েন্ট থিংকিং-সক্ষম Claude মডেলগুলোর জন্য, `/v1/models` এমন একটি **নো-থিংকিং** ভ্যারিয়েন্টও প্রদর্শন করে যার আইডির শুরুতে `claude-3-omniroute-no-thinking/` থাকে: ``` claude-3-omniroute-no-thinking// ``` এই আইডি নির্বাচন করলে (যেমন এমন একটি Claude Code কনফিগে, যা সবসময় একটি `thinking` ব্লক যুক্ত করে) রিজনিং দমন করে প্রকৃত `/`-এ ফিরে রিজলভ হয় — `/v1/messages` পাথে `thinking:{type:"disabled"}`, অথবা `/v1/chat/completions` পাথে `reasoning`/`reasoning_effort` ফিল্ডগুলো বাদ দেওয়া হয়। ভ্যারিয়েন্টটি কেবল সেই Claude-ফ্যামিলির মডেলগুলোর জন্য তালিকাভুক্ত হয়, যেগুলো থিংকিং সমর্থন করে **এবং** `disabled` মান্য করে (তাই, যেমন কেবল অ্যাডাপ্টিভ মডেল, যেগুলো `disabled` প্রত্যাখ্যান করে, সেগুলো বাদ পড়ে)। অপারেটররা `ModelSpec.noThinkingAlias`-এর মাধ্যমে প্রতিটি মডেলের জন্য ভ্যারিয়েন্টটি জোরপূর্বক চালু বা বন্ধ করতে পারেন। --- ## প্রোভাইডার প্লাগইন ম্যানিফেস্ট ```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 (সম্পাদনা/ইনপেইন্ট) | | 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 URL-এর মধ্যেও API কী গ্রহণ করে—হয় কোয়েরি-স্ট্রিং সামঞ্জস্যের মাধ্যমে (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`), অথবা নিচে নথিভুক্ত নির্দিষ্ট `/api/v1/vscode/{token}/...` এন্ডপয়েন্টগুলোর মাধ্যমে। ```bash # রির্যাঙ্ক POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] } # Jina ক্লাসিফাই (Foundation API ক্রেডেনশিয়াল) POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] } # Jina সেগমেন্টার POST /v1/segment { "content": "...", "return_chunks": true } # Jina সার্চ (s.jina.ai; প্রোভাইডার অ্যালিয়াস: jina-search, jina-ai, jina) POST /v1/search { "query": "...", "provider": "jina-search" } # মডারেশন POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." } # TTS — audio/mpeg (অথবা অনুরোধ করা ফরম্যাটের) বডি ফেরত দেয় POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" } # ছবি সম্পাদনা (multipart) POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png # ভিডিও / মিউজিক জেনারেশন (প্রোভাইডার-প্রিফিক্সযুক্ত মডেল আইডি) POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." } POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." } ``` ### নির্দিষ্ট প্রোভাইডার রুটসমূহ ```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` | একটি ফাইল আপলোড করুন (multipart: `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` | অপরিবর্তিত ফাইল বডি স্ট্রিম করে ফেরত পান | **প্রমাণীকরণ:** Bearer API কী — `getApiKeyRequestScope`-এর মাধ্যমে ফাইলগুলো প্রতিটি API কী অনুযায়ী সীমাবদ্ধ থাকে। একটি কী শুধু তার নিজস্ব ফাইল দেখতে, ডাউনলোড করতে এবং মুছতে পারে; কী ছাড়া একটি ড্যাশবোর্ড সেশন সম্পূর্ণ ইনস্ট্যান্স পড়তে পারে; মালিকবিহীন কোনো ফাইলের (বেনামী বা ড্যাশবোর্ড-সেশন আপলোড) অ্যাক্সেস প্রতিটি নন-সেশন কলারের জন্য প্রত্যাখ্যাত হয়। `GET /v1/files` কোনো বেনামী কলারকে — এবং এমন কোনো প্রদত্ত কী-কে যা সমাধান করা যায় না — `REQUIRE_API_KEY=false` হলেও `401` দিয়ে প্রত্যাখ্যান করে, যাতে প্রতিটি টেন্যান্টের ফাইল তালিকাভুক্ত না হয় (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523)। --- ## Batches API OpenAI-সামঞ্জস্যপূর্ণ ব্যাচ প্রক্রিয়াকরণ। | পদ্ধতি | পাথ | বিবরণ | | ------ | ------------------------- | -------------------------------------------------------------------------------------------------------------- | | POST | `/v1/batches` | ব্যাচ তৈরি করুন — বডি `v1BatchCreateSchema` দ্বারা যাচাইকৃত (`input_file_id`, `endpoint`, `completion_window`) | | GET | `/v1/batches` | ব্যাচগুলোর তালিকা দেখুন | | GET | `/v1/batches/[id]` | ব্যাচের স্ট্যাটাস + `request_counts` পুনরুদ্ধার করুন | | DELETE | `/v1/batches/[id]` | সমাপ্ত/ব্যর্থ ব্যাচ মুছুন | | POST | `/v1/batches/[id]/cancel` | চলমান ব্যাচ বাতিল করুন | **প্রমাণীকরণ:** Bearer API কী। ফাইলগুলোর মতো একই ত্রিমুখী নিয়মে ব্যাচগুলো প্রতিটি API কী অনুযায়ী সীমাবদ্ধ থাকে: শুধু নিজস্ব কী, ড্যাশবোর্ড সেশনের জন্য ইনস্ট্যান্স-ব্যাপী অ্যাক্সেস, এবং প্রতিটি নন-সেশন কলারের জন্য null-owner রেকর্ড প্রত্যাখ্যাত (পুনরুদ্ধার, মুছে ফেলা, বাতিল করা এবং তৈরির সময় `input_file_id` যাচাই)। `REQUIRE_API_KEY=false` হলেও `GET /v1/batches` কোনো বেনামী কলারকে `401` দিয়ে প্রত্যাখ্যান করে। --- ## Search API ওয়েব/সার্চ প্রদানকারীর বিমূর্তন (Tavily, Brave, Exa, Serper ইত্যাদি)। | পদ্ধতি | পাথ | বিবরণ | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------------- | | GET | `/v1/search` | কনফিগার করা সার্চ প্রদানকারী ও তাদের সক্ষমতার তালিকা দেখায় | | POST | `/v1/search` | একটি সার্চ কোয়েরি চালায় — বডি `v1SearchSchema` দ্বারা যাচাই করা হয় এবং ক্যাশিং/কোয়ালেসিং সমর্থন করে | | GET | `/v1/search/analytics` | প্রদানকারীভিত্তিক হিট/ল্যাটেন্সি/ক্যাশ পরিসংখ্যান | **প্রমাণীকরণ:** Bearer API কী (`extractApiKey` + `isValidApiKey`)। সার্চ নীতি `enforceApiKeyPolicy`-এর মাধ্যমে প্রয়োগ করা হয়। --- ## Web Fetch 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`) নির্দিষ্ট অগ্রাধিকারক্রমে (fill-first) ব্যবহার করা হয় — রেট-লিমিটেড কিন্তু কনফিগার করা প্রদানকারী অনুরোধটি সঙ্গে সঙ্গে শেষ করার পরিবর্তে এড়িয়ে যাওয়া হয় এবং পুনরায় চেষ্টা করা যায় এমন/কোটাজনিত আপস্ট্রিম ব্যর্থতা (HTTP 429 সর্বদা; Firecrawl/Tavily/TinyFish-এর কোটা-ধাঁচের ফ্রি টিয়ারের জন্য 402/403 — Jina Reader-এর জন্য নয় এবং সাধারণ 400 bad request-এর জন্য কখনোই নয়) অনুরোধের সময় পরবর্তী এখনও চেষ্টা না-করা ও ক্রেডেনশিয়ালযুক্ত প্রদানকারীতে চলে যায়। পুলের প্রতিটি প্রদানকারী নিঃশেষ হয়ে গেলে, এন্ডপয়েন্টটি আগের সাধারণ `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` থাকলে ডিফল্টরূপে এটিই সক্রিয় থাকে)। #### মডেল আইডি: সরাসরি ChatGPT আইডি ব্যবহার করুন (`codex/` প্রিফিক্স ছাড়া) OpenAI **Codex CLI** ক্লায়েন্ট-সাইডে মডেলের নাম যাচাই করে যখন `supports_websockets = true` থাকে এবং `codex/gpt-5.5`-এর মতো **প্রদানকারী-প্রিফিক্সযুক্ত আইডি প্রত্যাখ্যান করে** (`The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account`)। **সরাসরি** আইডি পাঠান (যেমন `gpt-5.5`)। OmniRoute-এর ব্রিজটি শুধু codex-এর জন্য, তাই আপস্ট্রিমে টানেল করার আগে এটি একটি সরাসরি আইডিকে codex মডেল হিসেবে (`resolveCodexWsModelInfo`) পুনরায় রিজলভ করে — যদিও সরাসরি `gpt-5.5` অন্যথায় HTTP-এর মাধ্যমে অন্য প্রদানকারীতে রাউট হতো। #### OpenAI Codex CLI কনফিগার করা `~/.codex/config.toml`-এ WebSocket সমর্থনসহ একটি কাস্টম প্রদানকারী যোগ করে Codex CLI-কে OmniRoute-এর দিকে নির্দেশ করুন (বিদ্যমান কনফিগে পরিবর্তন এড়াতে একটি আলাদা `CODEX_HOME` ব্যবহার করুন): ```toml model = "gpt-5.5" # সরাসরি আইডি — "codex/gpt-5.5" নয় model_provider = "omniroute" [model_providers.omniroute] name = "OmniRoute (WS)" base_url = "http://localhost:20128/v1" # শেষে স্ল্যাশ নয়; WS URL ডেরাইভ করা হয় (প্রোডাকশনে https/wss ব্যবহার করুন) wire_api = "responses" # Feb 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-কী ম্যানেজার প্রতিটি কীর জন্য এটি টগল করে)। এটি ছাড়া এন্ডপয়েন্টটি `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`-এর সুরক্ষার অধীনেই থাকে। --- ## সেম্যান্টিক ক্যাশ ```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 **কোনো আপস্ট্রিম কল ছাড়াই** ক্যাশ থেকে প্রতিক্রিয়া পরিবেশন করে, তাই রিপোর্ট করা `X-OmniRoute-Response-Latency` প্রায় শূন্য (মূল আপস্ট্রিম ল্যাটেন্সি নির্বিশেষে)। ল্যাটেন্সি-সংবেদনশীল ক্লায়েন্টগুলোর (বেঞ্চমার্কিং, p50/p99 পর্যবেক্ষণ) `X-OmniRoute-Cache-Latency` প্রতিক্রিয়া হেডারটি পরীক্ষা করা উচিত: | মান | অর্থ | | ------------- | ----------------------------------------------------------------------------- | | `synthetic` | প্রতিক্রিয়া ক্যাশ থেকে পরিবেশিত হয়েছে; ল্যাটেন্সি প্রকৃত আপস্ট্রিম সময় নয় | | _(অনুপস্থিত)_ | প্রকৃত আপস্ট্রিম কল থেকে পাওয়া প্রতিক্রিয়া | ### প্রতি-কী ক্যাশ বাইপাস API কীগুলো `cacheDefaultMode`-এর মাধ্যমে সেম্যান্টিক ক্যাশ রিড এড়িয়ে যেতে পারে: | মান | আচরণ | | -------- | -------------------------------------------------------------------- | | `legacy` | স্বাভাবিক ক্যাশ আচরণ (ডিফল্ট) | | `bypass` | ক্যাশ লুকআপ সম্পূর্ণভাবে এড়িয়ে যান; সবসময় আপস্ট্রিমে অনুরোধ পাঠান | কী তৈরির সময় (`POST /api/keys`) সেট করুন অথবা আপডেট করুন (`PATCH /api/keys/[id]`): ```json { "cacheDefaultMode": "bypass" } ``` ### প্রতি-অনুরোধ বাইপাস কী সেটিংস নির্বিশেষে যেকোনো অনুরোধ ক্যাশ বাইপাস করতে পারে: ``` X-OmniRoute-No-Cache: true ``` --- ## ড্যাশবোর্ড ও ব্যবস্থাপনা ম্যানেজমেন্ট রুটগুলো (`/api/*`, পাবলিক auth/login ব্যতীত) সাধারণ inference API key দ্বারা **অনুমোদিত নয়**। ক্রেডেনশিয়াল পরিবার, scope এবং curl উদাহরণ: [ম্যানেজমেন্ট প্রমাণীকরণ](../guides/MANAGEMENT-AUTH.md)। ### প্রমাণীকরণ | এন্ডপয়েন্ট | মেথড | বিবরণ | | ----------------------------- | ------- | -------------------------- | | `/api/auth/login` | POST | লগইন | | `/api/auth/logout` | POST | লগআউট | | `/api/settings/require-login` | GET/PUT | লগইন আবশ্যক কি না টগল করুন | ### প্রোভাইডার ব্যবস্থাপনা | এন্ডপয়েন্ট | মেথড | বিবরণ | | ---------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `/api/providers` | GET/POST | প্রোভাইডারগুলোর তালিকা দেখুন / তৈরি করুন | | `/api/providers/[id]` | GET/PUT/DELETE | একটি প্রোভাইডার পরিচালনা করুন | | `/api/providers/[id]/test` | POST | প্রোভাইডার সংযোগ পরীক্ষা করুন | | `/api/providers/[id]/models` | GET | প্রোভাইডারের মডেলগুলোর তালিকা দেখুন | | `/api/providers/validate` | POST | প্রোভাইডার কনফিগ যাচাই করুন | | `/api/providers/bulk` | POST | একটি প্রোভাইডারের জন্য একযোগে একাধিক API key যোগ করুন | | `/api/providers/import` | POST | পার্স করা CSV/JSON ফাইল থেকে বিভিন্ন ধরনের প্রোভাইডারের একটি তালিকা আমদানি করুন (#6836); প্রতিটি সারির আংশিক ব্যর্থতার ফলাফল | | `/api/provider-nodes*` | বিভিন্ন | প্রোভাইডার নোড ব্যবস্থাপনা | | `/api/provider-models` | GET/POST/PATCH/DELETE | কাস্টম মডেল (যোগ, হালনাগাদ, লুকানো/দেখানো, মুছে ফেলা) | ### OAuth প্রবাহ | এন্ডপয়েন্ট | মেথড | বিবরণ | | -------------------------------- | ------- | -------------------------- | | `/api/oauth/[provider]/[action]` | বিভিন্ন | প্রোভাইডার-নির্দিষ্ট OAuth | ### রাউটিং ও কনফিগ | এন্ডপয়েন্ট | মেথড | বিবরণ | | --------------------- | -------- | --------------------------------- | | `/api/models/alias` | GET/POST | মডেল উপনাম | | `/api/models/catalog` | GET | প্রোভাইডার + ধরন অনুযায়ী সব মডেল | | `/api/combos*` | বিভিন্ন | কম্বো ব্যবস্থাপনা | | `/api/keys*` | বিভিন্ন | API key ব্যবস্থাপনা | | `/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 | প্রতিটি প্রোভাইডার/মডেলের রোলিং লেটেন্সি সমষ্টি (avg/p50/p95/p99, সফলতার হার); ফিল্টার: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) | | `/api/usage/cache-health` | GET | `call_logs`-এর ভিত্তিতে প্রম্পট-ক্যাশের স্বাস্থ্যসারাংশ — লেখা/পড়ার অনুপাত, p50/p90/p99 লেখা-আকারের বণ্টন, অতিরিক্ত লেখার ঘনত্ব, প্রতিটি মডেল অনুযায়ী বিভাজন এবং একটি `healthy`/`degraded`/`thrash`/`no-data` সিদ্ধান্ত; ক্যোয়ারি প্যারামিটার `range` (`1h`\|`24h`\|`7d`\|`30d`, ডিফল্ট `24h`) এবং ঐচ্ছিক `model` (#8827) | ### সেটিংস | এন্ডপয়েন্ট | মেথড | বিবরণ | | ------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/settings` | GET/PUT/PATCH | সাধারণ সেটিংস | | `/api/settings/proxy` | GET/PUT | নেটওয়ার্ক প্রক্সি কনফিগারেশন | | `/api/settings/proxy/test` | POST | প্রক্সি সংযোগ পরীক্ষা করুন | | `/api/settings/ip-filter` | GET/PUT | IP অনুমোদন-তালিকা/ব্লক-তালিকা | | `/api/settings/thinking-budget` | GET/PUT | চিন্তা/যুক্তির **অনুরোধ** পুনর্লিখন মোড (অপরিবর্তিত প্রেরণ / স্বয়ংক্রিয়ভাবে বাদ দেওয়া / কাস্টম / অভিযোজিত)। কম্প্রেশন থেকে স্বতন্ত্র। [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md) দেখুন। | | `/api/settings/system-prompt` | GET/PUT | গ্লোবাল সিস্টেম প্রম্পট | | `/api/settings/compression` | GET/PUT | গ্লোবাল কম্প্রেশন কনফিগারেশন | | `/api/settings/purge-request-history` | POST | অনুরোধের লগ সারি এবং স্থানীয় কল-লগ আর্টিফ্যাক্ট মুছে ফেলুন | ### কনটেক্সট ও কম্প্রেশন | Endpoint | Method | Description | | -------------------------------------- | -------------- | ------------------------------------------------------------------ | | `/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 | কম্প্রেশন অ্যানালিটিক্সের উপনাম | ### পর্যবেক্ষণ | Endpoint | Method | Description | | ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/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 উপলভ্যতা ও সংস্করণসমূহ (no-store) | | `/api/modality-bridge/video/extract` | POST | অভ্যন্তরীণ প্রমাণীকৃত বিশ্বস্ত-লুপব্যাক বাইট ব্রোকার; 50 MiB ইনপুট, সীমাবদ্ধ কিউ/32 MiB আউটপুট, `503` সক্ষমতা, `499` সংযোগ বিচ্ছিন্নতা, `504` সময়সীমা; এটি কোনো পাবলিক আপলোড API নয় | ### ব্যাকআপ ও এক্সপোর্ট/ইমপোর্ট | এন্ডপয়েন্ট | মেথড | বিবরণ | | --------------------------- | ---- | ----------------------------------------------- | | `/api/db-backups` | GET | উপলভ্য ব্যাকআপগুলোর তালিকা প্রদর্শন | | `/api/db-backups` | PUT | ম্যানুয়াল ব্যাকআপ তৈরি | | `/api/db-backups` | POST | নির্দিষ্ট ব্যাকআপ থেকে পুনরুদ্ধার | | `/api/db-backups/export` | GET | ডেটাবেসটি .sqlite ফাইল হিসেবে ডাউনলোড | | `/api/db-backups/import` | POST | ডেটাবেস প্রতিস্থাপনের জন্য .sqlite ফাইল আপলোড | | `/api/db-backups/exportAll` | GET | সম্পূর্ণ ব্যাকআপ .tar.gz আর্কাইভ হিসেবে ডাউনলোড | ### ক্লাউড সিঙ্ক | এন্ডপয়েন্ট | মেথড | বিবরণ | | ---------------------- | ------- | ---------------------- | | `/api/sync/cloud` | বিভিন্ন | ক্লাউড সিঙ্ক কার্যক্রম | | `/api/sync/initialize` | POST | সিঙ্ক আরম্ভ করা | | `/api/cloud/*` | বিভিন্ন | ক্লাউড ব্যবস্থাপনা | ### টানেল | এন্ডপয়েন্ট | মেথড | বিবরণ | | -------------------------- | ---- | ---------------------------------------------------------------------------- | | `/api/tunnels/cloudflared` | GET | ড্যাশবোর্ডের জন্য Cloudflare Quick Tunnel-এর ইনস্টলেশন/রানটাইম অবস্থা দেখুন | | `/api/tunnels/cloudflared` | POST | Cloudflare Quick Tunnel সক্রিয় বা নিষ্ক্রিয় করুন (`action=enable/disable`) | | `/api/tunnels/ngrok` | GET | ড্যাশবোর্ডের জন্য ngrok Tunnel-এর রানটাইম অবস্থা দেখুন | | `/api/tunnels/ngrok` | POST | ngrok Tunnel সক্রিয় বা নিষ্ক্রিয় করুন (`action=enable/disable`) | ### CLI টুল | এন্ডপয়েন্ট | মেথড | বিবরণ | | ---------------------------------- | ---- | ---------------------- | | `/api/cli-tools/claude-settings` | GET | Claude CLI-এর অবস্থা | | `/api/cli-tools/codex-settings` | GET | Codex CLI-এর অবস্থা | | `/api/cli-tools/droid-settings` | GET | Droid CLI-এর অবস্থা | | `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI-এর অবস্থা | | `/api/cli-tools/runtime/[toolId]` | GET | সাধারণ CLI রানটাইম | CLI প্রতিক্রিয়ায় অন্তর্ভুক্ত থাকে: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`। ### ACP এজেন্ট | এন্ডপয়েন্ট | মেথড | বিবরণ | | ----------------- | ------ | ----------------------------------------------------------- | | `/api/acp/agents` | GET | অবস্থা-সহ শনাক্ত করা সব এজেন্টের তালিকা (বিল্ট-ইন + কাস্টম) | | `/api/acp/agents` | POST | কাস্টম এজেন্ট যোগ করা বা শনাক্তকরণ ক্যাশ রিফ্রেশ করা | | `/api/acp/agents` | DELETE | `id` কোয়েরি প্যারামিটার অনুযায়ী একটি কাস্টম এজেন্ট অপসারণ | GET প্রতিক্রিয়ায় `agents[]` (id, name, binary, version, installed, protocol, isCustom) এবং `summary` (total, installed, notFound, builtIn, custom) অন্তর্ভুক্ত থাকে। ### স্থিতিস্থাপকতা ও রেট সীমা | এন্ডপয়েন্ট | মেথড | বিবরণ | | --------------------------------- | --------- | ------------------------------------------------------------------------------------- | | `/api/resilience` | GET/PATCH | অনুরোধের সারি, সংযোগ কুলডাউন, প্রোভাইডার ব্রেকার এবং অপেক্ষার সেটিংস পাওয়া/আপডেট করা | | `/api/resilience/reset` | POST | প্রোভাইডার সার্কিট ব্রেকার রিসেট করা | | `/api/resilience/model-cooldowns` | GET | অবশিষ্ট সময় অনুযায়ী সাজানো সক্রিয় প্রতি-(প্রোভাইডার, সংযোগ, মডেল) লকআউটের তালিকা | | `/api/resilience/model-cooldowns` | DELETE | মডেল লকআউট মুছুন—বডি `{provider, model}` অথবা সবকিছু মুছতে `{all: true}` | | `/api/rate-limits` | GET | অ্যাকাউন্ট-প্রতি রেট সীমার অবস্থা | | `/api/rate-limit` | GET | গ্লোবাল রেট সীমার কনফিগারেশন | > `/api/resilience/*`-এর চারটি রুটেই **ম্যানেজমেন্ট অথ** (`requireManagementAuth`) আবশ্যক। প্রোভাইডার ব্রেকার বনাম সংযোগ কুলডাউন বনাম মডেল লকআউটের পূর্ণাঙ্গ বিশ্লেষণের জন্য [স্থিতিস্থাপকতা (বর্ধিত)](#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 SDK সামঞ্জস্য প্রয়োজন, তাদের জন্য এই এন্ডপয়েন্টগুলো Gemini-এর API ফরম্যাট অনুকরণ করে। ### অভ্যন্তরীণ / সিস্টেম API | এন্ডপয়েন্ট | মেথড | বিবরণ | | ------------------------ | ---- | -------------------------------------------------------------------- | | `/api/init` | GET | অ্যাপ্লিকেশন ইনিশিয়ালাইজেশন পরীক্ষা (প্রথমবার চালানোর সময় ব্যবহৃত) | | `/api/tags` | GET | Ollama-সামঞ্জস্যপূর্ণ মডেল ট্যাগ (Ollama ক্লায়েন্টের জন্য) | | `/api/restart` | POST | সার্ভারকে সুষ্ঠুভাবে পুনরায় চালু করে | | `/api/shutdown` | POST | সার্ভারকে সুষ্ঠুভাবে বন্ধ করে | | `/api/system/env/repair` | POST | OAuth প্রোভাইডারের এনভায়রনমেন্ট ভেরিয়েবল মেরামত করে | > **দ্রষ্টব্য:** এই এন্ডপয়েন্টগুলো সিস্টেমের অভ্যন্তরে অথবা Ollama ক্লায়েন্টের সঙ্গে সামঞ্জস্যের জন্য ব্যবহৃত হয়। সাধারণত শেষ ব্যবহারকারীরা এগুলো কল করেন না। ### OAuth এনভায়রনমেন্ট মেরামত _(v3.6.1+)_ ```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 POST /v1/audio/transcriptions Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` কনফিগার করা যেকোনো STT প্রোভাইডার ব্যবহার করে অডিও ফাইল ট্রান্সক্রাইব করুন। প্রথম পাথ সেগমেন্টটি নেটিভ প্রোভাইডার নির্বাচন করে (`openai/…`, `deepgram/…`)। অন্য কোনো ভেন্ডরের মডেল পুনরায় এক্সপোর্ট করা গেটওয়েগুলো একটি কোয়ালিফায়েড আইডি ব্যবহার করে (`openrouter/deepgram/nova-3`)। **রিকোয়েস্ট:** ```bash curl -X POST http://localhost:20128/v1/audio/transcriptions \ -H "Authorization: Bearer your-api-key" \ -F "file=@recording.mp3" \ -F "model=openai/whisper-1" ``` **রেসপন্স:** ```json { "text": "Hello, this is the transcribed audio content.", "task": "transcribe", "language": "en", "duration": 12.5 } ``` **মডেল আইডির উদাহরণ:** `openai/whisper-1` (একটি OpenAI কী প্রয়োজন), `openrouter/deepgram/nova-3` (একটি OpenRouter কী প্রয়োজন), `deepgram/nova-3` (একটি নেটিভ Deepgram কী প্রয়োজন)। একটি সরাসরি `deepgram/nova-3` রিকোয়েস্ট OpenRouter ব্যবহার করে **না**। **সমর্থিত ফরম্যাট:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`। --- ## Ollama সামঞ্জস্য Ollama-এর API ফরম্যাট ব্যবহারকারী ক্লায়েন্টগুলোর জন্য: ```bash # চ্যাট এন্ডপয়েন্ট (Ollama ফরম্যাট) POST /v1/api/chat # মডেলের তালিকা (Ollama ফরম্যাট) GET /api/tags ``` রিকোয়েস্টগুলো Ollama ও অভ্যন্তরীণ ফরম্যাটের মধ্যে স্বয়ংক্রিয়ভাবে রূপান্তর করা হয়। ## টোকেনযুক্ত VS Code / হেডারবিহীন অ্যালিয়াস কোনো ইন্টিগ্রেশন যখন একটি `Authorization` হেডার যোগ করতে পারে না এবং বেস URL-এর মধ্যে API কী এম্বেড করার প্রয়োজন হয়, তখন এই অ্যালিয়াসগুলো ব্যবহার করুন। ```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-key **টোকেন** বাজেট (উপরের USD-ভিত্তিক বাজেট থেকে আলাদা)। রিকোয়েস্ট পাথেই সরাসরি প্রয়োগ করা হয়: কোনো key-এর বর্তমান উইন্ডোর ব্যবহার তার সীমায় পৌঁছালে, রিকোয়েস্টগুলো `429 Too Many Requests` দিয়ে প্রত্যাখ্যান করা হয়। সীমাগুলো একটি নির্দিষ্ট `model`, একটি `provider`-এর জন্য নির্ধারণ করা যেতে পারে, অথবা পুরো key জুড়ে `global`ভাবে প্রয়োগ করা যেতে পারে; যখন একাধিক সীমা কোনো রিকোয়েস্টের সঙ্গে মিলে যায়, তখন সবচেয়ে কঠোর সীমাটি কার্যকর হয়। ```bash # কোনো key-এর টোকেন সীমার তালিকা দেখুন (লাইভ উইন্ডো ব্যবহারসহ) 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`) আবশ্যক। `scopeType` যদি `global` না হয়, তাহলে `scopeValue` আবশ্যক (যেমন `model` স্কোপের জন্য একটি model id, `provider` স্কোপের জন্য একটি provider id)। `tokenLimit` অবশ্যই একটি ধনাত্মক পূর্ণসংখ্যা হতে হবে (স্ট্রিং থেকে রূপান্তরিত)। ঐচ্ছিক: `id` (তৈরি করতে বাদ দিন, আপডেট করতে প্রদান করুন), `resetInterval` (`daily` | `weekly` | `monthly`, ডিফল্ট `monthly`), `resetTime` (`HH:MM`), `enabled` (ডিফল্ট `true`)। `GET` রেসপন্স প্রতিটি সীমার সঙ্গে `tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, এবং `nextResetAt` যোগ করে। এটি একটি ম্যানেজমেন্ট-শ্রেণির এন্ডপয়েন্ট (authz pipeline কেন্দ্রীয়ভাবে auth প্রয়োগ করে)। ## রিকোয়েস্ট প্রক্রিয়াকরণ 1. ক্লায়েন্ট `/v1/*`-এ রিকোয়েস্ট পাঠায় 2. রুট হ্যান্ডলার `handleChat`, `handleEmbedding`, `handleAudioTranscription`, অথবা `handleImageGeneration` কল করে 3. মডেল নির্ধারণ করা হয় (সরাসরি provider/model অথবা alias/combo) 4. অ্যাকাউন্টের উপলভ্যতা ফিল্টার করে স্থানীয় DB থেকে ক্রেডেনশিয়াল নির্বাচন করা হয় 5. চ্যাটের জন্য: `handleChatCore` semantic/signature cache পরীক্ষা করে এবং combo compression সেটিংস নির্ধারণ করে 6. সক্রিয় থাকলে provider translation-এর আগে proactive compression চালানো হয় (`lite`, Caveman, RTK, অথবা stacked) 7. Provider executor upstream রিকোয়েস্ট পাঠায় 8. রেসপন্স ক্লায়েন্ট ফরম্যাটে পুনরায় অনুবাদ করা হয় (চ্যাট) অথবা অপরিবর্তিত অবস্থায় ফেরত দেওয়া হয় (embeddings/images/audio) 9. ব্যবহার, compression analytics, এবং রিকোয়েস্ট লগ রেকর্ড করা হয় 10. Combo নিয়ম অনুযায়ী ত্রুটির ক্ষেত্রে fallback প্রয়োগ করা হয় সম্পূর্ণ আর্কিটেকচার রেফারেন্স: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md) --- ## Combo ব্যবস্থাপনা উচ্চতর-স্তরের রাউটিং combo-গুলো (`/api/combos*`-এর অধীনে ইতিমধ্যে সংক্ষেপিত) একটি model id প্যাটার্ন থেকে 1:1 অনুপাতেও ম্যাপ করা যায়, যা একটি OpenAI-ধাঁচের model id-কে স্বচ্ছভাবে কোনো combo-তে পুনর্নির্দেশ করতে দেয়। | পদ্ধতি | পাথ | বিবরণ | | ------ | -------------------------------- | --------------------------------------------------------------------------------- | | GET | `/api/model-combo-mappings` | সব model→combo mapping-এর তালিকা দেখুন | | POST | `/api/model-combo-mappings` | mapping তৈরি করুন — body: `{pattern, comboId, priority?, enabled?, description?}` | | GET | `/api/model-combo-mappings/[id]` | একটি নির্দিষ্ট mapping পুনরুদ্ধার করুন | | PUT | `/api/model-combo-mappings/[id]` | একটি বিদ্যমান mapping-এর ফিল্ডগুলো আপডেট করুন | | DELETE | `/api/model-combo-mappings/[id]` | একটি mapping সরিয়ে দিন | **Auth:** ম্যানেজমেন্ট session/API key (`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-এর মতো একই প্রভাব) | **প্রমাণীকরণ:** Bearer API কী (`isAuthenticated`)। আরও দেখুন `/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-এর আগে এগুলো প্রমাণীকরণবিহীন ছিল — ব্রেকিং পরিবর্তনের জন্য কমিট `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 তিনটি স্বতন্ত্র অস্থায়ী-ব্যর্থতা প্রক্রিয়া প্রকাশ করে; নিচের ব্যবস্থাপনা এন্ডপয়েন্টগুলো অপারেটরদের এগুলোর অবস্থা পড়তে এবং ওভাররাইড করতে দেয়: | পরিধি | স্টেট স্টোরেজ | পড়া | রিসেট / পরিষ্কার করা | | ------------------ | ------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------ | | প্রোভাইডার ব্রেকার | `domain_circuit_breakers` + ইন-মেমরি | `/api/monitoring/health` | `POST /api/resilience/reset` | | সংযোগ কুলডাউন | প্রোভাইডার সংযোগে `rateLimitedUntil` | `/api/rate-limits`, `/api/providers/[id]` | (প্রয়োজনের সময় পুনরায় সক্রিয় হয়; প্রোভাইডার PUT-এর মাধ্যমে পরিষ্কার করুন) | | মডেল লকআউট | ইন-মেমরি মডেল-উপলভ্যতা রেজিস্ট্রি | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` | `PATCH /api/resilience`-এ `providerBreaker.oauth` এবং `providerBreaker.apikey`-এর অধীনে প্রোভাইডার ব্রেকার ওভাররাইড গ্রহণ করা হয়। প্রতিটি প্রোফাইল `degradationThreshold`, `failureThreshold`, এবং `resetTimeoutMs` সমর্থন করে; একই ফিল্ডগুলো Dashboard → Settings → Resilience-এ পাওয়া যায়। ```bash # একটি নির্দিষ্ট মডেল লকআউট পরিষ্কার করুন curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \ -H "Cookie: auth_token=..." \ -H "Content-Type: application/json" \ -d '{"provider":"openai","model":"gpt-4o-mini"}' # সব লকআউট মুছে ফেলুন curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \ -H "Cookie: auth_token=..." \ -d '{"all":true}' ``` সম্পূর্ণ ধারণাগত রেফারেন্স এবং ব্রেকারের ডিফল্ট মানের জন্য দেখুন: [`CLAUDE.md`](../../CLAUDE.md) → "রানটাইম স্থিতিস্থাপকতার অবস্থা"। --- ## স্কিলসমূহ কাস্টম এক্সিকিউটেবল হ্যান্ডলার দিয়ে OmniRoute সম্প্রসারণের জন্য স্কিল ফ্রেমওয়ার্ক, সঙ্গে মার্কেটপ্লেস ইন্টিগ্রেশন। | মেথড | পাথ | বিবরণ | | ------ | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/skills` | ইনস্টল করা স্কিলের তালিকা — `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local` দিয়ে ফিল্টারযোগ্য এবং পৃষ্ঠাবিভক্ত | | GET | `/api/skills/[id]` | একটি স্কিল সংগ্রহ করুন | | PUT | `/api/skills/[id]` | স্কিল আপডেট করুন (নাম, বিবরণ, মোড, স্কিমা, হ্যান্ডলার, ট্যাগ) | | DELETE | `/api/skills/[id]` | একটি স্কিল আনইনস্টল করুন | | POST | `/api/skills/install` | একটি raw manifest থেকে স্কিল ইনস্টল করুন — বডি: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` | | GET | `/api/skills/executions` | সাম্প্রতিক স্কিল এক্সিকিউশনের তালিকা (ইনপুট/আউটপুট/সময়কালসহ অডিট ট্রেইল) | | GET | `/api/skills/marketplace?q=...` | SkillsMP মার্কেটপ্লেস থেকে অনুসন্ধান/জনপ্রিয় তালিকা (`skillsmpApiKey` সেটিং প্রয়োজন) | | POST | `/api/skills/marketplace/install` | SkillsMP থেকে id অনুযায়ী একটি স্কিল ইনস্টল করুন | | GET | `/api/skills/skillssh?q=&limit=` | skills.sh রেজিস্ট্রি অনুসন্ধান করুন | | POST | `/api/skills/skillssh/install` | skills.sh থেকে id অনুযায়ী একটি স্কিল ইনস্টল করুন | **প্রমাণীকরণ:** ব্যবস্থাপনা সেশন/API key। মার্কেটপ্লেস অনুসন্ধান রুটগুলো ব্যবস্থাপনা প্রমাণীকরণ অথবা একটি Bearer API key (`isAuthenticated`) গ্রহণ করে। --- ## মেমরি স্থায়ী কথোপকথনমূলক/তথ্যভিত্তিক মেমরি স্টোর, যা প্রতিটি API key / session অনুযায়ী সীমাবদ্ধ। | মেথড | পাথ | বিবরণ | | ------ | -------------------- | ------------------------------------------------------------------------------------------------------------- | | 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 backend, vector index-এর অবস্থা) | **প্রমাণীকরণ:** management session/API key (`requireManagementAuth`)। `type` enum: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (`src/lib/memory/types.ts`-এ `MemoryType` দেখুন)। --- ## MCP সার্ভার OmniRoute-এ 3টি transport (stdio, SSE, streamable-http) এবং scoped tools-সহ একটি এম্বেডেড Model Context Protocol সার্ভার অন্তর্ভুক্ত রয়েছে। নিচের dashboard endpoint-গুলো status/audit data পড়ে এবং HTTP transport-গুলোকে proxy করে। | মেথড | পাথ | বিবরণ | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- | | GET | `/api/mcp/status` | Heartbeat, transport, online state, সর্বশেষ কল, শীর্ষ tools, 24h সফলতার হার | | GET | `/api/mcp/tools` | `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints`-সহ MCP tools-এর তালিকা | | GET | `/api/mcp/sse` | SSE transport-এর জন্য SSE stream খুলুন (MCP নিষ্ক্রিয় থাকলে অথবা transport না মিললে `503` প্রদান করে) | | POST | `/api/mcp/sse` | SSE transport-এ JSON-RPC frame পাঠান | | GET | `/api/mcp/stream` | Streamable HTTP transport-এর SSE side খুলুন (server-initiated messages) | | POST | `/api/mcp/stream` | Streamable HTTP transport-এ JSON-RPC frame পাঠান | | DELETE | `/api/mcp/stream` | একটি Streamable HTTP session সমাপ্ত করুন | | GET | `/api/mcp/audit` | audit log query করুন — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` | | GET | `/api/mcp/audit/stats` | সমষ্টিগত audit stats (মোট সংখ্যা, সফলতার হার, গড় সময়কাল, শীর্ষ tools) | **প্রমাণীকরণ:** `sse`/`stream` transport-গুলো MCP-নির্দিষ্ট auth surface মেনে চলে (`mcp` scope-সহ Bearer API key); `status`/`tools`/`audit*` route-গুলো dashboard থেকে পাঠযোগ্য (dashboard host-এ পৌঁছানোর বাইরে অতিরিক্ত auth প্রয়োজন নেই)। > উভয় HTTP transport-ই `settings.mcpEnabled` এবং `settings.mcpTransport` দ্বারা নিয়ন্ত্রিত — transport না মিললে `400` এবং MCP নিষ্ক্রিয় থাকলে `503` প্রদান করা হয়। --- ## A2A সার্ভার OmniRoute একটি A2A (Agent-to-Agent) JSON-RPC 2.0 এন্ডপয়েন্টের পাশাপাশি পরিদর্শন/ড্যাশবোর্ড ব্যবহারের জন্য একটি REST র্যাপার উন্মুক্ত করে। ### JSON-RPC ```bash POST /a2a Authorization: Bearer your-api-key # OMNIROUTE_API_KEY সেট করা না থাকলে ঐচ্ছিক Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "message/send", "params": { "skill": "smart-routing", "messages": [{"role": "user", "content": "Route this coding task"}] } } ``` সমর্থিত মেথডসমূহ (সবগুলোই `settings.a2aEnabled` দ্বারা নিয়ন্ত্রিত): | মেথড | বিবরণ | | ---------------- | ----------------------------------------------------------------------- | | `message/send` | সিঙ্ক্রোনাস স্কিল এক্সিকিউশন; `{task, artifacts, metadata}` রিটার্ন করে | | `message/stream` | একই স্কিল সেটের স্ট্রিমিং SSE এক্সিকিউশন | | `tasks/get` | `taskId` দিয়ে একটি টাস্ক ফেচ করে | | `tasks/cancel` | `taskId` দিয়ে একটি টাস্ক বাতিল করে | বিল্ট-ইন স্কিলসমূহ: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`। ### এজেন্ট কার্ড ```bash GET /.well-known/agent.json ``` পাবলিক A2A এজেন্ট কার্ড (নাম, বিবরণ, সক্ষমতা, স্কিল ক্যাটালগ, অথ স্কিম) রিটার্ন করে — সর্বসাধারণের জন্য 1h ক্যাশ করা হয়। কোনো অথ প্রয়োজন নেই। ### REST সহায়কসমূহ | মেথড | পাথ | বিবরণ | | ---- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------- | | GET | `/api/a2a/status` | A2A সক্রিয় অবস্থা + টাস্ক পরিসংখ্যান + ক্যাশ করা এজেন্ট কার্ডের সারাংশ | | GET | `/api/a2a/tasks` | টাস্কের তালিকা — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` | | POST | `/api/a2a/tasks` | (REST সহায়ক হিসেবে বাস্তবায়িত নয় — JSON-RPC `message/send` দিয়ে তৈরি করুন) | | GET | `/api/a2a/tasks/[id]` | একটি টাস্ক পুনরুদ্ধার করে | | POST | `/api/a2a/tasks/[id]/cancel` | একটি টাস্ক বাতিল করে | **অথ:** REST সহায়কগুলো ম্যানেজমেন্ট অথ ছাড়াই চলে (ড্যাশবোর্ড থেকে পাঠযোগ্য); কনফিগার করা থাকলে JSON-RPC `/a2a` রুটটি Bearer `OMNIROUTE_API_KEY` ব্যবহার করে। --- ## ক্লাউড, ইভ্যাল ও অ্যাসেস | মেথড | পাথ | বিবরণ | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | POST | `/api/cloud/auth` | একটি Bearer কী যাচাই করে এবং ক্লাউড সিঙ্ক ক্লায়েন্টগুলোর জন্য মাস্ক করা প্রোভাইডার সংযোগ + মডেল অ্যালিয়াস রিটার্ন করে | | POST | `/api/cloud/credentials/update` | ক্লাউড-সিঙ্ক করা কোনো প্রোভাইডারের এনক্রিপ্ট করা ক্রেডেনশিয়াল আপডেট করে | | POST | `/api/cloud/model/resolve` | স্থানীয় রাউটিং টেবিল ব্যবহার করে একটি লজিক্যাল মডেল আইডিকে নির্দিষ্ট প্রোভাইডার/মডেলে রেজলভ করে | | GET | `/api/cloud/models/alias` | ক্লাউড সিঙ্কে উন্মুক্ত মডেল অ্যালিয়াসগুলোর তালিকা দেয় | | GET | `/api/assess` | সর্বশেষ অ্যাসেসমেন্ট শ্রেণিবিন্যাস পড়ে (প্রতি-প্রোভাইডার/মডেল) | | POST | `/api/assess` | একটি অ্যাসেসমেন্ট চালায় — বডি: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` | | GET | `/api/evals` | বিল্ট-ইন ইভ্যাল স্যুট + সর্বশেষ রানগুলোর তালিকা দেয় | | POST | `/api/evals` | একটি ইভ্যাল রান ট্রিগার করে | | POST | `/api/evals/suites` | একটি কাস্টম ইভ্যাল স্যুট তৈরি করে — বডি `evalSuiteSaveSchema` দ্বারা যাচাই করা হয় | | GET | `/api/evals/suites/[id]` | একটি কাস্টম ইভ্যাল স্যুট পুনরুদ্ধার করে | **অথ:** `/api/cloud/auth` সরাসরি একটি Bearer কী যাচাই করে; অন্যান্য `/api/cloud/*`, `/api/evals/*`, এবং `/api/assess` রুটের জন্য ম্যানেজমেন্ট সেশন/API কী প্রয়োজন। `/api/assess` POST একটি discriminated-union স্কোপ স্কিমার সঙ্গে `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 Framework](../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, chipotle, 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-এর কাস্টম GPT-এর অনুরূপ, তবে এজেন্টদের জন্য)। | মেথড | পাথ | বিবরণ | | ------ | ---------------------------- | --------------------------------------------------------------------------------------------- | | 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 কী) এবং ইনফারেন্স কীগুলোর সঙ্গে এগুলোর পার্থক্য জানতে [ম্যানেজমেন্ট প্রমাণীকরণ](../guides/MANAGEMENT-AUTH.md) দেখুন। - ড্যাশবোর্ড রুটগুলো (`/dashboard/*`) `auth_token` কুকি ব্যবহার করে - লগইনে সংরক্ষিত পাসওয়ার্ড হ্যাশ ব্যবহার করা হয়; ফলব্যাক হিসেবে `INITIAL_PASSWORD` - `/api/settings/require-login`-এর মাধ্যমে `requireLogin` টগল করা যায় - `REQUIRE_API_KEY=true` হলে `/v1/*` রুটগুলোর জন্য ঐচ্ছিকভাবে Bearer API কী প্রয়োজন হয় - এই রেফারেন্সে "ম্যানেজমেন্ট টোকেন" / "ম্যানেজমেন্ট-স্কোপযুক্ত API কী" বলতে ওই গাইডে উল্লেখ করা পরিবারগুলোর একটিকে বোঝায়—অসংজ্ঞায়িত কোনো অতিরিক্ত সিক্রেটের ধরন নয় > **ব্রেকিং পরিবর্তন (v3.8.0)** — `/api/v1/agents/tasks/*` এবং কুলডাউন ম্যানেজমেন্ট এন্ডপয়েন্টগুলোর জন্য এখন **ম্যানেজমেন্ট প্রমাণীকরণ** (ড্যাশবোর্ড `auth_token` কুকি অথবা ম্যানেজমেন্ট-স্কোপযুক্ত API কী) প্রয়োজন। যেসব ক্লায়েন্ট আগে প্রমাণীকরণ ছাড়াই এই রুটগুলো কল করত, তারা এখন `401 Unauthorized` পাবে। কমিট `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`) দেখুন।