# API Reference (Türkçe) 🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [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) · 🇺🇦 [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) --- 🌐 **Diller:** 🇺🇸 [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 için temel başvuru kaynağı. Herkese açık `/v1` yüzeyini ve en sık kullanılan yönetim uç noktalarını kapsar; makine tarafından okunabilir [`docs/openapi.yaml`](../openapi.yaml) ile `src/app/api/` altındaki rota ağacı, kapsamlı kaynaklardır. --- ## İçindekiler - [Sohbet Tamamlamaları](#chat-completions) - [Özel Yönetilen Oturum Kiralamaları](#exclusive-managed-session-leases) - [Gömme Vektörleri](#embeddings) - [Görüntü Oluşturma](#image-generation) - [Belge OCR](#document-ocr) - [Modelleri Listeleme](#list-models) - [Sağlayıcı Eklentisi Manifestosu](#provider-plugin-manifest) - [Uyumluluk Uç Noktaları](#compatibility-endpoints) - [Dosyalar API'si](#files-api) - [Toplu İşler API'si](#batches-api) - [Arama API'si](#search-api) - [WebSocket Akışı](#websocket-streaming) - [Kotalar ve Sorun Bildirimi](#quotas--issues-reporting) - [Semantik Önbellek](#semantic-cache) - [Pano ve Yönetim](#dashboard--management) - [Kombinasyon Yönetimi](#combo-management) - [Webhook'lar](#webhooks) - [Kayıtlı Anahtarlar (Otomatik Yönetim)](#registered-keys-auto-management) - [Ajan Protokolü](#agents-protocol) - [Yönetim Proxy'leri](#management-proxies) - [Dayanıklılık (genişletilmiş)](#resilience-extended) - [Beceriler](#skills) - [Bellek](#memory) - [MCP Sunucusu](#mcp-server) - [A2A Sunucusu](#a2a-server) - [Bulut, Değerlendirmeler ve Ölçme](#cloud-evals--assess) - [İstek İşleme](#request-processing) - [Kimlik Doğrulama](#authentication) --- ## Sohbet Tamamlamaları ```bash POST /v1/chat/completions Authorization: Bearer your-api-key Content-Type: application/json { "model": "cc/claude-opus-4-6", "messages": [ {"role": "user", "content": "Şunu gerçekleştiren bir işlev yaz..."} ], "stream": true } ``` ### Özel Üstbilgiler | Üstbilgi | Yön | Açıklama | | ------------------------ | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `X-OmniRoute-No-Cache` | İstek | Önbelleği atlamak için `true` olarak ayarlayın | | `x-omniroute-no-memory` | İstek | Bu istek için bellek ve beceri eklemeyi atlamak üzere `true` olarak ayarlayın (önbelleksiz davranışı yansıtır; çağrı başına belirteç/maliyet ek yükünü önler) | | `X-OmniRoute-Progress` | İstek | İlerleme olayları için `true` olarak ayarlayın | | `X-Session-Id` | İstek | Harici oturum benzeşimi için kalıcı oturum anahtarı | | `x_session_id` | İstek | Alt çizgili değişken de kabul edilir (doğrudan HTTP) | | `X-OmniRoute-Session-Id` | İstek | Çağıran tarafından sağlanan oturum/konuşma etiketi (belleği de besler). Mevcut olduğunda, oturum başına maliyet ilişkilendirmesi için `call_logs.session_tag` alanına olduğu gibi kalıcı olarak kaydedilir (#8249) — mevcut olmadığında asla oluşturulmaz | | `Idempotency-Key` | İstek | Tekilleştirme anahtarı (5 saniyelik pencere) | | `X-Request-Id` | İstek | Alternatif tekilleştirme anahtarı | | `X-OmniRoute-Cache` | Yanıt | `HIT` veya `MISS` (akışsız) | | `X-OmniRoute-Idempotent` | Yanıt | Tekilleştirildiyse `true` | | `X-OmniRoute-Progress` | Yanıt | İlerleme izleme açıksa `enabled` | | `X-OmniRoute-Session-Id` | Yanıt | OmniRoute tarafından kullanılan etkin oturum kimliği | | `X-OmniRoute-Request-Id` | Yanıt | İstek korelasyon kimliği (biliniyorsa) | | `X-OmniRoute-Version` | Yanıt | OmniRoute derleme sürümü (her zaman mevcut) | | `X-OmniRoute-Cost-Saved` | Yanıt | Önbelleğin bir HIT durumunda kaçındığı USD tutarı (yalnızca önbellek isabetleri) | | `X-OmniRoute-Decision` | Yanıt | Yönlendirme izi: `strategy=; provider=; latency_ms=` (`` kombinasyon stratejisidir veya kombinasyon dışı bir istek için `single` değeridir) — tamamlanma yanıtlarında her zaman bulunur | > Nginx notu: Alt çizgili üstbilgilere (örneğin `x_session_id`) güveniyorsanız `underscores_in_headers on;` ayarını etkinleştirin. > **Maliyet telemetrisi üstbilgileri:** akışsız başarılı yanıtlar ayrıca `X-OmniRoute-*` maliyet telemetrisi kümesini taşır: `X-OmniRoute-Response-Cost` (USD, sabit 10 ondalık basamak; ücretsiz/fiyatlandırılmamış olanlar için `0.0000000000`), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit` ve `X-OmniRoute-Fallback-Attempts` (yalnızca > 0 olduğunda); bunlara ek olarak `X-OmniRoute-Request-Id` ve `X-OmniRoute-Version`. Bunlar sohbet tamamlama işlemleri, `/v1/responses`, `/v1/messages` **ve medya uç noktaları** tarafından döndürülür: `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` ve `/v1/moderations` (maliyeti her zaman `0`). Medya maliyeti, fiyatlandırma mevcut olduğunda modalite başına (görsel başına, saniye başına, karakter başına, arama birimi başına) hesaplanır; aksi takdirde `0` olur (hata durumunda işleme devam edilir). > **Önbellek isabeti maliyet semantiği:** anlamsal önbellek İSABETİNDE (`X-OmniRoute-Cache-Hit: true`) üst sağlayıcıya çağrı yapılmaz; bu nedenle `X-OmniRoute-Response-Cost`, isabeti sunmanın **artımlı** maliyeti olan `0.0000000000` değerindedir. Özgün/gerçekleşmiş olacak maliyet, `X-OmniRoute-Cost-Saved` içinde ayrıca bildirilir. Faturalandırma tüketicileri `X-OmniRoute-Response-Cost` değerlerini toplamalıdır (isabetlerin maliyeti yoktur); önbellek analitiği ise `X-OmniRoute-Cost-Saved` değerlerini birleştirebilir. ## Özel Yönetilen Oturum Kiralamaları Özel yönetilen oturum kiralama, isteğe bağlı ve istemciden bağımsız bir yönlendirme sözleşmesidir: etkin tek bir sahip, uygun bir OmniRoute bağlantısını elinde tutar. Bir modeli kiralamaz, OAuth gerektirmez, belirli bir istemciyi tanımlamaz veya belirli bir sağlayıcıyı zorunlu kılmaz. Kimlik doğrulaması yapan API anahtarı `lease:exclusive` kapsamına ve açıkça belirtilmiş, boş olmayan bir `allowedConnections` listesine sahip olmalıdır. Veritabanı mutasyon sınırı, anahtar oluşturma ve kısmi güncellemeler sırasında her iki alanı birlikte zorunlu kılar. ```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"} ``` Başarılı edinme, yenileme ve serbest bırakma yanıtları zaman damgalarını, `state` değerini ve tam pozitif `generation` değerini sunar; ancak seçilen bağlantıyı veya kimlik bilgilerini hiçbir zaman sunmaz. Yenileme ve serbest bırakma işlemleri, generation değerini JSON gövdesinde sağlar: ```json { "action": "renew", "generation": 1 } ``` ```json { "action": "release", "generation": 1, "reason": "OWNER_EXIT" } ``` Etkin bir kiralama sahibi, mevcut bağlaması için gizliliği koruyan görüntüleme meta verilerini açıkça isteyebilir: ```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" } } ``` Bu isteğe bağlı durum eylemi; opak sahip, kimliği doğrulanmış yönetilen API anahtarı ve tam etkin generation ile tek bir veritabanı işlemi içinde korunur. `displayName`, yalnızca kırpılmış yapılandırılmış bağlantı adıdır; güvenli bir yapılandırılmış ad olmadığında `null` olur. OmniRoute hiçbir zaman bunun yerine bir e-posta adresi veya oluşturulmuş hesap kimliği kullanmaz. Sağlayıcı değeri, hassas olmayan bir görüntüleme etiketidir ve hiçbir zaman oluşturulmuş uyumlu sağlayıcı tanımlayıcısı değildir. Kimlik bilgileri, token'lar, çerezler, ham bağlantı veya API anahtarı kimlikleri, sahip hash'leri, koruma sırları ve dahili yönlendirme verileri hariç tutulur. Yanlış anahtar, yanlış sahip, eski generation, eksik, süresi dolmuş, serbest bırakılmış ve geçersiz kılınmış aramaların tümü, bağlantı meta verileri olmadan aynı `409 LEASE_FENCE_STALE` hatasını döndürür. Kapasite bekleme yanıtı alan bir istemcinin inceleyebileceği etkin bir bağlaması yoktur. Yönlendirme etkin bir kiralamayı başka bir bağlantıya geçirdiğinde, aynı generation geçerli kalır ve durum işlemi eski bağlamayı hiçbir zaman döndürmeden yeni bağlamayı atomik olarak döndürür. Edinme, yenileme, serbest bırakma ve bekleme yanıtları önceki biçimlerini koruduğundan mevcut istemciler değişmeden kalır. Bu sunucu sözleşmesi, standart OpenAI Codex `/status` davranışını değiştirmez. Standart Codex şu anda kendi model sağlayıcısını ve yerleşik kimlik doğrulama/hesap durumunu bildirir ancak isteğe bağlı özel sağlayıcı hesap meta verilerini göstermez; gelecekteki bir istemci entegrasyonu bu eylemi çağırmalı ve `connection.displayName` değerinin nasıl gösterileceğine karar vermelidir. Bundan sonra yönetilen her çıkarım isteği iki kontrol başlığını da sağlar: ```http X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters> X-OmniRoute-Lease-Generation: 1 ``` Tam sahip, generation, etkin bağlantı ve kimliği doğrulanmış API anahtarı, desteklenen her yukarı akış denemesinden hemen önce doğrulanır. Sahip ve generation değerlerinin başka bir anahtarla yeniden kullanılması, bu anahtar aynı bağlantıya izin verse bile başarısız olur. Ham sahip değerleri kalıcı olarak saklanmaz, günlüğe kaydedilmez, istek anlık görüntüsünde tutulmaz veya yukarı akışa iletilmez. Geçici çekişme, `Retry-After` ile birlikte HTTP `429` ve aşağıdaki yanıtı döndürür: ```json { "state": "WAITING_FOR_CAPACITY", "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" }, "reason": "NO_FREE_ELIGIBLE_CONNECTION", "retryAfter": 30 } ``` Bu yanıt yalnızca normal uygun kümenin boş olmadığı ve tüm boş adayların başka bir etkin kiralama tarafından tutulduğu anlamına gelir. Desteklenmeyen modeller/sağlayıcılar, politika uyumsuzluğu, bekleme süresi, kota, sağlık ve diğer normal uygunluk hataları mevcut OmniRoute yanıtlarını korur. ### `x-omniroute-compression` Sıkıştırma planının istek başına geçersiz kılınması. En yüksek önceliğe sahiptir — yönlendirme kombinasyonu geçersiz kılmasını, etkin profili, otomatik tetiklemeyi ve panel Varsayılanını geçersiz kılar. Değerler: | Değer | Etki | | ------------- | ------------------------------------------------------------------------------------------------------------ | | `off` | Bu istek için sıkıştırma uygulanmaz. | | `default` | Panelden türetilen Varsayılan profil (etkin profili yok sayar). | | `engine:` | Etkinleştirildiğinde tek bir motor, ör. `engine:rtk`. | | `` | Önce ada göre (büyük/küçük harf duyarsız), ardından kimliğe göre eşleştirilen adlandırılmış bir kombinasyon. | Notlar: - Bilinmeyen değerler yok sayılır (istek hiçbir zaman reddedilmez); çözümleme normal operatör önceliğine geri döner. - Birden fazla kombinasyon aynı adı paylaşıyorsa belirlenimci bir eşleşme için kombinasyonun **id** değerini iletin. - Adı `off` veya `default` olan bir kombinasyon adıyla seçilemez (önce bu anahtar sözcükler yorumlanır); böyle bir kombinasyona kimliğiyle başvurun. - Ana sıkıştırma anahtarı kesin bir geçittir: sıkıştırma genel olarak devre dışı bırakıldığında bu başlık sıkıştırmayı etkinleştiremez. Uygulanan plan, yanıt başlığında geri bildirilir: ``` X-OmniRoute-Compression: ; source= ``` Burada ``; `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` veya `off` değerlerinden biridir. --- ## Embedding'ler ```bash POST /v1/embeddings Authorization: Bearer your-api-key Content-Type: application/json { "model": "nebius/Qwen/Qwen3-Embedding-8B", "input": "The food was delicious" } ``` Kullanılabilir sağlayıcılar: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI. Katalog kimlikleri `provider/model` biçimindedir (örnek: `jina-ai/jina-embeddings-v5-omni-small`). Kayıt defterinde yer alan yalın Jina model kimlikleri de (örneğin `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) çözümlenir. Jina embed/rerank/classify/segment işlemleri öncelikle kontrol panelindeki `jina-ai` kimlik bilgilerini kullanır; `JINA_AI_API_KEY` yalnızca kontrol paneli anahtarı olmadığında geri dönüş seçeneğidir. `jina-reader` kartı yalnızca Reader / `r.jina.ai` içindir (`POST /v1/web/fetch`) ve hiçbir zaman embedding veya yeniden sıralama hizmeti sunmaz. Çok modlu desteği olduğunu belirten kayıt defteri modelleri, sağlayıcıdan bağımsız en fazla 32 yapılandırılmış öğeyi de kabul eder. Medya öğesi türleri `text`, `image`, `audio`, `video` ve `document` şeklindedir. Bunların medya `source` değeri ya `{"type":"url","url":"https://..."}` ya da `{"type":"base64","data":"...","media_type":"..."}` biçimindedir. Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano` ve aile diğer adı `jina-ai/jina-embeddings-v5-omni` → omni-small), Jina'nın yerel EmbeddingsV5Request belgelerini de kabul eder ve bunları `https://api.jina.ai/v1/embeddings` adresine **değiştirmeden iletir**: ```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,..." }] } ] } ``` Yerel `{ image | audio | video | pdf }` değerleri herkese açık bir HTTPS URL'si, bir `data:` URI'si veya ham base64 olabilir. OmniRoute bu nesneleri dizeye dönüştürmez veya yerel görüntü URL'lerini getirmez — herkese açık medyayı Jina kendisi alır. Ek Jina alanları (`task`, `normalized`, `truncate`, `embedding_type`) iletilir. Yalnızca metin destekleyen Jina SKU'ları, metin dışı belgeleri reddetmeye devam eder. Güvenlik ve aktarım sınırları: - Uzak medya URL'leri herkese açık HTTPS olmalıdır. Standart `{type,source:url}` öğeleri sunucu tarafında alınır (yönlendirme yeniden doğrulaması, zaman aşımı, boyut sınırları, herkese açık DNS, bağlantı sabitleme) ve sağlayıcı çağrısından önce satır içine eklenir. Jina'ya özgü `{image:"https://..."}` öğeleri, aynı herkese açık HTTPS kontrolünden sonra olduğu gibi iletilir; URL'yi Jina getirir. - Satır içi base64 medya, öğe başına çözümlenmiş 8 MiB ve istek genelinde çözümlenmiş 16 MiB ile sınırlıdır. Sağlayıcı dönüşümü (standart öğeler hiçbir zaman değiştirilmeden iletilmez): - Jina çok modlu modelleri: her üst düzey öğe, satır içi medya için veri URI'leri kullanılarak modalite anahtarlı tek bir nesneye (`text` / `image` / `audio` / `video` / `pdf`) dönüştürülür; her üst düzey öğe için bir vektör oluşturulur. - Gemini Embedding 2 ailesi: bir üst düzey dizi, `content.parts` (`text` veya `inline_data`) içeren tek bir yerel `models/{model}:embedContent` isteğine dönüştürülür. - Açık modalite meta verileri bulunmayan bilinmeyen/dinamik modeller, yapılandırılmış girdiyi HTTP 400 ile reddeder. ```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" } ``` Desteklenmeyen model/modalite kombinasyonları, öğeyi zorla dönüştürmek yerine HTTP 400 döndürür. Eski dize/token isteklerindeki girdi dışı uzantı alanları değişmeden aktarılmaya devam eder. ```bash # Tüm embedding modellerini listele GET /v1/embeddings ``` --- ## Görsel Oluşturma ```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" } ``` Kullanılabilir sağlayıcılar: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (yerel), ComfyUI (yerel). ```bash # Tüm görsel modellerini listele GET /v1/images/generations ``` --- ## Belge 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`, bir `provider/model` öneki aracılığıyla OCR sağlayıcısını seçer; yalnızca model kimliği (ör. `mistral-ocr-latest`) belirtilirse kayıtlı sağlayıcısına çözümlenir ve `model` atlanırsa varsayılan olarak Mistral (`mistral-ocr-latest`) kullanılır. Kayıtlı sağlayıcılar (`open-sse/config/ocrRegistry.ts`): | Sağlayıcı kimliği | Model kimliği | `model` değeri | Notlar | | ----------------------------- | -------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (veya yalnızca `mistral-ocr-latest`) | Eşzamanlı — yanıt, tek üst akış çağrısından doğrudan döndürülür. | | `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Eşzamansız üst akış (`analyze` + yoklama) — aşağıya bakın. | | `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Eşzamanlı, Vertex AI'ın `openapi/chat/completions` iş ortağı uç noktası üzerinden — kimlik doğrulama/URL için aşağıya bakın. | Üç sağlayıcı da Mistral ile aynı yapıdaki gövdeyle yanıt verir: ```json { "pages": [{ "index": 0, "markdown": "# Extracted text..." }], "model": "mistral-ocr-latest", "usage_info": { "pages_processed": 1 } } ``` ### Azure Document Intelligence yoklama akışı Azure Document Intelligence'ın `analyze` API'si eşzamansızdır: ilk istek, gövde yerine bir `Operation-Location` başlığı döndürür ve sonuç için yoklama yapılması gerekir. İşleyici (`open-sse/handlers/ocr.ts`) bu URL'yi en fazla 30 deneme boyunca saniyede bir yoklar, `ok` olmayan bir yoklama yanıtında veya `"failed"` durumunda hızlıca başarısız olur (yoklamaya devam etmez) ve deneme bütçesi tükendikten sonra işlem hâlâ devam ediyorsa `504` döndürür. Nihai Azure yanıtı, çağırana döndürülmeden önce Mistral tarafından kullanılan aynı `pages`/`markdown` yapısına normalleştirilir; böylece istemci kodunun sağlayıcıya özel durumları ele alması gerekmez. ### Vertex AI DeepSeek OCR kimlik doğrulaması ve uç nokta çözümlemesi `vertex-deepseek-ocr`, OmniRoute'un sohbet/görsel trafiği için zaten desteklediği aynı Vertex AI kimlik doğrulamasını (`open-sse/executors/vertex.ts`) yeniden kullanır: bağlantının API anahtarı, JWT-bearer akışı aracılığıyla kısa ömürlü bir OAuth erişim belirteciyle değiştirilen bir Service Account JSON kimlik bilgisi veya olduğu gibi kullanılan, önceden oluşturulmuş bir OAuth erişim belirtecidir. Üst akış uç noktası URL'si, bağlantının projesi ve bölgesi kullanılarak oluşturulan Vertex'ın genel `openapi/chat/completions` iş ortağı uç noktasıdır — açıkça belirtilen `providerSpecificData.project`/`providerSpecificData.region` her zaman önceliklidir; aksi takdirde proje, Service Account JSON içindeki `project_id` değerinden türetilir ve bölge varsayılan olarak `us-central1` olur. Her iki çözümleme de `open-sse/handlers/ocr.ts` içinde (`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`) gerçekleştirilir ve `handleOcr` işlevine aktarılmadan önce `src/app/api/v1/ocr/route.ts` tarafından kullanılır. --- ## Modelleri Listeleme ```bash GET /v1/models Authorization: Bearer your-api-key → Tüm sohbet, embedding ve görüntü modellerini + kombinasyonlarını OpenAI biçiminde döndürür ``` ### Model kimliği ön ekleri (`?prefix=`) Çoğu model bir **sağlayıcı ön eki** altında sunulur. Hangi ön eki alacağınız, `MODELS_CATALOG_PREFIX_MODE` özellik bayrağı tarafından kontrol edilir ve bir sorgu parametresiyle **her istek için** geçersiz kılınabilir — sunucu genelindeki ayarı diğer herkes için değiştirmeden temiz bir liste isteyen istemciler için kullanışlıdır: ```bash GET /v1/models?prefix=alias # model başına bir kimlik — kısa takma ad ön eki GET /v1/models?prefix=dual # her iki biçim (sunucu varsayılanı) GET /v1/models?prefix=canonical # yalnızca tam sağlayıcı kimliği ön eki ``` | Mod | Üretilen | Notlar | | ----------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dual` | `cc/claude-sonnet-4-6` **ve** `claude/claude-sonnet-4-6` | **Varsayılan.** Her iki kimlik de aynı modele yönlendirilir; iki biçimden birini sabit kodlayan istemci yapılandırmalarının çalışmaya devam etmesi için korunur. Kataloğun boyutunu yaklaşık ikiye katlar. | | `alias` | `cc/claude-sonnet-4-6` | Model başına bir giriş. Ayrı bir takma adı olmayan sağlayıcılar da girişlerini sunmaya devam eder, dolayısıyla hiçbir şey kaybolmaz. | | `canonical` | `claude/claude-sonnet-4-6` | Tam sağlayıcı kimliği ön eki altında model başına bir giriş. Ayrı bir takma adı olmayan sağlayıcılar (ör. `antigravity/…`, `agy/…`) burada da tek kimliklerini sunar, dolayısıyla hiçbir şey kaybolmaz. | `dual` modundaki bir yansı, sorgu parametresi olmadan da tanınabilir: birincil kimliğe işaret eden bir `parent` alanı taşır. Bir model seçici oluşturan istemciler `?prefix=alias` istemelidir — [OmniCopilot VS Code uzantısı](../guides/VSCODE-COPILOT.md) da bunu yapar. ### Düşünmesiz model varyantları Düşünme özelliğine sahip Claude modelleri için `/v1/models`, kimliğinin başına `claude-3-omniroute-no-thinking/` eklenmiş bir **düşünmesiz** varyantı da sunar: ``` claude-3-omniroute-no-thinking// ``` Bu kimliğin seçilmesi (ör. her zaman bir `thinking` bloğu ekleyen Claude Code yapılandırmasında), akıl yürütme devre dışı bırakılarak gerçek `/` modeline çözümlenir — `/v1/messages` yolunda `thinking:{type:"disabled"}` kullanılır veya `/v1/chat/completions` yolunda `reasoning`/`reasoning_effort` alanları kaldırılır. Bu varyant yalnızca düşünmeyi destekleyen **ve** `disabled` değerini kabul eden Claude ailesi modelleri için listelenir (dolayısıyla ör. `disabled` değerini reddeden yalnızca uyarlanabilir modeller hariç tutulur). Operatörler, `ModelSpec.noThinkingAlias` aracılığıyla bu varyantı model başına zorunlu olarak etkinleştirebilir veya devre dışı bırakabilir. --- ## Sağlayıcı Eklentisi Manifesti ```bash GET /api/v1/provider-plugin-manifest ``` Bifrost, CLIProxyAPI ve gelecekteki sidecar yönlendiricileri tarafından kullanılan, JSON açısından güvenli sağlayıcı eklentisi manifestini döndürür. Yanıt, TypeScript sağlayıcı kayıt defterinden oluşturulur ve OAuth istemci sırlarını, çalışma zamanı ortam çözümlemesini, yürütücü işlevlerini, istek başlıklarını ve hesap verilerini bilinçli olarak hariç tutar. Bir sidecar süreç dışında çalıştığında ve `open-sse/config/providerPluginManifestRegistry.ts` dosyasını doğrudan içe aktaramadığında bu uç noktayı kullanın. --- ## Uyumluluk Uç Noktaları | Yöntem | Yol | Biçim | | ------ | ----------------------------------------- | ----------------------------------------- | | 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 (düzenleme/inpainting) | | POST | `/v1/videos/generations` | OpenAI tarzı video oluşturma | | POST | `/v1/music/generations` | OpenAI tarzı müzik oluşturma | | POST | `/v1/audio/transcriptions` | OpenAI Audio (STT) | | POST | `/v1/audio/speech` | OpenAI TTS (ses gövdesi döndürür) | | POST | `/v1/rerank` | Cohere/Voyage tarzı yeniden sıralama | | POST | `/v1/classify` | Jina sınıflandırma (`api.jina.ai`) | | POST | `/v1/segment` | Jina bölümleyici (`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 katalog takma adı | | GET | `/api/v1/vscode/{token}/models` | OpenAI modelleri takma adı | | POST | `/api/v1/vscode/{token}/chat/completions` | OpenAI token tabanlı takma adı | | POST | `/api/v1/vscode/{token}/responses` | OpenAI Responses token tabanlı takma adı | | POST | `/api/v1/vscode/{token}/api/chat` | Ollama token tabanlı takma adı | | GET | `/api/v1/vscode/{token}/api/tags` | Ollama etiketleri token tabanlı takma adı | Tüm POST rotaları aynı yapıyı izler: `Bearer your-api-key` + Zod ile doğrulanmış JSON gövdesi (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` vb.; bkz. `src/shared/validation/schemas.ts`). Şema doğrulaması başarısız olduğunda 4xx döndürülür. `Authorization: Bearer ...` ekleyemeyen istemciler için OmniRoute, sorgu dizesi uyumluluğu (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) veya aşağıda belgelenen özel `/api/v1/vscode/{token}/...` uç noktaları aracılığıyla URL içinde API anahtarlarını da kabul eder. ```bash # Yeniden sıralama POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] } # Jina sınıflandırma (Foundation API kimlik bilgileri) POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] } # Jina bölümleyici POST /v1/segment { "content": "...", "return_chunks": true } # Jina arama (s.jina.ai; sağlayıcı takma adları: jina-search, jina-ai, jina) POST /v1/search { "query": "...", "provider": "jina-search" } # Moderasyonlar POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." } # TTS — audio/mpeg (veya istenen biçimde) gövde döndürür POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" } # Görsel düzenleme (multipart) POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png # Video / müzik oluşturma (sağlayıcı önekli model kimliği) POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." } POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." } ``` ### Özel Sağlayıcı Rotaları ```bash POST /v1/providers/{provider}/chat/completions POST /v1/providers/{provider}/embeddings POST /v1/providers/{provider}/images/generations ``` Eksikse sağlayıcı öneki otomatik olarak eklenir. Eşleşmeyen modeller `400` döndürür. --- ## Files API Toplu girdi/çıktı ve dosya amacıyla yüklemeler için OpenAI uyumlu dosya uç noktası. | Yöntem | Yol | Açıklama | | ------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------- | | POST | `/v1/files` | Dosya yükler (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — en fazla 512 MiB | | GET | `/v1/files` | Kimliği doğrulanmış API anahtarına ait dosyaları listeler | | GET | `/v1/files/[id]` | Bir dosyanın meta verilerini getirir | | DELETE | `/v1/files/[id]` | Bir dosyayı siler | | GET | `/v1/files/[id]/content` | Ham dosya gövdesini akış olarak geri gönderir | **Kimlik doğrulama:** Bearer API anahtarı — dosyaların kapsamı `getApiKeyRequestScope` aracılığıyla API anahtarı bazında belirlenir. Bir anahtar yalnızca kendi dosyalarını görür, indirir ve siler; anahtarı olmayan bir pano oturumu tüm örneği okur; sahibi olmayan bir dosyaya (anonim veya pano oturumu üzerinden yüklenmiş) oturum dışındaki her çağıranın erişimi reddedilir. `GET /v1/files`, `REQUIRE_API_KEY=false` olduğunda bile anonim bir çağıranı ve çözümlenemeyen, sunulmuş bir anahtarı, tüm kiracıların dosyalarını listelemek yerine `401` ile reddeder (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523). --- ## Batches API OpenAI uyumlu toplu işleme. | Yöntem | Yol | Açıklama | | ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | POST | `/v1/batches` | Toplu iş oluşturur — gövde `v1BatchCreateSchema` tarafından doğrulanır (`input_file_id`, `endpoint`, `completion_window`) | | GET | `/v1/batches` | Toplu işleri listeler | | GET | `/v1/batches/[id]` | Toplu iş durumunu ve `request_counts` değerini getirir | | DELETE | `/v1/batches/[id]` | Tamamlanmış/başarısız olmuş bir toplu işi siler | | POST | `/v1/batches/[id]/cancel` | Devam eden bir toplu işi iptal eder | **Kimlik doğrulama:** Bearer API anahtarı. Toplu işlerin kapsamı, dosyalarla aynı üç yönlü kural kapsamında API anahtarı bazında belirlenir: yalnızca kendi anahtarı, örnek genelinde pano oturumu, sahibi null olan kayıtlara ise oturum dışındaki her çağıranın erişimi reddedilir (getirme, silme, iptal etme ve oluşturma sırasındaki `input_file_id` denetimi). `GET /v1/batches`, `REQUIRE_API_KEY=false` olduğunda bile anonim bir çağıranı `401` ile reddeder. --- ## Arama API'si Web/arama sağlayıcısı soyutlaması (Tavily, Brave, Exa, Serper vb.). | Yöntem | Yol | Açıklama | | ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------- | | GET | `/v1/search` | Yapılandırılmış arama sağlayıcılarını ve yeteneklerini listeler | | POST | `/v1/search` | Bir arama sorgusu çalıştırır — gövde `v1SearchSchema` ile doğrulanır, önbelleğe almayı/birleştirmeyi destekler | | GET | `/v1/search/analytics` | Sağlayıcı başına isabet/gecikme/önbellek istatistikleri | **Kimlik doğrulama:** Bearer API anahtarı (`extractApiKey` + `isValidApiKey`). Arama politikası `enforceApiKeyPolicy` aracılığıyla uygulanır. --- ## Web Getirme API'si Yapılandırılmış bir web getirme sağlayıcısı (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract) aracılığıyla bir URL'den içerik çıkarır. | Yöntem | Yol | Açıklama | | ------ | --------------- | ------------------------------------------------------------------ | | POST | `/v1/web/fetch` | Bir URL'yi getirir/tarar — gövde `v1WebFetchSchema` ile doğrulanır | **Kimlik doğrulama:** Bearer API anahtarı (`extractApiKey` + `isValidApiKey`). Politika `enforceApiKeyPolicy` aracılığıyla uygulanır. **Kota duyarlı geri dönüş (#8297):** Açıkça bir `provider` belirtilmediğinde havuz (`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) sabit öncelik sırasıyla (önce doldurma) dolaşılır — hız sınırına takılmış ancak yapılandırılmış bir sağlayıcı, isteği hemen sonlandırmak yerine atlanır ve yeniden denenebilir/kota kaynaklı bir üst hizmet hatasında (HTTP 429 her zaman; Firecrawl/Tavily/TinyFish'in kota türü ücretsiz katmanları için 402/403 — Jina Reader için değil ve basit bir 400 hatalı istek için hiçbir zaman değil) istek sırasında henüz denenmemiş, kimlik bilgileri mevcut bir sonraki sağlayıcıya geçilir. Havuzdaki tüm sağlayıcılar tükendiğinde uç nokta, önceki genel `400` yerine tek bir `429` (`Retry-After` üstbilgisiyle birlikte) döndürür. Açıkça bir `provider` istendiğinde **sessiz bir geri dönüş yoktur** — hız sınırına takılan veya başarısız olan açık sağlayıcının kendi hatası yansıtılır (hız sınırına takılmışsa `429`, aksi takdirde üst hizmetin durumu). --- ## WebSocket Akışı ```bash GET /v1/ws?handshake=1 ``` Bir WebSocket yükseltme el sıkışmasını doğrular ve kablo protokolü örnek mesajlarını (`request`, `cancel`) döndürür. Gerçek WS çerçeveleri, Next.js rota tablosunun dışında paketlenmiş WS sunucusu tarafından işlenir. **Kimlik doğrulama:** El sıkışma sırasında Bearer API anahtarı. ### WebSocket üzerinden Responses API (yalnızca codex) ```bash # HTTP API'siyle aynı ana makine:bağlantı noktası (varsayılan 20128); bağlantıyı yükseltin: wscat -c "ws://localhost:20128/v1/responses?api_key=" # (veya: -H "Authorization: Bearer ") # İlk çerçeve MUTLAKA response.create olmalıdır: { "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] } ``` WebSocket üzerinden Responses API proxy'si **yalnızca `codex`e** (ChatGPT arka ucu) bağlıdır. API/pano ile aynı bağlantı noktasında `/v1/responses`, `/responses` ve `/api/v1/responses` yollarını dinler. İlk `response.create` çerçevesinde dahili `codex-responses-ws` köprüsü aracılığıyla kimlik doğrular ve hazırlık yapar, bir codex OAuth bağlantısı seçer ve `wreq-js` aktarımı üzerinden `wss://chatgpt.com/backend-api/codex/responses` adresine tünel oluşturur. **Codex dışındaki modeller reddedilir** (`codex_ws_provider_required`). Kota paylaşımlı yönlendirme için `model: "qtSd//codex/"` kullanın. Uygulama `app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts` içindedir. **Kimlik doğrulama:** El sıkışma sırasında Bearer API anahtarı. Paketlenmiş HTTP sunucusu (`server-ws.mjs`) etkin giriş noktası olmalıdır (`app/server-ws.mjs` mevcut olduğunda varsayılan olarak öyledir). #### Model kimliği: sade ChatGPT kimliğini kullanın (`codex/` öneki olmadan) OpenAI **Codex CLI**, `supports_websockets = true` olduğunda model adını istemci tarafında doğrular ve `codex/gpt-5.5` gibi **sağlayıcı önekli kimlikleri reddeder** (`The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account`). **Sade** kimliği gönderin (ör. `gpt-5.5`). OmniRoute'un köprüsü yalnızca codex içindir; bu nedenle sade bir kimliği, üst hizmete tünellemeden önce codex modeli olarak yeniden çözümler (`resolveCodexWsModelInfo`) — sade `gpt-5.5` aksi takdirde HTTP üzerinden başka bir sağlayıcıya yönlendirilecek olsa bile. #### OpenAI Codex CLI'ı yapılandırma `~/.codex/config.toml` dosyasına WebSocket desteğine sahip özel bir sağlayıcı ekleyerek Codex CLI'ı OmniRoute'a yönlendirin (mevcut bir yapılandırmaya dokunmamak için ayrı bir `CODEX_HOME` kullanın): ```toml model = "gpt-5.5" # sade kimlik — "codex/gpt-5.5" DEĞİL model_provider = "omniroute" [model_providers.omniroute] name = "OmniRoute (WS)" base_url = "http://localhost:20128/v1" # sonunda eğik çizgi yok; WS URL'si türetilir (üretimde https/wss kullanın) wire_api = "responses" # Şubat 2026'dan beri desteklenen tek değer supports_websockets = true # Responses-over-WS aktarımını etkinleştirir env_key = "OMNIROUTE_API_KEY" # OmniRoute API anahtarını içerir (Bearer) ``` ```bash export OMNIROUTE_API_KEY=sk-... # bir OmniRoute API anahtarı (REQUIRE_API_KEY=false ise herhangi bir anahtar) codex exec "Responda apenas: PONG" ``` CLI, `base_url + /responses` adresini bir WebSocket'e yükseltir ve OmniRoute bunu seçilen codex OAuth bağlantısına tüneller. Yerel sunucuya karşı uçtan uca doğrulanmıştır: ChatGPT, `codex.rate_limits` + `response.created` döndürür ve tamamlamayı akış halinde iletir. --- ## Kota ve Sorun Bildirimi | Yöntem | Yol | Açıklama | | ------ | ------------------- | ------------------------------------------------------------------------------------------- | | GET | `/v1/quotas/check` | Kayıtlı bir anahtar oluşturmadan önce `provider` + `accountId` kotasını önceden doğrular | | POST | `/v1/issues/report` | Kota/anahtar oluşturma hatasını GitHub'a bildirir (`GITHUB_ISSUES_REPO` + token gerektirir) | **Kimlik doğrulama:** Bearer API anahtarı (`isAuthenticated`). --- ## Self servis kullanım (`/api/usage/om-usage`) Herhangi bir API anahtarı, yönetim kimlik doğrulaması olmadan **kendi** kullanımını ve kotalarını okuyabilir. Bu, bir istemcinin (CLI, OmniCopilot paneli) anahtar sahibine harcamalarını göstermek için kullandığı uç noktadır. ```bash # Metin biçimi (tarihsel sözleşme — terminal için düz metin) curl -H "Authorization: Bearer " \ http://localhost:20128/api/usage/om-usage # Yapılandırılmış biçim — bir kullanıcı arayüzünün kullandığı biçim curl -H "Authorization: Bearer " \ "http://localhost:20128/api/usage/om-usage?format=json" ``` Anahtarda **`allowUsageCommand`** etkinleştirilmiş olmalıdır (varsayılan olarak kapalıdır — kontrol panelinin API anahtarı yöneticisi bunu her anahtar için ayrı ayrı değiştirir). Bu özellik olmadan uç nokta `403` yanıtını verir. `?format=json`, çağıranın reddedilmiş bir yanıttan hiçbir zaman veri alanı okumaması için ayırt edilebilir bir yapı döndürür. Başarılı olduğunda: ```jsonc { "allowed": true, // yalnızca anahtar, anahtar başına kullanım sınırlarını (günlük/haftalık USD) etkinleştirdiğinde bulunur: "personal": { "dailySpentUsd": 1.25, "dailyLimitUsd": 5, "dailyResetAtIso": "…", "weeklySpentUsd": 8, "weeklyLimitUsd": 20, "weeklyResetAtIso": "…" /* … */, }, // seçilen sağlayıcının kota anlık görüntüsü veya henüz hiçbir şey önbelleğe alınmadıysa null: "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */}, }, // kullanıcı arayüzünün birden fazla sağlayıcıyı yan yana görüntüleyebilmesi için her bağlantının anlık görüntüsü: "providers": [ { "connectionId": "…", "provider": "claude" /* … */ }, { "provider": "codex" /* … */ }, ], } ``` Reddedildiğinde (`401` hatalı anahtar / `403` izin verilmedi) aynı rota `{ "allowed": false, "error": { "message": "…" } }` döndürür. Mevcut ancak boş bir `personal`/`provider` (anahtara izin verilmiş ancak henüz hiçbir şey öğrenilmemiş) reddedilmeden farklı bir durumdur ve bunları yalnızca JSON biçimi birbirinden ayırır. **Kimlik doğrulama:** Çağıranın kendi Bearer API anahtarı, `isValidApiKey` ile doğrulanır. Bu, `requireManagementAuth` arkasında kalmaya devam eden yönetim yüzeyi (`/api/keys/…`) _değildir_. --- ## Semantik Önbellek ```bash # Önbellek istatistiklerini al GET /api/cache/stats # Tüm önbellekleri temizle DELETE /api/cache/stats ``` Yanıt örneği: ```json { "semanticCache": { "memorySize": 42, "memoryMaxSize": 500, "dbSize": 128, "hitRate": 0.65 }, "idempotency": { "activeKeys": 3, "windowMs": 5000 } } ``` ### Gecikme etkisi Bir semantik önbellek İSABETİ, yanıtı **üst sağlayıcı çağrısı yapmadan** önbellekten sunar; bu nedenle bildirilen `X-OmniRoute-Response-Latency`, orijinal üst sağlayıcı gecikmesinden bağımsız olarak sıfıra yakındır. Gecikmeye duyarlı istemciler (performans karşılaştırması, p50/p99 izleme) `X-OmniRoute-Cache-Latency` yanıt başlığını kontrol etmelidir: | Değer | Anlamı | | ----------- | -------------------------------------------------------------------- | | `synthetic` | Yanıt önbellekten sunuldu; gecikme gerçek üst sağlayıcı süresi değil | | _(yok)_ | Yanıt gerçek üst sağlayıcı çağrısından geldi | ### Anahtar başına önbelleği atlama API anahtarları, `cacheDefaultMode` aracılığıyla semantik önbellek okumalarını devre dışı bırakabilir: | Değer | Davranış | | -------- | ----------------------------------------------------------------- | | `legacy` | Normal önbellek davranışı (varsayılan) | | `bypass` | Önbellek aramasını tamamen atla; her zaman üst sağlayıcıya başvur | Anahtar oluşturulurken (`POST /api/keys`) ayarlayın veya (`PATCH /api/keys/[id]`) güncelleyin: ```json { "cacheDefaultMode": "bypass" } ``` ### İstek başına atlama Herhangi bir istek, anahtar ayarlarından bağımsız olarak önbelleği atlayabilir: ``` X-OmniRoute-No-Cache: true ``` --- ## Kontrol Paneli ve Yönetim Yönetim rotaları (`/api/*`, genel auth/login hariç) sıradan çıkarım API anahtarlarıyla **yetkilendirilmez**. Kimlik bilgisi aileleri, kapsamlar ve curl örnekleri: [Yönetim Kimlik Doğrulaması](../guides/MANAGEMENT-AUTH.md). ### Kimlik Doğrulama | Uç Nokta | Yöntem | Açıklama | | ----------------------------- | ------- | ---------------------------------- | | `/api/auth/login` | POST | Oturum açma | | `/api/auth/logout` | POST | Oturumu kapatma | | `/api/settings/require-login` | GET/PUT | Oturum açma gereksinimini aç/kapat | ### Sağlayıcı Yönetimi | Uç Nokta | Yöntem | Açıklama | | ---------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `/api/providers` | GET/POST | Sağlayıcıları listeleme / oluşturma | | `/api/providers/[id]` | GET/PUT/DELETE | Bir sağlayıcıyı yönetme | | `/api/providers/[id]/test` | POST | Sağlayıcı bağlantısını test etme | | `/api/providers/[id]/models` | GET | Sağlayıcı modellerini listeleme | | `/api/providers/validate` | POST | Sağlayıcı yapılandırmasını doğrulama | | `/api/providers/bulk` | POST | TEK bir sağlayıcı için API anahtarlarını toplu olarak ekleme | | `/api/providers/import` | POST | Ayrıştırılmış bir CSV/JSON dosyasından heterojen bir sağlayıcı LİSTESİNİ içe aktarma (#6836); satır bazında kısmi hata sonuçları | | `/api/provider-nodes*` | Çeşitli | Sağlayıcı düğümü yönetimi | | `/api/provider-models` | GET/POST/PATCH/DELETE | Özel modeller (ekleme, güncelleme, gizleme/gösterme, silme) | ### OAuth Akışları | Uç Nokta | Yöntem | Açıklama | | -------------------------------- | ------- | ---------------------- | | `/api/oauth/[provider]/[action]` | Çeşitli | Sağlayıcıya özgü OAuth | ### Yönlendirme ve Yapılandırma | Uç Nokta | Yöntem | Açıklama | | --------------------- | -------- | ----------------------------------- | | `/api/models/alias` | GET/POST | Model takma adları | | `/api/models/catalog` | GET | Sağlayıcı ve türe göre tüm modeller | | `/api/combos*` | Çeşitli | Kombinasyon yönetimi | | `/api/keys*` | Çeşitli | API anahtarı yönetimi | | `/api/pricing` | GET | Model fiyatlandırması | ### Kullanım ve Analizler | Uç Nokta | Yöntem | Açıklama | | -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/api/usage/history` | GET | Kullanım geçmişi | | `/api/usage/logs` | GET | Kullanım günlükleri | | `/api/usage/request-logs` | GET | İstek düzeyindeki günlükler | | `/api/usage/[connectionId]` | GET | Bağlantı başına kullanım | | `/api/usage/token-limits` | GET/POST/DELETE | API anahtarı başına token sınırı bütçeleri | | `/api/usage/model-latency-stats` | GET | Sağlayıcı/model başına hareketli gecikme istatistikleri (ort./p50/p95/p99, başarı oranı); filtreler: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) | | `/api/usage/cache-health` | GET | `call_logs` üzerindeki istem önbelleği sağlığı özeti — yazma/okuma oranı, p50/p90/p99 yazma boyutu dağılımı, yoğun yazma konsantrasyonu, model bazında dağılım ve `healthy`/`degraded`/`thrash`/`no-data` değerlendirmesi; sorgu parametreleri: `range` (`1h`\|`24h`\|`7d`\|`30d`, varsayılan `24h`) ve isteğe bağlı `model` (#8827) | ### Ayarlar | Uç Nokta | Yöntem | Açıklama | | ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `/api/settings` | GET/PUT/PATCH | Genel ayarlar | | `/api/settings/proxy` | GET/PUT | Ağ proxy yapılandırması | | `/api/settings/proxy/test` | POST | Proxy bağlantısını test et | | `/api/settings/ip-filter` | GET/PUT | IP izin listesi/engelleme listesi | | `/api/settings/thinking-budget` | GET/PUT | Düşünme/akıl yürütme **isteği** yeniden yazma modu (aynen iletme / otomatik çıkarma / özel / uyarlanabilir). Sıkıştırmadan bağımsızdır. Bkz. [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). | | `/api/settings/system-prompt` | GET/PUT | Genel sistem istemi | | `/api/settings/compression` | GET/PUT | Genel sıkıştırma yapılandırması | | `/api/settings/purge-request-history` | POST | İstek günlüğü satırlarını ve yerel çağrı günlüğü yapılarını temizle | ### Bağlam ve Sıkıştırma | Uç Nokta | Yöntem | Açıklama | | -------------------------------------- | -------------- | ---------------------------------------------------------------------- | | `/api/compression/preview` | POST | off/lite/standard/aggressive/ultra/RTK/stacked sıkıştırmasını önizleme | | `/api/compression/language-packs` | GET | Kullanılabilir Caveman dil paketlerini listeleme | | `/api/compression/rules` | GET | Caveman kural meta verilerini listeleme | | `/api/context/caveman/config` | GET/PUT | Caveman'a özgü ayarlar için diğer ad | | `/api/context/rtk/config` | GET/PUT | Özel filtreler ve ham çıktı saklama dâhil RTK'ye özgü ayarlar | | `/api/context/rtk/filters` | GET | RTK filtre kataloğu ve özel filtre tanılamaları | | `/api/context/rtk/test` | POST | Bir metin yükünde RTK önizlemesini/testini çalıştırma | | `/api/context/rtk/raw-output/[id]` | GET | İşaretçi kimliğine göre saklanan redakte edilmiş ham çıktıyı okuma | | `/api/context/combos` | GET/POST | Sıkıştırma kombinasyonlarını listeleme/oluşturma | | `/api/context/combos/[id]` | GET/PUT/DELETE | Sıkıştırma kombinasyonu ayrıntısı/güncelleme/silme | | `/api/context/combos/[id]/assignments` | GET/PUT | Sıkıştırma kombinasyonlarını yönlendirme kombinasyonlarına atama | | `/api/context/analytics` | GET | Sıkıştırma analitiği için diğer ad | ### İzleme | Uç Nokta | Yöntem | Açıklama | | ------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/api/sessions` | GET | Etkin oturum takibi | | `/api/rate-limits` | GET | Hesap başına hız sınırları | | `/api/monitoring/health` | GET | Sistem durumu denetimi + sağlayıcı özeti (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Yönetim görünümü `credentialHealth` alanını içerir: yoklama önbelleği skalerleri, `failed>0` olduğunda `failedConnections` ve `staleDbNonOkCount` (ölçüm göstergesi değil, kalıcı SQLite `test_status` değeri). Bkz. [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). | | `/api/cache/stats` | GET/DELETE | Önbellek istatistikleri / temizleme | | `/api/modality-bridge/stats` | GET | Bellek içi `attempts`, başarılar/`bridged`, başarısızlıklar, önbellek isabetleri, `totalLatencyMs`, `latencySamples`, örnek sayısını temel alan `averageLatencyMs` ve son kullanım zamanı (yeniden başlatıldığında sıfırlanır; yönetim kimlik doğrulaması) | | `/api/modality-bridge/video/runtime` | GET | Yönetim kimlik doğrulaması/yoklamasından önce katı güvenilir geri döngü denetimi; arındırılmış FFmpeg/ffprobe kullanılabilirlik ve sürüm bilgileri (no-store) | | `/api/modality-bridge/video/extract` | POST | Dahili, kimliği doğrulanmış güvenilir geri döngü bayt aracısı; 50 MiB girdi, sınırlandırılmış kuyruk/32 MiB çıktı, kapasite için `503`, bağlantı kesilmesi için `499`, son süre için `504`; herkese açık bir yükleme API'si değildir | ### Yedekleme ve Dışa/İçe Aktarma | Uç Nokta | Yöntem | Açıklama | | --------------------------- | ------ | ------------------------------------------- | | `/api/db-backups` | GET | Kullanılabilir yedekleri listele | | `/api/db-backups` | PUT | Manuel yedek oluştur | | `/api/db-backups` | POST | Belirli bir yedekten geri yükle | | `/api/db-backups/export` | GET | Veritabanını .sqlite dosyası olarak indir | | `/api/db-backups/import` | POST | Veritabanını değiştirmek için .sqlite yükle | | `/api/db-backups/exportAll` | GET | Tam yedeği .tar.gz arşivi olarak indir | ### Bulut Senkronizasyonu | Uç Nokta | Yöntem | Açıklama | | ---------------------- | ------- | ------------------------------- | | `/api/sync/cloud` | Çeşitli | Bulut senkronizasyonu işlemleri | | `/api/sync/initialize` | POST | Senkronizasyonu başlat | | `/api/cloud/*` | Çeşitli | Bulut yönetimi | ### Tüneller | Uç Nokta | Yöntem | Açıklama | | -------------------------- | ------ | ------------------------------------------------------------------------------------- | | `/api/tunnels/cloudflared` | GET | Pano için Cloudflare Quick Tunnel kurulum/çalışma durumunu oku | | `/api/tunnels/cloudflared` | POST | Cloudflare Quick Tunnel'ı etkinleştir veya devre dışı bırak (`action=enable/disable`) | | `/api/tunnels/ngrok` | GET | Pano için ngrok Tunnel çalışma durumunu oku | | `/api/tunnels/ngrok` | POST | ngrok Tunnel'ı etkinleştir veya devre dışı bırak (`action=enable/disable`) | ### CLI Araçları | Uç Nokta | Yöntem | Açıklama | | ---------------------------------- | ------ | ------------------------ | | `/api/cli-tools/claude-settings` | GET | Claude CLI durumu | | `/api/cli-tools/codex-settings` | GET | Codex CLI durumu | | `/api/cli-tools/droid-settings` | GET | Droid CLI durumu | | `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI durumu | | `/api/cli-tools/runtime/[toolId]` | GET | Genel CLI çalışma zamanı | CLI yanıtları şunları içerir: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`. ### ACP Aracıları | Uç Nokta | Yöntem | Açıklama | | ----------------- | ------ | ----------------------------------------------------------------------- | | `/api/acp/agents` | GET | Durumlarıyla birlikte algılanan tüm aracıları listele (yerleşik + özel) | | `/api/acp/agents` | POST | Özel aracı ekle veya algılama önbelleğini yenile | | `/api/acp/agents` | DELETE | `id` sorgu parametresine göre özel bir aracıyı kaldır | GET yanıtı, `agents[]` (id, name, binary, version, installed, protocol, isCustom) ve `summary` (total, installed, notFound, builtIn, custom) içerir. ### Dayanıklılık ve Hız Sınırları | Uç Nokta | Yöntem | Açıklama | | --------------------------------- | --------- | --------------------------------------------------------------------------------------------------- | | `/api/resilience` | GET/PATCH | İstek kuyruğu, bağlantı bekleme süresi, sağlayıcı devre kesicisi ve bekleme ayarlarını al/güncelle | | `/api/resilience/reset` | POST | Sağlayıcı devre kesicilerini sıfırla | | `/api/resilience/model-cooldowns` | GET | Etkin (sağlayıcı, bağlantı, model) bazlı kilitlenmeleri kalan süreye göre sıralayarak listele | | `/api/resilience/model-cooldowns` | DELETE | Bir model kilitlenmesini temizle — gövde: `{provider, model}` veya tümünü silmek için `{all: true}` | | `/api/rate-limits` | GET | Hesap bazında hız sınırı durumu | | `/api/rate-limit` | GET | Genel hız sınırı yapılandırması | > Dört `/api/resilience/*` rotasının tümü **yönetim kimlik doğrulaması** (`requireManagementAuth`) gerektirir. Sağlayıcı devre kesicisi, bağlantı bekleme süresi ve model kilitlenmesi arasındaki farkların ayrıntılı açıklaması için [Dayanıklılık (genişletilmiş)](#resilience-extended) bölümüne bakın. ### Değerlendirmeler | Uç Nokta | Yöntem | Açıklama | | ------------ | -------- | ---------------------------------------------------------- | | `/api/evals` | GET/POST | Değerlendirme paketlerini listele / değerlendirme çalıştır | ### Politikalar | Uç Nokta | Yöntem | Açıklama | | --------------- | --------------- | -------------------------------- | | `/api/policies` | GET/POST/DELETE | Yönlendirme politikalarını yönet | ### Uyumluluk | Uç Nokta | Yöntem | Açıklama | | --------------------------- | ------ | --------------------------------- | | `/api/compliance/audit-log` | GET | Uyumluluk denetim günlüğü (son N) | ### v1beta (Gemini Uyumlu) | Uç Nokta | Yöntem | Açıklama | | -------------------------- | ------ | ----------------------------------- | | `/v1beta/models` | GET | Modelleri Gemini biçiminde listele | | `/v1beta/models/{...path}` | POST | Gemini `generateContent` uç noktası | Bu uç noktalar, yerel Gemini SDK uyumluluğu bekleyen istemciler için Gemini'nin API biçimini yansıtır. ### Dahili / Sistem API'leri | Uç Nokta | Yöntem | Açıklama | | ------------------------ | ------ | ----------------------------------------------------------- | | `/api/init` | GET | Uygulama başlatma denetimi (ilk çalıştırmada kullanılır) | | `/api/tags` | GET | Ollama uyumlu model etiketleri (Ollama istemcileri için) | | `/api/restart` | POST | Sunucunun kontrollü şekilde yeniden başlatılmasını tetikler | | `/api/shutdown` | POST | Sunucunun kontrollü şekilde kapatılmasını tetikler | | `/api/system/env/repair` | POST | OAuth sağlayıcısı ortam değişkenlerini onarır | > **Not:** Bu uç noktalar, sistem tarafından dahili olarak veya Ollama istemci uyumluluğu için kullanılır. Genellikle son kullanıcılar tarafından çağrılmazlar. ### OAuth Ortam Değişkenlerini Onarma _(v3.6.1+)_ ```bash POST /api/system/env/repair Content-Type: application/json { "provider": "claude-code" } ``` Belirli bir sağlayıcı için eksik veya bozuk OAuth ortam değişkenlerini onarır. Şunu döndürür: ```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" } ``` --- ## Ses Transkripsiyonu ```bash POST /v1/audio/transcriptions Authorization: Bearer your-api-key Content-Type: multipart/form-data ``` Yapılandırılmış herhangi bir STT sağlayıcısını kullanarak ses dosyalarını yazıya dökün. İlk yol segmenti yerel sağlayıcıyı seçer (`openai/…`, `deepgram/…`). Başka bir sağlayıcının modelini yeniden dışa aktaran ağ geçitleri nitelikli bir kimlik kullanır (`openrouter/deepgram/nova-3`). **İstek:** ```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" ``` **Yanıt:** ```json { "text": "Hello, this is the transcribed audio content.", "task": "transcribe", "language": "en", "duration": 12.5 } ``` **Örnek model kimlikleri:** `openai/whisper-1` (bir OpenAI anahtarı gerektirir), `openrouter/deepgram/nova-3` (bir OpenRouter anahtarı gerektirir), `deepgram/nova-3` (yerel bir Deepgram anahtarı gerektirir). Yalın bir `deepgram/nova-3` isteği OpenRouter'ı **kullanmaz**. **Desteklenen biçimler:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`. --- ## Ollama Uyumluluğu Ollama'nın API biçimini kullanan istemciler için: ```bash # Sohbet uç noktası (Ollama biçimi) POST /v1/api/chat # Model listeleme (Ollama biçimi) GET /api/tags ``` İstekler, Ollama ile dahili biçimler arasında otomatik olarak dönüştürülür. ## Token İçeren VS Code / Başlıksız Takma Adlar Bir entegrasyon `Authorization` başlığı ekleyemediğinde ve API anahtarının temel URL'ye gömülmesi gerektiğinde bu takma adları kullanın. ```bash # OpenAI tarzı katalog takma adı GET /api/v1/vscode/{token}/ GET /api/v1/vscode/{token}/models # OpenAI tarzı sohbet takma adları POST /api/v1/vscode/{token}/chat/completions POST /api/v1/vscode/{token}/responses # Ollama tarzı takma adlar POST /api/v1/vscode/{token}/api/chat GET /api/v1/vscode/{token}/api/tags ``` Örnek: ```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"}]}' ``` Notlar: - Token içeren takma adlar, `/v1/*` ve `/api/tags` ile aynı işleyicileri yeniden kullanır; yanıt yapıları aynı kalır. - İstemci özel başlıkları desteklediğinde `Authorization: Bearer ...` kullanımını tercih edin. - URL tabanlı token'lar ters proxy günlüklerinde, tarayıcı geçmişinde ve OmniRoute dışındaki telemetride görünebilir. Bunları varsayılan kimlik doğrulama modu olarak değil, bir uyumluluk seçeneği olarak değerlendirin. --- ## Telemetri ```bash # Gecikme telemetrisi özetini al (sağlayıcı başına p50/p95/p99) GET /api/telemetry/summary ``` **Yanıt:** ```json { "providers": { "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 }, "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 } } } ``` --- ## Bütçe ```bash # Tüm API anahtarlarının bütçe durumunu al GET /api/usage/budget # Bir bütçe belirle veya güncelle 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" } ``` > **Şema notları** (`setBudgetSchema`): `apiKeyId` zorunludur; `dailyLimitUsd`, `weeklyLimitUsd` veya `monthlyLimitUsd` alanlarından en az biri sıfırdan büyük olmalıdır. İsteğe bağlı alanlar: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Eski `{keyId, limit, period}` yapısı `400 Bad Request` döndürür. ## Token Sınırları API anahtarı başına **token** bütçeleri (yukarıdaki USD tabanlı Bütçeden farklıdır). İstek yolunda doğrudan uygulanır: Bir anahtarın geçerli pencere kullanımı sınırına ulaştığında istekler `429 Too Many Requests` ile reddedilir. Sınırlar belirli bir `model` veya `provider` ile kapsamlandırılabilir ya da anahtar genelinde `global` olarak uygulanabilir; birden fazla sınır bir istekle eşleştiğinde en kısıtlayıcı olan geçerli olur. ```bash # Bir anahtarın token sınırlarını listele (canlı pencere kullanımını içerir) GET /api/usage/token-limits?apiKeyId=key-123 # Bir token sınırı oluştur veya güncelle POST /api/usage/token-limits Content-Type: application/json { "apiKeyId": "key-123", "scopeType": "model", "scopeValue": "openai/gpt-4o", "tokenLimit": 1000000, "resetInterval": "monthly", "enabled": true } # Kimliğe göre bir token sınırını sil DELETE /api/usage/token-limits?id=tl-abc ``` > **Şema notları** (`setTokenLimitSchema`): `apiKeyId` ve `scopeType` (`model` | `provider` | `global`) zorunludur. `scopeType`, `global` olmadığı sürece `scopeValue` zorunludur (ör. `model` kapsamı için bir model kimliği, `provider` kapsamı için bir sağlayıcı kimliği). `tokenLimit` pozitif bir tam sayı olmalıdır (dizeden dönüştürülür). İsteğe bağlı: `id` (oluşturmak için dahil etmeyin, güncellemek için belirtin), `resetInterval` (`daily` | `weekly` | `monthly`, varsayılan `monthly`), `resetTime` (`HH:MM`), `enabled` (varsayılan `true`). `GET` yanıtları her sınırı `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` ve `nextResetAt` ile zenginleştirir. Bu, yönetim sınıfı bir uç noktadır (kimlik doğrulama, authz işlem hattı tarafından merkezi olarak uygulanır). ## İstek İşleme 1. İstemci `/v1/*` adresine istek gönderir 2. Rota işleyicisi `handleChat`, `handleEmbedding`, `handleAudioTranscription` veya `handleImageGeneration` çağrısını yapar 3. Model çözümlenir (doğrudan sağlayıcı/model veya takma ad/kombinasyon) 4. Kimlik bilgileri, hesap kullanılabilirliği filtrelenerek yerel veritabanından seçilir 5. Sohbet için: `handleChatCore`, semantik/imza önbelleğini kontrol eder ve kombinasyon sıkıştırma ayarlarını çözümler 6. Etkinleştirildiğinde proaktif sıkıştırma, sağlayıcı çevirisinden önce çalışır (`lite`, Caveman, RTK veya yığınlanmış) 7. Sağlayıcı yürütücüsü yukarı akış isteğini gönderir 8. Yanıt, istemci biçimine geri çevrilir (sohbet) veya olduğu gibi döndürülür (gömme/görsel/ses) 9. Kullanım, sıkıştırma analizleri ve istek günlükleri kaydedilir 10. Hatalarda, kombinasyon kurallarına göre geri dönüş uygulanır Tam mimari başvurusu: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md) --- ## Kombinasyon Yönetimi Daha üst düzey yönlendirme kombinasyonları (daha önce `/api/combos*` altında özetlenmiştir), bir model kimliği deseninden bire bir eşlenerek OpenAI tarzı bir model kimliğinin şeffaf biçimde bir kombinasyona yönlendirilmesini de sağlayabilir. | Yöntem | Yol | Açıklama | | ------ | -------------------------------- | ------------------------------------------------------------------------------- | | GET | `/api/model-combo-mappings` | Tüm model→kombinasyon eşlemelerini listele | | POST | `/api/model-combo-mappings` | Eşleme oluştur — gövde: `{pattern, comboId, priority?, enabled?, description?}` | | GET | `/api/model-combo-mappings/[id]` | Tek bir eşlemeyi getir | | PUT | `/api/model-combo-mappings/[id]` | Mevcut bir eşlemenin alanlarını güncelle | | DELETE | `/api/model-combo-mappings/[id]` | Bir eşlemeyi kaldır | **Kimlik doğrulama:** yönetim oturumu/API anahtarı (`requireManagementAuth`). --- ## Webhook'lar OmniRoute olayları (istek tamamlanması, kotanın tükenmesi, anahtar rotasyonu vb.) için giden webhook abonelikleri. | Yöntem | Yol | Açıklama | | ------ | ------------------------- | ------------------------------------------------------------------------- | | GET | `/api/webhooks` | Webhook'ları listele (gizli anahtarlar `...` şeklinde maskelenir) | | POST | `/api/webhooks` | Webhook oluştur — gövde: `{url, events?: ["*"], secret?, description?}` | | GET | `/api/webhooks/[id]` | Bir webhook'u getir | | PUT | `/api/webhooks/[id]` | url/events/secret/description alanlarını güncelle | | DELETE | `/api/webhooks/[id]` | Bir webhook'u kaldır | | POST | `/api/webhooks/[id]/test` | Webhook URL'sine bir test yükü gönder ve teslimat durumunu döndür | **Kimlik doğrulama:** yönetim oturumu/API anahtarı (`requireManagementAuth`). --- ## Kayıtlı Anahtarlar (Otomatik Yönetim) Otomatik anahtar yönetimi alt sistemi tarafından, günlük/saatlik kotalarla bir arka uç sağlayıcısı/hesabı üzerinden API anahtarları oluşturmak ve döndürmek için kullanılır. | Yöntem | Yol | Açıklama | | ------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/registered-keys` | Kayıtlı anahtarları listele (yalnızca maskelenmiş ön ek) | | POST | `/api/v1/registered-keys` | Yeni bir kayıtlı anahtar oluştur — gövde: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Ham anahtarı **bir kez** döndürür. Kota reddinde `429` döndürür. | | GET | `/api/v1/registered-keys/[id]` | Kayıtlı bir anahtarın meta verilerini getir (ham anahtar materyali olmadan) | | DELETE | `/api/v1/registered-keys/[id]` | Kayıtlı bir anahtarı iptal et | | POST | `/api/v1/registered-keys/[id]/revoke` | Açık iptal uç noktası (DELETE ile aynı etkiye sahiptir) | **Kimlik doğrulama:** Bearer API anahtarı (`isAuthenticated`). Ayrıca `/v1/quotas/check` ve `/v1/issues/report` bölümlerine bakın. --- ## Ajanlar Protokolü OmniRoute kullanıcıları adına uzaktan yürütülen bulut ajanı görevleri (Claude Code, Codex Cloud, OpenHands vb.). | Yöntem | Yol | Açıklama | | ------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/agents/tasks` | Görevleri listeler — isteğe bağlı `?provider=`, `?status=`, `?limit=` (1–500, varsayılan 50) | | POST | `/api/v1/agents/tasks` | Görev oluşturur — gövde `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`) ile doğrulanır. Görev zarfıyla birlikte `201` döndürür | | DELETE | `/api/v1/agents/tasks?id=...` | Bir görevi siler | | GET | `/api/v1/agents/tasks/[id]` | Görevi okur — bir `external_id` ayarlandığında durumu üst akış bulut ajanından eşzamanlı olarak yeniler | | POST | `/api/v1/agents/tasks/[id]` | Ayrıştırılmış eylem: `{action: "approve"}`, `{action: "message", message}` veya `{action: "cancel"}` | | DELETE | `/api/v1/agents/tasks/[id]` | Belirli bir görevi kimliğine göre siler | > **Kimlik doğrulama:** her yöntemde yönetim kimlik doğrulaması gereklidir (`requireCloudAgentManagementAuth`). v3.8.0 öncesinde bunlar kimlik doğrulamasızdı — uyumluluğu bozan değişiklik için `588a0333` commit'ine bakın. ```bash # Bir Claude Code bulut görevi oluşturun 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":"..."}}' ``` --- ## Yönetim Proxy'leri Sağlayıcılara, hesaplara veya genel olarak atanabilen giden HTTP(S)/SOCKS proxy'leri. | Yöntem | Yol | Açıklama | | ------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/v1/management/proxies` | Proxy'leri listeler (`?id=` ile bir tanesini, `?id=&where_used=1` ile atama grafiğini döndürür) | | POST | `/api/v1/management/proxies` | Proxy oluşturur — gövde `createProxyRegistrySchema` ile doğrulanır | | PATCH | `/api/v1/management/proxies` | Proxy'yi günceller — gövde `updateProxyRegistrySchema` ile doğrulanır (`id` gerektirir) | | DELETE | `/api/v1/management/proxies?id=...&force=1` | Proxy'yi siler (atamaları kaldırmak için `force=1` kullanın) | | GET | `/api/v1/management/proxies/assignments` | Atamaları listeler — `proxy_id`, `scope`, `scope_id` ile filtrelenebilir; bir bağlantının etkin proxy'sini çözümlemek için `resolve_connection_id=` iletin | | PUT | `/api/v1/management/proxies/assignments` | Atar — gövde `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`) ile doğrulanır. Dağıtıcı önbelleğini temizler | | PUT | `/api/v1/management/proxies/bulk-assign` | Toplu atama yapar — gövde `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) ile doğrulanır | | GET | `/api/v1/management/proxies/health?hours=24` | Belirli bir zaman aralığındaki toplu proxy durumunu (başarılı/başarısız sayıları, gecikme) döndürür | **Kimlik doğrulama:** her rotada yönetim oturumu/API anahtarı gereklidir (`requireManagementAuth`). > Görev açıklamasındaki `POST /api/v1/management/proxies/[id]/assignments` ve `POST /api/v1/management/proxies/[id]/health`, yukarıda gösterilen düz `/assignments` ve `/health` rotaları tarafından sunulur — kod tabanında kimlik başına alt rotalar yoktur. --- ## Dayanıklılık (genişletilmiş) OmniRoute, birbirinden bağımsız üç geçici hata mekanizması sunar; aşağıdaki yönetim uç noktaları, operatörlerin bunları okumasına ve geçersiz kılmasına olanak tanır: | Kapsam | Durum depolama | Okuma | Sıfırlama / temizleme | | ------------------------ | ------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------- | | Sağlayıcı devre kesicisi | `domain_circuit_breakers` + bellek içi | `/api/monitoring/health` | `POST /api/resilience/reset` | | Bağlantı bekleme süresi | Sağlayıcı bağlantılarındaki `rateLimitedUntil` | `/api/rate-limits`, `/api/providers/[id]` | (gecikmeli olarak yeniden etkinleşir; sağlayıcı PUT isteğiyle temizlenir) | | Model kilitleme | Bellek içi model kullanılabilirliği kayıt sistemi | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` | `PATCH /api/resilience`, `providerBreaker.oauth` ve `providerBreaker.apikey` altında sağlayıcı devre kesicisi geçersiz kılmalarını kabul eder. Her profil `degradationThreshold`, `failureThreshold` ve `resetTimeoutMs` alanlarını destekler; aynı alanlar Pano → Ayarlar → Dayanıklılık bölümünde de sunulur. ```bash # Tek bir model kilitlemesini temizle 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"}' # Tüm kilitlemeleri temizle curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \ -H "Cookie: auth_token=..." \ -d '{"all":true}' ``` Kavramsal referansın tamamı ve devre kesici varsayılanları için [`CLAUDE.md`](../../CLAUDE.md) → "Dayanıklılık Çalışma Zamanı Durumu" bölümüne bakın. --- ## Beceriler OmniRoute'u özel çalıştırılabilir işleyicilerle genişletmeye yönelik beceri çerçevesi ve pazar yeri entegrasyonları. | Yöntem | Yol | Açıklama | | ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/skills` | Yüklü becerileri listeler — `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local` ile filtrelenebilir ve sayfalandırılır | | GET | `/api/skills/[id]` | Tek bir beceriyi getirir | | PUT | `/api/skills/[id]` | Beceriyi günceller (ad, açıklama, mod, şema, işleyici, etiketler) | | DELETE | `/api/skills/[id]` | Bir beceriyi kaldırır | | POST | `/api/skills/install` | Ham manifestten bir beceri yükler — gövde: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` | | GET | `/api/skills/executions` | Son beceri yürütmelerini listeler (girdiler/çıktılar/süre bilgilerini içeren denetim izi) | | GET | `/api/skills/marketplace?q=...` | SkillsMP pazar yerindeki arama/popülerlik listesini getirir (`skillsmpApiKey` ayarını gerektirir) | | POST | `/api/skills/marketplace/install` | SkillsMP'den kimliğe göre bir beceri yükler | | GET | `/api/skills/skillssh?q=&limit=` | skills.sh kayıt sisteminde arama yapar | | POST | `/api/skills/skillssh/install` | skills.sh üzerinden kimliğe göre bir beceri yükler | **Kimlik doğrulama:** yönetim oturumu/API anahtarı. Pazar yeri arama yolları, yönetim kimlik doğrulamasını veya Bearer API anahtarını (`isAuthenticated`) kabul eder. --- ## Bellek API anahtarı / oturum kapsamında kalıcı konuşma/olgusal bellek deposu. | Yöntem | Yol | Açıklama | | ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/memory` | Bellekleri listeler — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`; `offset/limit` veya `page/limit` sayfalandırmasıyla | | POST | `/api/memory` | Bellek oluşturur — gövde Zod tarafından doğrulanır: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` | | GET | `/api/memory/[id]` | Tek bir belleği getirir | | DELETE | `/api/memory/[id]` | Bir belleği siler | | GET | `/api/memory/health` | Bellek alt sisteminin durumu (DB bağlantısı, gömme arka ucu, vektör dizini durumu) | **Kimlik doğrulama:** yönetim oturumu/API anahtarı (`requireManagementAuth`). `type` enum'u: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (`src/lib/memory/types.ts` içindeki `MemoryType` bölümüne bakın). --- ## MCP Sunucusu OmniRoute, 3 aktarım (stdio, SSE, streamable-http) ve kapsamlı araçlar içeren yerleşik bir Model Context Protocol sunucusuyla birlikte gelir. Aşağıdaki pano uç noktaları durum/denetim verilerini okur ve HTTP aktarımlarına vekillik eder. | Yöntem | Yol | Açıklama | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- | | GET | `/api/mcp/status` | Sinyal, aktarım, çevrimiçi durumu, son çağrı, en çok kullanılan araçlar, 24 saatlik başarı oranı | | GET | `/api/mcp/tools` | `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` alanlarıyla MCP araçlarının listesi | | GET | `/api/mcp/sse` | SSE aktarımı için SSE akışı açar (MCP devre dışıysa veya aktarım uyuşmazlığı varsa `503` döndürür) | | POST | `/api/mcp/sse` | SSE aktarımı üzerinden JSON-RPC çerçevesi gönderir | | GET | `/api/mcp/stream` | Streamable HTTP aktarımının SSE tarafını açar (sunucu tarafından başlatılan mesajlar) | | POST | `/api/mcp/stream` | Streamable HTTP aktarımı üzerinden JSON-RPC çerçevesi gönderir | | DELETE | `/api/mcp/stream` | Bir Streamable HTTP oturumunu sonlandırır | | GET | `/api/mcp/audit` | Denetim günlüğünü sorgular — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` | | GET | `/api/mcp/audit/stats` | Toplu denetim istatistikleri (toplamlar, başarı oranı, ortalama süre, en çok kullanılan araçlar) | **Kimlik doğrulama:** `sse`/`stream` aktarımları MCP'ye özgü kimlik doğrulama yüzeyini kullanır (`mcp` kapsamına sahip Bearer API anahtarı); `status`/`tools`/`audit*` rotaları panodan okunabilir (pano ana makinesine erişmenin ötesinde ek kimlik doğrulama gerekmez). > Her iki HTTP aktarımı da `settings.mcpEnabled` ve `settings.mcpTransport` tarafından denetlenir — aktarım uyuşmazlığı `400`, MCP'nin devre dışı olması ise `503` döndürür. --- ## A2A Sunucusu OmniRoute, inceleme/pano kullanımı için bir REST sarmalayıcısına ek olarak bir A2A (Agent-to-Agent) JSON-RPC 2.0 uç noktası sunar. ### JSON-RPC ```bash POST /a2a Authorization: Bearer your-api-key # OMNIROUTE_API_KEY ayarlanmadığı sürece isteğe bağlıdır Content-Type: application/json { "jsonrpc": "2.0", "id": 1, "method": "message/send", "params": { "skill": "smart-routing", "messages": [{"role": "user", "content": "Route this coding task"}] } } ``` Desteklenen yöntemler (tümü `settings.a2aEnabled` ayarına bağlıdır): | Yöntem | Açıklama | | ---------------- | ---------------------------------------------------------------- | | `message/send` | Eşzamanlı beceri yürütme; `{task, artifacts, metadata}` döndürür | | `message/stream` | Aynı beceri kümesinin SSE üzerinden akış yürütmesi | | `tasks/get` | Bir görevi `taskId` ile getirir | | `tasks/cancel` | Bir görevi `taskId` ile iptal eder | Yerleşik beceriler: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`. ### Aracı Kartı ```bash GET /.well-known/agent.json ``` Herkese açık A2A aracı kartını (ad, açıklama, yetenekler, beceri kataloğu, kimlik doğrulama şeması) döndürür — herkese açık olarak 1 saat önbelleğe alınır. Kimlik doğrulama gerekmez. ### REST Yardımcıları | Yöntem | Yol | Açıklama | | ------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | GET | `/api/a2a/status` | A2A etkinlik durumu + görev istatistikleri + önbelleğe alınmış aracı kartı özeti | | GET | `/api/a2a/tasks` | Görevleri listeler — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` | | POST | `/api/a2a/tasks` | (REST yardımcısı olarak uygulanmamıştır — JSON-RPC `message/send` aracılığıyla oluşturun) | | GET | `/api/a2a/tasks/[id]` | Tek bir görevi getirir | | POST | `/api/a2a/tasks/[id]/cancel` | Bir görevi iptal eder | **Kimlik doğrulama:** REST yardımcıları yönetim kimlik doğrulaması olmadan çalışır (pano tarafından okunabilir); JSON-RPC `/a2a` rotası, yapılandırılmışsa Bearer `OMNIROUTE_API_KEY` kullanır. --- ## Bulut, Değerlendirmeler ve Analiz | Yöntem | Yol | Açıklama | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | POST | `/api/cloud/auth` | Bir Bearer anahtarını doğrular ve bulut eşitleme istemcileri için maskelenmiş sağlayıcı bağlantılarını + model takma adlarını döndürür | | POST | `/api/cloud/credentials/update` | Bulutla eşitlenen bir sağlayıcının şifrelenmiş kimlik bilgilerini günceller | | POST | `/api/cloud/model/resolve` | Yerel yönlendirme tablosunu kullanarak mantıksal bir model kimliğini somut bir sağlayıcıya/modele çözümler | | GET | `/api/cloud/models/alias` | Model takma adlarını bulut eşitlemeye sunuldukları biçimde listeler | | GET | `/api/assess` | En son analiz sınıflandırmalarını (sağlayıcı/model başına) okur | | POST | `/api/assess` | Bir analiz çalıştırır — gövde: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` | | GET | `/api/evals` | Yerleşik değerlendirme paketlerini + en son çalıştırmaları listeler | | POST | `/api/evals` | Bir değerlendirme çalıştırmasını tetikler | | POST | `/api/evals/suites` | Özel bir değerlendirme paketi oluşturur — gövde `evalSuiteSaveSchema` tarafından doğrulanır | | GET | `/api/evals/suites/[id]` | Özel bir değerlendirme paketini getirir | **Kimlik doğrulama:** `/api/cloud/auth`, bir Bearer anahtarını doğrudan doğrular; diğer `/api/cloud/*`, `/api/evals/*` ve `/api/assess` rotaları yönetim oturumu/API anahtarı gerektirir. `/api/assess` POST, ayrıştırılmış birleşim kapsam şemasıyla `validateBody` kullanır. --- ## ACP (Agent Client Protocol) Yönetimi alt süreçler olarak. Bu uç noktalar, ACP aracılarının algılanmasını ve özel aracıların kaydedilmesini yönetir. | Yöntem | Yol | Açıklama | | ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | GET | `/api/acp/agents` | Bilinen tüm CLI aracılarını (yerleşik + özel), kurulum durumu, sürüm ve ikili dosya bilgileriyle listeler | | POST | `/api/acp/agents` | Özel bir ACP aracısı kaydeder veya önbelleği yeniler — gövde: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` ya da `{action: "refresh"}` | | DELETE | `/api/acp/agents` | Özel bir ACP aracısını kaldırır — sorgu parametresi: `?id=` | **Yanıt örneği** (`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 } ``` **Kimlik doğrulama:** Yönetim oturumu (kontrol paneli `auth_token` çerezi) veya yönetim kapsamlı bir API anahtarı gerektirir. Tüm ayrıntılar için [ACP Framework](../frameworks/ACP.md) bölümüne bakın. --- ## Analitik ve Gözlemlenebilirlik Yönlendirme, sıkıştırma ve sağlayıcı çeşitliliğini izlemeye yönelik gerçek zamanlı analitik uç noktaları. Bunlar `/dashboard/analytics/*` sayfalarını destekler. ### Otomatik yönlendirme analitiği | Yöntem | Yol | Açıklama | | ------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/auto-routing` | Toplu otomatik yönlendirme istatistikleri: toplam çağrı, strateji dağılımı, katman dağılımı, başlıca sağlayıcılar | | GET | `/api/analytics/auto-routing?days=7` | Zaman pencereli istatistikler (varsayılan 24 sa.) | **Yanıt örneği**: ```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 } ] } ``` ### Sıkıştırma analitiği | Yöntem | Yol | Açıklama | | ------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/compression` | Toplu sıkıştırma istatistikleri: tasarruf edilen token'lar, tasarruf yüzdesi, mod dağılımı, motor kullanımı | **Yanıt örneği**: ```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 } } ``` ### Sağlayıcı çeşitliliği takibi | Yöntem | Yol | Açıklama | | ------ | -------------------------- | ---------------------------------------------------------------------------------------------------- | | GET | `/api/analytics/diversity` | Shannon entropisi tabanlı çeşitlilik takibi: sağlayıcı dağılımını ölçerek tek hata noktalarını önler | **Yanıt örneği**: ```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 trafiğin %40'ını oluşturuyor — çeşitlendirmeyi değerlendirin"] } ``` **Kimlik doğrulama:** Yönetim oturumu veya yönetim kapsamlı bir API anahtarı gerektirir. --- ## Yönetici İşlemleri Operasyonel yönetim için yalnızca yöneticilere açık uç noktalar. | Yöntem | Yol | Açıklama | | ------ | ------------------------ | ---------------------------------------------------------------------------------------------------- | | GET | `/api/admin/concurrency` | Mevcut eşzamanlılık sınırlarını oku (genel + sağlayıcı başına) | | POST | `/api/admin/concurrency` | Eşzamanlılık sınırlarını güncelle — gövde: `{global?: number, perProvider?: Record}` | **Kimlik doğrulama:** Yönetici kapsamına sahip bir yönetim oturumu gerektirir. --- ## CLI Araçları Yönetimi OmniRoute ile entegre olan CLI araçlarını (antigravity, chipotle, commandCode, devin-cli vb.) yönetin. Tam liste için [Sağlayıcı Referansı](./PROVIDER_REFERENCE.md) belgesine bakın. | Yöntem | Yol | Açıklama | | ------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/cli-tools/all-statuses` | Tüm CLI araçlarının durumu (kurulu olma durumu, sürüm, son görülme zamanı) | | GET | `/api/cli-tools/status` | Bir CLI aracının ayrıntılı durumu (`?tool=` sorgusu) | | POST | `/api/cli-tools/apply` | Bir aracın oluşturulan yapılandırmasını yaz (`dryRun` önizleme yapar; kapsayıcı ortamında `422` + `containerEphemeralTarget`; `migration`, eski bir Codex YAML'ını belirtir) | | GET | `/api/cli-tools/backups` | CLI aracı yapılandırma yedeklerini listele | | POST | `/api/cli-tools/backups` | Tüm CLI aracı yapılandırmalarının yedeğini oluştur | | POST | `/api/cli-tools/backups` | Geri yükle: gövdede `{tool, backupId}` ile aynı uç nokta, ilgili yedeği geri yükler | | GET | `/api/cli-tools/antigravity-mitm` | Antigravity MITM proxy durumu ("antigravity-mitm" CLI aracı) | | POST | `/api/cli-tools/antigravity-mitm/alias` | antigravity-mitm alias'larını yapılandır | **Kimlik doğrulama:** Yönetim oturumu gerektirir. --- ## Aracı Becerileri Yapay zekâ aracı becerilerini yönetin (OpenAI'ın özel GPT'lerine benzer, ancak aracılar içindir). | Yöntem | Yol | Açıklama | | ------ | ---------------------------- | -------------------------------------------------------------------------------------------- | | GET | `/api/agent-skills` | Tüm aracı becerilerini listele (yerleşik + özel) | | GET | `/api/agent-skills/[id]` | Belirli bir aracı becerisini getir | | POST | `/api/agent-skills` | Özel bir aracı becerisi oluştur — gövde: `{name, description, prompt, model?, temperature?}` | | PUT | `/api/agent-skills/[id]` | Özel bir aracı becerisini güncelle | | DELETE | `/api/agent-skills/[id]` | Özel bir aracı becerisini sil | | GET | `/api/agent-skills/[id]/raw` | Ham istemi + meta verileri getir (çalıştırma yok) | | POST | `/api/agent-skills/generate` | Doğal dil açıklamasından yapay zekâ ile yeni bir beceri oluştur | **Kimlik doğrulama:** Yönetim oturumu veya yönetim kapsamlı API anahtarı gerektirir. --- ## Önbellek Yönetimi Anlamsal önbelleği ve akıl yürütme önbelleğini yönetin. | Yöntem | Yol | Açıklama | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | GET | `/api/cache` | Önbelleğe genel bakış: toplam kayıt sayısı, isabet oranı, diskteki boyut | | GET | `/api/cache/entries` | Önbelleğe alınmış kayıtları listele (sayfalandırma ile) | | DELETE | `/api/cache/entries` | Önbellek kayıtlarını sil (sorgu parametrelerine göre filtrele) | | GET | `/api/cache/stats` | Ayrıntılı önbellek istatistikleri (sağlayıcı ve model bazında) | | GET | `/api/cache/reasoning` | Akıl yürütme önbelleğinin durumu (akıl yürütmeyi yeniden oynatmak için) | | DELETE | `/api/cache/reasoning` | Akıl yürütme önbelleğini temizle — sorgu parametreleri: `?toolCallId=` (tek) veya `?provider=

