Files
OmniRoute/docs/i18n/phi/docs/reference/API_REFERENCE.md

198 KiB
Raw Permalink Blame History

API Reference (Filipino)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 hi · 🇭🇷 hr · 🇭🇺 hu · 🇦🇲 hy · 🇮🇩 id · 🇳🇬 ig · 🇮🇹 it · 🇯🇵 ja · 🇬🇪 ka · 🇰🇭 km · 🇮🇳 kn · 🇰🇷 ko · 🇱🇹 lt · 🇱🇻 lv · 🇮🇳 ml · 🇮🇳 mr · 🇲🇾 ms · 🇲🇹 mt · 🇲🇲 my · 🇳🇵 ne · 🇳🇱 nl · 🇳🇴 no · 🇮🇳 or · 🇮🇳 pa · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇸🇮 sl · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW


🌐 Mga Wika: 🇺🇸 English | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇧🇦 Bosanski | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇩🇪 Deutsch | 🇬🇷 Ελληνικά | 🇪🇸 Español | 🇪🇪 Eesti | 🇮🇷 فارسی | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇪 Gaeilge | 🇮🇳 ગુજરાતી | 🇳🇬 Hausa | 🇮🇱 עברית | 🇮🇳 हिन्दी | 🇭🇷 Hrvatski | 🇭🇺 Magyar | 🇦🇲 Հայերեն | 🇮🇩 Bahasa Indonesia | 🇳🇬 Igbo | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇬🇪 ქართული | 🇰🇭 ខ្មែរ | 🇮🇳 ಕನ್ನಡ | 🇰🇷 한국어 | 🇱🇹 Lietuvių | 🇱🇻 Latviešu | 🇮🇳 മലയാളം | 🇮🇳 मराठी | 🇲🇾 Bahasa Melayu | 🇲🇹 Malti | 🇲🇲 မြန်မာ | 🇳🇵 नेपाली | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇮🇳 ଓଡ଼ିଆ | 🇮🇳 ਪੰਜਾਬੀ | 🇵🇭 Filipino | 🇵🇱 Polski | 🇵🇹 Português (Portugal) | 🇧🇷 Português (Brasil) | 🇷🇴 Română | 🇷🇺 Русский | 🇱🇰 සිංහල | 🇸🇰 Slovenčina | 🇸🇮 Slovenščina | 🇷🇸 Српски | 🇸🇪 Svenska | 🇰🇪 Kiswahili | 🇮🇳 தமிழ் | 🇮🇳 తెలుగు | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇵🇰 اردو | 🇺🇿 Oʻzbekcha | 🇻🇳 Tiếng Việt | 🇳🇬 Yorùbá | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

Pangunahing sanggunian para sa OmniRoute API. Saklaw nito ang pampublikong /v1 surface at ang mga pinakaginagamit na endpoint para sa pamamahala; ang machine-readable na docs/openapi.yaml at ang puno ng mga ruta sa ilalim ng src/app/api/ ang kumpletong mga sanggunian.

Para sa nakatuong protocol na katugma ng OpenAI at matrix ng mga kakayahan ng provider, tingnan ang OPENAI_COMPATIBILITY.md.

Ang bawat deployment ay naghahatid ng sarili nitong kopya ng spec sa /openapi.yaml, na binubuo mula sa docs/openapi.yaml habang isinasagawa ang build. Taglay nito ang bersyon ng build at isang relative na server URL (./), kaya nananatili ang mga request sa host na naghatid ng dokumento. Walang ganoong host ang tool na nag-i-import ng na-download na file, kaya kailangang itakda nang manu-mano ang base URL.


Talaan ng mga Nilalaman


Mga Chat Completion

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

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Write a function to..."}
  ],
  "stream": true
}

Mga Custom Header

Header Direction Description
X-OmniRoute-No-Cache Kahilingan Itakda sa true upang lampasan ang cache
x-omniroute-no-memory Kahilingan Itakda sa true upang laktawan ang pag-inject ng memory + skills para sa kahilingang ito (kapareho ng no-cache; iniiwasan ang overhead ng token/gastos sa bawat tawag)
X-OmniRoute-Progress Kahilingan Itakda sa true para sa mga event ng progreso
X-Session-Id Kahilingan Sticky session key para sa external session affinity
x_session_id Kahilingan Tinatanggap din ang variant na may underscore (direct HTTP)
X-OmniRoute-Session-Id Kahilingan Tag ng session/conversation na ibinibigay ng caller (ipinapasa rin sa memory). Kapag mayroon, sine-save nang eksakto sa call_logs.session_tag para sa pagtatalaga ng gastos kada session (#8249) — hindi kailanman ginagawa kapag wala
Idempotency-Key Kahilingan Dedup key (5s na palugit)
X-Request-Id Kahilingan Alternatibong dedup key
x-omniroute-connection Kahilingan I-pin ang isang single-model na kahilingan sa isang koneksyon ng provider (account) ayon sa ID nito — tingnan ang Pag-pin ng account kada kahilingan
X-OmniRoute-Cache Tugon HIT o MISS (hindi streaming)
X-OmniRoute-Idempotent Tugon true kung na-deduplicate
X-OmniRoute-Progress Tugon enabled kung naka-on ang pagsubaybay sa progreso
X-OmniRoute-Session-Id Tugon Aktuwal na session ID na ginamit ng OmniRoute
X-OmniRoute-Request-Id Tugon ID ng correlation ng kahilingan (kapag alam)
X-OmniRoute-Version Tugon Bersyon ng build ng OmniRoute (laging naroroon)
X-OmniRoute-Cost-Saved Tugon USD na naiwasan ng cache sa isang HIT (mga cache hit lamang)
X-OmniRoute-Decision Tugon Trace ng pagruruta: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> ang combo strategy, o single para sa kahilingang hindi combo) — laging naroroon sa mga response kapag kumpleto na

Tala sa Nginx: kung umaasa ka sa mga header na may underscore (halimbawa, x_session_id), paganahin ang underscores_in_headers on;.

Pag-pin ng account kada kahilingan

Kapag ang isang provider ay may ilang koneksyon (mga account o key), karaniwang pumipili ang OmniRoute ng isa gamit ang strategy nito sa pagpili ng account. Sa halip, maaaring i-pin ng isang kahilingan ang isang partikular na koneksyon gamit ang header na x-omniroute-connection:

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer <your OmniRoute API key>" \
  -H "Content-Type: application/json" \
  -H "x-omniroute-connection: <connection id>" \
  -d '{"model": "codex/gpt-5.5", "messages": [{"role": "user", "content": "hi"}]}'
  • Saan makikita ang id. Buksan ang provider page sa dashboard (Dashboard → Providers → ) at i-click ang xxxxxxxx… id chip sa isang connection row — kokopyahin nito ang buong connection id.
  • Aling mga request ang kumikilala rito. Mga single-model request (provider/model) sa /v1/chat/completions, /v1/messages at /v1/responses. Hindi pinapansin ng mga combo ang header: i-pin ang isang account para sa bawat combo step sa pamamagitan ng sariling connection ng step.
  • Mahigpit ang pin, hindi ito preference. Eksklusibong gagamitin ang naka-pin na connection. Kapag nagkaroon ng failure sa loob ng request, itatala ang cooldown ng account ngunit hindi lilipat sa sibling account ng parehong provider.
  • Inaalis ng cooldown at quota ang pin. Habang naka-cooldown ang naka-pin na connection, naubusan ng quota o na-block ng quota policy, ang mga susunod na request ay gagamit ng ibang connection ng provider, gaya mismo ng unpinned traffic.
  • Nagdudulot ng failure ang hindi kilala o disabled na id. Ang id na wala sa active pool ng provider (na-delete, na-deactivate, o kabilang sa ibang provider) ay walang ineligible na account, kaya magfa-fail ang request sa halip na tahimik na i-route sa ibang lugar.

Nagpapadala ang Claude Code ng mga custom header sa pamamagitan ng ANTHROPIC_CUSTOM_HEADERS. Ilagay ito sa env block ng ~/.claude/settings.json, o sa project-level na .claude/settings.json para mag-pin ng ibang account bawat project:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
    "ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: <connection id>",
  },
}

Source: src/sse/handlers/chat.ts (pagbasa ng header), src/sse/services/auth.ts at src/sse/services/sessionAffinityPin.ts (pag-release ng pin at pag-check kung nawawala sa pool).

Mga header ng cost telemetry: ang mga non-streaming success response ay naglalaman din ng X-OmniRoute-* cost-telemetry set — X-OmniRoute-Response-Cost (USD, fixed na 10 decimal; 0.0000000000 para sa libre/walang presyo), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit, at X-OmniRoute-Fallback-Attempts (kapag > 0 lamang), pati X-OmniRoute-Request-Id at X-OmniRoute-Version. Ipinapadala ang mga ito ng chat completions, /v1/responses, /v1/messages, at ng mga media endpoint — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations, at /v1/moderations (palaging cost na 0). Kinakalkula ang media cost ayon sa modality (bawat larawan, bawat segundo, bawat character, bawat search-unit) kapag available ang pricing; kung hindi, 0 (fail-open).

Semantics ng cost kapag cache hit: kapag may semantic-cache HIT (X-OmniRoute-Cache-Hit: true), walang upstream call na ginagawa, kaya ang X-OmniRoute-Response-Cost ay 0.0000000000 (ang incremental na cost ng pag-serve sa hit). Hiwalay na iniuulat ang orihinal/would-have-been cost sa X-OmniRoute-Cost-Saved. Dapat pagsamahin ng mga consumer ng billing ang X-OmniRoute-Response-Cost (walang cost ang mga hit); maaaring i-aggregate ng cache analytics ang X-OmniRoute-Cost-Saved.

Eksklusibong Pinamamahalaang Lease ng Session

Ang eksklusibong pinamamahalaang session leasing ay isang opt-in, client-neutral na routing contract: isang aktibong owner ang may hawak ng isang kwalipikadong OmniRoute connection. Hindi ito nagle-lease ng model, hindi nangangailangan ng OAuth, hindi tumutukoy sa isang partikular na client, at hindi nangangailangan ng isang partikular na provider.

Dapat ay may saklaw na lease:exclusive at tahasang hindi walang-laman na listahang allowedConnections ang API key na ginagamit sa authentication. Ipinatutupad ng hangganan ng database mutation ang parehong field nang sabay sa paggawa ng key at sa mga partial update.

POST /api/v1/session-leases
Authorization: Bearer <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>

{"action":"acquire","model":"glm/glm-4.6"}

Ang matagumpay na mga tugon para sa acquire, renew, at release ay naglalantad ng mga timestamp, state, at ng eksaktong positibong generation, ngunit hindi kailanman ng napiling connection o mga credential. Ipinapadala ng renew at release ang generation sa JSON body:

{ "action": "renew", "generation": 1 }
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }

Ang isang aktibong lease owner ay maaaring tahasang humiling ng privacy-safe na display metadata para sa kasalukuyan nitong binding:

{ "action": "status", "generation": 1 }
{
  "state": "ACTIVE",
  "generation": 1,
  "acquiredAt": "2026-08-28T12:00:00.000Z",
  "renewedAt": "2026-08-28T12:00:30.000Z",
  "expiresAt": "2026-08-28T12:02:30.000Z",
  "connection": {
    "displayName": "Primary Codex",
    "provider": "codex"
  }
}

Ang opt-in na action na ito para sa status ay ipinapatupad gamit ang opaque owner, authenticated managed API key, at eksaktong aktibong generation sa isang database transaction. Ang displayName ay ang na-trim lamang na naka-configure na pangalan ng connection; null ito kapag walang ligtas na naka-configure na pangalan. Hindi kailanman pinapalitan ng OmniRoute ang pangalan ng isang email o nabuong account identity. Ang provider value ay isang display label na hindi sensitibo at hindi kailanman isang nabuong compatible-provider identifier. Hindi kasama rito ang mga credential, token, cookie, raw connection o API key id, owner hash, fencing secret, at internal routing data.

Ang mga lookup na may maling key, maling owner, lipas na generation, nawawala, nag-expire, ni-release, o na-invalidate ay lahat nagbabalik ng parehong 409 LEASE_FENCE_STALE error nang walang connection metadata. Ang client na nakatanggap ng capacity-wait response ay walang aktibong binding na maaaring siyasatin. Kapag nag-transition ang routing ng isang aktibong lease, nanatiling valid ang parehong generation at atomiko namang ibinabalik ng status ang bagong binding, hindi kailanman ang luma. Hindi nagbabago ang mga kasalukuyang client dahil nananatili sa dati nilang hugis ang mga response para sa acquire, renew, release, at waiting.

Hindi binabago ng server contract na ito ang stock OpenAI Codex /status. Kasalukuyang iniuulat ng stock Codex ang model provider nito at ang built-in authentication/account state, ngunit hindi nito nirere-render ang arbitraryong custom provider account metadata; kailangang tawagin ng isang susunod na client integration ang action na ito at magpasya kung paano ipapakita ang connection.displayName.

Ang bawat managed inference request ay nagbibigay pagkatapos ng parehong control header:

X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1

Ang eksaktong owner, generation, aktibong connection, at authenticated API key ay agad na ipinapatupad bago ang bawat suportadong upstream attempt. Mabibigo ang pag-replay ng owner at generation gamit ang ibang key kahit pinapahintulutan ng key na iyon ang parehong connection. Hindi sine-save ang mga raw owner, hindi nilala-log, hindi pinananatili sa request snapshot, at hindi ipinapasa upstream.

Ang pansamantalang contention ay nagbabalik ng HTTP 429 na may Retry-After at:

{
  "state": "WAITING_FOR_CAPACITY",
  "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
  "reason": "NO_FREE_ELIGIBLE_CONNECTION",
  "retryAfter": 30
}

Nangangahulugan lamang ang response na ito na hindi walang-laman ang ordinaryong eligible set at ang bawat libreng candidate ay hawak ng isang foreign active lease. Pinananatili ng mga hindi suportadong model/provider, policy mismatch, cooldown, quota, health, at iba pang karaniwang eligibility failure ang dati nilang mga response ng OmniRoute.

x-omniroute-compression

Per-request na override ng compression plan. Pinakamataas ang precedence — nangingibabaw sa routing-combo override, aktibong profile, auto-trigger, at Default ng panel. Mga value:

Value Effect
off Walang compression para sa request na ito.
default Ang Default profile na hinango mula sa panel (binabalewala ang aktibong profile). Nananatiling naka-off ang mga lossy engine.
safe Dedup at whitespace folding lamang.
allow-lossy Panatilihin ang operator plan para sa request na ito, kabilang ang mga summary at style rewrite.
engine:<id> Isang engine kapag naka-enable, hal. engine:rtk. Per-request na opt-in para sa engine na iyon.
<combo> Isang pinangalanang combo, na unang itinutugma ayon sa pangalan (case-insensitive), pagkatapos ay ayon sa id.

Mga tala:

  • Binabalewala ang mga hindi kilalang value (hindi kailanman nire-reject ang request); bumababa ang resolution sa normal na operator precedence.
  • Kung maraming combo ang may parehong pangalan, ipasa ang combo id para sa deterministic na pagtutugma.
  • Ang combo na ang pangalan ay off o default ay hindi maaaring piliin ayon sa pangalan (binibigyang-kahulugan muna ang mga keyword na ito); tukuyin ang naturang combo gamit ang id nito.
  • Ang master compression switch ay isang mahigpit na gate: kapag globally naka-disable ang compression, hindi ito maaaring i-enable ng header na ito.

Ibinabalik sa response header ang inilapat na plan:

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

kung saan ang <source> ay isa sa request-header, routing-override, active-profile, auto-trigger, default, o off.


Mga embedding

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

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

Mga available na provider: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

Ang mga catalog ID ay provider/model (halimbawa: jina-ai/jina-embeddings-v5-omni-small). Nalulutas din ang mga bare Jina model ID na lumilitaw sa registry (halimbawa, jina-embeddings-v5-text-small, jina-reranker-v3.5). Ang Jina embed/rerank/classify/segment ay unang gumagamit ng mga credential na jina-ai mula sa dashboard; fallback lamang ang JINA_AI_API_KEY kapag walang dashboard key. Ang card na jina-reader ay para lamang sa Reader / r.jina.ai (POST /v1/web/fetch) at hindi kailanman nagsisilbi ng embeddings o rerank.

Ang mga registry model na nag-aanunsyo ng multimodal support ay tumatanggap din ng hanggang 32 provider-neutral na structured item. Ang mga uri ng media item ay text, image, audio, video, at document. Ang source ng kanilang media ay alinman sa {"type":"url","url":"https://..."} o {"type":"base64","data":"...","media_type":"..."}.

