Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

161 KB
Raw Blame

API Reference (Slovenščina)

🌐 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 · 🇵🇭 phi · 🇵🇱 pl · 🇵🇹 pt · 🇧🇷 pt-BR · 🇷🇴 ro · 🇷🇺 ru · 🇱🇰 si · 🇸🇰 sk · 🇷🇸 sr · 🇸🇪 sv · 🇰🇪 sw · 🇮🇳 ta · 🇮🇳 te · 🇹🇭 th · 🇹🇷 tr · 🇺🇦 uk-UA · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW


🌐 Jeziki: 🇺🇸 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á | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

Osnovna referenčna dokumentacija za API OmniRoute. Zajema javni vmesnik /v1 in najpogosteje uporabljene končne točke za upravljanje; strojno berljiva datoteka docs/openapi.yaml in drevo poti v src/app/api/ so izčrpni viri.

Za namensko dokumentacijo protokola, združljivega z OpenAI, in matriko zmogljivosti ponudnikov glejte OPENAI_COMPATIBILITY.md.


Kazalo vsebine


Dokončanja klepeta

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
}

Glave po meri

Glava Smer Opis
X-OmniRoute-No-Cache Zahteva Nastavite na true, da zaobidete predpomnilnik
x-omniroute-no-memory Zahteva Nastavite na true, da za to zahtevo preskočite vstavljanje pomnilnika in veščin (ustreza možnosti brez predpomnilnika; prepreči stroške žetonov in denarne stroške pri vsakem klicu)
X-OmniRoute-Progress Zahteva Nastavite na true za dogodke napredka
X-Session-Id Zahteva Ključ lepljive seje za zunanjo afiniteto seje
x_session_id Zahteva Sprejeta je tudi različica s podčrtajem (neposredni HTTP)
X-OmniRoute-Session-Id Zahteva Oznaka seje/pogovora, ki jo poda klicatelj (uporablja se tudi za pomnilnik). Če je prisotna, se dobesedno shrani v call_logs.session_tag za pripisovanje stroškov po sejah (#8249) — če manjka, se nikoli ne ustvari
Idempotency-Key Zahteva Ključ za odstranjevanje dvojnikov (5-sekundno okno)
X-Request-Id Zahteva Alternativni ključ za odstranjevanje dvojnikov
x-omniroute-connection Zahteva Zahtevo za en model pripne na eno povezavo ponudnika (račun) glede na njen ID — glejte Pripenjanje računa za posamezno zahtevo
X-OmniRoute-Cache Odgovor HIT ali MISS (brez pretakanja)
X-OmniRoute-Idempotent Odgovor true, če je bil dvojnik odstranjen
X-OmniRoute-Progress Odgovor enabled, če je sledenje napredku vklopljeno
X-OmniRoute-Session-Id Odgovor Dejanski ID seje, ki ga uporablja OmniRoute
X-OmniRoute-Request-Id Odgovor ID za povezovanje zahteve (če je znan)
X-OmniRoute-Version Odgovor Različica gradnje OmniRoute (vedno prisotna)
X-OmniRoute-Cost-Saved Odgovor Znesek v USD, prihranjen zaradi predpomnilnika ob zadetku HIT (samo zadetki predpomnilnika)
X-OmniRoute-Decision Odgovor Sled usmerjanja: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> je kombinirana strategija ali single za nekombinirano zahtevo) — vedno prisotna v odgovorih ob dokončanju

Opomba za Nginx: če uporabljate glave s podčrtaji (na primer x_session_id), omogočite underscores_in_headers on;.

Pripenjanje računa za posamezno zahtevo

Kadar ima ponudnik več povezav (računov ali ključev), OmniRoute običajno izbere eno s svojo strategijo izbire računa. Namesto tega lahko zahteva pripne določeno povezavo z glavo 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"}]}'
  • Kje najti ID. Odprite stran ponudnika na nadzorni plošči (Nadzorna plošča → Ponudniki → ) in kliknite oznako ID-ja xxxxxxxx… v vrstici povezave — s tem kopirate celoten ID povezave.
  • Katere zahteve ga upoštevajo. Zahteve za en sam model (provider/model) na /v1/chat/completions, /v1/messages in /v1/responses. Kombinacije glavo prezrejo: račun za vsak korak kombinacije pripnite prek povezave tega koraka.
  • Pripenjanje je strogo in ni le prednostna izbira. Uporabi se izključno pripeta povezava. Napaka znotraj zahteve zabeleži obdobje mirovanja računa, vendar ne preklopi na drug račun istega ponudnika.
  • Obdobje mirovanja in kvota sprostita pripenjanje. Ko je pripeta povezava v obdobju mirovanja, je njena kvota izčrpana ali pa jo blokira pravilnik kvot, se poznejše zahteve preusmerijo na druge povezave ponudnika, enako kot promet brez pripenjanja.
  • Neznani ali onemogočeni ID-ji povzročijo napako. ID, ki ni v aktivnem naboru ponudnika (ker je izbrisan, deaktiviran ali pripada drugemu ponudniku), ne omogoča izbire nobenega ustreznega računa, zato zahteva ne uspe, namesto da bi bila neopazno preusmerjena drugam.

Claude Code pošilja glave po meri prek ANTHROPIC_CUSTOM_HEADERS. Dodajte jo v blok env v ~/.claude/settings.json ali v projektno datoteko .claude/settings.json, da za vsak projekt pripnete drug račun:

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

Vir: src/sse/handlers/chat.ts (branje glave), src/sse/services/auth.ts in src/sse/services/sessionAffinityPin.ts (sprostitev pripenjanja in preverjanje odsotnosti iz nabora).

Glave za telemetrijo stroškov: uspešni odgovori brez pretakanja vsebujejo tudi nabor za telemetrijo stroškov X-OmniRoute-* — X-OmniRoute-Response-Cost (USD, natančno 10 decimalnih mest; 0.0000000000 za brezplačne postavke oziroma postavke brez določene cene), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit in X-OmniRoute-Fallback-Attempts (samo kadar je > 0), poleg tega pa še X-OmniRoute-Request-Id in X-OmniRoute-Version. Te glave se dodajo odgovorom za dokončanja klepeta, /v1/responses, /v1/messages in končne točke za večpredstavnostne vsebine — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations in /v1/moderations (strošek je vedno 0). Strošek večpredstavnostnih vsebin se izračuna glede na vrsto (na sliko, sekundo, znak ali iskalno enoto), kadar so cene na voljo, sicer pa znaša 0 (fail-open).

Semantika stroška pri zadetku predpomnilnika: pri ZADETKU v semantičnem predpomnilniku (X-OmniRoute-Cache-Hit: true) se ne izvede noben klic navzgor, zato je vrednost X-OmniRoute-Response-Cost enaka 0.0000000000 (inkrementalni strošek posredovanja zadetka). Izvirni oziroma pričakovani strošek je ločeno naveden v X-OmniRoute-Cost-Saved. Sistemi za obračunavanje naj seštejejo vrednosti X-OmniRoute-Response-Cost (zadetki ne stanejo nič); analitika predpomnilnika pa lahko združuje vrednosti X-OmniRoute-Cost-Saved.

Ekskluzivne najemnine upravljanih sej

Ekskluzivno najemanje upravljanih sej je izbirna, odjemalcu nevtralna pogodba o usmerjanju: en aktiven lastnik ima eno ustrezno povezavo OmniRoute. Ne najema modela, ne zahteva OAuth, ne identificira določenega odjemalca in ne zahteva določenega ponudnika.

Avtentikacijski API ključ mora imeti obseg lease:exclusive in eksplicitno neprazno listo allowedConnections. Meja mutacije baze podatkov uveljavlja obe polji skupaj pri ustvarjanju ključa in delnih posodobitvah.

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

Uspešni odzivi za pridobitev, podaljšanje in sprostitev razkrivajo časovne žige, state in natančno pozitivno generation, nikoli pa izbrane povezave ali poverilnic. Podaljšanje in sprostitev zagotavljata generacijo v JSON telesu:

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

Aktiven lastnik najema lahko eksplicitno zahteva metapodatke za prikaz, varne za zasebnost, za svojo trenutno vezavo:

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

To izbirno dejanje statusa je zaščiteno z nepreglednim lastnikom, avtenticiranim upravljanim API ključem in natančno aktivno generacijo v eni transakciji baze podatkov. displayName je le obrezano konfigurirano ime povezave; je null, če varno konfigurirano ime ne obstaja. OmniRoute nikoli ne nadomesti e-pošte ali generirane identitete računa. Vrednost ponudnika je neobčutljiva oznaka za prikaz in nikoli generiran združljiv identifikator ponudnika. Poverilnice, žetoni, piškotki, neobdelani ID-ji povezav ali API ključev, zgoščene vrednosti lastnikov, varnostne skrivnosti in notranji podatki o usmerjanju so izključeni.

Napačen ključ, napačen lastnik, zastarela generacija, manjkajoče, potekle, sproščene in neveljavne poizvedbe vrnejo isto napako 409 LEASE_FENCE_STALE brez metapodatkov o povezavi. Odjemalec, ki je prejel odziv čakanja na zmogljivost, nima aktivne vezave za pregled. Ko usmerjanje preklopi aktivni najem, ista generacija ostane veljavna in status atomsko vrne novo vezavo, nikoli stare. Obstoječi odjemalci ostanejo nespremenjeni, ker odzivi za pridobitev, podaljšanje, sprostitev in čakanje ohranijo svoje prejšnje oblike.

Ta strežniška pogodba ne spreminja standardnega OpenAI Codex /status. Standardni Codex trenutno poroča o svojem ponudniku modela in vgrajenem stanju avtentikacije/računa, vendar ne prikazuje poljubnih metapodatkov računa ponudnika po meri; kasnejša integracija odjemalca mora poklicati to dejanje in se odločiti, kako prikazati connection.displayName.

Vsaka zahteva za upravljano sklepanje nato zagotavlja oba nadzorna glava:

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

Natančen lastnik, generacija, aktivna povezava in avtenticiran API ključ so zaščiteni takoj pred vsakim podprtim poskusom navzgor. Ponovno predvajanje lastnika in generacije z drugim ključem ne uspe, tudi če ta ključ dovoljuje isto povezavo. Neobdelani lastniki se ne shranjujejo, ne beležijo, ne hranijo v posnetku zahteve in se ne posredujejo navzgor.

Začasna konkurenca vrne HTTP 429 z Retry-After in:

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

Ta odziv pomeni le, da običajni upravičeni nabor ni bil prazen in da je vsakega prostega kandidata zadržal tuji aktivni najem. Nepodprti modeli/ponudniki, neujemanje pravilnikov, ohladitev, kvota, zdravje in druge običajne napake pri upravičenosti ohranijo svoje obstoječe odzive OmniRoute.

x-omniroute-compression

Prepis načrta stiskanja na zahtevo. Najvišja prednost — preglasi prepis usmerjevalne kombinacije, aktivni profil, samodejni sprožilec in privzeto ploščo. Vrednosti:

Vrednost Učinek
off Brez stiskanja za to zahtevo.
default Privzeti profil, izpeljan iz plošče (ignorira aktivni profil). Izgubni motorji so izklopljeni.
safe Samo deduplikacija in zlaganje presledkov.
allow-lossy Ohrani operaterski načrt za to zahtevo, vključno s povzetki in prepisi sloga.
engine:<id> En sam motor, ko je omogočen, npr. engine:rtk. Izbirna možnost na zahtevo za ta motor.
<combo> Imenovana kombinacija, najprej se ujema po imenu (neobčutljivo na velikost črk), nato po ID-ju.

Opombe:

  • Neznane vrednosti so ignorirane (zahteva ni nikoli zavrnjena); razrešitev se nadaljuje z običajno operatersko prednostjo.
  • Če si več kombinacij deli ime, posredujte ID kombinacije za deterministično ujemanje.
  • Kombinacije, katerih ime je off ali default, ni mogoče izbrati po imenu (te ključne besede se interpretirajo najprej); takšno kombinacijo navedite po njenem ID-ju.
  • Glavno stikalo za stiskanje je trda zapora: ko je stiskanje globalno onemogočeno, ta glava ne more omogočiti.

Uporabljeni načrt se ponovi v glavi odziva:

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

kjer je <source> eden od request-header, routing-override, active-profile, auto-trigger, default ali off.


Vdelave

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

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

Razpoložljivi ponudniki: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, OpenRouter, Jina AI.

ID-ji kataloga imajo obliko provider/model (primer: jina-ai/jina-embeddings-v5-omni-small). Razrešijo se tudi samostojni ID-ji modelov Jina, ki so navedeni v registru (na primer jina-embeddings-v5-text-small, jina-reranker-v3.5). Operacije embed/rerank/classify/segment ponudnika Jina najprej uporabijo poverilnice jina-ai z nadzorne plošče; JINA_AI_API_KEY se uporabi kot nadomestna možnost samo, kadar ključ z nadzorne plošče ne obstaja. Kartica jina-reader je namenjena samo storitvi Reader / r.jina.ai (POST /v1/web/fetch) in nikoli ne izvaja vdelav ali ponovnega razvrščanja.