` ya da parametresiz (tümü) | **Kimlik doğrulama:** Yönetim oturumu gerektirir. --- ## Bellek Sistemi Kalıcı belleği (FTS5 + vektör gömmeleri) yönetin. | Yöntem | Yol | Açıklama | | ------ | ------------------ | --------------------------------------------------------------------------- | | GET | `/api/memory` | Bellek kayıtlarını listele (kapsama, türe ve arama sorgusuna göre filtrele) | | POST | `/api/memory` | Yeni bir bellek kaydı oluştur — gövde: `{scope, type, content, metadata?}` | | GET | `/api/memory/[id]` | Belirli bir bellek kaydını getir | | PUT | `/api/memory/[id]` | Bir bellek kaydını güncelle | | DELETE | `/api/memory/[id]` | Bir bellek kaydını sil | | GET | `/api/memory?q=` | Bellekte ara (FTS5 + vektör) — istatistikler aynı yanıta dahil edilir | **Kimlik doğrulama:** Yönetim oturumu veya yönetim kapsamlı API anahtarı gerektirir. --- ## Webhook'lar Olaylara yönelik webhook aboneliklerini yönetin. | Yöntem | Yol | Açıklama | | ------ | ------------------------------- | -------------------------------------------------------------------------- | | GET | `/api/webhooks` | Tüm webhook aboneliklerini listele | | POST | `/api/webhooks` | Bir webhook aboneliği oluştur — gövde: `{url, events[], secret?, active?}` | | GET | `/api/webhooks/[id]` | Belirli bir webhook aboneliğini getir | | PUT | `/api/webhooks/[id]` | Bir webhook aboneliğini güncelle | | DELETE | `/api/webhooks/[id]` | Bir webhook aboneliğini sil | | GET | `/api/webhooks/[id]/deliveries` | Bir webhook'un teslimat geçmişini listele (başarı/başarısızlık günlüğü) | | POST | `/api/webhooks/[id]/test` | Bir webhook'a test olayı gönder | **Kimlik doğrulama:** Yönetim oturumu gerektirir. Tüm olay türleri için [Webhook Çerçevesi](../frameworks/WEBHOOKS.md) bölümüne bakın. --- ## Skills Çerçevesi Skills'leri (otonom eklentiler çerçevesi) yönetin. | Yöntem | Yol | Açıklama | | ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------- | | GET | `/api/skills` | Yüklü tüm Skills'leri listeleyin (yerleşik + özel) | | POST | `/api/skills/install` | Yerel bir yoldan veya URL'den Skill yükleyin | | DELETE | `/api/skills/[id]` | Bir Skill'i kaldırın | | PUT | `/api/skills/[id]` | Bir Skill'i etkinleştirin veya devre dışı bırakın — gövde: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` | | POST | `/api/skills/executions` | Bir Skill çalıştırın — gövde: `{skillName, apiKeyId, input?, sessionId?}` | | GET | `/api/skills/executions` | Tüm Skills'lerin yürütme geçmişini listeleyin (`?apiKeyId=` ile filtreleyin) | **Kimlik doğrulama:** Yönetim oturumu veya yönetim kapsamlı API anahtarı gerektirir. Tüm ayrıntılar için [Skills Çerçevesi](../frameworks/SKILLS.md) belgesine bakın. --- ## Eklentiler OmniRoute eklentilerini (üçüncü taraf uzantıları) yönetin. | Yöntem | Yol | Açıklama | | ------ | ---------------------------------- | ------------------------------------ | | GET | `/api/plugins` | Yüklü eklentileri listeleyin | | POST | `/api/plugins/marketplace/install` | Pazaryerinden bir eklenti yükleyin | | DELETE | `/api/plugins/[name]` | Bir eklentiyi kaldırın | | POST | `/api/plugins/[name]/activate` | Bir eklentiyi etkinleştirin | | POST | `/api/plugins/[name]/deactivate` | Bir eklentiyi devre dışı bırakın | | GET | `/api/plugins/[name]/config` | Eklenti yapılandırmasını alın | | PUT | `/api/plugins/[name]/config` | Eklenti yapılandırmasını güncelleyin | **Kimlik doğrulama:** Yönetim oturumu gerektirir. Tüm ayrıntılar için [Eklentiler Çerçevesi](../frameworks/PLUGIN_SDK.md) belgesine bakın. --- ## Gölge Yönlendirme Sağlayıcıların gölge / A-B karşılaştırması **bağımsız bir REST yüzeyi değildir** — birleşik yönlendirme aracılığıyla yapılandırılır (bkz. [Otomatik Birleşim](../routing/AUTO-COMBO.md)). Birleşim başına karşılaştırma metrikleri `GET /api/combos/metrics` tarafından sunulur. --- ## Koruma Mekanizmaları Çalışma zamanı koruma mekanizmalarını (PII algılama, istem enjeksiyonu algılama, görsel köprüleme) inceleyin. Koruma mekanizmaları her istekte çalışır; çağrı bazında devre dışı bırakma işlemi `x-omniroute-disabled-guardrails` istek başlığı aracılığıyla yapılır — kalıcı bir etkinleştirme/devre dışı bırakma yüzeyi yoktur. | Yöntem | Yol | Açıklama | | ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------- | | GET | `/api/guardrails` | Kayıtlı koruma mekanizmalarını ve durumlarını listeleyin (ad / etkin / öncelik) | | POST | `/api/guardrails/test` | Çağrı öncesi işlem hattını örnek bir girdi üzerinde deneme amaçlı çalıştırın — gövde: `{input, disabledGuardrails?}` | **Kimlik doğrulama:** Yönetim oturumu gerektirir. Tüm ayrıntılar için [Güvenlik > Koruma Mekanizmaları](../security/GUARDRAILS.md) belgesine bakın. --- --- ## Kimlik Doğrulama Dört kimlik bilgisi ailesi (gösterge paneli oturumu, yerel CLI token'ı, `oma_live_…` Erişim Token'ı, yönetim kapsamlı API anahtarı) ve bunların çıkarım anahtarlarından farkları için [Yönetim Kimlik Doğrulaması](../guides/MANAGEMENT-AUTH.md) bölümüne bakın. - Gösterge paneli rotaları (`/dashboard/*`) `auth_token` çerezini kullanır - Giriş işlemi, kaydedilmiş parola karmasını kullanır; mevcut değilse `INITIAL_PASSWORD` kullanılır - `requireLogin`, `/api/settings/require-login` üzerinden açılıp kapatılabilir - `/v1/*` rotaları, `REQUIRE_API_KEY=true` olduğunda isteğe bağlı olarak Bearer API anahtarı gerektirir - Bu referanstaki "yönetim token'ı" / "yönetim kapsamlı API anahtarı", ilgili kılavuzdaki ailelerden birini ifade eder — tanımlanmamış ek bir gizli bilgi türünü değil > **Geriye dönük uyumluluğu bozan değişiklik (v3.8.0)** — `/api/v1/agents/tasks/*` ve bekleme süresi yönetimi uç noktaları artık **yönetim kimlik doğrulaması** (gösterge paneli `auth_token` çerezi veya yönetim kapsamlı bir API anahtarı) gerektirir. Daha önce bu rotaları kimlik doğrulaması olmadan çağıran istemciler `401 Unauthorized` yanıtını alacaktır. `588a0333` (`fix(auth): temsilci ve bekleme süresi API'leri için yönetim kimlik doğrulaması gerektir`) commit'ine bakın.