Ang Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano, at ang family alias na jina-ai/jina-embeddings-v5-omni → omni-small) ay tumatanggap din ng native na Jina EmbeddingsV5Request docs at ipinapasa ang mga ito nang buo sa https://api.jina.ai/v1/embeddings:

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

Ang mga native na value na { image | audio | video | pdf } ay maaaring isang pampublikong HTTPS URL, isang data: URI, o raw base64. Hindi sini-stringify ng OmniRoute ang mga object na iyon o kinukuha ang mga native image URL — si Jina mismo ang kumukuha ng pampublikong media. Ipinapasa ang mga karagdagang field ng Jina (task, normalized, truncate, embedding_type). Tinatanggihan pa rin ng mga text-only Jina SKU ang mga non-text na dokumento.

Mga limitasyon sa seguridad at transportasyon:

  • Dapat pampublikong HTTPS ang mga remote media URL. Ang mga canonical na {type,source:url} item ay kinukuha sa server side (muling pag-validate ng redirect, timeout, mga limitasyon sa laki, pampublikong DNS, pag-pin ng koneksyon) at ini-inline bago ang tawag sa provider. Ipinapasa nang ganoon din ang mga Jina-native na {image:"https://..."} item matapos ang parehong pagsusuri sa pampublikong HTTPS; si Jina ang kumukuha ng URL.
  • Nililimitahan ang inline base64 media sa 8 MiB na decoded bawat item at 16 MiB na decoded sa buong request.

Pagsasalin para sa provider (hindi kailanman ipinapasa nang hindi binabago ang mga canonical item):

  • Mga Jina multimodal model: ang bawat top-level item ay nagiging isang object na may modality key (text / image / audio / video / pdf) gamit ang mga data URI para sa inline media; isang vector bawat top-level item.
  • Gemini Embedding 2 family: ang isang top-level array ay nagiging isang native na models/{model}:embedContent request na may content.parts (text o inline_data).
  • llama.cpp (llama-cpp/<model>, anumang model na na-load ng lokal na server): ang mga canonical na text item ay nagiging mga plain string, at ang image / audio / video ay nagiging tig-isang {"content": [part]} object, gamit ang mga chat content part ng llama-server (image_url, input_audio na may format na wav / mp3 / flac, input_video) na may inline data; isang vector bawat top-level item. Dapat tumakbo ang server gamit ang --embedding --mmproj …; kung walang projector, ito mismo ang tatanggi sa media. Hindi sinusuportahan ang document.
  • Tinatanggihan ng mga unknown/dynamic model na walang tahasang modality metadata ang structured input gamit ang HTTP 400.
{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}

Ang mga hindi sinusuportahang kombinasyon ng model/modality ay nagbabalik ng HTTP 400 sa halip na piliting i-coerce ang item. Patuloy na ipinapasa nang hindi binabago ang mga non-input extension field sa mga legacy string/token request.

# Ilista ang lahat ng embedding model
GET /v1/embeddings

Pagbuo ng Larawan

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"
}

Kasama sa mga available na provider ang OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana,OpenRouter ,ZenMux , SD WebUI (lokal), ComfyUI (lokal).

ibinabalik n ang mga n na larawan sa data[]. Ang mga provider na ang upstream API ay nagbabalik ng isang larawan sa bawat tawag (Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik, NVIDIA NIM, Cloudflare Workers AI) ay nakakakuha ng n na magkakahiwalay na upstream na tawag, hindi hihigit sa 4 sa paglipad. Ang isang nakapirming seed ay na-offset ng call index (seed, seed + 1, …), kaya ang mga imahe ay naiiba ngunit nananatiling reproducible. n ay nililimitahan sa 10. Ang kahilingan ay nabigo sa kabuuan kung ang anumang tawag ay nabigo. Ang listahan ng mga fan-out na format ay SINGLE_IMAGE_FANOUT_FORMATS sa open-sse/handlers/imageGeneration/fanOut.ts.

Muling ginagamit ZenMux ang umiiral nang API-key na koneksyon at tumatanggap ng zenmux/ o zm/ prefix:

  • zenmux/openai/gpt-image-2 ay gumagamit ng ZenMux's OpenAI Images API. Kasama sa mga opsyon ang size, quality, n, output_format, output_compression, background, at response_format.
  • Ang ibang mga publisher, gaya ng zm/meta/muse-image-1.0, ay gumagamit ng ZenMux's Vertex AI :predict endpoint. n mapa sa sampleCount, aspect_ratio sa aspectRatio, at image_size (1K, 2K, 4K) sa sampleImageSize. Ang isang pixel size ay nagbibigay lamang ng isang aspect ratio, hindi garantisadong mga dimensyon ng pixel. Ang mga sinusuportahang ratio, resolusyon, at bilang ay nag-iiba ayon sa modelo.
  • pinipili zm/inclusionai/ming-image-0.1-design ang sarili nitong mga sukat. Alisin size, aspect_ratio, at image_size; Ang mga tahasang halaga ay nagbabalik HTTP 400. PNG, JPEG, at WebP ay maaaring hilingin gamit ang output_format.

Sinusuportahan ng pagsasamang ito ang pagbuo ng text-to-image, hindi ang pag-edit ng reference-image. Ang output ng vertex ay na-normalize sa data[].b64_json; response_format: "url" ay nagbabalik ng upstream HTTPS URL o isang base64 na data URL kapag ang mga byte ng imahe lamang ang magagamit. Ang mga output Empty/filtered ay nagbabalik ng isang error sa halip na isang walang laman na tagumpay. Ang pag-access ng modelo ay depende sa ZenMux account. Tingnan ang ZenMux's Vertex API at OpenAI Images API.

Ang Microsoft 365 Copilot sign-in connection ay nagsisilbi copilot-m365-web/m365-copilot-image sa pamamagitan ng built-in na tool ng imahe ng Copilot: isang Copilot turn sa bawat larawan (n 1–4), size steering lang ang orientation, at mga larawang ibinalik inline (b64_json, o isang data URL para sa response_format: "url"). Tingnan ang Microsoft 365 Copilot.

# List all image models
GET /v1/images/generations

OCR ng Dokumento

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"
  }
}

Pinipili ng model ang OCR provider sa pamamagitan ng prefix na provider/model; ang model id na walang prefix (hal. mistral-ocr-latest) ay nire-resolve sa nakarehistrong provider nito, at ang hindi pagtukoy ng model ay nagde-default sa Mistral (mistral-ocr-latest). Mga nakarehistrong provider (open-sse/config/ocrRegistry.ts):

Provider id Model id model value Mga Tala
mistral mistral-ocr-latest mistral/mistral-ocr-latest (o bare mistral-ocr-latest) Synchronous — direktang ibinabalik ang response mula sa iisang upstream call.
azure-document-intelligence prebuilt-read azure-document-intelligence/prebuilt-read Asynchronous ang upstream (analyze + poll) — tingnan sa ibaba.
vertex-deepseek-ocr deepseek-ocr-maas vertex-deepseek-ocr/deepseek-ocr-maas Synchronous, sa pamamagitan ng openapi/chat/completions partner endpoint ng Vertex AI — tingnan sa ibaba para sa auth/URL.

Lahat ng tatlong provider ay tumutugon gamit ang iisang body na hugis-Mistral:

{
  "pages": [{ "index": 0, "markdown": "# Extracted text..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}

Poll flow ng Azure Document Intelligence

Asynchronous ang analyze API ng Azure Document Intelligence: ang paunang request ay nagbabalik ng header na Operation-Location sa halip na body, at kailangang i-poll ang resulta. Ang handler (open-sse/handlers/ocr.ts) ay nagpo-poll sa URL na iyon bawat segundo nang hanggang 30 pagtatangka, mabilis na nabibigo (hindi nagpapatuloy sa pag-poll) kapag non-ok ang response ng poll o "failed" ang status, at nagbabalik ng 504 kung tumatakbo pa rin ang operation matapos maubos ang budget ng mga pagtatangka. Ang huling Azure response ay nino-normalize sa parehong hugis na pages/markdown na ginagamit ng Mistral bago ibalik sa caller, kaya hindi kailangang gumawa ng espesyal na paghawak ang client code para sa provider.

Auth at pag-resolve ng endpoint para sa Vertex AI DeepSeek OCR

Muling ginagamit ng vertex-deepseek-ocr ang parehong authentication ng Vertex AI na sinusuportahan na ng OmniRoute para sa chat/image traffic (open-sse/executors/vertex.ts): ang API key ng koneksyon ay maaaring isang kredensyal na Service Account JSON (ipinagpapalit para sa panandaliang OAuth access token sa pamamagitan ng JWT-bearer flow) o isang dati nang na-mint na OAuth access token na ginagamit ayon sa pagkakakuha. Ang upstream endpoint URL ay generic na openapi/chat/completions partner endpoint ng Vertex, na binubuo mula sa project at region ng koneksyon — palaging mananaig ang tahasang providerSpecificData.project/providerSpecificData.region; kung hindi, kinukuha ang project mula sa project_id ng Service Account JSON at nagde-default ang region sa us-central1. Parehong resolution ay nagaganap sa open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl), at ginagamit ng src/app/api/v1/ocr/route.ts bago ipadala sa handleOcr.


Ilista ang mga Modelo

GET /v1/models
Authorization: Bearer your-api-key

→ Ibinabalik ang lahat ng chat, embedding, at image model + combo sa format ng OpenAI

Mga presyo ng modelo (pricing)

May dalang object na pricing ang isang entry kapag alam ng OmniRoute ang presyo ng modelo. Ang presyo ay nagmumula sa talahanayan ng presyo na ginagamit ng cost accounting: mga built-in na default, mga naka-sync na presyo, at mga override na itinakda sa pamamagitan ng /api/pricing. Mga list price ang mga ito, kaya nagpapakita rin ang mga subscription provider ng presyo bawat token.

"pricing": {
  "prompt": "0.000005",
  "completion": "0.000025",
  "input_cache_read": "0.0000005",
  "input_cache_write": "0.00000625",
  "input": 5,
  "output": 25,
  "cached": 0.5,
  "cache_creation": 6.25
}
Mga field Unit Mga tala
prompt, completion, input_cache_read, input_cache_write USD bawat token, decimal string Compatible sa OpenRouter, at hindi kailanman nasa exponent notation. Lumilitaw lamang ang dalawang cache field kapag may presyo ng cache.
input, output, cached, cache_creation USD bawat 1M token, number Mga field mula sa mga naunang bersyon ng catalog, na pinanatili para sa mga kasalukuyang client. Lumilitaw din ang reasoning at long_context kapag mayroon ang pricing row ng mga ito.
  • Taglay ng mga combo ang presyo ng una nilang nakikitang target. Pumipili ng target sa oras ng request ang mga built-in na auto/* combo, kaya wala silang pricing.
  • Ipinapakita ng mga libreng modelo ang "0" (at 0) kapag zero ang presyo ng mga ito. Ang modelong walang pricing row ay nagpapakita rin ng "0" kapag minamarkahan ito ng catalog bilang libre (free: true) o nakalista ito sa built-in na free-model catalog.
  • Hindi alam ang presyo: walang pricing key ang entry.
  • Ang mga provider na sinusukat ayon sa credit (tulad ng Kiro) ay naniningil bawat request sa halip na bawat token. Pinananatili ng kanilang mga entry ang numeric per-1M field na mayroon na sila dati at walang dalang per-token string field.
  • Kinokopya ng mga variant (mga reasoning-effort id, mga no-thinking alias, at mga discovery at gateway mirror) ang presyo ng modelong dinadaanan nila.
  • Mga base rate lamang ang dala ng mga field. Hindi binabago ng mga tier para sa long-context (ang numeric na long_context field) at mga multiplier ng service tier (halimbawa, Codex fast o flex) ang prompt o completion.
  • Pareho ang object para sa bawat istilo ng authentication, kabilang ang isang Anthropic-style request na may x-api-key at anthropic-version (nananatiling { "object": "list", "data": [...] } ang response). Implementasyon: src/app/api/v1/models/catalogPricing.ts.

Mga prefix ng model id (?prefix=)

Karamihan sa mga modelo ay ina-advertise gamit ang prefix ng provider. Kinokontrol ng feature flag na MODELS_CATALOG_PREFIX_MODE kung aling prefix ang makukuha mo, at maaari itong i-override bawat request gamit ang query parameter — kapaki-pakinabang para sa client na nais ng malinis na listahan nang hindi binabago ang setting na saklaw ng buong server para sa lahat:

GET /v1/models?prefix=alias        # isang id bawat modelo — ang maikling alias prefix
GET /v1/models?prefix=dual         # parehong anyo (default ng server)
GET /v1/models?prefix=canonical    # ang buong provider-id prefix lamang
Mode Ipinapadala Mga tala
dual cc/claude-sonnet-4-6 at claude/claude-sonnet-4-6 Default. Parehong id ang dumadaan sa iisang modelo; pinanatili ang mga ito upang patuloy na gumana ang mga client config na nag-hardcode sa alinman sa mga anyo. Halos nadodoble ang catalog.
alias cc/claude-sonnet-4-6 Isang entry bawat modelo. Ipinapadala pa rin ang entry ng mga provider na walang natatanging alias, kaya walang nawawala.
canonical claude/claude-sonnet-4-6 Isang entry bawat modelo sa ilalim ng buong provider-id prefix. Ipinapadala rin dito ng mga provider na walang natatanging alias (hal. antigravity/…, agy/…) ang kanilang iisang id, kaya walang nawawala.

Makikilala rin ang isang mirror na nasa dual mode nang walang query parameter: mayroon itong parent field na tumuturo sa pangunahing id.

Ang mga client na nagre-render ng model picker ay dapat humiling ng ?prefix=alias — ito ang ginagawa ng OmniCopilot VS Code extension.

Mga filter sa discovery (?capability=, ?min_context=, ?kind=, ?q=)

Tumatanggap ang GET /v1/models ng mga opt-in na filter para sa discovery. Kung wala ang alinman sa mga ito, hindi nagbabago ang response. Pinapaliit ng mga ito ang catalog na nakikita na ng tumatawag (una munang inilalapat ang mga pahintulot ng API key), at tumatakbo ang mga ito bago ang paging na limit / after na istilo ng OpenAI:

GET /v1/models?capability=vision&capability=tool_calling   # dapat true ang bawat nakalistang capability
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding                              # catalog na `type`; ang mga row na walang isa ay `chat`
GET /v1/models?q=sonnet&limit=10                           # case-insensitive na pagtutugma sa id o name
Param Mga value
capability attachment, reasoning, structured_output, temperature, thinking, tool_calling, vision
min_context non-negative integer, ikinukumpara sa context_length
kind chat, audio, embedding, image, moderation, music, rerank, video
q 1–200 character

Ang hindi kilalang value, o isang min_context na hindi non-negative integer (halimbawa, 1.5), ay nagbabalik ng HTTP 400 at inililista ng mensahe ang mga valid na value. Implementasyon: src/app/api/v1/models/catalogFilters.ts.

Maikling listahan ng modelo (POST /v1/models/query)

Ang POST /v1/models/query ay nagbabalik ng maikli at deterministic na listahan mula sa parehong catalog, na may parehong auth at visibility bawat key gaya ng GET /v1/models:

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

{ "capabilities": ["vision", "tool_calling"], "min_context": 128000, "max_output": 16000,
  "kind": "chat", "q": "gpt", "owned_by": "openai", "exclude": ["openai/gpt-4o"], "limit": 5 }

→ { "object": "list", "data": [ ...models ] }

Opsyonal ang bawat field. Ang capabilities at exclude ay tumatanggap ng array o string na pinaghihiwalay ng kuwit; ikinukumpara ang max_output sa max_output_tokens. Ang mga resulta ay inaayos ayon sa owned_by, pagkatapos ay id. Ang default ng limit ay 20 at nililimitahan sa 100 ang mga value na lampas sa 100. Ang invalid na JSON, hindi kilalang field, o invalid na value ay nagbabalik ng HTTP 400.

Mga indibidwal na nakatagong chat model

Ang modelong minarkahang Nakatago sa pahina ng provider nito ay inaalis sa catalog at tinatanggihan ng HTTP 404 / model_not_found kapag tahasang hiniling. Ginagamit ng pagsusuri ang naresolbang provider at modelo, kabilang ang mga alias ng provider, mga prefix ng compatible-provider node, at mga default ng koneksyon. Nilalaktawan ng combo ang mga nakatagong target at maaaring gumamit ng nakikitang sibling; kapag wala nang natitirang executable target, ibinabalik nito ang parehong error code. Magkakabisa ang pag-alis sa pagkakatago sa susunod na request. Hindi itinatago ng mga override sa visibility na pang-image lamang ang chat model na may parehong ID.

Hiwalay ang indibidwal na setting ng modelong ito sa model exposure allow/deny lists, na nagsasala sa pag-aanunsyo sa catalog at sa mga kandidato ng auto-routing habang pinananatili ang tahasang dispatch. Patuloy na hiwalay na inilalapat ang mga pahintulot ng modelo para sa API key. Nanatiling dual ang default na catalog prefix mode.

Mga variant ng modelong walang thinking

Para sa mga Claude model na may kakayahang mag-thinking, nag-aanunsyo rin ang /v1/models ng variant na walang thinking na ang id ay may prefix na claude-3-omniroute-no-thinking/:

claude-3-omniroute-no-thinking/<provider>/<model>

Kapag pinili ang id na ito (hal., sa isang configuration ng Claude Code na palaging naglalakip ng thinking block), bumabalik ang resolution sa totoong <provider>/<model> na pinigilan ang reasoning — thinking:{type:"disabled"} sa /v1/messages path, o inaalis ang mga field na reasoning/reasoning_effort sa /v1/chat/completions path. Inililista lamang ang variant para sa mga modelong kabilang sa Claude family na sumusuporta sa thinking at gumagalang sa disabled (kaya, halimbawa, hindi kasama ang mga modelong adaptive-only na tumatanggi sa disabled). Maaaring pilitin ng mga operator na i-on o i-off ang variant para sa bawat modelo sa pamamagitan ng ModelSpec.noThinkingAlias.


Manifesto ng Provider Plugin

GET /api/v1/provider-plugin-manifest

Ibinabalik ang JSON-safe na manifesto ng provider plugin na ginagamit ng Bifrost, CLIProxyAPI, at mga hinaharap na sidecar router. Binubuo ang tugon mula sa TypeScript provider registry at sadyang hindi kasama rito ang mga OAuth client secret, runtime environment resolution, executor function, request header, at account data.

Gamitin ang endpoint na ito kapag tumatakbo ang isang sidecar nang out-of-process at hindi nito mai-import nang direkta ang open-sse/config/providerPluginManifestRegistry.ts.


Pagbuo ng audio gamit ang ElevenLabs

Mag-configure ng koneksyon ng elevenlabs provider sa OmniRoute gamit ang iyong ElevenLabs API key. Nag-a-authenticate ang mga client gamit ang iyong OmniRoute key (Authorization: Bearer $OMNIROUTE_API_KEY); ibinibigay ng gateway ang nakaimbak na provider key bilang xi-api-key. Huwag kailanman magpadala ng ElevenLabs key bilang bearer token ng gateway.

Paraan Path Tugon Kategorya ng endpoint ng API key
POST /v1/sound-generation Mga native na audio byte elevenlabs
POST /v1/music Mga native na audio byte music
POST /v1/music/stream Mga streaming na audio byte music
POST /v1/music/detailed Native na multipart audio at composition plan music
POST /v1/music/detailed/stream Native na SSE metadata at mga audio chunk music
POST /v1/music/plan JSON composition plan music

Ang mga endpoint na ito ay karagdagan sa mga umiiral nang route na /v1/audio/speech, /v1/audio/transcriptions, /v1/voices, /v1/text-to-speech/{voiceId} at /v1/speech-to-text. Pinananatili ang mga native JSON field at query parameter gaya ng output_format at enable_logging. Pinananatili ng mga tugon ng /v1/music/detailed ang mga multipart boundary; i-parse ang mga ito bilang multipart. Nagbabalik ang /v1/music/detailed/stream ng text/event-stream na may composition metadata at mga base64 audio chunk sa mga SSE event. Sinusuportahan ng lahat ng anim na route ang CORS preflight.

export OMNIROUTE_BASE_URL="http://localhost:20128"
export OMNIROUTE_API_KEY="your-omniroute-api-key"

# Isang maikling sound effect. Tagal: 0.5 hanggang 30 segundo.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/sound-generation?output_format=mp3_44100_128" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"A single soft bell chime","duration_seconds":1,"model_id":"eleven_text_to_sound_v2"}' \
  --output effect.mp3

# Ang tagal ng musika ay ipinapahayag sa millisecond: 3000 hanggang 600000.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music?output_format=mp3_44100_128" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Gentle instrumental piano","music_length_ms":10000,"force_instrumental":true,"model_id":"music_v1"}' \
  --output music.mp3

Gamitin ang /v1/music/stream kasama ang kaparehong JSON body para sa incremental na paghahatid ng audio. Ang composition ay tumatanggap ng eksaktong isa sa prompt o composition_plan; kinakailangan ng /v1/music/plan ang prompt at opsyonal nitong tinatanggap ang source_composition_plan. Pinananatili ng mga native schema ang mga karagdagang field ng provider upang makarating sa ElevenLabs ang mga bersyon ng composition plan at mga opsyon sa fine-tuning.

Tumatanggap din ang pinag-isang endpoint na /v1/music/generations ng elevenlabs/music_v1, elevenlabs/music_v2 at elevenlabs/music_v2_5. Kapag may aktibong koneksyon sa ElevenLabs, inilalantad ang mga modelong ito ng music catalog. Ibinabalik ng endpoint na ito ang {"created":...,"data":[{"b64_json":"...","format":"mp3"}]}. Ang field nitong duration ay nasa segundo at itinatapat sa music_length_ms; nangunguna ang tahasang itinakdang music_length_ms. Itinatapat ang instrumental sa force_instrumental, kung saan nangunguna ang native field. Gamitin ang mga native streaming endpoint para sa streaming at ang native composition endpoint para sa mga request na composition plan lamang ang pinagmumulan.

curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music/generations" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs/music_v1","prompt":"Gentle instrumental piano","duration":10,"instrumental":true}'

Ipinapatupad ang mga paghihigpit sa endpoint, model, budget, at koneksyon bago ang upstream call. Ibinabalik ng mga native route ang mga status code at error body ng upstream nang hindi binabago, kabilang ang 402 para sa paghihigpit ng plan at 429 para sa limitasyon ng quota. Pinananatili ang mga header na character-cost, song-id, request-id at retry-after kapag mayroon. Hindi ginagarantiya ng libreng credit balance ang access sa bawat music model, output format o feature ng API: ElevenLabs ang nagpapasya sa entitlement para sa bawat request. Pinananatili ng pinag-isang endpoint ang mga error status code sa normalized error envelope ng OmniRoute.

Mga upstream contract: mga sound effect, composition ng musika at mga detalye ng streaming music.


Mga Endpoint ng Compatibility

Paraan Path Format
POST /v1/chat/completions OpenAI
POST /v1/messages Anthropic
POST /v1/responses Mga Response ng OpenAI
POST /v1/embeddings OpenAI
POST /v1/images/generations Mga Larawan ng OpenAI
POST /v1/images/edits Mga Larawan ng OpenAI (edit/inpaint)
POST /v1/videos/generations Pagbuo ng video na istilong OpenAI
POST /v1/music/generations Pagbuo ng musika na istilong OpenAI
POST /v1/audio/transcriptions Audio ng OpenAI (STT)
POST /v1/audio/speech TTS ng OpenAI (nagbabalik ng audio body)
POST /v1/rerank Rerank na istilong Cohere/Voyage
POST /v1/classify Jina classify (api.jina.ai)
POST /v1/segment Jina segmenter (segment.jina.ai)
POST /v1/moderations Mga Moderation ng OpenAI
GET /v1/models OpenAI
POST /v1/models/query Piniling listahan ng model na na-filter
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}/ Alias ng catalog ng OpenAI
GET /api/v1/vscode/{token}/models Alias ng mga model ng OpenAI
POST /api/v1/vscode/{token}/chat/completions Alias ng OpenAI na may token
POST /api/v1/vscode/{token}/responses Alias ng OpenAI Responses na may token
POST /api/v1/vscode/{token}/api/chat Alias ng Ollama na may token
GET /api/v1/vscode/{token}/api/tags Alias ng mga tag ng Ollama na may token

Pare-pareho ang hugis ng lahat ng POST route: Bearer your-api-key + JSON body na na-validate ng Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema, at iba pa; tingnan ang src/shared/validation/schemas.ts). Ibinabalik ang 4xx kapag nabigo ang schema.

Para sa mga client na hindi makapagdagdag ng Authorization: Bearer ..., tumatanggap din ang OmniRoute ng mga API key sa URL sa pamamagitan ng query-string compatibility (?token=..., ?apiKey=..., ?api_key=..., ?key=...) o ng nakalaang mga endpoint na /api/v1/vscode/{token}/... na nakadokumento sa ibaba.

# Rerank (provider mula sa cloud registry, o isang node ng provider na compatible sa OpenAI bilang "<prefix>/<model>")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina classify (mga kredensyal ng Foundation API)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina segmenter
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina search (s.jina.ai; mga alias ng provider: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Mga moderation
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — nagbabalik ng audio/mpeg (o ang hinihinging format) na body
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Nangangailangan ang Soniox TTS ng wika at boses: ang `language` ay default na "en"; ang nawawalang
# boses o pangalan ng stock voice ng OpenAI (alloy, nova, …) ay nagiging "Adrian"
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }

# Pag-edit ng larawan (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Pagbuo ng video / musika (provider-prefixed na model id)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }

Mga node ng provider para sa rerank: Ang POST /v1/rerank ay nagre-route din sa mga node ng provider na compatible sa OpenAI (oMLX, vLLM, Infinity, TEI sa likod ng gateway, …) na tinutukoy bilang <node-prefix>/<model>. Palaging kwalipikado ang mga loopback node (localhost, 127.0.0.1, 172.16.0.0/12), gayundin ang mga hostname na inilista ng operator sa OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS (hal., pangalan ng serbisyo sa Docker/Compose gaya ng http://reranker:8080/v1; direktang tinatawagan ang mga ito, hindi kailanman sa pamamagitan ng HTTP(S)_PROXY o ng naka-pin na proxy ng isang koneksyon). Ang mga node sa iba pang host — isang LAN box o Tailscale peer — ay kwalipikado lamang kapag pinagana ng operator ang feature flag na RERANK_REMOTE_PROVIDER_NODES at pumapasa ang base URL ng node sa outbound URL policy ng provider (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS / OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS). Tinatawagan ng memory engine ang rutang ito sa pamamagitan ng loopback sa hakbang na rerank, kaya ang parehong patakaran ang namamahala sa rerankProviderModel sa mga setting ng Memory.

Mga anyo ng lokal na server: Tinatawagan ang node sa <base>/v1/rerank at, kapag 404, sa <base>/rerank (Infinity, TEI). Parehong spelling ng Cohere/OpenAI (documents, return_documents) at spelling ng TEI (texts, return_text) ang dala ng upstream body, at ang tugon mula sa upstream ay ginagawang pare-pareho sa Cohere envelope: ang bare na [{index, score, text}] ng TEI, {results: [{index, score}]} mula sa mga thin gateway, at ang Voyage-style na {data: [...]} ay ibinabalik sa client bilang {results: [{index, relevance_score, document?}]}, inayos ayon sa score at nilimitahan sa top_n.

Pagtuklas ng mga node ng provider: Lumilitaw ang mga modelo sa isang provider node na compatible sa OpenAI sa GET /v1/models sa ilalim ng prefix ng node. Ang mga row na walang metadata ng endpoint (karaniwan sa mga lokal na listing ng /v1/models) ay nagmamana ng apiType ng node, kaya ang mga modelo ng node na embeddings ay nagiging type: "embedding" at ang mga modelo ng node na rerank ay nagiging type: "rerank" sa halip na maging chat bilang default; mananaig pa rin ang isang tahasang supportedEndpoints sa isang naka-sync o manu-manong idinagdag na row.

Mga Dedicated na Ruta ng Provider

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

Awtomatikong idinadagdag ang prefix ng provider kapag wala ito. Nagbabalik ng 400 ang mga modelong hindi tugma.


Files API

Endpoint ng files na compatible sa OpenAI para sa batch input/output at mga upload na may layunin ng file.

Method Path Description
POST /v1/files Mag-upload ng file (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — maximum na 512 MiB
GET /v1/files Ilista ang mga file para sa naka-authenticate na API key
GET /v1/files/[id] Kunin ang metadata ng isang file
DELETE /v1/files/[id] Mag-delete ng file
GET /v1/files/[id]/content I-stream pabalik ang raw file body

Auth: Bearer API key — ang mga file ay naka-scope sa bawat API key sa pamamagitan ng getApiKeyRequestScope. Isang key lamang ang makakakita, makakapag-download, at makakapag-delete ng sarili nitong mga file; ang isang dashboard session na walang key ay makakabasa sa buong instance; ang isang file na walang owner (na-upload nang anonymous o sa pamamagitan ng dashboard session) ay hindi maaaring ma-access ng anumang caller na hindi session. Tinatanggihan ng GET /v1/files ang anonymous caller — at ang ipinakitang key na hindi ma-resolve — gamit ang 401 kahit REQUIRE_API_KEY=false, sa halip na ilista ang mga file ng bawat tenant (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).


Batches API

Pagproseso ng batch na compatible sa OpenAI.

Method Path Description
POST /v1/batches Gumawa ng batch — bina-validate ang body ng v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET /v1/batches Ilista ang mga batch
GET /v1/batches/[id] Kunin ang status ng batch at ang request_counts
DELETE /v1/batches/[id] Mag-delete ng natapos o nabigong batch
POST /v1/batches/[id]/cancel Kanselahin ang kasalukuyang isinasagawang batch

Auth: Bearer API key. Ang mga batch ay naka-scope sa bawat API key ayon sa parehong tatlong-daan na panuntunan tulad ng files: sariling key lamang, dashboard session na sakop ang buong instance, at ang mga record na walang owner ay hindi maaaring ma-access ng anumang caller na hindi session (retrieve, delete, cancel, at ang pagsusuri ng input_file_id sa create). Tinatanggihan ng GET /v1/batches ang anonymous caller gamit ang 401 kahit REQUIRE_API_KEY=false.


Hanapin API

Web/search provider abstraction (Tavily, Brave, Exa, Serper, atbp.).

Pamamaraan Daan Paglalarawan
GET /v1/search Ilista ang mga naka-configure na search provider + na kakayahan
POST /v1/search Magpatakbo ng query sa paghahanap — body na napatunayan ng v1SearchSchema, sumusuporta sa caching/coalescing
GET /v1/search/analytics Bawat provider hit/latency/cache stats

Awth: Tagadala ng API key (extractApiKey + isValidApiKey). Ipinatupad ang patakaran sa paghahanap sa pamamagitan ng enforceApiKeyPolicy.

Auto-select: nang walang provider, ang pinakamurang provider na may naka-configure na koneksyon ay tumatakbo muna at ang susunod na pinakamurang ay ang failover. Ang mga libreng last-resort provider (duckduckgo-free) ay ginagamit lamang kapag wala nang iba pang naka-configure. Ang isang self-hosted SearXNG ay binibilang bilang na-configure kapag ang koneksyon nito ay nag-imbak ng isang tunay baseUrl (hindi ang catalog default http(s) http://localhost:8888/search): ito ay nagraranggo bilang isang $0 na provider na nangunguna sa mga naka- baseUrl, na ang pinakamurang naka-key na URL bilang failover, kabilang ang kapag SearXNG ay sumagot ng 400, 401, 403 o 404. hindi mabilang. Ang koneksyong SearXNG na nag-iimbak ng token ay nasa ganitong paraan lamang sa https:// o loopback http://. Sa malayuang plain http:// hindi ito isang failover at nananatiling huling paraan, ginagamit lamang kapag walang ibang provider ang na-configure o kapag hiniling sa pamamagitan ng pangalan, kaya ipinapadala nito ang token sa cleartext sa dalawang sitwasyong iyon.

Exa at Tavily provider_options

Binabasa ng Exa at Tavily ang mga field na partikular sa provider mula sa isang namespaced na bag: provider_options.exa (o provider_options["exa-search"]) at provider_options.tavily (o provider_options["tavily-search"]). Ang mga susi lamang sa ibaba ang ipinapasa. Ang bawat isa ay sinusuri laban sa sarili nitong Zod schema sa open-sse/handlers/search/providerOptionsPassthrough.ts, at ang isang susi na may maling uri ay nahuhulog. Anumang iba pang susi ay binabalewala, kabilang ang auth, base URL, stream at outputSchema. Ang mga flat key na ginagamit ng ibang mga provider (cx, depth, ...) ay gumagana tulad ng dati.

Provider Mga patlang sa pinakamataas na antas Nested
Exa type, category, userLocation, moderation, additionalQueries, objective, systemPrompt, compliance (flat primitives), startPublishedDate, endPublishedDate Pinagsama contents.{text, highlights, summary, extras, livecrawlTimeout, maxAgeHours} sa default { text: true, highlights: true }
Tavily search_depth, chunks_per_source, time_range, start_date, end_date, include_published_date, filter_by_published_date, include_answer, include_raw_content, include_images, include_image_descriptions, include_favicon, include_domains_mode, language, filter_by_language, auto_parameters, exact_match, include_usage, safe_search —

Palaging panalo ang mga generic na field: query, max_results, filters (mga domain), country at ang paksang hinango mula sa search_type. Sa Exa, pinapanatili ng search_type: "news" category: "news". Tumatanggap din ang Tavily search_type: "finance" (topic: "finance").

Ang gastos sa paghahanap ng Firecrawl ay naitala sa bawat panimulang bloke ng 10 ibinalik na mga resulta, sa $0.002 (2 credits) isang bloke at hindi bababa sa isang bloke bawat tawag ( Firecrawl billing ): Ang 11 resulta ay nagkakahalaga ng $0.004.

Naabot na ngayon ng generic time_range ang parehong provider: Ang Exa ay nakakakuha ng startPublishedDate (ISO timestamp) at Tavily ay nakakakuha ng start_date (YYYY-MM-DD). Ino-override ng isang tahasang petsa sa provider_options ang naka-map.

Ang mga resulta ng Exa ay nagpapanatili id, highlights (bawat highlight, hindi lamang ang unang ginamit bilang snippet), highlight_scores, summary, subpages, entities at extras sa provider_raw. Ang mga resulta ng Tavily ay nagpapanatili images at favicon.

Ang gastos sa paghahanap ng linkup ay naitala sa $0.005 para sa depth fast at standard at $0.05 para sa deep ( Pagpepresyo ng linkup ), kung depth ay nanggaling sa provider_options o sa mga setting ng koneksyon.

Ang Exa type: "lite" (Exa 3.0) ay tumatanggap ng mas maliit na hanay ng mga field at tinatanggihan ang buong kahilingan kapag nakatakda ang anumang ibang field. Para sa lite, additionalQueries, systemPrompt at bawat contents key maliban text at highlights ay ibinababa bago ang tawag. Ang hindi na ginagamit na subpages, subpageTarget, highlights.numSentences at highlights.highlightsPerUrl ay hindi na naipapasa.

Ang cost accounting ay ang flat registry costPerQuery, maliban sa Exa, na sumusunod sa sariling pagpepresyo ng Exa: $0.007 bawat tawag para sa auto (at ang legacy fast) o $0.004 para sa lite (at ang legacy instant), na sumasaklaw sa 10 resulta; $0.001 para sa bawat karagdagang resulta; at $0.001 bawat ibinalik na resulta kapag itinakda ang contents.summary. Ang Tavily ay naitala sa 1 credit ($0.008) para sa search_depth basic, fast at ultra-fast, at 2 credits ($0.016) para sa advanced ( Tavily API credits ). Ang isang tawag na may auto_parameters: true na ina-upgrade ni Tavily sa advanced ay naitala pa rin sa 1 credit.


Web Fetch API

Mag-extract ng content mula sa isang URL sa pamamagitan ng naka-configure na web-fetch provider (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract).

Ang Parallel Extract (parallel-search, kaparehong API key ng Parallel Search) ay nagbabalik ng Markdown lamang — anumang ibang format ay nagreresulta sa 400 — at nililimitahan ang content sa 100,000 character. Kapag hindi ma-extract ang target page mismo, iniuulat ito ng upstream sa loob ng HTTP 200; ipinapakita iyon ng OmniRoute bilang 422 na may nakapirming mensahe.

Method Path Description
POST /v1/web/fetch Mag-fetch/mag-scrape ng URL — bina-validate ang body ng v1WebFetchSchema

Auth: Bearer API key (extractApiKey + isValidApiKey). Ipinapatupad ang policy sa pamamagitan ng enforceApiKeyPolicy.

Quota-aware fallback (#8297): kapag walang ibinigay na tahasang provider, nilalakbay ang pool (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search → parallel-search) sa nakapirming priority order (fill-first) — nilalaktawan ang provider na may rate limit ngunit naka-configure sa halip na agad wakasan ang request, at ang isang retryable/quota upstream failure (HTTP 429 palagi; 402/403 para sa mga quota-style free tier ng Firecrawl/Tavily/TinyFish — hindi para sa Jina Reader, at hindi kailanman para sa simpleng 400 na bad request) ay ipinapasa sa susunod na hindi pa nasusubukang credentialed provider sa oras ng request. Kapag naubos ang lahat ng provider sa pool, nagbabalik ang endpoint ng isang 429 (na may Retry-After header) sa halip na dating generic na 400. Kapag tahasang hiniling ang provider, walang silent fallback — ipinapakita ng pumalya o na-rate-limit na tahasang provider ang sarili nitong error (429 kung rate-limited, kung hindi ay ang upstream status).


WebSocket Streaming

GET /v1/ws?handshake=1

Bine-validate ang WebSocket upgrade handshake at ibinabalik ang mga halimbawang mensahe ng wire protocol (request, cancel). Ang aktuwal na WS frames ay pinangangasiwaan ng bundled WS server sa labas ng Next.js route table.

Auth: Bearer API key habang isinasagawa ang handshake.

Responses API sa WebSocket (codex lamang)

# Parehong host:port ng HTTP API (default 20128); i-upgrade ang koneksyon:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (o: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# DAPAT na response.create ang unang frame:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Ang Responses-API-over-WebSocket proxy ay eksklusibong nakakabit sa codex (ChatGPT backend). Nakikinig ito sa parehong port ng API/dashboard sa mga path na /v1/responses, /responses, at /api/v1/responses. Sa unang response.create frame, nag-a-authenticate ito at naghahanda sa pamamagitan ng internal na codex-responses-ws bridge, pumipili ng codex OAuth connection, at nagtu-tunnel sa wss://chatgpt.com/backend-api/codex/responses gamit ang wreq-js transport. Tinatanggihan ang mga non-codex model (codex_ws_provider_required). Para sa quota-share routing, gamitin ang model: "qtSd/<group>/codex/<model>". Ipinatupad ito sa app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

Auth: Bearer API key habang isinasagawa ang handshake. Dapat na aktibong entrypoint ang bundled HTTP server (server-ws.mjs) (ito ang default kapag umiiral ang app/server-ws.mjs).

Model id: gamitin ang bare ChatGPT id (walang codex/ prefix)

Bine-validate ng OpenAI Codex CLI ang pangalan ng model sa client-side kapag supports_websockets = true at tinatanggihan ang provider-prefixed id gaya ng codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Ipadala ang bare id (hal. gpt-5.5). Codex-only ang bridge ng OmniRoute, kaya muli nitong nireresolba ang bare id bilang codex model (resolveCodexWsModelInfo) bago mag-tunnel upstream — kahit na ang bare na gpt-5.5 ay kung hindi man ay mairuruta sa ibang provider sa HTTP.

Pag-configure sa OpenAI Codex CLI

Ituro ang Codex CLI sa OmniRoute sa pamamagitan ng pagdaragdag ng custom provider na may WebSocket support sa ~/.codex/config.toml (gumamit ng hiwalay na CODEX_HOME upang maiwasang galawin ang umiiral na config):

model = "gpt-5.5"                 # bare id — HINDI "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # walang trailing slash; awtomatikong hinango ang WS URL (gumamit ng https/wss sa production)
wire_api = "responses"                    # tanging suportadong value mula Peb 2026
supports_websockets = true                # pinapagana ang Responses-over-WS transport
env_key = "OMNIROUTE_API_KEY"             # naglalaman ng OmniRoute API key (Bearer)
export OMNIROUTE_API_KEY=sk-...           # isang OmniRoute API key (anumang key kung REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

Ina-upgrade ng CLI ang base_url + /responses bilang WebSocket at tina-tunnel ito ng OmniRoute sa napiling codex OAuth connection. Na-validate ito end-to-end laban sa lokal na server: ibinabalik ng ChatGPT ang codex.rate_limits + response.created at sini-stream ang completion.


Pag-uulat ng Mga Quota at Isyu

Paraan Path Paglalarawan
GET /v1/quotas/check Paunang pagpapatunay ng quota para sa provider + accountId bago mag-isyu ng nakarehistrong key
POST /v1/issues/report Iulat sa GitHub ang pagkabigo sa pag-isyu ng quota/key (nangangailangan ng GITHUB_ISSUES_REPO + token)

Auth: Bearer API key (isAuthenticated).

Pagbawi ng quota session (opsyonal)

Ang isang non-streaming na POST /v1/chat/completions o POST /v1/responses na nabigo dahil sa terminal quota error (402/429/503 na ang body ay nagsasabing naubos na ang quota o credits) ay maaaring iparada at i-replay sa ibang pagkakataon sa halip na ibalik ang error. Nag-o-opt in ang caller sa bawat request gamit ang tatlong header:

Header Halaga
x-omniroute-quota-recovery auto
x-omniroute-session session id, [A-Za-z0-9._:-]{1,128}
x-omniroute-recovery-turn turn id na natatangi sa loob ng session (parehong panuntunan)

Ang mga turn lang na stream: false na walang tools, tool history o previous_response_id, at walang x-omniroute-connection pin, ang kwalipikado, at dapat nakatakda ang STORAGE_ENCRYPTION_KEY (ang request ay naka-store na encrypted nang hanggang 24 na oras). Ang response ay magiging 202 na may recovery.poll; i-poll ang GET /v1/quota-recoveries/{id} (202 habang nakabinbin, 200 na may recovered body kapag nakumpleto) o kanselahin gamit ang DELETE. Ang mga ticket ay makikita lamang ng API key na lumikha sa mga ito. Ang replay na hindi tiyak ang kinalabasan ay nagtatapos sa needs_confirmation sa halip na maipadala nang dalawang beses. Source: src/lib/quota/quotaSessionRecovery.ts.


Self-service na paggamit (/api/usage/om-usage)

Mababasa ang anumang API key** sarili nito** paggamit at quota — walang management auth. Ito ang endpoint na ginagamit ng isang kliyente (CLI, ang OmniCopilot panel) upang ipakita sa isang key holder ang kanilang paggastos.

# Text form (the historical contract — plain text for a terminal)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Structured form — what a UI consumes
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

Dapat mayroon ang susi**allowUsageCommand** naka-enable (naka-off bilang default — i-toggle ito ng API-key manager ng dashboard sa bawat key). Kung wala ito ang endpoint ay sumasagot 403.

?format=json ay nagbabalik ng isang discriminated na hugis kaya ang isang tumatawag ay hindi kailanman nagbabasa ng field ng data sa isang pagtanggi. Sa tagumpay:

{
  "allowed": true,
  // present only when the key opted into per-key usage limits (daily/weekly/5-hour USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // the selected provider quota snapshot, or null when nothing is cached yet:
  "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */} },
  // every connection's snapshot, so a UI can render several providers side by side:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