Modeli registra, ki oglašujejo večmodalno podporo, sprejmejo tudi do 32 strukturiranih elementov, neodvisnih od ponudnika. Vrste predstavnostnih elementov so text, image, audio, video in document. Njihov predstavnostni source je bodisi {"type":"url","url":"https://..."} bodisi {"type":"base64","data":"...","media_type":"..."}.

Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano in vzdevek družine jina-ai/jina-embeddings-v5-omni → omni-small) sprejema tudi Jinine izvorne dokumente EmbeddingsV5Request in jih nespremenjene posreduje na 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,..." }]
    }
  ]
}

Izvorne vrednosti { image | audio | video | pdf } so lahko javni URL HTTPS, URI data: ali neobdelana vsebina base64. OmniRoute teh objektov ne pretvarja v nize in ne pridobiva izvornih URL-jev slik — Jina sama pridobi javno dostopne predstavnostne vsebine. Dodatna polja Jina (task, normalized, truncate, embedding_type) se posredujejo naprej. Jina SKU-ji, namenjeni samo besedilu, še vedno zavrnejo dokumente, ki niso besedilni.

Varnostne in transportne omejitve:

  • Oddaljeni URL-ji predstavnostnih vsebin morajo biti javni URL-ji HTTPS. Kanonični elementi {type,source:url} se pridobijo na strani strežnika (ponovno preverjanje preusmeritev, časovna omejitev, omejitve velikosti, javni DNS, pripenjanje povezave) in vključijo neposredno pred klicem ponudnika. Izvorni elementi Jina {image:"https://..."} se pošljejo nespremenjeni po istem preverjanju javnega HTTPS-ja; Jina pridobi URL.
  • Vdelana predstavnostna vsebina base64 je omejena na 8 MiB dekodiranih podatkov na element in 16 MiB dekodiranih podatkov v celotni zahtevi.

Prevajanje za ponudnike (kanonični elementi se nikoli ne posredujejo nespremenjeni):

  • Večmodalni modeli Jina: vsak element najvišje ravni postane en objekt s ključem modalnosti (text / image / audio / video / pdf), ki za vdelane predstavnostne vsebine uporablja URI-je podatkov; en vektor na element najvišje ravni.
  • Družina Gemini Embedding 2: eno polje najvišje ravni postane ena sama izvorna zahteva models/{model}:embedContent z content.parts (text ali inline_data).
  • llama.cpp (llama-cpp/<model>, kateri koli model, ki ga je naložil lokalni strežnik): kanonični elementi text postanejo navadni nizi, image / audio / video pa vsak postane en objekt {"content": [part]}, ki uporablja dele vsebine klepeta strežnika llama-server (image_url, input_audio z obliko wav / mp3 / flac, input_video) z vdelanimi podatki; en vektor na element najvišje ravni. Strežnik se mora izvajati z --embedding --mmproj …; brez projektorja sam zavrne predstavnostno vsebino. document ni podprt.
  • Neznani/dinamični modeli brez izrecnih metapodatkov o modalnosti zavrnejo strukturiran vhod s 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"
}

Nepodprte kombinacije modela/modalnosti vrnejo HTTP 400, namesto da bi element prisilno pretvorile. Razširitvena polja, ki niso vhodna, se pri podedovanih zahtevah z nizi/žetoni še naprej posredujejo nespremenjena.

# Navedi vse modele za vdelave
GET /v1/embeddings

Ustvarjanje slik

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

{
  "model": "openai/gpt-image-2",
  "prompt": "Čudovit sončni zahod nad gorami",
  "size": "1024x1024"
}

Razpoložljivi ponudniki vključujejo OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, ZenMux, SD WebUI (lokalno), ComfyUI (lokalno).

n vrne n slik v data[]. Pri ponudnikih, katerih izvorni API vrne eno sliko na klic (Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik, NVIDIA NIM, Cloudflare Workers AI), se izvede n ločenih klicev izvornega API-ja, pri čemer so sočasno v izvajanju največ 4. Fiksna vrednost seed se poveča za indeks klica (seed, seed + 1, …), zato se slike razlikujejo, vendar ostanejo ponovljive. Vrednost n je omejena na 10. Celotna zahteva ne uspe, če ne uspe kateri koli klic. Seznam formatov z razpršitvijo klicev je SINGLE_IMAGE_FANOUT_FORMATS v open-sse/handlers/imageGeneration/fanOut.ts.

ZenMux znova uporabi obstoječo povezavo s ključem API in sprejema predponi zenmux/ ali zm/:

  • zenmux/openai/gpt-image-2 uporablja ZenMuxov OpenAI Images API. Možnosti vključujejo size, quality, n, output_format, output_compression, background in response_format.
  • Drugi izdajatelji, kot je zm/meta/muse-image-1.0, uporabljajo ZenMuxovo končno točko Vertex AI :predict. n se preslika v sampleCount, aspect_ratio v aspectRatio, image_size (1K, 2K, 4K) pa v sampleImageSize. Vrednost size v slikovnih pikah določa samo razmerje stranic, ne pa zajamčenih dimenzij v slikovnih pikah. Podprta razmerja, ločljivosti in števila se razlikujejo glede na model.
  • zm/inclusionai/ming-image-0.1-design sam izbere svoje dimenzije. Izpustite size, aspect_ratio in image_size; izrecne vrednosti vrnejo HTTP 400. Formate PNG, JPEG in WebP lahko zahtevate z output_format.

Ta integracija podpira ustvarjanje slik iz besedila, ne pa urejanja z referenčnimi slikami. Izhod Vertex se normalizira v data[].b64_json; response_format: "url" vrne izvorni URL HTTPS ali podatkovni URL base64, kadar so na voljo samo slikovni bajti. Prazni/filtrirani izhodi vrnejo napako namesto praznega uspešnega odgovora. Dostop do modelov je odvisen od računa ZenMux. Glejte ZenMuxov API Vertex in OpenAI Images API.

# Prikaži vse slikovne modele
GET /v1/images/generations

OCR dokumentov

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

{
  "model": "mistral/mistral-ocr-latest",
  "document": {
    "type": "document_url",
    "document_url": "https://example.com/invoice.pdf"
  }
}

model izbere ponudnika OCR prek predpone provider/model; samostojni ID modela (npr. mistral-ocr-latest) se razreši v registriranega ponudnika, izpuščeni model pa privzeto uporabi Mistral (mistral-ocr-latest). Registrirani ponudniki (open-sse/config/ocrRegistry.ts):

ID ponudnika ID modela Vrednost model Opombe
mistral mistral-ocr-latest mistral/mistral-ocr-latest (ali samo mistral-ocr-latest) Sinhrono — odgovor se vrne neposredno iz enega samega klica nadrejene storitve.
azure-document-intelligence prebuilt-read azure-document-intelligence/prebuilt-read Asinhrona nadrejena storitev (analyze + preverjanje stanja) — glejte spodaj.
vertex-deepseek-ocr deepseek-ocr-maas vertex-deepseek-ocr/deepseek-ocr-maas Sinhrono, prek partnerske končne točke Vertex AI openapi/chat/completions — za overjanje/URL glejte spodaj.

Vsi trije ponudniki odgovorijo z enakim telesom v obliki Mistral:

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

Potek preverjanja stanja Azure Document Intelligence

API analyze storitve Azure Document Intelligence je asinhron: začetna zahteva namesto telesa vrne glavo Operation-Location, nato pa je treba stanje rezultata redno preverjati. Obdelovalnik (open-sse/handlers/ocr.ts) ta URL preverja vsako sekundo, največ 30-krat; ob odgovoru preverjanja, ki ni ok, ali stanju "failed" takoj vrne napako (brez nadaljnjega preverjanja), če pa se operacija po izčrpanju dovoljenega števila poskusov še vedno izvaja, vrne 504. Končni odgovor storitve Azure se pred vrnitvijo klicatelju normalizira v enako obliko pages/markdown, kot jo uporablja Mistral, zato odjemalski kodi ni treba posebej obravnavati posameznega ponudnika.

Overjanje in razreševanje končne točke za Vertex AI DeepSeek OCR

vertex-deepseek-ocr ponovno uporabi isto overjanje Vertex AI, ki ga OmniRoute že podpira za promet klepeta/slik (open-sse/executors/vertex.ts): ključ API povezave je bodisi poverilnica Service Account JSON (ki se prek poteka JWT-bearer zamenja za kratkotrajni žeton za dostop OAuth) bodisi že izdan žeton za dostop OAuth, ki se uporabi neposredno. URL nadrejene končne točke je splošna partnerska končna točka Vertex openapi/chat/completions, sestavljena iz projekta in regije povezave — izrecno navedena providerSpecificData.project/providerSpecificData.region imata vedno prednost; sicer se projekt izpelje iz project_id v Service Account JSON, regija pa je privzeto nastavljena na us-central1. Obe razrešitvi se izvedeta v open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl), uporabi pa ju src/app/api/v1/ocr/route.ts, preden zahtevo posreduje funkciji handleOcr.


Seznam modelov

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

→ Vrne vse modele za klepet, vdelave in slike ter kombinacije v obliki OpenAI

Predpone ID-jev modelov (?prefix=)

Večina modelov je objavljena pod predpono ponudnika. Katero predpono dobite, določa zastavica funkcionalnosti MODELS_CATALOG_PREFIX_MODE, ki jo je mogoče preglasiti za posamezno zahtevo s parametrom poizvedbe — uporabno za odjemalca, ki želi čist seznam, ne da bi za vse druge spreminjal nastavitev na ravni strežnika:

GET /v1/models?prefix=alias        # en ID na model — kratka predpona vzdevka
GET /v1/models?prefix=dual         # obe obliki (privzeta nastavitev strežnika)
GET /v1/models?prefix=canonical    # samo polna predpona ID-ja ponudnika
Način Odda Opombe
dual cc/claude-sonnet-4-6 in claude/claude-sonnet-4-6 Privzeto. Oba ID-ja usmerjata na isti model; ohranjena sta, da konfiguracije odjemalcev, v katerih je katera koli oblika trdo kodirana, še naprej delujejo. Približno podvoji velikost kataloga.
alias cc/claude-sonnet-4-6 En vnos na model. Ponudniki brez ločenega vzdevka še vedno oddajo svoj vnos, zato se nič ne izgubi.
canonical claude/claude-sonnet-4-6 En vnos na model pod polno predpono ID-ja ponudnika. Ponudniki brez ločenega vzdevka (npr. antigravity/…, agy/…) tudi tukaj oddajo svoj edini ID, zato se nič ne izgubi.

Zrcalni vnos v načinu dual je mogoče prepoznati tudi brez parametra poizvedbe: vsebuje polje parent, ki kaže na primarni ID.

Odjemalci, ki prikazujejo izbirnik modelov, naj zahtevajo ?prefix=alias — tako deluje razširitev OmniCopilot za VS Code.

Filtri za odkrivanje (?capability=, ?min_context=, ?kind=, ?q=)

GET /v1/models podpira izbirne filtre za odkrivanje. Brez njih ostane odziv nespremenjen. Zožijo katalog, ki ga klicatelj že vidi (najprej se uveljavijo dovoljenja ključa API), in se izvedejo pred ostranjevanjem limit / after v slogu OpenAI:

GET /v1/models?capability=vision&capability=tool_calling   # vsaka navedena zmožnost mora biti omogočena
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding                              # `type` kataloga; vrstice brez njega so `chat`
GET /v1/models?q=sonnet&limit=10                           # ujemanje ID-ja ali imena brez razlikovanja velikosti črk
Parameter Vrednosti
capability attachment, reasoning, structured_output, temperature, thinking, tool_calling, vision
min_context nenegativno celo število, primerjano z context_length
kind chat, audio, embedding, image, moderation, music, rerank, video
q 1–200 znakov

Neznana vrednost ali min_context, ki ni nenegativno celo število (na primer 1.5), vrne HTTP 400, sporočilo pa navede veljavne vrednosti. Implementacija: src/app/api/v1/models/catalogFilters.ts.

Ožji izbor modelov (POST /v1/models/query)

POST /v1/models/query vrne kratek, determinističen seznam iz istega kataloga z enakim preverjanjem pristnosti in vidnostjo za posamezni ključ kot 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 ] }

Vsako polje je izbirno. capabilities in exclude sprejmeta matriko ali niz, ločen z vejicami; max_output se primerja z max_output_tokens. Rezultati so razvrščeni po owned_by, nato po id. Privzeta vrednost za limit je 20, vrednosti nad 100 pa so omejene na 100. Neveljaven JSON, neznano polje ali neveljavna vrednost vrne HTTP 400.

Posamezno skriti modeli za klepet

Model, ki je na strani svojega ponudnika označen kot Skrit, je izključen iz kataloga in ob izrecni zahtevi zavrnjen z napako HTTP 404 / model_not_found. Preverjanje uporablja razrešenega ponudnika in model, vključno z vzdevki ponudnikov, predponami vozlišč združljivih ponudnikov in privzetimi nastavitvami povezav. Kombinacija preskoči skrite cilje in lahko uporabi vidni sorodni model; če ne ostane noben izvedljiv cilj, vrne isto kodo napake. Razkritje modela začne veljati ob naslednji zahtevi. Preglasitve vidnosti, ki veljajo samo za slike, ne skrijejo modela za klepet z istim ID-jem.