Sa pagtanggi (401 bad key / 403 not allowed) ang parehong ruta ay nagbabalik ng { "allowed": false, "error": { "message": "…" } } — a present-but-empty personal/provider (key allow, wala pang natutunan) ay ibang estado sa pagtanggi, at ang JSON form lang ang nagpapakilala sa kanila.

Awth: sariling Bearer API key ng tumatawag, na-validate sa isValidApiKey — ito ay hindi ang management surface (/api/keys/…), na nananatili sa likod requireManagementAuth.

Raw vs. Cutoff-Adjusted Quota Porsyento

Kapag gumagamit ng /api/usage/om-usage, dapat tandaan ng mga tumatawag ang pagkakaiba sa pagitan ng mga porsyentong ipinakita ng** plain-text na output** at ang nakabalangkasJSON output :

Aspeto Plain-text na format (/api/usage/om-usage / @@om-usage) JSON format (?format=json)
Output field NN% left (hal., 20% left) provider.quotas / providers[].quotas
Pagsusukat Cutoff-adjust na magagamit na allowance : natitirang kapasidad sa itaas ng cutoff threshold Raw upstream quota : hindi nababagay na pagsukat ng provider
Cutoff scaling Na-scale sa pamamagitan ng effectiveRemainingPercent() kaya ang protektadong reserba ay nagbabasa bilang 0% left Wala (mga raw snapshot value gaya ng iniulat ng provider)
Threshold data Isinama sa ipinakitang porsyento Naka-imbak sa quotaWindowThresholds bawat koneksyon (o mga default ng server)
Pangunahing mamimili Interactive CLIs, terminal prompt, human operator Mga programmatic na integration, dashboard, analytics, billing tracker

Ang Cutoff Adjustment Formula

Sinusuportahan ng OmniRoute ang mga proactive na cutoff ng quota para maiwasan ang upstream exhaustion (na-configure sa pamamagitan ng koneksyon quotaWindowThresholds, mga default ng provider, o mga setting ng global resilience). Kapag ang isang cutoff threshold (hal., cutoff = 25%) ay aktibo sa isang quota window, kinakalkula ng text renderer ang natitirang allowance bilang:

  • Kung remaining <= cutoff: nagbabalik ng 0%.
  • Kung remaining > cutoff: nagbabalik ng ((remaining - cutoff) / (100 - cutoff)) * 100.

Ang na-format na output ng text ay iniikot ito sa pinakamalapit na integer (Math.round(...)).

Mapaglarawang Halimbawa

Isaalang-alang ang isang window ng provider na may** 60% raw na paggamit** (kaya** 40% raw ang natitirang quota** ) at isang naka-configure** 25% na natitirang-quota cutoff** threshold:

Representasyon Pagkalkula Natitira Ipinahiwatig na Ginamit
Raw JSON (?format=json) Upstream snapshot (quotas[window]) 40% 60%
Format ng teksto (NN% left) ((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100 20% 80% (kung kinakalkula 100 - remaining)
  • Bakit ipinapakita ng text ang 20% na natitira: Mula sa 40% na pisikal na quota na natitira sa account, 25% ang nakalaan sa patakaran ng cutoff. Ang tumatawag ay mayroon na lamang 15% sa 75% magagamit na headroom na natitira bago huminto ang router sa pagruruta sa koneksyong ito. Tinitiyak ng pag-scale na ang koneksyon ay nagpapahiwatig ng pagkaubos (0% left) nang eksakto kung kailan titigil ang pagruruta.
  • Bakit pinapanatili JSON ang mga hilaw na halaga: Ibinabalik ng JSON payload ang eksaktong snapshot ng provider (UsageSnapshot) para magkaroon ng access ang mga external na tool sa paggamit ng ground-truth upstream at quotaWindowThresholds sa antas ng koneksyon nang walang lossy scaling sa panig ng server.

Patnubay sa Migrasyon ng Consumer

Kung ang isang panlabas na pagsasama (gaya ng isang editor plugin o extension ng ahente) ay dati nang nag-scrap sa text endpoint (NN% left) at nakalkula ang ginamit na porsyento bilang 100 - NN, ang pag-migrate sa ?format=json ay nangangahulugang:

  • Ang pagbabasa ng mga hilaw na halaga JSON ay magpapakita** aktwal na upstream na pagkonsumo** (60% ang ginamit sa halimbawa sa itaas).
  • Kung nais ng integration na mapanatili ang magagamit na allowance na semantics ng endpoint ng text, masusuri nito ang epektibong natitirang formula sa client-side gamit ang quotaWindowThresholds para sa mga override sa antas ng koneksyon.

Semantic Cache

# Kunin ang mga istatistika ng cache
GET /api/cache/stats

# I-clear ang lahat ng cache
DELETE /api/cache/stats

Halimbawa ng response:

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

Epekto sa latency

Ang isang semantic cache HIT ay naghahatid ng response mula sa cache nang walang upstream call, kaya halos zero ang iniulat na X-OmniRoute-Response-Latency (anuman ang orihinal na upstream latency). Dapat tingnan ng mga client na sensitibo sa latency (gaya ng benchmarking at p50/p99 monitoring) ang response header na X-OmniRoute-Cache-Latency:

Value Kahulugan
synthetic Response na inihatid mula sa cache; hindi tunay na upstream time ang latency
(absent) Response mula sa tunay na upstream call

Pag-bypass ng cache sa bawat key

Maaaring mag-opt out ang mga API key sa mga semantic cache read sa pamamagitan ng cacheDefaultMode:

Value Gawi
legacy Karaniwang gawi ng cache (default)
bypass Laktawan nang buo ang cache lookup; palaging mag-hit sa upstream

Itakda sa paggawa ng key (POST /api/keys) o pag-update (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Pag-bypass ng cache sa bawat request

Maaaring mag-bypass ng cache ang anumang request anuman ang mga setting ng key:

X-OmniRoute-No-Cache: true

Compatibility sa Pamamahala ng CLIProxyAPI

Sinasagot ng OmniRoute ang tatlong endpoint ng pamamahala ng CLIProxyAPI na ginagamit ng mga usage dashboard upang basahin ang mga limitasyon ng subscription sa Claude at Codex (halimbawa, ang cliproxy usage-limit source ng T3 Code). Ituro ang base URL ng client sa OmniRoute at gumamit ng API key na may manage scope bilang management key nito. Inihahatid ang mga route sa /v0/management/* at sa /api/v0/management/*.

Method Path Paglalarawan
GET /v0/management/auth-files Mga Claude at Codex OAuth connection bilang { files: [{ id, auth_index, provider, email, disabled, id_token }] }. Walang token
POST /v0/management/api-call Body { auth_index, method, url, header?, data? }. Nagpapadala ng isang pinapayagang request gamit ang token ng account at nagbabalik ng { status_code, body }
POST /v0/management/reset-quota Body { auth_index }. Nililinis ang connection cooldown, model lockout at mga Codex per-scope cooldown ng isang account
  • Ang auth_index ay ang connection id ng OmniRoute. Ang provider ay claude o codex (mga OAuth connection lamang; hindi nakalista ang anthropic API-key provider). Para sa Codex, ang id_token.chatgpt_account_id ay ang nakaimbak na workspace id at ang plan_type ang nakaimbak na plan.
  • Ang api-call ay hindi isang generic proxy. Tumatanggap lamang ito ng Claude GET https://api.anthropic.com/api/oauth/usage at Codex GET https://chatgpt.com/backend-api/wham/usage, GET .../wham/rate-limit-reset-credits at POST .../wham/rate-limit-reset-credits/consume, at bawat isa ay para lamang sa account ng katugmang provider. Anumang iba pa ay nagbabalik ng 403 nang hindi kumokontak sa upstream. Hindi pinapansin ang Authorization header ng tumatawag (kabilang ang placeholder na $TOKEN$): ini-inject ng OmniRoute ang access token ng connection, nire-refresh muna ito kapag malapit nang mag-expire, at ipinapasa lamang ang mga pinapayagang header (anthropic-beta; OpenAI-Beta, Originator, Chatgpt-Account-Id; Accept, Content-Type). Kung walang Chatgpt-Account-Id, ginagamit bilang default ang nakaimbak na workspace id. Nagta-time out ang mga request makalipas ang 15 segundo at ginagamit ang proxy ng connection.
  • Iniiwan ng reset-quota ang mga terminal state (banned, expired, credits_exhausted) na hindi nababago. Ang hindi kilalang auth_index ay nagbabalik ng 404.

Auth: dashboard session o API key na may manage scope, na kinakailangan kahit naka-disable ang login (nasa ALWAYS_PROTECTED_API_PATHS ang mga path). Nagkakakuha ng 403 ang mga key na para lamang sa inference. Source: src/lib/cliproxyCompat/managementApi.ts.


Dashboard at Pamamahala

Ang mga ruta ng pamamahala (/api/* maliban sa pampublikong auth/login) ay** hindi** pinahintulutan ng ordinaryong inference API key. Mga pamilya ng kredensyal, saklaw, at mga halimbawa ng curl: Pagpapatunay ng Pamamahala.

Authentication

Endpoint Pamamaraan Paglalarawan
/api/auth/login POST Mag-login
/api/auth/logout POST Mag-logout
/api/settings/require-login GET/POST Katayuan sa pag-login (GET, pampubliko). itinatakda ng POST ang password / toggles login: operator-only once na may password (dashboard session, local CLI, o login disabled — API keys at oma_ token get 403); ang isang dashboard session ay nagpapadala ng currentPassword upang palitan ang password

Pamamahala ng Provider

Endpoint Pamamaraan Paglalarawan
/api/providers GET/POST Maglista / gumawa ng mga provider
/api/providers/[id] GET/PUT/DELETE Pamahalaan ang isang provider
/api/providers/[id]/test POST Subukan ang koneksyon ng provider
/api/providers/[id]/models GET Maglista ng mga modelo ng provider
/api/providers/validate POST I-validate ang config ng provider
/api/providers/bulk POST Maramihang magdagdag ng mga API key para sa provider ONE
/api/providers/import POST Mag-import ng magkakaibang provider LIST mula sa na-parse CSV/JSON file (#6836); per-row partial-failure na mga resulta
/api/provider-nodes* Iba't-ibang Pamamahala ng node ng provider
/api/provider-models GET/POST/PUT/PATCH/DELETE Mga custom na modelo at mga override sa bawat modelo (idagdag, i-update, hide/show, tanggalin)
/api/provider-models/validate-and-add POST Pamamahala-authenticated, opt-in mahigpit na koneksyon validation at atomic custom-modelo pagpaparehistro; tingnan ang pagpapatunay ng modelo

Para sa mga modelong synced/imported, tinatanggap ng PUT /api/provider-models provider, modelId, at maxOutputTokenOverride: isang positive integer ang nagtatakda ng manu-manong output-token cap, at ki-clear ito null para ibalik ang default. ibinabalik GET /api/provider-models?provider=<provider> ang mga value na ito sa modelOutputOverrides, kabilang ang mga modelong walang custom-model row. Ang override ay gumagamit ng runtime max_output_tokens na kakayahan at nakakaligtas sa isang muling pag-sync ng modelo. Ang pahina ng provider na katugma sa OpenAI ay nag-aalok ng parehong edit/clear na kontrol at pagmamarka ng mga modelo na may tahasang suporta sa paningin.

Sa isang katugmang node ng provider, iniimbak ng mga write path (POST, PUT, PATCH, DELETE at /api/provider-models/validate-and-add) ang modelong id bilang hubad na upstream id: ang isang id na na-paste mula sa isang prefix na listahan ay may anumang nangungunang stack ng sariling prefix ng node na na-collapse, at ang mga tugon ay nag-echo sa nakaimbak na id. Ang mga naka-slash na id ng Canonical providers (hal. nvidia/nemotron-…) ay iniimbak ng verbatim. /v1/models ay hindi kailanman naglalabas ng nakasalansan na <prefix>/<prefix>/<model> id.

Ang mga node ng Custom na Pagkumpleto ng Chat ay iniangkop ang mga tahasang pag-opt-out sa pangangatwiran sa upstream na backend. Awtomatikong pinipili ng matagumpay na pagsubok sa koneksyon ang mga kontrol sa chat-template para sa bawat eksaktong modelong ID na ang /models entry ay nagpapatunay ng kinikilalang halaga owned_by : vllm, sglang, o llamacpp. Maaaring mapanatili ng mga transparent na wrapper na tugma sa OpenAI ang orihinal na entry ng modelo sa loob ng isang nested openai object; ang pagtuklas ay sumusunod hanggang sa tatlong ganoong sobre. Ang mga modelong may nawawala, hindi alam, o sumasalungat na pagmamay-ari ay nagpapanatili ng ordinaryong OpenAI na gawi. Muling ginagamit ng Detection ang kasalukuyang kahilingan sa catalog, hindi bumubuo ng mga token sa pagkumpleto, at hindi wasto kapag nagbago ang endpoint ng koneksyon.

Upang i-pin ang gawi para sa isang backend na hindi naglalantad sa metadata na iyon, gamitin ang kasalukuyang bahagyang update ng provider API:

{
  "providerSpecificData": {
    "reasoningControl": "chat-template"
  }
}

Ipadala ang katawan na iyon gamit ang PUT /api/providers/<connection-id>. Sa koneksyon na iyon, ang isang tahasang pagsisikap sa pangangatwiran ng none ay ipinapadala bilang chat_template_kwargs.thinking=false at chat_template_kwargs.enable_thinking=false. Ang mga tahasang halaga ng native na template ay nananatiling may awtoridad maliban kung ang isang server-side na panuntunan sa pangangatwiran ay pumipilit ng pagsisikap. Nalalapat lang ang setting kapag ang isang custom na koneksyon na katugma sa OpenAI ay nagpapadala ng katawan ng Mga Pagkumpleto ng Chat; Pinapanatili ng mga kahilingan sa pagtugon at ordinaryong provider ang hugis ng kanilang katutubong kahilingan. Itakda reasoningControl sa openai upang pilitin ang ordinaryong OpenAI reasoning_effort passthrough, o alisin ang it/set sa null upang gumamit ng awtomatikong pag-detect.

Claude Code auto-mode classifier ay humihiling ng default na katutubong pag-iisip na i-disable kapag wala silang mga tahasang kontrol sa pangangatwiran. Ginagamit ng detection ang system marker ng classifier sa mga kahilingan sa format ng Claude, hindi sa mga pangalan ng modelo o mga limitasyon sa pagkumpleto. Ang mga tahasang kontrol sa katawan, suportadong effort/thinking header, mga panuntunan sa pagruruta, at nalutas na pagsusumikap sa modelo ay nagpapanatili sa kanilang kasalukuyang priyoridad. Ang parehong mga yugto ng classifier ay nagpapanatili ng kanilang mga senyas, mga limitasyon sa pagkumpleto, mga pagkakasunud-sunod ng paghinto, at mga tunay na hatol ng pahintulot sa upstream; ang ikalawang yugto ay maaari pa ring gumawa ng hinihiling nitong nakikitang pangangatwiran bilang ordinaryong teksto.

OAuth dumadaloy

Endpoint Pamamaraan Paglalarawan
/api/oauth/[provider]/[action] Iba't-ibang OAuth na partikular sa provider

Routing at Config

Endpoint Pamamaraan Paglalarawan
/api/models GET/PUT Listahan ng modelo / pag-update ng alyas
/api/models/alias GET/POST Mga alyas ng modelo
/api/models/catalog GET Lahat ng modelo ayon sa uri ng provider +
/api/combos* Iba't-ibang Pamamahala ng combo
/api/keys* Iba't-ibang API key na pamamahala
/api/pricing GET Pagpepresyo ng modelo

Limitado ng modelo ang pinagmulan

GET /api/models?withLimits=1 ( true din ; 0/false o pag-alis dito ay nagpapanatili sa default na payload na hindi nagbabago) ay nagdaragdag ng contextWindow, maxInputTokens, maxOutputTokens at isang capsSource object sa bawat hilera ng modelo. Pinangalanan ng capsSource ang panuntunang nagbigay ng bawat limitasyon, kaya ang nakakagulat na limitasyon (halimbawa, 128k sa isang 1M na modelo) ay maaaring ma-trace sa pinagmulan nito. Ang mga nalutas na halaga ay pareho sa mga ginagamit sa pagruruta; ang bandila ay nagdaragdag lamang ng mga patlang at hindi kailanman nagbabago ng isang halaga. Anumang iba pang halaga withLimits ay tinanggihan ng 400.

halaga capsSource Pinagmulan
override:context Patuloy na pag-override sa context-window override (model_context_overrides)
override:max_input / override:max_output Patuloy na pag-override sa kakayahan ng max_input_tokens / max_output_tokens
static-authoritative:<provider>/<model> Static authoritative context-window table
synced:<provider>/<model> models.dev synced capability row
registry:<provider>/<model> Entry sa pagpapatala ng provider
spec:<model> Static modelo spec
prefix effort-base: Row na hiniram mula sa base na modelo ng isang effort-suffixed na variant
none Walang pinagmulan ang nagpahayag ng limitasyon (ang halaga ay null)

Pagpapatupad: getResolvedModelCapabilitiesWithLimitSources() sa src/lib/modelCapabilities.ts at ang mga precedence chain sa src/lib/modelCapabilityLimits.ts.

Paggamit at Analytics

Endpoint Pamamaraan Paglalarawan
/api/usage/history GET Kasaysayan ng paggamit
/api/usage/logs GET Mga log ng paggamit
/api/usage/request-logs GET Mga log sa antas ng kahilingan
/api/usage/[connectionId] GET Paggamit sa bawat koneksyon
/api/usage/token-limits GET/POST/DELETE Per-API-key token-limit na mga badyet
/api/usage/model-latency-stats GET Rolling per-provider/model latency aggregate (avg/p50/p95/p99, rate ng tagumpay); mga filter: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health GET Prompt-cache na buod ng kalusugan sa call_logs — write/read ratio, p50/p90/p99 write-size distribution, heavy-write concentration, per-model split, at isang healthy/degraded/thrash/no-data na hatol; query params range (1h| 24h| 7d| 30d, default 24h) at opsyonal model (#8827)

API key na mga pahintulot

Ina-update PATCH /api/keys/{id} ang mga pahintulot ng umiiral nang key. Tulad ng bawat ruta /api/keys* kailangan nito ng pahintulot sa pamamahala (tingnan ang Management Authentication ), hindi isang inference key. Ipadala lamang ang mga field na gusto mong baguhin; ang isang kahilingan na wala sa kanila ay tinanggihan ng No valid fields to update. Ang mga tinanggap na field ay tinukoy ng updateKeyPermissionsSchema sa src/shared/validation/schemas/keys.ts.

Patlang Uri Mga Tala
name string, 1-200 character
isActive boolean
isBanned boolean
expiresAt ISO 8601 datetime o null nililinis null ang pag-expire
modelAccessMode all | restricted Dapat walang laman allowedModels kapag all ang mode
allowedModels, blockedModels hanay ng mga string, hanggang 1000
allowedCombos hanay ng mga string, hanggang 500 Maaaring tumawag ang mga gate na nagsasama ng susi; Ang mga direktang modelo ay pinamamahalaan ng modelAccessMode / allowedModels
connectionAccessMode all | restricted allowedConnections ay dapat na walang laman kapag restricted at walang laman kapag all
allowedConnections hanay ng UUIDs, hanggang 100
allowAutoCombos boolean tinatanggihan false ang mga kahilingan para sa mga modelong auto/* na may ganitong key; pinapayagan ang mga key na hindi kailanman nagtakda nito
catalogScope all | combos | models Ano ang inilista ng GET /v1/models para sa key na ito (mga combos lang, mga modelo lang, o pareho); hindi nito binabago kung ano ang maaaring tawagin ng susi
forcedModel string hanggang 300 char, o null Iruta ang mga kahilingan sa chat sa model/combo na ito, sa X-Route-Model at body.model; nalalapat pa rin ang mga limitasyon ng susi
noLog, autoResolve boolean
throttleDelayMs integer, 0-300000
maxSessions integer, 0-10000
rateLimits array ng { limit, window } (positive integers, hanggang 50) o null nililimas null ang mga limitasyon
accessSchedule bagay sa iskedyul o null nililinis null ang iskedyul
scopes hanay ng mga string, hanggang 32
allowedEndpoints hanay ng mga string, hanggang 20
streamDefaultMode legacy | json
cacheDefaultMode legacy | bypass Tingnan ang Per-key cache bypass
compressionEnabled boolean
codexServiceMode isa sa mga mode ng serbisyo Codex
disableNonPublicModels boolean
allowUsageCommand boolean
usageLimitEnabled boolean
dailyUsageLimitUsd, weeklyUsageLimitUsd numero >= 0 o null
fiveHourUsageLimitUsd numero >= 0 o null Rolling 5-hour USD budget, na ipinapatupad tulad ng pang-araw-araw at lingguhang limitasyon (usageLimitEnabled, UNPRICED_USAGE_BUDGET_POLICY). retry-after ay kapag ang pinakamatandang paggastos sa window ay lumampas, na maaaring mag-iwan ng key na lampas sa limitasyon nito na naka-block pa rin.
chaosModeEnabled boolean
curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \
  -H "Authorization: Bearer <management-credential>" \
  -H "Content-Type: application/json" \
  -d '{ "allowAutoCombos": false, "catalogScope": "combos" }'

Mga setting

Endpoint Pamamaraan Paglalarawan
/api/settings GET/PUT/PATCH Pangkalahatang mga setting. Ang mga security-policy key (requireLogin, newPassword, oidc*, corsOrigins, bruteForceProtection) ay nangangailangan ng currentPassword at isang kredensyal ng operator — API key at oma_ token ay nakakakuha ng 403; bawat mutation ay nangangailangan ng admin access-token scope
/api/settings/proxy GET/PUT Config ng proxy ng network
/api/settings/proxy/test POST Subukan ang koneksyon ng proxy
/api/settings/ip-filter GET/PUT IP allowlist/blocklist
/api/settings/thinking-budget GET/PUT Thinking/reasoning** kahilingan** rewrite mode (passthrough / auto-strip / custom / adaptive). Malaya sa compression. Tingnan ang THINKING_BUDGET.md.
/api/settings/system-prompt GET/PUT Prompt ng pandaigdigang sistema
/api/settings/compression GET/PUT Global compression config
/api/settings/purge-request-history POST I-clear ang mga hilera ng log ng kahilingan at mga lokal na artifact ng call-log

Konteksto at Compression

Endpoint Pamamaraan Paglalarawan
/api/compression/preview POST I-preview off/lite/standard/aggressive/ultra/RTK/stacked compression
/api/compression/language-packs GET Ilista ang mga available na pack ng wika ng Caveman
/api/compression/rules GET Ilista ang metadata ng panuntunan ng Caveman
/api/context/caveman/config GET/PUT alias ng mga setting na partikular sa Caveman
/api/context/rtk/config GET/PUT Mga setting na tukoy sa RTK, kabilang ang mga custom na filter at pagpapanatili ng raw-output
/api/context/rtk/filters GET RTK filter catalog at custom-filter diagnostics
/api/context/rtk/test POST Patakbuhin ang RTK preview/test laban sa isang text payload
/api/context/rtk/raw-output/[id] GET Basahin ang nananatiling na-redact na raw na output sa pamamagitan ng pointer id
/api/context/combos GET/POST Compression combo list/create
/api/context/combos/[id] GET/PUT/DELETE Compression combo detail/update/delete
/api/context/combos/[id]/assignments GET/PUT Magtalaga ng mga compression combo sa mga routing combo
/api/context/analytics GET alias ng compression analytics

Pagsubaybay

Endpoint Pamamaraan Paglalarawan
/api/sessions GET Aktibong pagsubaybay sa session
/api/rate-limits GET Mga limitasyon sa rate ng bawat account
/api/monitoring/health GET Buod ng provider + sa pagsusuri sa kalusugan (catalogCount, configuredCount, activeCount, monitoredCount). Kasama sa view ng pamamahala ang credentialHealth: probe-cache scalars, failedConnections when failed>0, at staleDbNonOkCount (SQLite sticky test_status, hindi ang gauge). Tingnan ang MONITORING_GUIDE.md.
/api/cache/stats GET/DELETE Mga istatistika ng cache / malinaw
/api/modality-bridge/stats GET In-memory attempts, mga tagumpay/bridged, mga pagkabigo, mga hit sa cache, totalLatencyMs, latencySamples, sample-denominated averageLatencyMs, at oras ng huling paggamit (i-reset sa pag-restart; pamamahala ng auth)
/api/modality-bridge/video/runtime GET Mahigpit na pinagkakatiwalaang-loopback check bago pamamahala auth/probe; sanitized FFmpeg/ffprobe availability at mga bersyon (no-store)
/api/modality-bridge/video/extract POST Panloob na napatotohanan pinagkakatiwalaang-loopback byte broker; 50 MiB input, bounded queue/32 MiB output, 503 capacity, 499 disconnect, 504 deadline; hindi isang pampublikong pag-upload API

Pag-drill-down ng video frame

Nabasa GET /api/v1/video-bridge/drilldown ang isang opaque na handle na ibinalik sa x-omniroute-video-drilldown pagkatapos ng tahasang pagpayag na kahilingan sa Video Bridge. Ang parehong pagbabasa at DELETE ay palaging nangangailangan ng isang wastong API key at ang independiyenteng pahintulot modalityBridgeVideoDrilldownRemoteEnabled ng operator. Ang pagpapanatili ng produksyon ay nangangailangan din modalityBridgeVideoDrilldownEnabled at mahigpit na per-part drilldown: true. Kung ang key ay may walang laman na endpoint allowlist, dapat itong may kasamang video para sa parehong GET at DELETE, gumagamit man ang tumatawag /v1 o /api/v1.

GET query: kinakailangan handle; opsyonal variant (preview, standard, detail), limit (1–8; tinatanggap ang legacy frames ngunit hindi maaaring pagsamahin sa limit), zero-based na page, at start/end na segundo. Kapag ang parehong mga hangganan ng focus ay ibinigay, end ay dapat na mas malaki kaysa sa start. Ang mga Duplicate/unknown query key ay tinanggihan. Ang mga matagumpay na tugon ay naglalaman ng derivation, durationSeconds, frames, hasMore, page, variant, at opsyonal focusWindow; Ang no-store JSON ay nililimitahan sa 32 MiB kasama ang Base64. Ang sobrang laki ng output ay nagbabalik ng 413; humiling ng mas kaunting mga frame.

ibinabalik ng DELETE /api/v1/video-bridge/drilldown?handle=... { "removed": 0|1 }. Hindi alam, nag-expire at cross-key GETs ay hindi nakikilala 404 mga tugon; hindi maalis ng cross-key DELETE ang entry ng may-ari. Ang disabled na pag-access ay nagbabalik ng 403, missing/invalid authentication 401, mga invalid na query 400, pagkansela 499 at mga pansamantalang error 503. Ang mga handle ay lokal na proseso, mag-e-expire pagkalipas ng sampung minuto, at hindi makakaligtas sa pag-restart. Gumagamit ang mga bagong handle v1. kasama ang isang 32-byte na random Base64URL token; mga token hash lang ang pinananatili. Ang mga legacy na 64-hex na token ay nananatiling syntactically readable para sa compatibility. Tingnan ang mga guardrail ng Video Bridge para sa pahintulot, mga quota at mga detalye ng derivation ng variant.

Backup at Export/Import

Endpoint Pamamaraan Paglalarawan
/api/db-backups GET Ilista ang mga available na backup
/api/db-backups PUT Gumawa ng manu-manong backup
/api/db-backups POST Ibalik mula sa isang partikular na backup
/api/db-backups PATCH I-save ang mga setting ng backup na pagpapanatili (operator-only)
/api/db-backups DELETE Putulin ang mga naka-imbak na backup sa mga setting ng pagpapanatili (operator-only)
/api/db-backups/export GET I-download ang database bilang .sqlite file
/api/db-backups/import POST Mag-upload ng .sqlite file para palitan ang database (?dryRun=true validates lang)
/api/db-backups/exportAll GET I-download ang buong backup bilang .tar.gz archive

/api/db-backups/export, /api/db-backups/exportAll at /api/settings/export-json ibigay ang bawat naka-imbak na kredensyal, kaya kailangan nila ang session ng dashboard o ang lokal CLI (o hindi pinagana ang pag-login). API key ng anumang saklaw at oma_ access token ay makakakuha ng 403. Ang mga pagpapanumbalik ay may parehong hangganan: POST /api/db-backups/import (dryRun=true kasama), POST /api/db-backups (ibalik sa pamamagitan ng id) at POST /api/settings/import-json ay palitan ang live na database o mga setting, kaya ang isang kredensyal ng makina ay makakakuha din 403 doon; Ipinapadala ng omniroute sync import ang lokal na kredensyal CLI. Gayon din DELETE /api/db-backups (prune stored backups) at PATCH /api/db-backups (retention settings: ang mga persisted values ay nagtutulak ng awtomatikong pruning pagkatapos ng bawat backup). Ang listahan (GET) at paglikha ng manu-manong backup (PUT) ay nagpapanatili ng ordinaryong pamamahala ng auth.

Cloud Sync

Endpoint Pamamaraan Paglalarawan
/api/sync/cloud Iba't-ibang Mga pagpapatakbo ng cloud sync
/api/sync/initialize POST Simulan ang pag-sync
/api/cloud/* Iba't-ibang Pamamahala ng ulap

Mga lagusan

Endpoint Pamamaraan Paglalarawan
/api/tunnels/cloudflared GET Basahin ang Cloudflare Quick Tunnel install/runtime status para sa dashboard
/api/tunnels/cloudflared POST Paganahin o huwag paganahin ang Cloudflare Quick Tunnel (action=enable/disable)
/api/tunnels/ngrok GET Basahin ang ngrok Tunnel runtime status para sa dashboard
/api/tunnels/ngrok POST Paganahin o huwag paganahin ang ngrok Tunnel (action=enable/disable)

CLI Tools

Endpoint Pamamaraan Paglalarawan
/api/cli-tools/claude-settings GET katayuan Claude CLI
/api/cli-tools/codex-settings GET katayuan Codex CLI
/api/cli-tools/droid-settings GET Katayuan ng Droid CLI
/api/cli-tools/openclaw-settings GET katayuan OpenClaw CLI
/api/cli-tools/runtime/[toolId] GET Pangkaraniwang CLI runtime

Kasama sa mga tugon CLI ang: installed, runnable, command, commandPath, runtimeMode, reason.

ACP Ahente

Endpoint Pamamaraan Paglalarawan
/api/acp/agents GET Ilista ang lahat ng nakitang ahente (built-in na + custom) na may status
/api/acp/agents POST Magdagdag ng custom na ahente o i-refresh ang detection cache
/api/acp/agents DELETE Mag-alis ng custom na ahente sa pamamagitan ng id query param

Kasama sa tugon ng GET ang agents[] (id, pangalan, binary, bersyon, naka-install, protocol, isCustom) at summary (kabuuan, naka-install, notFound, builtIn, custom).

Mga Limitasyon sa Katatagan at Rate

Endpoint Pamamaraan Paglalarawan
/api/resilience GET/PATCH Get/update request queue, connection cooldown, provider breaker, at mga setting ng paghihintay
/api/resilience/reset POST I-reset ang mga circuit breaker ng provider
/api/resilience/model-cooldowns GET Maglista ng mga aktibong lockout sa bawat (provider, koneksyon, modelo), pinagsunod-sunod ayon sa natitirang oras
/api/resilience/model-cooldowns DELETE I-clear ang isang model lockout — body {provider, model} o {all: true} para i-wipe ang lahat
/api/rate-limits GET/POST Per-account rate limit status (GET) o toggle rate-limit na proteksyon para sa isang koneksyon (POST {connectionId, enabled}). Sinusuportahang write path para sa rateLimitProtection (hindi kailanman binago sa pamamagitan PUT /api/providers/[id]). Tandaan: hindi pinapagana enabled: false ang tahasang proteksyon ngunit hindi nag-o-opt ng aktibong koneksyon sa API-key mula sa pandaigdigang auto-enable na safety net (autoEnableApiKeyProviders).
/api/rate-limit GET Pangkalahatang pagsasaayos ng limitasyon sa rate (hindi na ginagamit; alias hanggang /api/rate-limits)

Lahat ng apat na ruta /api/resilience/* ay nangangailangan** pamamahala ng auth** (requireManagementAuth). Tingnan ang Resilience (extended) para sa kumpletong breakdown ng provider breaker vs connection cooldown vs model lockout.

Evals

Endpoint Pamamaraan Paglalarawan
/api/evals GET/POST Maglista ng mga eval suite / run evaluation

Mga patakaran

Endpoint Pamamaraan Paglalarawan
/api/policies GET/POST/DELETE Pamahalaan ang mga patakaran sa pagruruta

Pagsunod

Endpoint Pamamaraan Paglalarawan
/api/compliance/audit-log GET Log ng audit ng pagsunod (huling N)

v1beta (Gemini-Compatible)

Endpoint Pamamaraan Paglalarawan
/v1beta/models GET Maglista ng mga modelo sa Gemini format
/v1beta/models/{...path} POST Gemini generateContent endpoint

Ang mga endpoint na ito ay sumasalamin Gemini's API na format para sa mga kliyenteng umaasa sa native Gemini SDK compatibility.

Panloob / System APIs

Endpoint Pamamaraan Paglalarawan
/api/init GET Simulan ang mga serbisyo sa pag-sync sa background (pamamahala ng auth)
/api/tags GET Mga tag ng modelong katugma sa Ollama (para sa mga kliyente Ollama )
/api/restart POST I-trigger ang magandang pag-restart ng server
/api/shutdown POST Mag-trigger ng magandang pag-shutdown ng server
/api/system/env/repair POST Ayusin ang mga variable ng environment ng provider OAuth
/api/system/version GET Current/latest bersyon, i-update ang katayuan, release channel
/api/system/version POST Magsimula ng update sa deployment-aware sa pinakabagong bersyon

Tandaan: Ang mga endpoint na ito ay panloob na ginagamit ng system o para sa Ollama client compatibility. Hindi sila karaniwang tinatawag ng mga end user.

OAuth Pag-aayos ng Kapaligiran (v3.6.1 +)

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

{
  "provider": "claude-code"
}

Nag-aayos ng nawawala o sira na mga variable ng kapaligiran OAuth para sa isang partikular na provider. Ibinabalik:

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

Bersyon at Channel ng Paglabas

GET /api/system/version

Loopback-only na ruta ng pamamahala (admin auth). Ibinabalik ang tumatakbong bersyon, ang pinakabagong na-publish na bersyon at ang auto-update na katayuan. releaseChannel at channels ay mga additive field (rail 3.8.54); Pinapanatili channel ang kahulugan nito — ang deployment mode na ginagamit ng dashboard updater (npm, source o docker-compose).

{
  "current": "3.8.52",
  "latest": "3.8.52",
  "updateAvailable": false,
  "channel": "npm",
  "autoUpdateSupported": true,
  "autoUpdateError": null,
  "news": null,
  "releaseChannel": "latest",
  "channels": { "latest": "3.8.52", "next": "3.8.53-rc.1" }
}
  • releaseChannel — npm channel ng tumatakbong build: nightly para sa mga bersyon -nightly.*, next para sa iba pang mga pre-release (-rc.*, -beta.*, -alpha.*), lts para sa isang stable na bersyon ng isang mas lumang major kaysa sa channels.latest, kung hindi latest. Parehong mga panuntunan tulad ng scripts/release/dist-tag.mjs, na pumipili ng npm dist-tag sa oras ng pag-publish.
  • channels — na-publish na head ng bawat dist-tag, mula sa npm view omniroute dist-tags (registry HTTP fallback), naka-cache na may parehong 10 minutong TTL bilang latest. latest ay palaging naroroon (bumalik sa latest field, pagkatapos ay "unavailable"); next, nightly at lts ay lilitaw lamang kapag umiiral ang dist-tag na iyon. Ang isang Cache-Control: no-cache na kahilingan ay nagre-refresh ng parehong paghahanap.

Ang modelo ng channel (latest = v3 hanggang sa 4.0 GA, next = rc, nightly = develop build, lts = v3 patch pagkatapos ng 4.0 GA) ay inilalarawan sa docs/ops/RELEASE_STRATEGY.md.


Transkripsiyon ng Audio

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

Mag-transcribe ng mga audio file gamit ang anumang naka-configure na STT provider. Pinipili ng unang segment ng path ang native provider (openai/…, deepgram/…). Gumagamit ang mga gateway na muling nag-e-export ng modelo ng ibang vendor ng qualified id (openrouter/deepgram/nova-3).

Request:

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

Response:

{
  "text": "Hello, this is the transcribed audio content.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}

Mga halimbawa ng model id: openai/whisper-1 (nangangailangan ng OpenAI key), openrouter/deepgram/nova-3 (nangangailangan ng OpenRouter key), deepgram/nova-3 (nangangailangan ng native Deepgram key). Ang isang bare deepgram/nova-3 request ay hindi gumagamit ng OpenRouter.

Mga sinusuportahang format: mp3, wav, m4a, flac, ogg, webm.

Gemini Live (gemini/gemini-3.5-transcribe-live): transkripsiyon sa file mode sa pamamagitan ng Gemini Live WebSocket (nangangailangan ng Gemini API key). Kino-convert ang upload sa 16 kHz mono PCM gamit ang ffmpeg (na dapat nasa PATH, maliban kung ang file ay isa nang 16 kHz mono PCM WAV), ini-stream sa session, at ibinabalik ang pinal na text bilang { "text": "..." }. Ipinapasa ang mga opsyonal na language at prompt form field. Mga limitasyon: ang mga upload na lampas sa 25 MiB o ang na-decode na audio na mas mahaba sa 10 minuto ay tumutugon ng 413; kapag ang conversion ay tumakbo nang lampas sa 60 s, ihihinto ito at tutugon ng 504. Ipinapadala ang API key sa x-goog-api-key header lamang, at hindi kailanman sa WebSocket URL.


Compatibility sa Ollama

Para sa mga client na gumagamit ng format ng API ng Ollama:

# Chat endpoint (format ng Ollama)
POST /v1/api/chat

# Listahan ng modelo (format ng Ollama)
GET /api/tags

Awtomatikong isinasalin ang mga kahilingan sa pagitan ng mga internal na format at format ng Ollama.

Mga Tokenized VS Code / Headerless Alias

Gamitin ang mga alias na ito kapag hindi makapag-inject ng Authorization header ang isang integration at kailangang i-embed ang API key sa base URL.

# Alias ng catalog na istilong OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Mga chat alias na istilong OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Mga alias na istilong Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Halimbawa:

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"}]}'

Mga tala:

  • Muling ginagamit ng mga tokenized alias ang parehong handler gaya ng /v1/* at /api/tags; nananatiling magkapareho ang mga anyo ng tugon.
  • Mas mainam ang Authorization: Bearer ... kapag sinusuportahan ng client ang mga custom header.
  • Maaaring lumitaw ang mga token na nakabatay sa URL sa mga log ng reverse-proxy, history ng browser, at telemetry sa labas ng OmniRoute. Ituring ang mga ito bilang opsyon sa compatibility, hindi bilang default na mode ng authentication.

Telemetry

# Kumuha ng buod ng latency telemetry (p50/p95/p99 bawat provider)
GET /api/telemetry/summary

Tugon:

{
  "providers": {
    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
  }
}

Badyet

# Kunin ang status ng badyet para sa lahat ng API key
GET /api/usage/budget

# Magtakda o mag-update ng badyet
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"
}

Mga tala sa schema (setBudgetSchema): Kinakailangan ang apiKeyId; dapat na mas malaki sa zero ang kahit isa sa dailyLimitUsd, weeklyLimitUsd, o monthlyLimitUsd. Mga opsyonal na field: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Ang legacy na anyong {keyId, limit, period} ay nagbabalik ng 400 Bad Request.

Mga Limitasyon sa Token

Mga badyet sa token bawat API key (hiwalay sa badyet na batay sa USD sa itaas). Ipinapatupad ang mga ito inline sa request path: kapag umabot sa limitasyon ang kasalukuyang paggamit ng window ng isang key, tatanggihan ang mga request na may 429 Too Many Requests. Maaaring i-scope ang mga limitasyon sa isang partikular na model, isang provider, o ilapat sa buong key gamit ang global; kapag maraming limitasyon ang tumugma sa isang request, mananaig ang pinakahigpit.

# Ilista ang mga limitasyon sa token ng isang key (kasama ang live na paggamit ng window)
GET /api/usage/token-limits?apiKeyId=key-123

# Lumikha o mag-update ng limitasyon sa token
POST /api/usage/token-limits
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "scopeType": "model",
  "scopeValue": "openai/gpt-4o",
  "tokenLimit": 1000000,
  "resetInterval": "monthly",
  "enabled": true
}

# Mag-delete ng limitasyon sa token ayon sa id
DELETE /api/usage/token-limits?id=tl-abc

Mga tala sa schema (setTokenLimitSchema): Kinakailangan ang apiKeyId at scopeType (model | provider | global). Kinakailangan ang scopeValue maliban kung global ang scopeType (hal., isang model id para sa saklaw na model, o isang provider id para sa saklaw na provider). Dapat positibong integer ang tokenLimit (kino-coerce mula sa string). Opsyonal ang: id (iwanang blangko para lumikha, magbigay para mag-update), resetInterval (daily | weekly | monthly, default na monthly), resetTime (HH:MM), at enabled (default na true). Pinayayaman ng mga tugon ng GET ang bawat limitasyon gamit ang tokensUsed, remaining, windowStart, periodStartAt, at nextResetAt. Endpoint ito na kabilang sa management class (sentral na ipinapatupad ng authz pipeline ang pagpapatotoo).

Pagproseso ng Request

  1. Nagpapadala ang client ng request sa /v1/*
  2. Tinatawag ng route handler ang handleChat, handleEmbedding, handleAudioTranscription, o handleImageGeneration
  3. Nireresolba ang model (direktang provider/model o alias/combo)
  4. Pinipili ang mga credential mula sa lokal na DB gamit ang pag-filter ayon sa availability ng account
  5. Para sa chat: sinusuri ng handleChatCore ang semantic/signature cache at nireresolba ang mga setting ng combo compression
  6. Isinasagawa ang proactive compression bago ang provider translation kapag pinagana (lite, Caveman, RTK, o stacked)
  7. Nagpapadala ang provider executor ng upstream request
  8. Isinasalin pabalik ang tugon sa format ng client (chat) o ibinabalik ito nang hindi binabago (embeddings/images/audio)
  9. Itinatala ang paggamit, compression analytics, at mga log ng request
  10. Inilalapat ang fallback kapag may mga error ayon sa mga panuntunan ng combo

Buong sanggunian sa arkitektura: ARCHITECTURE.md


Pamamahala ng Combo

Ang mga higher-level routing combo (na naibuod na sa ilalim ng /api/combos*) ay maaari ring i-map nang 1:1 mula sa pattern ng model id, na nagbibigay-daan sa transparent na pag-redirect ng isang OpenAI-style model id patungo sa isang combo.

Paraan Path Paglalarawan
GET /api/model-combo-mappings Ilista ang lahat ng model→combo mapping
POST /api/model-combo-mappings Lumikha ng mapping — body: {pattern, comboId, priority?, enabled?, description?}
GET /api/model-combo-mappings/[id] Kunin ang isang mapping
PUT /api/model-combo-mappings/[id] I-update ang mga field ng isang umiiral na mapping
DELETE /api/model-combo-mappings/[id] Mag-alis ng mapping

Pagpapatotoo: management session/API key (requireManagementAuth).


Mga Webhook

Mga outbound na subscription ng webhook para sa mga event ng OmniRoute (pagkumpleto ng request, pagkaubos ng quota, pag-ikot ng key, at iba pa).

Paraan Path Paglalarawan
GET /api/webhooks Ilista ang mga webhook (ang mga secret ay nakamaskara bilang <prefix>...)
POST /api/webhooks Gumawa ng webhook — katawan: {url, events?: ["*"], secret?, description?}
GET /api/webhooks/[id] Kunin ang isang webhook
PUT /api/webhooks/[id] I-update ang url/events/secret/description
DELETE /api/webhooks/[id] Alisin ang isang webhook
POST /api/webhooks/[id]/test Magpadala ng test payload sa URL ng webhook at ibalik ang status ng delivery

Pagpapatunay: management session/API key (requireManagementAuth).


Mga Nakarehistrong Key (Awtomatikong Pamamahala)

Ginagamit ng subsystem ng awtomatikong pamamahala ng key upang mag-isyu at magpaikot ng mga API key laban sa isang backing provider/account, na may mga quota bawat araw/oras.

Paraan Path Paglalarawan
GET /api/v1/registered-keys Ilista ang mga nakarehistrong key (masked prefix lamang)
POST /api/v1/registered-keys Mag-isyu ng bagong nakarehistrong key — katawan: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Ibinabalik ang raw key nang isang beses lamang. Nagbabalik ng 429 kapag tinanggihan dahil sa quota.
GET /api/v1/registered-keys/[id] Kunin ang metadata ng isang nakarehistrong key (walang raw material)
DELETE /api/v1/registered-keys/[id] Bawiin ang isang nakarehistrong key
POST /api/v1/registered-keys/[id]/revoke Tiyak na endpoint para sa pagbawi (kapareho ng epekto ng DELETE)

Pagpapatunay: management session/API key (requireManagementAuth) — kaparehong guard ng /api/keys: isang dashboard session, ang lokal na CLI token, o isang API key na may manage/admin scope; ang mga API key na para lamang sa inference ay nakakakuha ng 403. Tingnan din ang /v1/quotas/check at /v1/issues/report.


Protocol ng mga Agent

Mga gawain ng cloud agent (Claude Code, Codex Cloud, OpenHands, atbp.) na isinasagawa nang malayuan para sa mga user ng OmniRoute.

Method Path Description
GET /api/v1/agents/tasks Maglista ng mga gawain — opsyonal ang ?provider=, ?status=, ?limit= (1–500, default na 50)
POST /api/v1/agents/tasks Gumawa ng gawain — bino-validate ang body ng CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Nagbabalik ng 201 na may task envelope
DELETE /api/v1/agents/tasks?id=... Mag-delete ng gawain
GET /api/v1/agents/tasks/[id] Basahin ang gawain — sabay na nire-refresh ang status mula sa upstream cloud agent kapag nakatakda ang external_id
POST /api/v1/agents/tasks/[id] Discriminated action: {action: "approve"}, {action: "message", message}, o {action: "cancel"}
DELETE /api/v1/agents/tasks/[id] Mag-delete ng partikular na gawain ayon sa id

Auth: kinakailangan ang management auth sa bawat method (requireCloudAgentManagementAuth). Bago ang v3.8.0, hindi authenticated ang mga ito — tingnan ang commit na 588a0333 para sa breaking change.

# Gumawa ng cloud task ng Claude Code
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'

Mga Proxy sa Pamamahala

Mga outbound HTTP(S)/SOCKS proxy na maaaring italaga sa mga provider, account, o sa buong system.

Method Path Description
GET /api/v1/management/proxies Maglista ng mga proxy (kapag may ?id=, isa ang ibinabalik; kapag may ?id=&where_used=1, ibinabalik ang assignment graph)
POST /api/v1/management/proxies Gumawa ng proxy — bino-validate ang body ng createProxyRegistrySchema
PATCH /api/v1/management/proxies I-update ang proxy — bino-validate ang body ng updateProxyRegistrySchema (kinakailangan ang id)
DELETE /api/v1/management/proxies?id=...&force=1 Mag-delete ng proxy (gamitin ang force=1 upang alisin ang mga assignment)
GET /api/v1/management/proxies/assignments Maglista ng mga assignment — maaaring i-filter ayon sa proxy_id, scope, scope_id; ipasa ang resolve_connection_id=<id> upang i-resolve ang aktibong proxy para sa isang connection
PUT /api/v1/management/proxies/assignments Magtalaga — bino-validate ang body ng proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Nililinis ang dispatcher cache
PUT /api/v1/management/proxies/bulk-assign Magtalaga nang maramihan — bino-validate ang body ng bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET /api/v1/management/proxies/health?hours=24 Pinagsama-samang kalusugan ng proxy (mga bilang ng tagumpay/pagkabigo, latency) sa loob ng isang window

Auth: kinakailangan ang management session/API key sa bawat route (requireManagementAuth).

Ang POST /api/v1/management/proxies/[id]/assignments at POST /api/v1/management/proxies/[id]/health na nasa paglalarawan ng task ay pinapangasiwaan ng flat na /assignments at /health route na ipinapakita sa itaas — walang mga per-id subroute sa codebase.


Katatagan (pinalawak)

Naglalantad ang OmniRoute ng tatlong magkakahiwalay na mekanismo para sa pansamantalang pagkabigo; hinahayaan ng mga management endpoint sa ibaba ang mga operator na basahin at i-override ang mga ito:

Saklaw Imbakan ng estado Basahin I-reset / i-clear
Breaker ng provider domain_circuit_breakers + nasa memorya /api/monitoring/health POST /api/resilience/reset
Cooldown ng koneksiyon rateLimitedUntil sa mga koneksiyon ng provider /api/rate-limits, /api/providers/[id] (muling pinapagana nang lazy; i-clear sa pamamagitan ng provider PUT)
Lockout ng modelo Registry ng availability ng modelo na nasa memorya GET /api/resilience/model-cooldowns DELETE /api/resilience/model-cooldowns

Tumatanggap ang PATCH /api/resilience ng mga override para sa breaker ng provider sa ilalim ng providerBreaker.oauth at providerBreaker.apikey. Sinusuportahan ng bawat profile ang degradationThreshold, failureThreshold, at resetTimeoutMs; inilalantad din ang parehong mga field sa Dashboard → Mga Setting → Katatagan.

# I-clear ang lockout ng isang modelo
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"}'

# Burahin ang lahat ng lockout
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

Para sa buong konseptuwal na sanggunian at mga default ng breaker, tingnan ang CLAUDE.md → "Resilience Runtime State" at docs/architecture/RESILIENCE_GUIDE.md.

Queue ng Rate Limit at Pangkaligtasang Mekanismo ng Awtomatikong Pagpapagana

  • Sinusuportahang path ng pagsulat: Ang POST /api/rate-limits na may body na {"connectionId": "<id>", "enabled": true|false} ang sinusuportahang management endpoint para i-toggle ang proteksiyon ng rate limit para sa isang koneksiyon. Sadyang hindi binabago o tina-toggle ng PUT /api/providers/[id] ang rateLimitProtection (#11278).
  • Semantika ng enabled: false: Ang pagtatakda ng enabled: false ay nag-aalis ng tahasang proteksiyon para sa koneksiyon, ngunit hindi nito inaalis sa pangkalahatang pangkaligtasang mekanismo ng awtomatikong pagpapagana (autoEnableApiKeyProviders = true) ang isang aktibong koneksiyong API-key. Sa reconcileEnabledConnections (open-sse/services/rateLimitManager.ts), magkapareho ang kahulugan ng false at undefined; nananatiling protektado sa ilalim ng pangkaligtasang mekanismo ng awtomatikong pagpapagana ang mga aktibong koneksiyong API-key na walang tahasang proteksiyon.
  • Pandaigdigang pag-disable: Para patakbuhin ang mga koneksiyong API-key nang walang mga queue ng rate limit, i-disable sa buong sistema ang pangkaligtasang mekanismo sa pamamagitan ng RATE_LIMIT_AUTO_ENABLE=false (env) o resilienceSettings.requestQueue.autoEnableApiKeyProviders = false (Mga Setting → Katatagan / PATCH /api/resilience).

Mga Skill

Framework ng skill para sa pagpapalawak ng OmniRoute gamit ang mga custom na executable handler, kasama ang mga integrasyon sa marketplace.

Paraan Path Paglalarawan
GET /api/skills Ilista ang mga naka-install na skill — maaaring i-filter ayon sa ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, na may pagination
GET /api/skills/[id] Kunin ang isang skill
PUT /api/skills/[id] I-update ang skill (pangalan, paglalarawan, mode, schema, handler, mga tag)
DELETE /api/skills/[id] I-uninstall ang isang skill
POST /api/skills/install Mag-install ng skill mula sa isang raw manifest — body: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET /api/skills/executions Ilista ang mga kamakailang execution ng skill (audit trail na may mga input/output/tagal)
GET /api/skills/marketplace?q=... Maghanap/listahan ng mga sikat na skill mula sa marketplace ng SkillsMP (nangangailangan ng setting na skillsmpApiKey)
POST /api/skills/marketplace/install Mag-install ng skill ayon sa id mula sa SkillsMP
GET /api/skills/skillssh?q=&limit= Maghanap sa registry ng skills.sh
POST /api/skills/skillssh/install Mag-install ng skill ayon sa id mula sa skills.sh

Pagpapatunay: session/API key para sa pamamahala. Tumatanggap ang mga route ng paghahanap sa marketplace ng alinman sa auth para sa pamamahala o Bearer API key (isAuthenticated).


Memorya

Persistenteng tindahan ng memoryang pang-usap/pangkaalaman, saklaw bawat API key / session.

Pamamaraan Path Paglalarawan
GET /api/memory Ilista ang mga memorya — ?apiKeyId=, ?type=, ?sessionId=, ?q=, gamit ang pagination na offset/limit o page/limit
POST /api/memory Gumawa ng memorya — vine-validate ng Zod ang body: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET /api/memory/[id] Kunin ang isang memorya
DELETE /api/memory/[id] Magtanggal ng isang memorya
GET /api/memory/health Kalagayan ng subsystem ng memorya (pagkakakonekta sa DB, backend ng embeddings, status ng vector index)

Pagpapatunay: management session/API key (requireManagementAuth). Enum ng type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (tingnan ang MemoryType sa src/lib/memory/types.ts).


Server ng MCP

Ang OmniRoute ay may kasamang naka-embed na Model Context Protocol server na may 3 transportasyon (stdio, SSE, streamable-http) at mga saklaw na tool. Binabasa ng mga endpoint ng dashboard sa ibaba ang status/data ng audit at ipinapasa ang mga HTTP transport.

Pamamaraan Path Paglalarawan
GET /api/mcp/status Heartbeat, transport, online state, huling tawag, nangungunang mga tool, rate ng tagumpay sa loob ng 24 na oras
GET /api/mcp/tools Listahan ng mga MCP tool na may name, description, scopes, phase, auditLevel, sourceEndpoints
GET /api/mcp/sse Magbukas ng SSE stream para sa SSE transport (nagbabalik ng 503 kung hindi pinagana ang MCP o hindi tugma ang transport)
POST /api/mcp/sse Magpadala ng JSON-RPC frame sa SSE transport
GET /api/mcp/stream Magbukas ng SSE side ng Streamable HTTP transport (mga mensaheng sinimulan ng server)
POST /api/mcp/stream Magpadala ng JSON-RPC frame sa Streamable HTTP transport
DELETE /api/mcp/stream Tapusin ang isang Streamable HTTP session
GET /api/mcp/audit Mag-query ng audit log — ?limit=, ?offset=, ?tool=, `?success=true false, ?apiKeyId=`
GET /api/mcp/audit/stats Pinagsama-samang audit stats (mga kabuuan, rate ng tagumpay, average na tagal, nangungunang mga tool)

Pagpapatunay: sinusunod ng mga sse/stream transport ang partikular na auth surface ng MCP (Bearer API key na may saklaw na mcp); maaaring basahin mula sa dashboard ang mga rutang status/tools/audit* (walang karagdagang pagpapatunay maliban sa pag-abot sa dashboard host).

Ang parehong HTTP transport ay kinokontrol ng settings.mcpEnabled at settings.mcpTransport — nagbabalik ng 400 ang hindi tugmang transport, at nagbabalik ng 503 ang estadong hindi pinagana ang MCP.


A2A Server

Inilalantad ng OmniRoute ang isang A2A (Agent-to-Agent) JSON-RPC 2.0 endpoint kasama ang isang REST wrapper para sa inspeksyon/paggamit ng dashboard.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # opsyonal maliban kung nakatakda ang OMNIROUTE_API_KEY
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Route this coding task"}]
  }
}

Mga sinusuportahang method (lahat ay nakadepende sa settings.a2aEnabled):

Method Paglalarawan
message/send Synchronous na pagpapatupad ng skill; nagbabalik ng {task, artifacts, metadata}
message/stream Streaming SSE na pagpapatupad ng parehong set ng skill
tasks/get Kinukuha ang task ayon sa taskId
tasks/cancel Kinakansela ang task ayon sa taskId

Mga built-in na skill: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Agent Card

GET /.well-known/agent.json

Ibinabalik ang pampublikong A2A agent card (pangalan, paglalarawan, mga capability, katalogo ng skill, scheme ng authentication) — naka-cache sa publiko sa loob ng 1 oras. Hindi kailangan ng authentication.

Mga REST helper

Method Path Paglalarawan
GET /api/a2a/status Naka-enable ba ang A2A + mga istatistika ng task + buod ng naka-cache na agent card
GET /api/a2a/tasks Maglista ng mga task — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST /api/a2a/tasks (Hindi ipinatupad bilang REST helper — gumawa sa pamamagitan ng JSON-RPC message/send)
GET /api/a2a/tasks/[id] Kunin ang isang task
POST /api/a2a/tasks/[id]/cancel Kanselahin ang isang task

Authentication: gumagana ang mga REST helper nang walang management authentication (nababasang ng dashboard); ginagamit ng JSON-RPC /a2a route ang Bearer OMNIROUTE_API_KEY kung na-configure.


Cloud, Evals at Assess

Method Path Paglalarawan
POST /api/cloud/auth Bine-verify ang isang Bearer key at ibinabalik ang mga naka-mask na koneksyon ng provider + mga alias ng modelo para sa mga client ng cloud sync
POST /api/cloud/credentials/update Ina-update ang mga naka-encrypt na credential para sa isang provider na naka-sync sa cloud
POST /api/cloud/model/resolve Nireresolba ang isang lohikal na model id sa isang partikular na provider/model gamit ang lokal na routing table
GET /api/cloud/models/alias Naglilista ng mga alias ng modelo ayon sa pagkakalantad ng mga ito sa cloud sync
GET /api/assess Binabasa ang pinakabagong mga kategorya ng assessment (bawat provider/model)
POST /api/assess Nagpapatakbo ng assessment — katawan: `{scope: {type:"all"} {type:"provider", providerId} {type:"model", modelId}, trigger?}`
GET /api/evals Naglilista ng mga built-in na eval suite + mga pinakabagong run
POST /api/evals Nagti-trigger ng eval run
POST /api/evals/suites Gumagawa ng custom na eval suite — bino-validate ang katawan ng evalSuiteSaveSchema
GET /api/evals/suites/[id] Kinukuha ang isang custom na eval suite

Authentication: direktang vine-validate ng /api/cloud/auth ang isang Bearer key at ibinabalik ang naka-mask na key at projectId ng bawat koneksyon para lamang sa isang key na may saklaw na manage / admin; nangangailangan ng management session/API key ang iba pang /api/cloud/*, /api/evals/*, at /api/assess route. Gumagamit ang POST ng /api/assess ng validateBody na may discriminated-union scope schema.


Pamamahala ng ACP (Agent Client Protocol)

bilang mga child process. Pinamamahalaan ng mga endpoint na ito ang pagtukoy sa mga ACP agent at pagpaparehistro ng mga custom agent.

Paraan Path Paglalarawan
GET /api/acp/agents Ilista ang lahat ng kilalang CLI agent (built-in + custom), kasama ang status ng pag-install, bersyon, at binary
POST /api/acp/agents Magrehistro ng custom ACP agent o i-refresh ang cache — body: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} o {action: "refresh"}
DELETE /api/acp/agents Mag-alis ng custom ACP agent — query param: ?id=<agentId>

Halimbawa ng tugon (GET /api/acp/agents):

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

Pagpapatunay: Nangangailangan ng management session (dashboard na auth_token cookie) o API key na saklaw ng management.

Tingnan ang ACP Framework para sa buong detalye.


Analytics at Observability

Mga real-time analytics endpoint para sa pagsubaybay sa routing, compression, at pagkakaiba-iba ng provider. Pinapagana ng mga ito ang mga pahina sa /dashboard/analytics/*.

Analytics ng auto-routing

Paraan Path Paglalarawan
GET /api/analytics/auto-routing Pinagsama-samang istatistika ng auto-routing: kabuuang mga tawag, distribusyon ng strategy, distribusyon ng tier, mga pangunahing provider
GET /api/analytics/auto-routing?days=7 Mga istatistikang nakabatay sa saklaw ng oras (default na 24h)

Halimbawa ng tugon:

{
  "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 }
  ]
}

Analytics ng compression

Paraan Path Paglalarawan
GET /api/analytics/compression Pinagsama-samang istatistika ng compression: mga token na natipid, porsyento ng natipid, distribusyon ng mode, paggamit ng engine

Halimbawa ng tugon:

{
  "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
  }
}

Pagsubaybay sa pagkakaiba-iba ng provider

Paraan Path Paglalarawan
GET /api/analytics/diversity Pagsubaybay sa pagkakaiba-iba batay sa Shannon entropy: pinipigilan ang mga single point of failure sa pamamagitan ng pagsukat sa distribusyon ng mga provider

Halimbawa ng tugon:

{
  "window": "24h",
  "shannonEntropy": 2.45,
  "maxEntropy": 3.17,
  "diversityRatio": 0.77,
  "providerUsage": {
    "openai": 0.4,
    "anthropic": 0.25,
    "google": 0.2,
    "kiro": 0.15
  },
  "warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"]
}

Pagpapatunay: Nangangailangan ng management session o API key na saklaw ng management.


Mga Operasyong Pang-admin

Mga endpoint na para lamang sa admin para sa pamamahalang operasyon.

Paraan Path Paglalarawan
GET /api/admin/concurrency Basahin ang kasalukuyang limitasyon ng concurrency (global + bawat provider)
POST /api/admin/concurrency I-update ang mga limitasyon ng concurrency — body: {global?: number, perProvider?: Record<string, number>}

Pagpapatotoo: Nangangailangan ng management session na may saklaw na admin.


Pamamahala ng CLI Tools

Pamahalaan ang mga CLI tool na sumasama sa OmniRoute (antigravity, commandCode, devin-cli, atbp.). Tingnan ang Sanggunian ng Provider para sa kumpletong listahan.

Paraan Path Paglalarawan
GET /api/cli-tools/all-statuses Katayuan ng lahat ng CLI tool (naka-install, bersyon, huling nakita)
GET /api/cli-tools/status Detalye ng katayuan para sa isang CLI tool (?tool= query)
POST /api/cli-tools/apply Isulat ang nabuong configuration ng isang tool (dryRun ay nagbibigay ng preview; 422 + containerEphemeralTarget kapag containerized; migration ay nagtatalaga ng legacy Codex YAML)
GET /api/cli-tools/backups Ilista ang mga backup ng configuration ng CLI tool
POST /api/cli-tools/backups Gumawa ng backup ng lahat ng configuration ng CLI tool
POST /api/cli-tools/backups I-restore: ang parehong endpoint na may {tool, backupId} sa body ay nagre-restore ng backup na iyon
GET /api/cli-tools/antigravity-mitm Katayuan ng Antigravity MITM proxy (ang CLI tool na "antigravity-mitm")
POST /api/cli-tools/antigravity-mitm/alias I-configure ang mga alias ng antigravity-mitm

Pagpapatotoo: Nangangailangan ng management session.


Mga Kakayahan ng Agent

Pamahalaan ang mga kakayahan ng AI agent (katulad ng mga custom GPT ng OpenAI ngunit para sa mga agent).

Paraan Path Paglalarawan
GET /api/agent-skills Ilista ang lahat ng kakayahan ng agent (built-in + custom)
GET /api/agent-skills/[id] Kunin ang isang partikular na kakayahan ng agent
POST /api/agent-skills Gumawa ng custom na kakayahan ng agent — body: {name, description, prompt, model?, temperature?}
PUT /api/agent-skills/[id] I-update ang isang custom na kakayahan ng agent
DELETE /api/agent-skills/[id] Tanggalin ang isang custom na kakayahan ng agent
GET /api/agent-skills/[id]/raw Kunin ang raw prompt + metadata (walang execution)
POST /api/agent-skills/generate Bumuo ang AI ng bagong kakayahan mula sa paglalarawan sa natural na wika

Pagpapatotoo: Nangangailangan ng management session o management-scoped API key.


Pamamahala ng Cache

Pamahalaan ang semantic cache at reasoning cache.

Method Path Description
GET /api/cache Pangkalahatang-ideya ng cache: kabuuang bilang ng entry, hit rate, laki sa disk
GET /api/cache/entries Maglista ng mga naka-cache na entry (may pagination)
DELETE /api/cache/entries Magtanggal ng mga cache entry (i-filter ayon sa mga query parameter)
GET /api/cache/stats Detalyadong mga istatistika ng cache (bawat provider, bawat modelo)
GET /api/cache/reasoning Status ng reasoning cache (para sa reasoning replay)
DELETE /api/cache/reasoning I-clear ang reasoning cache — mga query param: ?toolCallId=<id> (isa) o ?provider=<p> o walang param (lahat)

Auth: Nangangailangan ng management session.


Memory System

Pamahalaan ang persistent memory (FTS5 + vector embeddings).

Method Path Description
GET /api/memory Maglista ng mga memory entry (i-filter ayon sa scope, type, search query)
POST /api/memory Gumawa ng bagong memory entry — body: {scope, type, content, metadata?}
GET /api/memory/[id] Kunin ang partikular na memory entry
PUT /api/memory/[id] I-update ang isang memory entry
DELETE /api/memory/[id] Magtanggal ng memory entry
GET /api/memory?q= Maghanap sa memory (FTS5 + vector) — kasama ang mga istatistika sa parehong response

Auth: Nangangailangan ng management session o API key na may saklaw na management.


Webhooks

Pamahalaan ang mga subscription sa webhook para sa mga event.

Method Path Description
GET /api/webhooks Maglista ng lahat ng subscription sa webhook
POST /api/webhooks Gumawa ng subscription sa webhook — body: {url, events[], secret?, active?}
GET /api/webhooks/[id] Kunin ang partikular na subscription sa webhook
PUT /api/webhooks/[id] I-update ang isang subscription sa webhook
DELETE /api/webhooks/[id] Magtanggal ng subscription sa webhook
GET /api/webhooks/[id]/deliveries Maglista ng history ng delivery para sa isang webhook (log ng tagumpay/pagkabigo)
POST /api/webhooks/[id]/test Magpadala ng test event sa isang webhook

Auth: Nangangailangan ng management session.

Tingnan ang Framework ng Webhooks para sa kumpletong mga uri ng event.


Framework ng Skills

Pamahalaan ang Skills (framework ng mga agentic extension).

Method Path Description
GET /api/skills Ilista ang lahat ng naka-install na skill (built-in + custom)
POST /api/skills/install Mag-install ng skill mula sa lokal na path o URL
DELETE /api/skills/[id] I-uninstall ang isang skill
PUT /api/skills/[id] I-enable o i-disable ang isang skill — body: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST /api/skills/executions Mag-execute ng skill — body: {skillName, apiKeyId, input?, sessionId?}
GET /api/skills/executions Ilista ang history ng execution para sa lahat ng skill (i-filter gamit ang ?apiKeyId=)

Auth: Nangangailangan ng management session o management-scoped API key.

Tingnan ang Skills Framework para sa kumpletong detalye.


Mga Plugin

Pamahalaan ang mga plugin ng OmniRoute (mga third-party extension).

Method Path Description
GET /api/plugins Ilista ang mga naka-install na plugin
POST /api/plugins/marketplace/install Mag-install ng plugin mula sa marketplace
DELETE /api/plugins/[name] I-uninstall ang isang plugin
POST /api/plugins/[name]/activate I-activate ang isang plugin
POST /api/plugins/[name]/deactivate I-deactivate ang isang plugin
GET /api/plugins/[name]/config Kunin ang configuration ng plugin
PUT /api/plugins/[name]/config I-update ang configuration ng plugin

Auth: Nangangailangan ng management session.

Tingnan ang Plugins Framework para sa kumpletong detalye.


Shadow Routing

Ang Shadow / A-B comparison ng mga provider ay hindi isang standalone REST surface — kino-configure ito sa pamamagitan ng combo routing (tingnan ang Auto-Combo). Ang mga metric ng comparison para sa bawat combo ay ibinibigay ng GET /api/combos/metrics.


Mga Guardrail

Suriin ang mga runtime guardrail (PII detection, prompt injection detection, vision bridging). Tumatakbo ang mga guardrail sa bawat request; ang per-call opt-out ay sa pamamagitan ng request header na x-omniroute-disabled-guardrails — walang naka-persist na enable/disable surface.

Method Path Description
GET /api/guardrails Ilista ang mga nakarehistrong guardrail at ang status ng mga ito (name / enabled / priority)
POST /api/guardrails/test Magsagawa ng dry-run ng pre-call pipeline gamit ang sample input — body: {input, disabledGuardrails?}

Auth: Nangangailangan ng management session.

Tingnan ang Security > Guardrails para sa kumpletong detalye.



Pagpapatunay

Tingnan ang Management Authentication para sa apat na pamilya ng kredensyal (dashboard session, lokal na CLI token, oma_live_… Access Token, manage-scoped API key) at kung paano naiiba ang mga ito sa mga inference key.

  • Gumagamit ang mga dashboard route (/dashboard/*) ng auth_token cookie
  • Gumagamit ang login ng naka-save na password hash; fallback sa INITIAL_PASSWORD
  • Maaaring i-toggle ang requireLogin sa pamamagitan ng /api/settings/require-login
  • Opsyonal na nangangailangan ang mga /v1/* route ng Bearer API key kapag REQUIRE_API_KEY=true
  • Ang "management token" / "management-scoped API key" sa sangguniang ito ay nangangahulugang isa sa mga pamilya sa gabay na iyon — hindi isang hindi tinukoy na karagdagang uri ng lihim

Breaking change (v3.8.0) — Nangangailangan na ngayon ang /api/v1/agents/tasks/* at mga endpoint sa pamamahala ng cooldown ng management auth (dashboard auth_token cookie o isang management-scoped API key). Makakatanggap ng 401 Unauthorized ang mga client na dati nang tumatawag sa mga route na ito nang walang authentication. Tingnan ang commit 588a0333 (fix(auth): require management auth for agent and cooldown APIs).