Ta nastavitev posameznega modela je ločena od seznamov dovoljenih/prepovedanih modelov za izpostavitev, ki filtrirajo objavo v katalogu in kandidate za samodejno usmerjanje, hkrati pa ohranijo izrecno posredovanje. Dovoljenja modelov za ključe API se še naprej uporabljajo neodvisno. Privzeti način predpone kataloga ostaja dual.

Različice modelov brez razmišljanja

Za modele Claude, ki podpirajo razmišljanje, /v1/models objavi tudi različico brez razmišljanja, katere ID ima predpono claude-3-omniroute-no-thinking/:

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

Izbira tega id-ja (npr. v konfiguraciji Claude Code, ki vedno priloži blok thinking) se preslika nazaj na dejanski <provider>/<model> z onemogočenim sklepanjem — thinking:{type:"disabled"} na poti /v1/messages oziroma z izpuščenima poljema reasoning/reasoning_effort na poti /v1/chat/completions. Različica je navedena samo za modele družine Claude, ki podpirajo razmišljanje in upoštevajo vrednost disabled (zato so npr. izključeni modeli, ki podpirajo samo prilagodljivi način in zavrnejo vrednost disabled). Upravljavci lahko različico za posamezen model prisilno omogočijo ali onemogočijo prek ModelSpec.noThinkingAlias.


Manifest vtičnika ponudnika

GET /api/v1/provider-plugin-manifest

Vrne manifest vtičnika ponudnika, varen za JSON, ki ga uporabljajo Bifrost, CLIProxyAPI in prihodnji stranski usmerjevalniki. Odgovor se ustvari iz registra ponudnikov TypeScript in namenoma ne vključuje skrivnosti odjemalcev OAuth, razreševanja izvajalnega okolja, izvajalnih funkcij, glav zahtev in podatkov o računih.

To končno točko uporabite, ko se stranski proces izvaja zunaj glavnega procesa in ne more neposredno uvoziti datoteke open-sse/config/providerPluginManifestRegistry.ts.


Združljive končne točke

Metoda Pot Oblika
POST /v1/chat/completions OpenAI
POST /v1/messages Anthropic
POST /v1/responses Odgovori OpenAI
POST /v1/embeddings OpenAI
POST /v1/images/generations Slike OpenAI
POST /v1/images/edits Slike OpenAI (urejanje/zapolnjevanje)
POST /v1/videos/generations Ustvarjanje videoposnetkov v slogu OpenAI
POST /v1/music/generations Ustvarjanje glasbe v slogu OpenAI
POST /v1/audio/transcriptions Zvok OpenAI (STT)
POST /v1/audio/speech OpenAI TTS (vrne telo z zvokom)
POST /v1/rerank Prerazvrščanje v slogu Cohere/Voyage
POST /v1/classify Razvrščanje Jina (api.jina.ai)
POST /v1/segment Segmentator Jina (segment.jina.ai)
POST /v1/moderations Moderiranje OpenAI
GET /v1/models OpenAI
POST /v1/models/query Filtriran ožji izbor modelov
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}/ Vzdevek kataloga OpenAI
GET /api/v1/vscode/{token}/models Vzdevek modelov OpenAI
POST /api/v1/vscode/{token}/chat/completions Vzdevek OpenAI z žetonom
POST /api/v1/vscode/{token}/responses Vzdevek odgovorov OpenAI z žetonom
POST /api/v1/vscode/{token}/api/chat Vzdevek Ollama z žetonom
GET /api/v1/vscode/{token}/api/tags Vzdevek oznak Ollama z žetonom

Vse poti POST uporabljajo enako obliko: Bearer your-api-key + telo JSON, preverjeno z Zod (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema itd.; glejte src/shared/validation/schemas.ts). Ob neuspešnem preverjanju sheme je vrnjena napaka 4xx.

Za odjemalce, ki ne morejo dodati Authorization: Bearer ..., OmniRoute sprejema ključe API tudi v URL-ju prek združljivih parametrov poizvedbenega niza (?token=..., ?apiKey=..., ?api_key=..., ?key=...) ali prek namenskih končnih točk /api/v1/vscode/{token}/..., dokumentiranih spodaj.

# Prerazvrščanje (ponudnik iz registra v oblaku ali vozlišče ponudnika, združljivo z OpenAI, v obliki "<prefix>/<model>")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Razvrščanje Jina (poverilnice API-ja Foundation)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

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

# Iskanje Jina (s.jina.ai; vzdevki ponudnika: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

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

# TTS — vrne telo audio/mpeg (ali zahtevano obliko)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Soniox TTS zahteva jezik in glas: privzeta vrednost za `language` je "en"; manjkajoči
# glas ali ime standardnega glasu OpenAI (alloy, nova, …) se spremeni v "Adrian"
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }

# Urejanje slike (multipart)
POST /v1/images/edits  -F [email protected] -F prompt="..." -F [email protected]

# Ustvarjanje videoposnetkov/glasbe (ID modela s predpono ponudnika)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }

Vozlišča ponudnikov za prerazvrščanje: POST /v1/rerank zahteve usmerja tudi v vozlišča ponudnikov, združljiva z OpenAI (oMLX, vLLM, Infinity, TEI za prehodom, …), ki so naslovljena kot <node-prefix>/<model>. Vozlišča povratne zanke (localhost, 127.0.0.1, 172.16.0.0/12) so vedno upravičena, prav tako pa tudi imena gostiteljev, ki jih upravljavec navede v OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS (npr. ime storitve Docker/Compose, kot je http://reranker:8080/v1; ta vozlišča se kličejo neposredno, nikoli prek HTTP(S)_PROXY ali pripetega posredniškega strežnika povezave). Vozlišča na katerem koli drugem gostitelju — naprava v omrežju LAN ali vrstnik Tailscale — so upravičena le, če upravljavec omogoči funkcijsko zastavico RERANK_REMOTE_PROVIDER_NODES in osnovni URL vozlišča prestane pravilnik ponudnika za odhodne URL-je (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS / OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS). Korak prerazvrščanja pomnilniškega mehanizma to pot kliče prek povratne zanke, zato isto pravilo velja za rerankProviderModel v nastavitvah pomnilnika.

Oblike lokalnih strežnikov: vozlišče se kliče na <base>/v1/rerank, ob odgovoru 404 pa na <base>/rerank (Infinity, TEI). Telo zahteve navzgor vsebuje tako zapis Cohere/OpenAI (documents, return_documents) kot zapis TEI (texts, return_text), odgovor od zgornjega strežnika pa se normalizira v ovojnico Cohere: TEI-jev goli [{index, score, text}], {results: [{index, score}]} iz preprostih prehodov in Voyageov zapis {data: [...]} se odjemalcu vrnejo kot {results: [{index, relevance_score, document?}]}, razvrščeni po oceni in omejeni na top_n.

Odkrivanje vozlišč ponudnikov: modeli v vozlišču ponudnika, združljivem z OpenAI, so prikazani v GET /v1/models pod predpono vozlišča. Vrstice brez metapodatkov o končnih točkah (kar je značilno za lokalne sezname /v1/models) podedujejo apiType vozlišča, zato imajo modeli vozlišča embeddings vrednost type: "embedding", modeli vozlišča rerank pa type: "rerank", namesto da bi bila privzeta vrsta klepet; izrecno določen supportedEndpoints v sinhronizirani ali ročno dodani vrstici ima še vedno prednost.

Namenske poti ponudnikov

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

Če predpona ponudnika manjka, se doda samodejno. Neujemajoči se modeli vrnejo 400.


API za datoteke

Z OpenAI združljiva končna točka za datoteke, namenjena paketnemu vhodu/izhodu in nalaganju datotek z določenim namenom.

Metoda Pot Opis
POST /v1/files Naloži datoteko (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — največ 512 MiB
GET /v1/files Prikaže seznam datotek za overjeni ključ API
GET /v1/files/[id] Pridobi metapodatke datoteke
DELETE /v1/files/[id] Izbriše datoteko
GET /v1/files/[id]/content Pretočno vrne neobdelano telo datoteke

Overjanje: Nosilni ključ API — datoteke so prek getApiKeyRequestScope omejene na posamezen ključ API. Ključ lahko vidi, prenese in izbriše samo svoje datoteke; seja nadzorne plošče brez ključa lahko bere celoten primerek; dostop do datoteke brez lastnika (anonimno nalaganje ali nalaganje prek seje nadzorne plošče) je zavrnjen vsakemu klicatelju brez seje. GET /v1/files anonimnega klicatelja — in predloženi ključ, ki ga ni mogoče razrešiti — zavrne s 401, tudi ko je REQUIRE_API_KEY=false, namesto da bi prikazal datoteke vseh najemnikov (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).


API za paketno obdelavo

Paketna obdelava, združljiva z OpenAI.

Metoda Pot Opis
POST /v1/batches Ustvari paket — telo je preverjeno s v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET /v1/batches Prikaže seznam paketov
GET /v1/batches/[id] Pridobi stanje paketa + request_counts
DELETE /v1/batches/[id] Izbriše dokončan/neuspešen paket
POST /v1/batches/[id]/cancel Prekliče paket, ki je v obdelavi

Preverjanje pristnosti: Ključ API vrste Bearer. Paketi so omejeni na posamezni ključ API po istem tristranskem pravilu kot datoteke: samo lasten ključ, seja nadzorne plošče za celoten primerek, zapisi brez lastnika pa so zavrnjeni za vsakega klicatelja brez seje (pridobivanje, brisanje, preklic in preverjanje input_file_id ob ustvarjanju). GET /v1/batches anonimnega klicatelja zavrne z 401, tudi če je REQUIRE_API_KEY=false.


API za iskanje

Abstrakcija ponudnikov spletnega iskanja (Tavily, Brave, Exa, Serper itd.).

Metoda Pot Opis
GET /v1/search Prikaže konfigurirane ponudnike iskanja in njihove zmogljivosti
POST /v1/search Izvede iskalno poizvedbo — telo preveri v1SearchSchema; podpira predpomnjenje/združevanje zahtev
GET /v1/search/analytics Statistika zadetkov/zakasnitev/predpomnilnika po ponudnikih

Preverjanje pristnosti: API-ključ Bearer (extractApiKey + isValidApiKey). Pravilnik iskanja se uveljavlja prek enforceApiKeyPolicy.

provider_options za Exa in Tavily

Exa in Tavily bereta polja, specifična za ponudnika, iz imensko omejene zbirke: provider_options.exa (ali provider_options["exa-search"]) in provider_options.tavily (ali provider_options["tavily-search"]). Posredujejo se samo spodnji ključi. Vsak od njih se preveri glede na lastno shemo Zod v open-sse/handlers/search/providerOptionsPassthrough.ts, ključ z napačno vrsto pa se zavrže. Vsi drugi ključi se prezrejo, vključno s preverjanjem pristnosti, osnovnim URL-jem, stream in outputSchema. Nespremenjeni ključi, ki jih uporabljajo drugi ponudniki (cx, depth, ...), delujejo kot prej.

Ponudnik Polja najvišje ravni Ugnezdeno
Exa type, category, userLocation, moderation, additionalQueries, objective, systemPrompt, compliance (enostavne vrednosti), startPublishedDate, endPublishedDate contents.{text, highlights, summary, extras, subpages, subpageTarget, livecrawlTimeout, maxAgeHours}, združeno s privzeto vrednostjo { 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 —

Splošna polja imajo vedno prednost: query, max_results, filters (domene), country in tema, izpeljana iz search_type. Pri Exa search_type: "news" ohrani category: "news". Tavily sprejema tudi search_type: "finance" (topic: "finance").

Splošni time_range se zdaj posreduje obema ponudnikoma: Exa prejme startPublishedDate (časovni žig ISO), Tavily pa start_date (YYYY-MM-DD). Izrecno naveden datum v provider_options preglasi preslikanega.

Rezultati Exa v provider_raw ohranijo id, highlight_scores, summary, subpages, entities in extras. Rezultati Tavily ohranijo images in favicon.

Obračunavanje stroškov še vedno uporablja enoten register costPerQuery. Tavily za search_depth: "advanced" zaračuna več dobropisov na klic, ta razlika pa ni upoštevana v usage.search_cost_usd.


API za spletno pridobivanje

Pridobite vsebino iz URL-ja prek konfiguriranega ponudnika za spletno pridobivanje (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract).

Parallel Extract (parallel-search, isti ključ API kot za Parallel Search) vrača samo Markdown — katerikoli drug format povzroči napako 400 — in omejuje vsebino na 100.000 znakov. Ko ciljne strani ni mogoče pridobiti, ponudnik to sporoči znotraj odgovora HTTP 200; OmniRoute to prikaže kot 422 s stalnim sporočilom.

Metoda Pot Opis
POST /v1/web/fetch Pridobi/izlušči URL — telo se preveri z v1WebFetchSchema

Avtentikacija: ključ API vrste Bearer (extractApiKey + isValidApiKey). Pravilnik se uveljavlja prek enforceApiKeyPolicy.

Nadomestni preklop z upoštevanjem kvote (#8297): kadar ni naveden izrecen provider, se nabor (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search → parallel-search) pregleda po nespremenljivem prednostnem vrstnem redu (najprej zapolni prvega) — ponudnik, ki je konfiguriran, vendar omejen s hitrostjo, se preskoči, namesto da bi se zahteva takoj prekinila, napaka ponudnika, ki omogoča ponovni poskus oziroma je povezana s kvoto (HTTP 429 vedno; 402/403 za brezplačne ravni Firecrawl/Tavily/TinyFish s kvotami — ne za Jina Reader in nikoli za običajno slabo zahtevo 400), pa med izvajanjem zahteve sproži prehod na naslednjega še nepreizkušenega ponudnika z nastavljenimi poverilnicami. Ko so vsi ponudniki v naboru izčrpani, končna točka vrne en sam 429 (z glavo Retry-After) namesto prejšnjega splošnega 400. Ko je izrecno zahtevan določen provider, ni tihega nadomestnega preklopa — izrecno izbrani ponudnik, ki je omejen s hitrostjo ali ne deluje, vrne svojo napako (429, če je omejen s hitrostjo, sicer pa stanje ponudnika).


Pretakanje prek WebSocket

GET /v1/ws?handshake=1

Preveri rokovanje za nadgradnjo na WebSocket in vrne primere sporočil žičnega protokola (request, cancel). Dejanske okvirje WS obravnava priloženi strežnik WS zunaj tabele poti Next.js.

Preverjanje pristnosti: Ključ API Bearer med rokovanjem.

Responses API prek WebSocket (samo codex)

# Isti gostitelj:vrata kot API HTTP (privzeto 20128); nadgradite povezavo:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (ali: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# Prvi okvir MORA biti response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Posredniški strežnik Responses-API-over-WebSocket je povezan izključno s codex (zaledje ChatGPT). Posluša na istih vratih kot API/nadzorna plošča na poteh /v1/responses, /responses in /api/v1/responses. Ob prvem okviru response.create izvede preverjanje pristnosti in pripravo prek notranjega mostu codex-responses-ws, izbere povezavo OAuth za codex ter vzpostavi tunel do wss://chatgpt.com/backend-api/codex/responses prek transporta wreq-js. Modeli, ki niso codex, so zavrnjeni (codex_ws_provider_required). Za usmerjanje z deljenjem kvote uporabite model: "qtSd/<group>/codex/<model>". Implementirano v app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

Preverjanje pristnosti: Ključ API Bearer med rokovanjem. Priloženi strežnik HTTP (server-ws.mjs) mora biti aktivna vstopna točka (kar je privzeto, kadar obstaja app/server-ws.mjs).

ID modela: uporabite osnovni ID ChatGPT (brez predpone codex/)

OpenAI Codex CLI preveri ime modela na strani odjemalca, kadar je supports_websockets = true, in zavrne ID-je s predpono ponudnika, kot je codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). Pošljite osnovni ID (npr. gpt-5.5). Most OmniRoute je namenjen samo za codex, zato osnovni ID pred tuneliranjem do ponudnika višje ravni znova razreši kot model codex (resolveCodexWsModelInfo) — čeprav bi bil osnovni gpt-5.5 prek HTTP sicer usmerjen k drugemu ponudniku.

Nastavitev OpenAI Codex CLI

Usmerite Codex CLI na OmniRoute tako, da v ~/.codex/config.toml dodate ponudnika po meri s podporo za WebSocket (uporabite ločen CODEX_HOME, da ne spremenite obstoječe konfiguracije):

model = "gpt-5.5"                 # osnovni ID — NE "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # brez končne poševnice; URL za WS se izpelje samodejno (v produkciji uporabite https/wss)
wire_api = "responses"                    # edina podprta vrednost od februarja 2026
supports_websockets = true                # omogoči transport Responses prek WS
env_key = "OMNIROUTE_API_KEY"             # vsebuje ključ API OmniRoute (Bearer)
export OMNIROUTE_API_KEY=sk-...           # ključ API OmniRoute (kateri koli ključ, če je REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

CLI nadgradi base_url + /responses na WebSocket, OmniRoute pa povezavo tunelira do izbrane povezave OAuth za codex. Preverjeno od začetka do konca z lokalnim strežnikom: ChatGPT vrne codex.rate_limits + response.created in pretočno pošlje dokončanje.


Kvote in poročanje o težavah

Metoda Pot Opis
GET /v1/quotas/check Vnaprej preveri kvoto za provider + accountId pred izdajo registriranega ključa
POST /v1/issues/report Prijavi napako pri izdaji kvote/ključa v GitHub (zahteva GITHUB_ISSUES_REPO + žeton)

Avtentikacija: API-ključ Bearer (isAuthenticated).


Samopostrežna uporaba (/api/usage/om-usage)

Vsak ključ API lahko bere lastno porabo in kvote — brez skrbniškega preverjanja pristnosti. To je končna točka, ki jo odjemalec (CLI, plošča OmniCopilot) uporablja, da imetniku ključa prikaže njegovo porabo.

# Besedilna oblika (zgodovinski dogovor — navadno besedilo za terminal)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Strukturirana oblika — uporablja jo uporabniški vmesnik
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

Ključ mora imeti omogočeno možnost allowUsageCommand (privzeto je izklopljena — upravljalnik ključev API na nadzorni plošči jo preklaplja za vsak ključ posebej). Brez nje končna točka odgovori s 403.

?format=json vrne razločljivo strukturo, tako da klicatelj nikoli ne bere podatkovnega polja iz zavrnitve. Ob uspehu:

{
  "allowed": true,
  // prisotno samo, ko so bile za ključ omogočene omejitve porabe po ključu (dnevne/tedenske v USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // posnetek kvote izbranega ponudnika ali null, kadar še ni nič v predpomnilniku:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // posnetek vsake povezave, da lahko uporabniški vmesnik prikaže več ponudnikov enega ob drugem:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

Ob zavrnitvi (401 neveljaven ključ / 403 ni dovoljeno) ista pot vrne { "allowed": false, "error": { "message": "…" } } — prisotno, vendar prazno polje personal/provider (ključ je dovoljen, vendar še ni bilo pridobljenih podatkov) predstavlja drugačno stanje od zavrnitve, razlikovati pa ju je mogoče samo v obliki JSON.

Preverjanje pristnosti: klicateljev lastni ključ API Bearer, preverjen z isValidApiKey — to ni površina za upravljanje (/api/keys/…), ki ostaja zaščitena z requireManagementAuth.

Neobdelani in glede na prag zaustavitve prilagojeni odstotki kvot

Pri uporabi /api/usage/om-usage morajo klicatelji upoštevati razliko med odstotki, prikazanimi v izpisu navadnega besedila, in strukturiranim izpisom JSON:

Vidik Oblika navadnega besedila (/api/usage/om-usage / @@om-usage) Oblika JSON (?format=json)
Izhodno polje NN% left (npr. 20% left) provider.quotas / providers[].quotas
Meritev Uporabljiva količina, prilagojena glede na prag zaustavitve: preostala zmogljivost nad pragom zaustavitve Neobdelana kvota ponudnika: neprilagojena meritev ponudnika
Prilagajanje pragu zaustavitve Prilagojeno prek effectiveRemainingPercent(), tako da je zaščitena rezerva prikazana kot 0% left Brez (neobdelane vrednosti posnetka, kot jih sporoči ponudnik)
Podatki o pragu Vključeni v prikazani odstotek Shranjeni v quotaWindowThresholds za posamezno povezavo (ali privzete vrednosti strežnika)
Primarni uporabnik Interaktivni CLI-ji, terminalski pozivi, človeški operaterji Programske integracije, nadzorne plošče, analitika, sledilniki obračunavanja

Formula prilagoditve glede na prag zaustavitve

OmniRoute podpira proaktivne pragove zaustavitve kvot za preprečevanje izčrpanja pri ponudniku (nastavljene prek quotaWindowThresholds povezave, privzetih nastavitev ponudnika ali globalnih nastavitev odpornosti). Ko je prag zaustavitve (npr. cutoff = 25%) aktiven za obdobje kvote, upodabljalnik besedila izračuna preostalo količino tako:

  • Če je remaining <= cutoff: vrne 0%.
  • Če je remaining > cutoff: vrne ((remaining - cutoff) / (100 - cutoff)) * 100.

Oblikovani besedilni izpis to zaokroži na najbližje celo število (Math.round(...)).

Ponazoritveni primer

Oglejmo si obdobje ponudnika s 60-odstotno neobdelano porabo (torej 40-odstotno neobdelano preostalo kvoto) in nastavljenim pragom zaustavitve pri 25 % preostale kvote:

Predstavitev Izračun Preostanek Izpeljana poraba
Neobdelani JSON (?format=json) Posnetek ponudnika (quotas[window]) 40% 60%
Besedilna oblika (NN% left) ((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100 20% 80% (pri izračunu 100 - remaining)
  • Zakaj besedilo prikazuje 20 % preostanka: Od 40 % fizične kvote, ki je še na voljo v računu, je 25 % rezerviranih s pravilnikom praga zaustavitve. Klicatelju ostane samo 15 % od 75 % uporabljivega razpoložljivega prostora, preden usmerjevalnik preneha usmerjati v to povezavo. Prilagajanje zagotavlja, da povezava sporoči izčrpanost (0% left) natanko takrat, ko se usmerjanje preneha.
  • Zakaj JSON ohrani neobdelane vrednosti: Koristna vsebina JSON vrne natančen posnetek ponudnika (UsageSnapshot), tako da imajo zunanja orodja dostop do dejanske izrabe pri ponudniku in nastavitev quotaWindowThresholds na ravni povezave brez izgubnega prilagajanja na strani strežnika.

Navodila za selitev odjemalcev

Če je zunanja integracija (kot je vtičnik urejevalnika ali razširitev agenta) prej razčlenjevala besedilno končno točko (NN% left) in izračunala odstotek porabe kot 100 - NN, selitev na ?format=json pomeni:

  • Branje neobdelanih vrednosti JSON bo odražalo dejansko porabo pri ponudniku (60 % porabljeno v zgornjem primeru).
  • Če želi integracija ohraniti semantiko uporabljive količine iz besedilne končne točke, lahko formulo efektivnega preostanka izračuna na strani odjemalca z uporabo quotaWindowThresholds za preglasitve na ravni povezave.

Semantični predpomnilnik

# Pridobi statistiko predpomnilnika
GET /api/cache/stats

# Počisti vse predpomnilnike
DELETE /api/cache/stats

Primer odgovora:

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

Vpliv na zakasnitev

Zadetek v semantičnem predpomnilniku vrne odgovor iz predpomnilnika brez klica zunanje storitve, zato je sporočena vrednost X-OmniRoute-Response-Latency skoraj ničelna (ne glede na prvotno zakasnitev zunanje storitve). Odjemalci, občutljivi na zakasnitev (primerjalno preskušanje, spremljanje p50/p99), naj preverijo odzivno glavo X-OmniRoute-Cache-Latency:

Vrednost Pomen
synthetic Odgovor je bil vrnjen iz predpomnilnika; zakasnitev ni dejanski čas zunanje storitve
(odsotna) Odgovor iz dejanskega klica zunanje storitve

Obhod predpomnilnika za posamezni ključ

API-ključi lahko prek cacheDefaultMode onemogočijo branje iz semantičnega predpomnilnika:

Vrednost Vedenje
legacy Običajno vedenje predpomnilnika (privzeto)
bypass V celoti preskoči iskanje v predpomnilniku; vedno pokliče zunanjo storitev

Nastavite ob ustvarjanju ključa (POST /api/keys) ali posodobitvi (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

Obhod za posamezno zahtevo

Vsaka zahteva lahko obide predpomnilnik ne glede na nastavitve ključa:

X-OmniRoute-No-Cache: true

Nadzorna plošča in upravljanje

Upravljavske poti (/api/*, razen javne avtentikacije/prijave) ne dovoljujejo dostopa z običajnimi API-ključi za sklepanje. Družine poverilnic, obsegi in primeri curl: Avtentikacija za upravljanje.

Avtentikacija

Končna točka Metoda Opis
/api/auth/login POST Prijava
/api/auth/logout POST Odjava
/api/settings/require-login GET/POST Stanje prijave (GET, javno). POST nastavi geslo/preklopi zahtevo za prijavo: ko geslo obstaja, je dostop dovoljen samo operaterju (seja nadzorne plošče, lokalni CLI ali onemogočena prijava — API-ključi in žetoni oma_ prejmejo 403); seja nadzorne plošče pošlje currentPassword za zamenjavo gesla

Upravljanje ponudnikov

Končna točka Metoda Opis
/api/providers GET/POST Prikaz seznama/ustvarjanje ponudnikov
/api/providers/[id] GET/PUT/DELETE Upravljanje ponudnika
/api/providers/[id]/test POST Preizkus povezave s ponudnikom
/api/providers/[id]/models GET Prikaz seznama modelov ponudnika
/api/providers/validate POST Preverjanje veljavnosti konfiguracije ponudnika
/api/providers/bulk POST Množično dodajanje API-ključev za ENEGA ponudnika
/api/providers/import POST Uvoz heterogenega SEZNAMA ponudnikov iz razčlenjene datoteke CSV/JSON (#6836); rezultati delnih napak po posameznih vrsticah
/api/provider-nodes* Različne Upravljanje vozlišč ponudnikov
/api/provider-models GET/POST/PUT/PATCH/DELETE Modeli po meri in preglasitve za posamezne modele (dodajanje, posodabljanje, skrivanje/prikazovanje, brisanje)
/api/provider-models/validate-and-add POST Strogo preverjanje povezave z upravljavsko avtentikacijo in izrecno privolitvijo ter atomska registracija modela po meri; glejte Preverjanje veljavnosti modela

Za sinhronizirane/uvožene modele PUT /api/provider-models sprejema provider, modelId in maxOutputTokenOverride: pozitivno celo število nastavi ročno omejitev izhodnih žetonov, null pa jo odstrani in obnovi privzeto vrednost. GET /api/provider-models?provider=<provider> vrne te vrednosti v modelOutputOverrides, vključno z modeli brez vrstice modela po meri. Preglasitev uporablja izvajalno zmogljivost max_output_tokens in se ohrani po ponovni sinhronizaciji modela. Stran ponudnika, združljivega z OpenAI, ponuja enake kontrolnike za urejanje/brisanje in označuje modele z izrecno podporo za vid.

Vozlišča Chat Completions po meri prilagodijo izrecne izklope sklepanja zalednemu sistemu. Uspešen preizkus povezave samodejno izbere kontrolnike predloge klepeta za vsak natančen ID modela, katerega vnos /models potrjuje prepoznano vrednost owned_by: vllm, sglang ali llamacpp. Prosojni ovoji, združljivi z OpenAI, lahko ohranijo izvirni vnos modela znotraj ugnezdenega objekta openai; zaznavanje sledi do trem takim ovojnicam. Modeli z manjkajočim, neznanim ali nasprotujočim si lastništvom ohranijo običajno vedenje OpenAI. Zaznavanje ponovno uporabi obstoječo zahtevo kataloga, ne ustvari nobenih žetonov dokončanja in se razveljavi, ko se spremeni končna točka povezave.

Če želite določiti vedenje za zaledni sistem, ki teh metapodatkov ne razkriva, uporabite obstoječi API za delno posodobitev ponudnika:

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

To telo pošljite z PUT /api/providers/<connection-id>. Pri tej povezavi se izrecna raven sklepanja none pošlje kot chat_template_kwargs.thinking=false in chat_template_kwargs.enable_thinking=false. Izrecne izvorne vrednosti predloge ostanejo merodajne, razen če strežniško pravilo sklepanja vsili raven. Nastavitev se uporabi samo, ko povezava po meri, združljiva z OpenAI, posreduje telo Chat Completions; zahteve Responses in običajni ponudniki ohranijo svojo izvorno obliko zahteve. Nastavite reasoningControl na openai, da vsilite običajno posredovanje OpenAI reasoning_effort, ali pa ga izpustite oziroma nastavite na null, da uporabite samodejno zaznavanje.

Zahteve klasifikatorja samodejnega načina Claude Code privzeto onemogočijo izvorno razmišljanje, kadar ne vsebujejo izrecnih kontrol sklepanja. Zaznavanje uporablja sistemsko oznako klasifikatorja v zahtevah oblike Claude, ne pa imen modelov ali omejitev dokončanja. Izrecne kontrole telesa, podprte glave za raven sklepanja/razmišljanja, pravila usmerjanja in razrešena raven sklepanja modela ohranijo svojo obstoječo prednost. Obe stopnji klasifikatorja ohranita svoje pozive, omejitve dokončanja, ustavitvena zaporedja in dejanske razsodbe nadrejenega sistema o dovoljenjih; druga stopnja lahko še vedno ustvari zahtevano vidno sklepanje kot običajno besedilo.

Tokovi OAuth

Končna točka Metoda Opis
/api/oauth/[provider]/[action] Različno OAuth, specifičen za ponudnika

Usmerjanje in konfiguracija

Končna točka Metoda Opis
/api/models/alias GET/POST Vzdevki modelov
/api/models/catalog GET Vsi modeli po ponudniku in vrsti
/api/combos* Različno Upravljanje kombinacij
/api/keys* Različno Upravljanje ključev API
/api/pricing GET Cene modelov

Uporaba in analitika

Končna točka Metoda Opis
/api/usage/history GET Zgodovina uporabe
/api/usage/logs GET Dnevniki uporabe
/api/usage/request-logs GET Dnevniki na ravni zahtev
/api/usage/[connectionId] GET Uporaba po posamezni povezavi
/api/usage/token-limits GET/POST/DELETE Proračuni omejitev žetonov za posamezen ključ API
/api/usage/model-latency-stats GET Drseči agregat zakasnitve po ponudniku/modelu (povprečje/p50/p95/p99, stopnja uspešnosti); filtri: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health GET Povzetek stanja predpomnilnika pozivov na podlagi call_logs — razmerje zapisov/branj, porazdelitev velikosti zapisov p50/p90/p99, koncentracija obsežnih zapisov, razčlenitev po modelih in razsodba healthy/degraded/thrash/no-data; parametra poizvedbe range (1h|24h|7d|30d, privzeto 24h) in izbirni model (#8827)

Dovoljenja ključev API

PATCH /api/keys/{id} posodobi dovoljenja obstoječega ključa. Kot vsaka pot /api/keys* zahteva pooblastilo za upravljanje (glejte Preverjanje pristnosti za upravljanje), ne pa ključa za inferenco. Pošljite samo polja, ki jih želite spremeniti; zahteva brez katerega koli od njih je zavrnjena z No valid fields to update. Sprejeta polja določa updateKeyPermissionsSchema v src/shared/validation/schemas/keys.ts.

Polje Vrsta Opombe
name niz, 1–200 znakov
isActive logična vrednost
isBanned logična vrednost
expiresAt datum in čas po standardu ISO 8601 ali null null odstrani čas poteka veljavnosti
modelAccessMode all | restricted allowedModels mora biti prazen, ko je način all
allowedModels, blockedModels polje nizov, največ 1000
allowedCombos polje nizov, največ 500 Določa, katere kombinacije lahko kliče ključ; neposredne modele urejata modelAccessMode / allowedModels
connectionAccessMode all | restricted allowedConnections ne sme biti prazen pri restricted in mora biti prazen pri all
allowedConnections polje UUID-jev, največ 100
allowAutoCombos logična vrednost false zavrne zahteve za modele auto/* s tem ključem; ključi, pri katerih ta vrednost ni bila nastavljena, so dovoljeni
catalogScope all | combos | models Določa, kaj GET /v1/models navede za ta ključ (samo kombinacije, samo modele ali oboje); ne spremeni tega, kaj lahko ključ kliče
forcedModel niz z največ 300 znaki ali null Usmeri zahteve za klepet v ta model/kombinacijo, prednostno pred X-Route-Model in body.model; omejitve ključa še vedno veljajo
noLog, autoResolve logična vrednost
throttleDelayMs celo število, 0–300000
maxSessions celo število, 0–10000
rateLimits polje { limit, window } (pozitivna cela števila, največ 50) ali null null odstrani omejitve
accessSchedule objekt urnika ali null null odstrani urnik
scopes polje nizov, največ 32
allowedEndpoints polje nizov, največ 20
streamDefaultMode legacy | json
cacheDefaultMode legacy | bypass Glejte Onemogočanje predpomnilnika za posamezni ključ
compressionEnabled logična vrednost
codexServiceMode eden od načinov storitve Codex
disableNonPublicModels boolean
allowUsageCommand boolean
usageLimitEnabled boolean
dailyUsageLimitUsd, weeklyUsageLimitUsd number >= 0 ali null
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" }'

Nastavitve

Končna točka Metoda Opis
/api/settings GET/PUT/PATCH Splošne nastavitve. Ključi varnostnih pravilnikov (requireLogin, newPassword, oidc*, corsOrigins, bruteForceProtection) zahtevajo currentPassword in poverilnico operaterja — ključi API in žetoni oma_ prejmejo 403; vsaka sprememba zahteva obseg admin dostopnega žetona
/api/settings/proxy GET/PUT Konfiguracija omrežnega posredniškega strežnika
/api/settings/proxy/test POST Preizkus povezave s posredniškim strežnikom
/api/settings/ip-filter GET/PUT Seznam dovoljenih/blokiranih naslovov IP
/api/settings/thinking-budget GET/PUT Način prepisovanja zahtev za razmišljanje/sklepanje (nespremenjen prenos / samodejna odstranitev / po meri / prilagodljivo). Neodvisno od stiskanja. Glejte THINKING_BUDGET.md.
/api/settings/system-prompt GET/PUT Globalni sistemski poziv
/api/settings/compression GET/PUT Globalna konfiguracija stiskanja
/api/settings/purge-request-history POST Izbris vrstic dnevnika zahtev in lokalnih artefaktov dnevnika klicev

Kontekst in stiskanje

Končna točka Metoda Opis
/api/compression/preview POST Predogled stiskanja off/lite/standard/aggressive/ultra/RTK/stacked
/api/compression/language-packs GET Seznam razpoložljivih jezikovnih paketov Caveman
/api/compression/rules GET Seznam metapodatkov pravil Caveman
/api/context/caveman/config GET/PUT Vzdevek za nastavitve, specifične za Caveman
/api/context/rtk/config GET/PUT Nastavitve, specifične za RTK, vključno s filtri po meri in ohranjanjem neobdelanega izhoda
/api/context/rtk/filters GET Katalog filtrov RTK in diagnostika filtrov po meri
/api/context/rtk/test POST Izvedba predogleda/preizkusa RTK na besedilni koristni vsebini
/api/context/rtk/raw-output/[id] GET Branje ohranjenega redigiranega neobdelanega izhoda po ID-ju kazalca
/api/context/combos GET/POST Seznam/ustvarjanje kombinacij stiskanja
/api/context/combos/[id] GET/PUT/DELETE Podrobnosti/posodobitev/brisanje kombinacije stiskanja
/api/context/combos/[id]/assignments GET/PUT Dodeljevanje kombinacij stiskanja kombinacijam usmerjanja
/api/context/analytics GET Vzdevek za analitiko stiskanja

Spremljanje

Končna točka Metoda Opis
/api/sessions GET Sledenje aktivnim sejam
/api/rate-limits GET Omejitve hitrosti za posamezen račun
/api/monitoring/health GET Preverjanje stanja + povzetek ponudnikov (catalogCount, configuredCount, activeCount, monitoredCount). Pogled za upravljanje vključuje credentialHealth: skalarne vrednosti predpomnilnika preverjanj, failedConnections, ko je failed>0, in staleDbNonOkCount (lepljivi test_status SQLite, ne merilnik). Glejte MONITORING_GUIDE.md.
/api/cache/stats GET/DELETE Statistika predpomnilnika / brisanje
/api/modality-bridge/stats GET Vrednosti attempts v pomnilniku, uspehi/bridged, neuspehi, zadetki predpomnilnika, totalLatencyMs, latencySamples, averageLatencyMs, izračunan na podlagi števila vzorcev, in čas zadnje uporabe (ponastavitev ob ponovnem zagonu; overjanje za upravljanje)
/api/modality-bridge/video/runtime GET Strogo preverjanje zaupanja vredne povratne zanke pred overjanjem/preverjanjem za upravljanje; razpoložljivost in različice FFmpeg/ffprobe v prečiščeni obliki (brez shranjevanja)
/api/modality-bridge/video/extract POST Notranji overjeni posrednik bajtov prek zaupanja vredne povratne zanke; vhod 50 MiB, omejena čakalna vrsta/izhod 32 MiB, 503 za zapolnjeno zmogljivost, 499 za prekinitev povezave, 504 za prekoračitev roka; ni javni API za nalaganje datotek

Varnostno kopiranje in izvoz/uvoz

Končna točka Metoda Opis
/api/db-backups GET Prikaže razpoložljive varnostne kopije
/api/db-backups PUT Ustvari ročno varnostno kopijo
/api/db-backups POST Obnovi iz določene varnostne kopije
/api/db-backups PATCH Shrani nastavitve hrambe varnostnih kopij (samo za operaterje)
/api/db-backups DELETE Odstrani shranjene varnostne kopije skladno z nastavitvami hrambe (samo za operaterje)
/api/db-backups/export GET Prenese podatkovno zbirko kot datoteko .sqlite
/api/db-backups/import POST Naloži datoteko .sqlite za zamenjavo podatkovne zbirke (?dryRun=true samo preveri)
/api/db-backups/exportAll GET Prenese celotno varnostno kopijo kot arhiv .tar.gz

/api/db-backups/export, /api/db-backups/exportAll in /api/settings/export-json razkrijejo vse shranjene poverilnice, zato zahtevajo sejo nadzorne plošče ali lokalni CLI (oziroma onemogočeno prijavo). Ključi API katerega koli obsega in dostopni žetoni oma_ prejmejo 403. Za obnovitve velja ista omejitev: POST /api/db-backups/import (vključno z dryRun=true), POST /api/db-backups (obnovitev po ID-ju) in POST /api/settings/import-json zamenjajo aktivno podatkovno zbirko ali nastavitve, zato strojna poverilnica tudi tam prejme 403; omniroute sync import pošlje poverilnico lokalnega CLI-ja. Enako velja za DELETE /api/db-backups (odstranjevanje shranjenih varnostnih kopij) in PATCH /api/db-backups (nastavitve hrambe: shranjene vrednosti določajo samodejno odstranjevanje po vsakem varnostnem kopiranju). Prikaz seznama (GET) in ustvarjanje ročne varnostne kopije (PUT) ohranita običajno preverjanje pristnosti za upravljanje.

Sinhronizacija z oblakom

Končna točka Metoda Opis
/api/sync/cloud Različno Operacije sinhronizacije z oblakom
/api/sync/initialize POST Inicializira sinhronizacijo
/api/cloud/* Različno Upravljanje oblaka

Predori

Končna točka Metoda Opis
/api/tunnels/cloudflared GET Prebere stanje namestitve/izvajanja Cloudflare Quick Tunnel za nadzorno ploščo
/api/tunnels/cloudflared POST Omogoči ali onemogoči Cloudflare Quick Tunnel (action=enable/disable)
/api/tunnels/ngrok GET Prebere stanje izvajanja ngrok Tunnel za nadzorno ploščo
/api/tunnels/ngrok POST Omogoči ali onemogoči ngrok Tunnel (action=enable/disable)

Orodja CLI

Končna točka Metoda Opis
/api/cli-tools/claude-settings GET Stanje Claude CLI
/api/cli-tools/codex-settings GET Stanje Codex CLI
/api/cli-tools/droid-settings GET Stanje Droid CLI
/api/cli-tools/openclaw-settings GET Stanje OpenClaw CLI
/api/cli-tools/runtime/[toolId] GET Splošno izvajalno okolje CLI

Odgovori CLI vključujejo: installed, runnable, command, commandPath, runtimeMode, reason.

Agenti ACP

Končna točka Metoda Opis
/api/acp/agents GET Prikaže vse zaznane agente (vgrajene in prilagojene) skupaj s stanjem
/api/acp/agents POST Doda prilagojenega agenta ali osveži predpomnilnik zaznavanja
/api/acp/agents DELETE Odstrani prilagojenega agenta glede na poizvedbeni parameter id

Odgovor GET vključuje agents[] (id, name, binary, version, installed, protocol, isCustom) in summary (total, installed, notFound, builtIn, custom).

Odpornost in omejitve hitrosti

Končna točka Metoda Opis
/api/resilience GET/PATCH Pridobi/posodobi čakalno vrsto zahtev, obdobje mirovanja povezave, odklopnik ponudnika in nastavitve čakanja
/api/resilience/reset POST Ponastavi odklopnike vezij ponudnikov
/api/resilience/model-cooldowns GET Prikaže aktivne blokade za posamezno kombinacijo (ponudnik, povezava, model), razvrščene po preostalem času
/api/resilience/model-cooldowns DELETE Počisti blokado modela — telo {provider, model} ali {all: true} za izbris vseh
/api/rate-limits GET Stanje omejitve hitrosti za posamezen račun
/api/rate-limit GET Globalna konfiguracija omejitve hitrosti

Vse štiri poti /api/resilience/* zahtevajo preverjanje pristnosti za upravljanje (requireManagementAuth). Za popolno razčlenitev odklopnika ponudnika, obdobja mirovanja povezave in blokade modela glejte Odpornost (razširjeno).

Evalvacije

Končna točka Metoda Opis
/api/evals GET/POST Prikaže zbirke evalvacij / zažene evalvacijo

Pravilniki

Končna točka Metoda Opis
/api/policies GET/POST/DELETE Upravlja pravilnike usmerjanja

Skladnost

Končna točka Metoda Opis
/api/compliance/audit-log GET Dnevnik revizije skladnosti (zadnjih N)

v1beta (združljiv z Gemini)

Končna točka Metoda Opis
/v1beta/models GET Seznam modelov v obliki Gemini
/v1beta/models/{...path} POST Končna točka Gemini generateContent

Te končne točke posnemajo obliko API-ja Gemini za odjemalce, ki pričakujejo izvorno združljivost z Gemini SDK.

Notranji/sistemski API-ji

Končna točka Metoda Opis
/api/init GET Preverjanje inicializacije aplikacije (ob prvem zagonu)
/api/tags GET Oznake modelov, združljive z Ollama (za odjemalce Ollama)
/api/restart POST Sproži nadzorovan ponovni zagon strežnika
/api/shutdown POST Sproži nadzorovano zaustavitev strežnika
/api/system/env/repair POST Popravi okoljske spremenljivke ponudnika OAuth
/api/system/version GET Trenutna/najnovejša različica, stanje posodobitve, kanal izdaje
/api/system/version POST Začne posodobitev na najnovejšo različico, prilagojeno načinu namestitve

Opomba: Te končne točke sistem uporablja interno ali za združljivost z odjemalci Ollama. Končni uporabniki jih običajno ne kličejo.

Popravilo okolja OAuth (v3.6.1+)

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

{
  "provider": "claude-code"
}

Popravi manjkajoče ali poškodovane okoljske spremenljivke OAuth za določenega ponudnika. Vrne:

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

Različica in kanal izdaje

GET /api/system/version

Upravljavska pot, dostopna samo prek povratne zanke (skrbniško preverjanje pristnosti). Vrne trenutno različico, najnovejšo objavljeno različico in stanje samodejnega posodabljanja. releaseChannel in channels sta dodatni polji (veja 3.8.54); channel ohranja svoj pomen — način namestitve, ki ga uporablja posodabljalnik nadzorne plošče (npm, source ali 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 — kanal npm trenutne gradnje: nightly za različice -nightly.*, next za druge predizdaje (-rc.*, -beta.*, -alpha.*), lts za stabilno različico starejše glavne različice od channels.latest, sicer latest. Veljajo enaka pravila kot v scripts/release/dist-tag.mjs, ki ob objavi izbere npm dist-tag.
  • channels — najnovejša objavljena različica vsake oznake dist-tag, pridobljena z npm view omniroute dist-tags (z nadomestnim dostopom prek HTTP registra), predpomnjena z enakim 10-minutnim TTL kot latest. latest je vedno prisoten (če ni na voljo, uporabi polje latest, nato "unavailable"); next, nightly in lts se pojavijo samo, kadar ustrezna oznaka dist-tag obstaja. Zahteva Cache-Control: no-cache osveži obe poizvedbi.

Model kanalov (latest = v3 do splošne razpoložljivosti različice 4.0, next = rc, nightly = gradnje iz veje develop, lts = popravki v3 po splošni razpoložljivosti različice 4.0) je opisan v docs/ops/RELEASE_STRATEGY.md.


Prepis zvoka

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

Prepišite zvočne datoteke s katerim koli konfiguriranim ponudnikom STT. Prvi segment poti izbere izvornega ponudnika (openai/…, deepgram/…). Prehodi, ki ponovno izvažajo model drugega ponudnika, uporabljajo kvalificirani ID (openrouter/deepgram/nova-3).

Zahteva:

curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "[email protected]" \
  -F "model=openai/whisper-1"

Odgovor:

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

Primeri ID-jev modelov: openai/whisper-1 (zahteva ključ OpenAI), openrouter/deepgram/nova-3 (zahteva ključ OpenRouter), deepgram/nova-3 (zahteva izvorni ključ Deepgram). Zahteva samo za deepgram/nova-3 ne uporablja OpenRouterja.

Podprte oblike: mp3, wav, m4a, flac, ogg, webm.


Združljivost z Ollama

Za odjemalce, ki uporabljajo obliko API-ja Ollama:

# Končna točka za klepet (oblika Ollama)
POST /v1/api/chat

# Seznam modelov (oblika Ollama)
GET /api/tags

Zahteve se samodejno pretvarjajo med obliko Ollama in notranjimi oblikami.

Vzdevki za VS Code z žetonom / brez glave

Te vzdevke uporabite, kadar integracija ne more vstaviti glave Authorization in mora biti ključ API vdelan v osnovni URL.

# Vzdevek kataloga v slogu OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# Vzdevki za klepet v slogu OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Vzdevki v slogu Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

Primer:

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

Opombe:

  • Vzdevki z žetonom znova uporabljajo iste obdelovalnike kot /v1/* in /api/tags; oblike odgovorov ostanejo enake.
  • Kadar odjemalec podpira glave po meri, dajte prednost Authorization: Bearer ....
  • Žetoni v URL-jih se lahko pojavijo v dnevnikih povratnega posredniškega strežnika, zgodovini brskalnika in telemetriji zunaj OmniRoute. Obravnavajte jih kot možnost za zagotavljanje združljivosti in ne kot privzeti način preverjanja pristnosti.

Telemetrija

# Pridobi povzetek telemetrije zakasnitev (p50/p95/p99 za vsakega ponudnika)
GET /api/telemetry/summary

Odgovor:

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

Proračun

# Pridobi stanje proračuna za vse ključe API
GET /api/usage/budget

# Nastavi ali posodobi proračun
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"
}

Opombe o shemi (setBudgetSchema): apiKeyId je obvezen; vsaj ena od vrednosti dailyLimitUsd, weeklyLimitUsd ali monthlyLimitUsd mora biti večja od nič. Izbirna polja: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Zastarela oblika {keyId, limit, period} vrne 400 Bad Request.

Omejitve žetonov

Proračuni žetonov za posamezen ključ API (ločeni od zgornjega proračuna v USD). Uveljavljajo se neposredno na poti zahteve: ko uporaba ključa v trenutnem časovnem oknu doseže omejitev, so zahteve zavrnjene z napako 429 Too Many Requests. Omejitve je mogoče določiti za določen model, provider ali uporabiti globalno za celoten ključ; kadar se z zahtevo ujema več omejitev, velja najstrožja.

# Prikaži omejitve žetonov ključa (vključuje trenutno uporabo v časovnem oknu)
GET /api/usage/token-limits?apiKeyId=key-123

# Ustvari ali posodobi omejitev žetonov
POST /api/usage/token-limits
Content-Type: application/json

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

# Izbriši omejitev žetonov po ID-ju
DELETE /api/usage/token-limits?id=tl-abc

Opombe o shemi (setTokenLimitSchema): apiKeyId in scopeType (model | provider | global) sta obvezna. scopeValue je obvezen, razen če je scopeType nastavljen na global (npr. ID modela za obseg model ali ID ponudnika za obseg provider). tokenLimit mora biti pozitivno celo število (pretvorjeno iz niza). Izbirno: id (izpustite za ustvarjanje, navedite za posodobitev), resetInterval (daily | weekly | monthly, privzeto monthly), resetTime (HH:MM), enabled (privzeto true). Odgovori GET vsako omejitev dopolnijo s polji tokensUsed, remaining, windowStart, periodStartAt in nextResetAt. To je končna točka upravljavskega razreda (preverjanje pristnosti se centralno uveljavlja prek cevovoda za avtorizacijo).

Obdelava zahtev

  1. Odjemalec pošlje zahtevo na /v1/*
  2. Obdelovalnik poti pokliče handleChat, handleEmbedding, handleAudioTranscription ali handleImageGeneration
  3. Model se razreši (neposredni ponudnik/model ali vzdevek/kombinacija)
  4. Poverilnice se izberejo iz lokalne zbirke podatkov s filtriranjem glede na razpoložljivost računa
  5. Za klepet: handleChatCore preveri semantični/podpisni predpomnilnik in razreši nastavitve stiskanja kombinacije
  6. Če je omogočeno, se pred pretvorbo za ponudnika izvede proaktivno stiskanje (lite, Caveman, RTK ali naloženo)
  7. Izvajalnik ponudnika pošlje zahtevo nadrejeni storitvi
  8. Odgovor se pretvori nazaj v obliko odjemalca (klepet) ali vrne nespremenjen (vdelave/slike/zvok)
  9. Zabeležijo se uporaba, analitika stiskanja in dnevniki zahtev
  10. Ob napakah se v skladu s pravili kombinacije uporabi nadomestna možnost

Celoten opis arhitekture: ARCHITECTURE.md


Upravljanje kombinacij

Kombinacije usmerjanja višje ravni (že povzete pod /api/combos*) je mogoče preslikati tudi v razmerju 1:1 iz vzorca ID-ja modela, kar omogoča pregledno preusmeritev ID-ja modela v slogu OpenAI na kombinacijo.

Metoda Pot Opis
GET /api/model-combo-mappings Prikaže vse preslikave model→kombinacija
POST /api/model-combo-mappings Ustvari preslikavo — telo: {pattern, comboId, priority?, enabled?, description?}
GET /api/model-combo-mappings/[id] Pridobi posamezno preslikavo
PUT /api/model-combo-mappings/[id] Posodobi polja obstoječe preslikave
DELETE /api/model-combo-mappings/[id] Odstrani preslikavo

Preverjanje pristnosti: upravljavska seja/ključ API (requireManagementAuth).


Spletni kavlji

Naročnine na odhodne spletne kavlje za dogodke OmniRoute (dokončanje zahteve, izčrpanje kvote, rotacija ključa itd.).

Metoda Pot Opis
GET /api/webhooks Prikaže seznam spletnih kavljev (skrivnosti so zakrite kot <prefix>...)
POST /api/webhooks Ustvari spletni kavelj — telo: {url, events?: ["*"], secret?, description?}
GET /api/webhooks/[id] Pridobi spletni kavelj
PUT /api/webhooks/[id] Posodobi url/events/secret/description
DELETE /api/webhooks/[id] Odstrani spletni kavelj
POST /api/webhooks/[id]/test Pošlje preskusno koristno vsebino na URL spletnega kavlja in vrne stanje dostave

Avtentikacija: upravljavska seja/ključ API (requireManagementAuth).


Registrirani ključi (samodejno upravljanje)

Podsistem za samodejno upravljanje ključev ga uporablja za izdajanje in menjavanje ključev API pri ponudniku/računu v ozadju z dnevnimi/urnimi kvotami.

Metoda Pot Opis
GET /api/v1/registered-keys Prikaže seznam registriranih ključev (samo zakrita predpona)
POST /api/v1/registered-keys Izda nov registrirani ključ — telo: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Neobdelani ključ vrne enkrat. Ob zavrnitvi zaradi kvote vrne 429.
GET /api/v1/registered-keys/[id] Pridobi metapodatke registriranega ključa (brez neobdelanega ključa)
DELETE /api/v1/registered-keys/[id] Prekliče registrirani ključ
POST /api/v1/registered-keys/[id]/revoke Izrecna končna točka za preklic (enak učinek kot DELETE)

Preverjanje pristnosti: upravljavska seja/ključ API (requireManagementAuth) — enaka zaščita kot pri /api/keys: seja nadzorne plošče, lokalni žeton CLI ali ključ API z obsegom manage/admin; ključi API, namenjeni samo sklepanju, prejmejo 403. Glejte tudi /v1/quotas/check in /v1/issues/report.


Protokol agentov

Opravila agentov v oblaku (Claude Code, Codex Cloud, OpenHands itd.), izvedena na daljavo v imenu uporabnikov OmniRoute.

Metoda Pot Opis
GET /api/v1/agents/tasks Prikaže opravila — izbirni parametri ?provider=, ?status=, ?limit= (1–500, privzeto 50)
POST /api/v1/agents/tasks Ustvari opravilo — telo je preverjeno z CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Vrne 201 z ovojnico opravila
DELETE /api/v1/agents/tasks?id=... Izbriše opravilo
GET /api/v1/agents/tasks/[id] Prebere opravilo — sinhrono osveži stanje pri nadrejenem agentu v oblaku, ko je nastavljen external_id
POST /api/v1/agents/tasks/[id] Razločeno dejanje: {action: "approve"}, {action: "message", message} ali {action: "cancel"}
DELETE /api/v1/agents/tasks/[id] Izbriše določeno opravilo po ID-ju

Preverjanje pristnosti: za vsako metodo je potrebno upravljavsko preverjanje pristnosti (requireCloudAgentManagementAuth). Pred različico v3.8.0 te metode niso zahtevale preverjanja pristnosti — za kritično spremembo glejte potrditev 588a0333.

# Ustvari opravilo Claude Code v oblaku
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":"..."}}'

Upravljavski posredniški strežniki

Izhodni posredniški strežniki HTTP(S)/SOCKS, ki jih je mogoče dodeliti ponudnikom, računom ali globalno.

Metoda Pot Opis
GET /api/v1/management/proxies Prikaže posredniške strežnike (z ?id= vrne enega; z ?id=&where_used=1 vrne graf dodelitev)
POST /api/v1/management/proxies Ustvari posredniški strežnik — telo je preverjeno z createProxyRegistrySchema
PATCH /api/v1/management/proxies Posodobi posredniški strežnik — telo je preverjeno z updateProxyRegistrySchema (zahteva id)
DELETE /api/v1/management/proxies?id=...&force=1 Izbriše posredniški strežnik (uporabite force=1 za odstranitev dodelitev)
GET /api/v1/management/proxies/assignments Prikaže dodelitve — mogoče jih je filtrirati po proxy_id, scope, scope_id; podajte resolve_connection_id=<id>, da razrešite aktivni posredniški strežnik za povezavo
PUT /api/v1/management/proxies/assignments Dodeli — telo je preverjeno s proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Počisti predpomnilnik razpošiljevalnika
PUT /api/v1/management/proxies/bulk-assign Množično dodeli — telo je preverjeno z bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?})
GET /api/v1/management/proxies/health?hours=24 Združeno stanje posredniških strežnikov (število uspehov/neuspehov, zakasnitev) v časovnem oknu

Preverjanje pristnosti: upravljavska seja/ključ API na vsaki poti (requireManagementAuth).

Poti POST /api/v1/management/proxies/[id]/assignments in POST /api/v1/management/proxies/[id]/health iz opisa opravila zagotavljata zgoraj prikazani enotni poti /assignments in /health — v kodni zbirki ni podrejenih poti za posamezen ID.


Odpornost (razširjeno)

OmniRoute ponuja tri neodvisne mehanizme za začasne napake; spodnje upravljalske končne točke operaterjem omogočajo njihov pregled in preglasitev:

Obseg Shramba stanja Branje Ponastavitev / čiščenje
Odklopnik ponudnika domain_circuit_breakers + v pomnilniku /api/monitoring/health POST /api/resilience/reset
Mirovanje povezave rateLimitedUntil na povezavah ponudnikov /api/rate-limits, /api/providers/[id] (znova se omogoči ob uporabi; počistite prek ponudnikove zahteve PUT)
Zaklep modela Register razpoložljivosti modelov v pomnilniku GET /api/resilience/model-cooldowns DELETE /api/resilience/model-cooldowns

PATCH /api/resilience sprejema preglasitve odklopnika ponudnika pod providerBreaker.oauth in providerBreaker.apikey. Vsak profil podpira degradationThreshold, failureThreshold in resetTimeoutMs; ista polja so na voljo tudi v Nadzorna plošča → Nastavitve → Odpornost.

# Počisti zaklep posameznega modela
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"}'

# Izbriši vse zaklepe
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

Celoten konceptualni opis in privzete vrednosti odklopnikov: glejte CLAUDE.md → »Stanje izvajanja odpornosti«.


Veščine

Ogrodje veščin za razširjanje OmniRoute z izvedljivimi obravnavalniki po meri ter integracijami s tržnicami.

Metoda Pot Opis
GET /api/skills Prikaže nameščene veščine — filtriranje z ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, s paginacijo
GET /api/skills/[id] Pridobi eno veščino
PUT /api/skills/[id] Posodobi veščino (ime, opis, način, shema, obravnavalnik, oznake)
DELETE /api/skills/[id] Odstrani veščino
POST /api/skills/install Namesti veščino iz neobdelanega manifesta — telo: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET /api/skills/executions Prikaže nedavne izvedbe veščin (revizijska sled z vhodi/izhodi/trajanjem)
GET /api/skills/marketplace?q=... Iskanje/seznam priljubljenih veščin s tržnice SkillsMP (zahteva nastavitev skillsmpApiKey)
POST /api/skills/marketplace/install Namesti veščino po ID-ju iz SkillsMP
GET /api/skills/skillssh?q=&limit= Preišče register skills.sh
POST /api/skills/skillssh/install Namesti veščino po ID-ju iz skills.sh

Overjanje: upravljalska seja/ključ API. Poti za iskanje po tržnici sprejemajo upravljalsko overjanje ali ključ API vrste Bearer (isAuthenticated).


Pomnilnik

Trajna shramba pogovornega oziroma dejstvenega pomnilnika, omejena na ključ API/sejo.

Metoda Pot Opis
GET /api/memory Prikaže pomnilniške zapise — ?apiKeyId=, ?type=, ?sessionId=, ?q=, s paginacijo offset/limit ali page/limit
POST /api/memory Ustvari pomnilniški zapis — telo preveri Zod: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET /api/memory/[id] Pridobi en pomnilniški zapis
DELETE /api/memory/[id] Izbriše pomnilniški zapis
GET /api/memory/health Stanje pomnilniškega podsistema (povezljivost s podatkovno zbirko, zaledje vdelav, stanje vektorskega indeksa)

Preverjanje pristnosti: upravljavska seja/ključ API (requireManagementAuth). Naštevanje type: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (glejte MemoryType v src/lib/memory/types.ts).


Strežnik MCP

OmniRoute vključuje vdelan strežnik Model Context Protocol s 3 prenosi (stdio, SSE, streamable-http) in orodji z omejenim obsegom. Spodnje končne točke nadzorne plošče berejo podatke o stanju/reviziji in posredujejo prenose HTTP.

| Metoda | Pot | Opis | | ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- | | GET | /api/mcp/status | Signal delovanja, prenos, stanje povezave, zadnji klic, najpogostejša orodja, stopnja uspešnosti v zadnjih 24 urah | | GET | /api/mcp/tools | Seznam orodij MCP z name, description, scopes, phase, auditLevel, sourceEndpoints | | GET | /api/mcp/sse | Odpre tok SSE za prenos SSE (vrne 503, če je MCP onemogočen ali se prenos ne ujema) | | POST | /api/mcp/sse | Pošlje okvir JSON-RPC prek prenosa SSE | | GET | /api/mcp/stream | Odpre stran SSE prenosa Streamable HTTP (sporočila, ki jih sproži strežnik) | | POST | /api/mcp/stream | Pošlje okvir JSON-RPC prek prenosa Streamable HTTP | | DELETE | /api/mcp/stream | Konča sejo Streamable HTTP | | GET | /api/mcp/audit | Poizveduje po revizijskem dnevniku — ?limit=, ?offset=, ?tool=, ?success=true | false, ?apiKeyId= | | GET | /api/mcp/audit/stats | Združena revizijska statistika (skupne vrednosti, stopnja uspešnosti, povprečno trajanje, najpogostejša orodja) |

Preverjanje pristnosti: prenosa sse/stream upoštevata preverjanje pristnosti, specifično za MCP (ključ API Bearer z obsegom mcp); poti status/tools/audit* je mogoče brati z nadzorne plošče (razen dostopa do gostitelja nadzorne plošče ni potrebno dodatno preverjanje pristnosti).

Oba prenosa HTTP sta omejena z settings.mcpEnabled in settings.mcpTransport — neujemanje prenosa vrne 400, onemogočeno stanje MCP pa vrne 503.


Strežnik A2A

OmniRoute ponuja končno točko A2A (agent-agent) JSON-RPC 2.0 in ovoj REST za pregledovanje oziroma uporabo na nadzorni plošči.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # izbirno, razen če je nastavljen 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"}]
  }
}

Podprte metode (vse so omogočene le, če je omogočen settings.a2aEnabled):

Metoda Opis
message/send Sinhrono izvajanje veščine; vrne {task, artifacts, metadata}
message/stream Pretočno izvajanje istega nabora veščin prek SSE
tasks/get Pridobi opravilo glede na taskId
tasks/cancel Prekliče opravilo glede na taskId

Vgrajene veščine: smart-routing, quota-management, provider-discovery, cost-analysis, health-report.

Kartica agenta

GET /.well-known/agent.json

Vrne javno kartico agenta A2A (ime, opis, zmogljivosti, katalog veščin, shemo preverjanja pristnosti) — javno predpomnjeno za 1h. Preverjanje pristnosti ni potrebno.

Pomožne poti REST

Metoda Pot Opis
GET /api/a2a/status Stanje omogočenosti A2A + statistika opravil + predpomnjen povzetek kartice agenta
GET /api/a2a/tasks Seznam opravil — ?state=submitted|working|completed|failed|cancelled, ?skill=, ?limit= (≤200), ?offset=
POST /api/a2a/tasks (Ni implementirano kot pomožna pot REST — ustvarite prek JSON-RPC message/send)
GET /api/a2a/tasks/[id] Pridobi posamezno opravilo
POST /api/a2a/tasks/[id]/cancel Prekliče opravilo

Preverjanje pristnosti: pomožne poti REST delujejo brez skrbniškega preverjanja pristnosti (berljive za nadzorno ploščo); pot JSON-RPC /a2a uporablja Bearer OMNIROUTE_API_KEY, če je konfiguriran.


Oblak, evalvacije in ocenjevanje

| Metoda | Pot | Opis | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | POST | /api/cloud/auth | Preveri ključ Bearer ter vrne prikrite povezave ponudnikov in vzdevke modelov za odjemalce sinhronizacije z oblakom | | POST | /api/cloud/credentials/update | Posodobi šifrirane poverilnice za ponudnika, sinhroniziranega z oblakom | | POST | /api/cloud/model/resolve | Razreši logični ID modela v konkretnega ponudnika/model z uporabo lokalne usmerjevalne tabele | | GET | /api/cloud/models/alias | Navede vzdevke modelov, kot so na voljo sinhronizaciji z oblakom | | GET | /api/assess | Prebere najnovejše kategorizacije ocenjevanja (po ponudniku/modelu) | | POST | /api/assess | Izvede ocenjevanje — telo: {scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?} | | GET | /api/evals | Navede vgrajene zbirke evalvacij in najnovejše izvedbe | | POST | /api/evals | Sproži izvedbo evalvacije | | POST | /api/evals/suites | Ustvari zbirko evalvacij po meri — telo je preverjeno z evalSuiteSaveSchema | | GET | /api/evals/suites/[id] | Pridobi zbirko evalvacij po meri |

Preverjanje pristnosti: /api/cloud/auth neposredno preveri ključ Bearer ter vrne prikriti ključ in projectId vsake povezave samo za ključ z obsegom manage / admin; druge poti /api/cloud/*, /api/evals/* in /api/assess zahtevajo upravljavsko sejo/ključ API. Zahteva POST za /api/assess uporablja validateBody s shemo obsega diskriminirane unije.


Upravljanje ACP (Agent Client Protocol)

kot podrejene procese. Te končne točke upravljajo zaznavanje agentov ACP in registracijo agentov po meri.

Metoda Pot Opis
GET /api/acp/agents Prikaže vse znane agente CLI (vgrajene in po meri) s stanjem namestitve, različico in binarno datoteko
POST /api/acp/agents Registrira agenta ACP po meri ali osveži predpomnilnik — telo: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} ali {action: "refresh"}
DELETE /api/acp/agents Odstrani agenta ACP po meri — parameter poizvedbe: ?id=<agentId>

Primer odgovora (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
}

Preverjanje pristnosti: Zahtevana je upravljavska seja (piškotek nadzorne plošče auth_token) ali ključ API z upravljavskim obsegom.

Za vse podrobnosti glejte Ogrodje ACP.


Analitika in opazljivost

Končne točke za analitiko v realnem času, namenjene spremljanju usmerjanja, stiskanja in raznolikosti ponudnikov. Te omogočajo delovanje strani /dashboard/analytics/*.

Analitika samodejnega usmerjanja

Metoda Pot Opis
GET /api/analytics/auto-routing Združeni statistični podatki samodejnega usmerjanja: skupno število klicev, porazdelitev strategij, porazdelitev ravni, najpogostejši ponudniki
GET /api/analytics/auto-routing?days=7 Statistični podatki za časovno okno (privzeto 24 ur)

Primer odgovora:

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

Analitika stiskanja

Metoda Pot Opis
GET /api/analytics/compression Združeni statistični podatki stiskanja: prihranjeni žetoni, % prihranka, porazdelitev načinov, uporaba mehanizmov

Primer odgovora:

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

Spremljanje raznolikosti ponudnikov

Metoda Pot Opis
GET /api/analytics/diversity Spremljanje raznolikosti na podlagi Shannonove entropije: preprečuje posamezne točke odpovedi z merjenjem porazdelitve med ponudniki

Primer odgovora:

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

Preverjanje pristnosti: Zahtevana je upravljavska seja ali ključ API z upravljavskim obsegom.


Skrbniške operacije

Končne točke, namenjene izključno skrbnikom, za operativno upravljanje.

Metoda Pot Opis
GET /api/admin/concurrency Pridobi trenutne omejitve sočasnosti (globalne in za posameznega ponudnika)
POST /api/admin/concurrency Posodobi omejitve sočasnosti — telo: {global?: number, perProvider?: Record<string, number>}

Preverjanje pristnosti: Zahteva upravljavsko sejo s skrbniškim obsegom.


Upravljanje orodij CLI

Upravljajte orodja CLI, ki se integrirajo z OmniRoute (antigravity, commandCode, devin-cli itd.). Za celoten seznam glejte Referenco ponudnikov.

Metoda Pot Opis
GET /api/cli-tools/all-statuses Stanje vseh orodij CLI (nameščenost, različica, čas zadnje zaznave)
GET /api/cli-tools/status Podrobnosti stanja enega orodja CLI (poizvedba ?tool=)
POST /api/cli-tools/apply Zapiše ustvarjeno konfiguracijo orodja (dryRun prikaže predogled; 422 + containerEphemeralTarget pri izvajanju v vsebniku; migration navede starejši Codex YAML)
GET /api/cli-tools/backups Prikaže varnostne kopije konfiguracij orodij CLI
POST /api/cli-tools/backups Ustvari varnostno kopijo konfiguracij vseh orodij CLI
POST /api/cli-tools/backups Obnovitev: ista končna točka z {tool, backupId} v telesu obnovi navedeno varnostno kopijo
GET /api/cli-tools/antigravity-mitm Stanje posredniškega strežnika MITM Antigravity (orodje CLI »antigravity-mitm«)
POST /api/cli-tools/antigravity-mitm/alias Konfigurira vzdevke antigravity-mitm

Preverjanje pristnosti: Zahteva upravljavsko sejo.


Veščine agentov

Upravljajte veščine agentov UI (podobno OpenAI-jevim GPT-jem po meri, vendar za agente).

Metoda Pot Opis
GET /api/agent-skills Prikaže vse veščine agentov (vgrajene in tiste po meri)
GET /api/agent-skills/[id] Pridobi določeno veščino agenta
POST /api/agent-skills Ustvari veščino agenta po meri — telo: {name, description, prompt, model?, temperature?}
PUT /api/agent-skills/[id] Posodobi veščino agenta po meri
DELETE /api/agent-skills/[id] Izbriše veščino agenta po meri
GET /api/agent-skills/[id]/raw Pridobi neobdelani poziv in metapodatke (brez izvajanja)
POST /api/agent-skills/generate Z umetno inteligenco ustvari novo veščino iz opisa v naravnem jeziku

Preverjanje pristnosti: Zahteva upravljavsko sejo ali ključ API z upravljavskim obsegom.


Upravljanje predpomnilnika

Upravljajte semantični predpomnilnik in predpomnilnik sklepanja.

Metoda Pot Opis
GET /api/cache Pregled predpomnilnika: skupno število vnosov, delež zadetkov, velikost na disku
GET /api/cache/entries Seznam predpomnjenih vnosov (s paginacijo)
DELETE /api/cache/entries Brisanje vnosov predpomnilnika (filtriranje po parametrih poizvedbe)
GET /api/cache/stats Podrobna statistika predpomnilnika (po ponudniku in modelu)
GET /api/cache/reasoning Stanje predpomnilnika sklepanja (za ponovno predvajanje sklepanja)
DELETE /api/cache/reasoning Brisanje predpomnilnika sklepanja — parametri poizvedbe: ?toolCallId=<id> (posamezen), ?provider=<p> ali brez parametrov (vsi)

Preverjanje pristnosti: Zahteva upravljavsko sejo.


Pomnilniški sistem

Upravljajte trajni pomnilnik (FTS5 + vektorske vložitve).

Metoda Pot Opis
GET /api/memory Seznam vnosov v pomnilniku (filtriranje po obsegu, vrsti in iskalni poizvedbi)
POST /api/memory Ustvarjanje novega vnosa v pomnilniku — telo: {scope, type, content, metadata?}
GET /api/memory/[id] Pridobivanje določenega vnosa iz pomnilnika
PUT /api/memory/[id] Posodobitev vnosa v pomnilniku
DELETE /api/memory/[id] Brisanje vnosa iz pomnilnika
GET /api/memory?q= Iskanje po pomnilniku (FTS5 + vektorji) — statistika je vključena v isti odgovor

Preverjanje pristnosti: Zahteva upravljavsko sejo ali API-ključ z upravljavskim obsegom.


Spletni kavlji

Upravljajte naročnine spletnih kavljev na dogodke.

Metoda Pot Opis
GET /api/webhooks Seznam vseh naročnin spletnih kavljev
POST /api/webhooks Ustvarjanje naročnine spletnega kavlja — telo: {url, events[], secret?, active?}
GET /api/webhooks/[id] Pridobivanje določene naročnine spletnega kavlja
PUT /api/webhooks/[id] Posodobitev naročnine spletnega kavlja
DELETE /api/webhooks/[id] Brisanje naročnine spletnega kavlja
GET /api/webhooks/[id]/deliveries Seznam zgodovine dostav spletnega kavlja (dnevnik uspehov/neuspehov)
POST /api/webhooks/[id]/test Pošiljanje preskusnega dogodka spletnemu kavlju

Preverjanje pristnosti: Zahteva upravljavsko sejo.

Za vse vrste dogodkov glejte Ogrodje spletnih kavljev.


Ogrodje veščin

Upravljajte veščine (ogrodje za agentne razširitve).

Metoda Pot Opis
GET /api/skills Prikaže vse nameščene veščine (vgrajene in prilagojene)
POST /api/skills/install Namesti veščino iz lokalne poti ali URL-ja
DELETE /api/skills/[id] Odstrani veščino
PUT /api/skills/[id] Omogoči ali onemogoči veščino — telo: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST /api/skills/executions Izvede veščino — telo: {skillName, apiKeyId, input?, sessionId?}
GET /api/skills/executions Prikaže zgodovino izvajanj za vse veščine (filtriranje z ?apiKeyId=)

Preverjanje pristnosti: Zahtevana je upravljavska seja ali ključ API z upravljavskim obsegom.

Za vse podrobnosti glejte Ogrodje veščin.


Vtičniki

Upravljajte vtičnike OmniRoute (razširitve tretjih oseb).

Metoda Pot Opis
GET /api/plugins Prikaže nameščene vtičnike
POST /api/plugins/marketplace/install Namesti vtičnik iz tržnice
DELETE /api/plugins/[name] Odstrani vtičnik
POST /api/plugins/[name]/activate Aktivira vtičnik
POST /api/plugins/[name]/deactivate Deaktivira vtičnik
GET /api/plugins/[name]/config Pridobi konfiguracijo vtičnika
PUT /api/plugins/[name]/config Posodobi konfiguracijo vtičnika

Preverjanje pristnosti: Zahtevana je upravljavska seja.

Za vse podrobnosti glejte Ogrodje vtičnikov.


Senčno usmerjanje

Senčna primerjava oziroma primerjava A/B ponudnikov ni samostojen vmesnik REST — konfigurira se prek kombiniranega usmerjanja (glejte Samodejno kombiniranje). Primerjalne metrike za posamezno kombinacijo zagotavlja GET /api/combos/metrics.


Zaščitni mehanizmi

Preglejte zaščitne mehanizme med izvajanjem (zaznavanje osebno določljivih podatkov, zaznavanje vbrizgavanja pozivov, premoščanje za vidne modele). Zaščitni mehanizmi se izvajajo pri vsaki zahtevi; posamezen klic jih lahko izključi z glavo zahteve x-omniroute-disabled-guardrails — trajna možnost za omogočanje ali onemogočanje ne obstaja.

Metoda Pot Opis
GET /api/guardrails Prikaže registrirane zaščitne mehanizme in njihovo stanje (ime / omogočeno / prednost)
POST /api/guardrails/test Poskusno izvede cevovod pred klicem nad vzorčnim vhodom — telo: {input, disabledGuardrails?}

Preverjanje pristnosti: Zahtevana je upravljavska seja.

Za vse podrobnosti glejte Varnost > Zaščitni mehanizmi.



Preverjanje pristnosti

Za štiri skupine poverilnic (seja nadzorne plošče, lokalni žeton CLI, dostopni žeton oma_live_…, API-ključ z obsegom za upravljanje) in razlike med njimi ter ključi za sklepanje glejte Preverjanje pristnosti za upravljanje.

  • Poti nadzorne plošče (/dashboard/*) uporabljajo piškotek auth_token
  • Prijava uporablja shranjeno zgoščeno vrednost gesla; kot nadomestna možnost se uporabi INITIAL_PASSWORD
  • Nastavitev requireLogin je mogoče preklopiti prek /api/settings/require-login
  • Poti /v1/* lahko zahtevajo API-ključ Bearer, ko je REQUIRE_API_KEY=true
  • »žeton za upravljanje« / »API-ključ z obsegom za upravljanje« v tej referenčni dokumentaciji pomeni eno od skupin iz navedenega vodnika — ne pa nedoločene dodatne vrste skrivnosti

Prelomna sprememba (v3.8.0) — /api/v1/agents/tasks/* in končne točke za upravljanje obdobja mirovanja zdaj zahtevajo preverjanje pristnosti za upravljanje (piškotek auth_token nadzorne plošče ali API-ključ z obsegom za upravljanje). Odjemalci, ki so te poti prej klicali brez preverjanja pristnosti, bodo prejeli odgovor 401 Unauthorized. Glejte potrditev 588a0333 (fix(auth): require management auth for agent and cooldown APIs).