188 KiB
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: 🇺🇸 Angleščina | 🇪🇹 Amharščina | 🇸🇦 Arabščina | 🇦🇿 Azerbajdžanščina | 🇧🇬 Bolgarščina | 🇧🇩 Bengalščina | 🇧🇦 Bosanščina | 🇨🇿 Češčina | 🇩🇰 Danščina | 🇩🇪 Nemščina | 🇬🇷 Grščina | 🇪🇸 Španščina | 🇪🇪 Estonščina | 🇮🇷 Perzijščina | 🇫🇮 Finščina | 🇫🇷 Francoščina | 🇮🇪 Irščina | 🇮🇳 Gudžaratščina | 🇳🇬 Havščina | 🇮🇱 Hebrejščina | 🇮🇳 Hindijščina | 🇭🇷 Hrvaščina | 🇭🇺 Madžarščina | 🇦🇲 Armenščina | 🇮🇩 Indonezijščina | 🇳🇬 Igbojščina | 🇮🇹 Italijanščina | 🇯🇵 Japonščina | 🇬🇪 Gruzijščina | 🇰🇭 Kmerščina | 🇮🇳 Kanadščina | 🇰🇷 Korejščina | 🇱🇹 Litovščina | 🇱🇻 Latvijščina | 🇮🇳 Malajalamščina | 🇮🇳 Maratščina | 🇲🇾 Malajščina | 🇲🇹 Malteščina | 🇲🇲 Burmanščina | 🇳🇵 Nepalščina | 🇳🇱 Nizozemščina | 🇳🇴 Norveščina | 🇮🇳 Odijščina | 🇮🇳 Pandžabščina | 🇵🇭 Filipinščina | 🇵🇱 Poljščina | 🇵🇹 Portugalščina (Portugalska) | 🇧🇷 Portugalščina (Brazilija) | 🇷🇴 Romunščina | 🇷🇺 Ruščina | 🇱🇰 Sinhala | 🇸🇰 Slovaščina | 🇸🇮 Slovenščina | 🇷🇸 Srbščina | 🇸🇪 Švedščina | 🇰🇪 Svahili | 🇮🇳 Tamilščina | 🇮🇳 Telugijščina | 🇹🇭 Tajščina | 🇹🇷 Turščina | 🇺🇦 Ukrajinščina | 🇵🇰 Urdu | 🇺🇿 Uzbeščina | 🇻🇳 Vietnamščina | 🇳🇬 Jorubščina | 🇨🇳 Kitajščina (poenostavljena) | 🇹🇼 Kitajščina (tradicionalna)
Osrednji referenčni priročnik za API OmniRoute. Zajema javni del /v1 in najpogosteje uporabljane skrbniške končne točke; strojno berljiva datoteka docs/openapi.yaml in drevo poti v imeniku src/app/api/ sta izčrpna vira.
Za osredotočen protokol, združljiv z OpenAI, in matriko zmožnosti ponudnikov glejte
OPENAI_COMPATIBILITY.md.
Vsaka uvedba streže lastno kopijo specifikacije na naslovu /openapi.yaml, ki se med gradnjo ustvari iz datoteke docs/openapi.yaml. Vsebuje različico gradnje in relativni URL strežnika (./), zato zahteve ostanejo na gostitelju, ki je posredoval dokument. Orodje, ki uvozi preneseno datoteko, nima takega gostitelja, zato je treba osnovni URL nastaviti ročno.
Kazalo
- Dokončanja klepeta
- Izključne najemne pogodbe za upravljane seje
- Vdelave
- Ustvarjanje slik
- OCR dokumentov
- Seznam modelov
- Manifest vtičnika ponudnika
- Končne točke združljivosti
- API za datoteke
- API za paketno obdelavo
- API za iskanje
- Pretakanje WebSocket
- Kvote in poročanje o težavah
- Semantični predpomnilnik
- Združljivost upravljanja CLIProxyAPI
- Nadzorna plošča in upravljanje
- Upravljanje kombinacij
- Spletni kavlji
- Registrirani ključi (samodejno upravljanje)
- Protokol agentov
- Upravljalni posredniški strežniki
- Odpornost (razširjeno)
- Veščine
- Pomnilnik
- Strežnik MCP
- Strežnik A2A
- Oblak, evalvacije in ocenjevanje
- Obdelava zahtev
- Preverjanje pristnosti
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 obidete predpomnilnik |
x-omniroute-no-memory |
Zahteva | Nastavite na true, da za to zahtevo preskočite vstavljanje pomnilnika in veščin (zrcali nastavitev no-cache; prepreči režijske stroške žetonov/stroškov na klic) |
X-OmniRoute-Progress |
Zahteva | Nastavite na true za dogodke napredka |
X-Session-Id |
Zahteva | Ključ lepljive seje za afiniteto zunanje 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 določi klicatelj (vpliva tudi na pomnilnik). Če je prisotna, se dobesedno zapiše v call_logs.session_tag za pripis stroškov posamezni seji (#8249) — če je ni, se nikoli ne ustvari samodejno |
Idempotency-Key |
Zahteva | Ključ za odstranjevanje podvojitev (5-sekundno okno) |
X-Request-Id |
Zahteva | Alternativni ključ za odstranjevanje podvojitev |
x-omniroute-connection |
Zahteva | Pripne zahtevo za en model na eno povezavo ponudnika (račun) glede na njen ID — glejte Pripenjanje računa na zahtevo |
X-OmniRoute-Cache |
Odgovor | HIT ali MISS (brez pretakanja) |
X-OmniRoute-Idempotent |
Odgovor | true, če je bila zahteva odstranjena kot podvojena |
X-OmniRoute-Progress |
Odgovor | enabled, če je sledenje napredku vklopljeno |
X-OmniRoute-Session-Id |
Odgovor | Učinkoviti ID seje, ki ga uporablja OmniRoute |
X-OmniRoute-Request-Id |
Odgovor | ID za korelacijo zahteve (ko je znan) |
X-OmniRoute-Version |
Odgovor | Različica gradnje OmniRoute (vedno prisotna) |
X-OmniRoute-Cost-Saved |
Odgovor | Znesek v USD, ki se mu je predpomnilnik izognil ob zadetku (samo zadetki predpomnilnika) |
X-OmniRoute-Decision |
Odgovor | Sled usmerjanja: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> je kombinirana strategija ali single za zahtevo brez kombiniranja) — vedno prisotna v odgovorih ob zaključku |
Opomba za Nginx: če se zanašate na glave s podčrtaji (na primer
x_session_id), omogočiteunderscores_in_headers on;.
Pripenjanje računa na zahtevo
Ko ima ponudnik več povezav (računov ali ključev), OmniRoute običajno izbere eno
s svojo strategijo izbire računa. Zahteva lahko namesto tega pripne eno 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 ploščico z ID-jem
xxxxxxxx…v vrstici povezave — s tem kopirate celoten ID povezave. - Katere zahteve ga upoštevajo. Zahteve za posamezni model (
provider/model) na/v1/chat/completions,/v1/messagesin/v1/responses. Kombinacije glavo prezrejo: pripnite račun za vsak korak kombinacije prek njegove lastne povezave. - Pripenjanje je strogo, ne le prednostna izbira. Pripeta povezava se uporablja izključno. Napaka znotraj zahteve zabeleži ohlajanje računa, vendar ne preklopi na sorodni račun istega ponudnika.
- Ohlajanje in kvota sprostita pripenjanje. Medtem ko se pripeta povezava ohlaja, ima izčrpano kvoto ali jo pravilnik kvot blokira, se poznejše zahteve vrnejo na druge povezave ponudnika, natanko tako kot promet brez pripenjanja.
- Neznani ali onemogočeni ID-ji povzročijo napako. ID, ki ni v aktivnem naboru ponudnika (izbrisan, deaktiviran ali pripada drugemu ponudniku), ne pusti nobenega upravičenega računa, zato zahteva spodleti, namesto da bi bila tiho usmerjena drugam.
Claude Code pošilja glave po meri prek ANTHROPIC_CUSTOM_HEADERS. Vstavite jo v blok
env datoteke ~/.claude/settings.json ali v projektno datoteko .claude/settings.json, da pripnete drug račun za posamezen projekt:
{
"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, ali povezave ni v naboru).
Glave telemetrije stroškov: uspešni odgovori brez pretakanja vsebujejo tudi nabor
X-OmniRoute-*za telemetrijo stroškov —X-OmniRoute-Response-Cost(v USD, natančno 10 decimalnih mest;0.0000000000za brezplačno storitev ali storitev brez cene),X-OmniRoute-Tokens-In/X-OmniRoute-Tokens-Out,X-OmniRoute-Model,X-OmniRoute-Provider,X-OmniRoute-Latency-Ms,X-OmniRoute-Cache-HitinX-OmniRoute-Fallback-Attempts(samo, kadar je vrednost > 0), polegX-OmniRoute-Request-IdinX-OmniRoute-Version. Te se pošiljajo pri dokončanjih klepeta,/v1/responses,/v1/messages, in predstavnostnih končnih točkah —/v1/embeddings,/v1/images/generations,/v1/audio/speech,/v1/audio/transcriptions,/v1/rerank,/v1/videos/generations,/v1/music/generationsin/v1/moderations(vedno s stroškom0). Strošek predstavnosti se izračuna glede na posamezno modalnost (na sliko, sekundo, znak ali iskalno enoto), kadar so cene na voljo, sicer je0(ob napaki se zahteva vseeno nadaljuje).
Semantika stroškov zadetkov predpomnilnika: pri zadetku semantičnega predpomnilnika (
X-OmniRoute-Cache-Hit: true) se klic navzgornje storitve ne izvede, zato jeX-OmniRoute-Response-Cost0.0000000000(inkrementalni strošek zagotavljanja zadetka). Izvirni/predvideni strošek je ločeno naveden vX-OmniRoute-Cost-Saved. Odjemalci za obračunavanje naj seštevajoX-OmniRoute-Response-Cost(zadeti vnosi nič ne stanejo); analitika predpomnilnika lahko združiX-OmniRoute-Cost-Saved.
Ekskluzivni upravljani najemi sej
Ekskluzivni upravljani najem sej je neobvezna usmerjevalna pogodba, neodvisna od odjemalca: en aktivni lastnik ima v lasti eno upravičeno povezavo OmniRoute. Ne najema modela, ne zahteva OAuth, ne identificira določenega odjemalca in ne zahteva določenega ponudnika.
Ključ API-ja za preverjanje pristnosti mora imeti obseg lease:exclusive in izrecno neprazen
seznam allowedConnections. Meja mutacije podatkovne zbirke 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 odgovori za pridobitev, podaljšanje in sprostitev razkrivajo časovne žige, state in natančno pozitivno
generation, nikoli pa ne razkrivajo izbrane povezave ali poverilnic. Pri podaljšanju in sprostitvi se
generacija posreduje v telesu JSON:
{ "action": "renew", "generation": 1 }
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
Aktivni lastnik najema lahko izrecno zahteva metapodatke za prikaz, varne z vidika zasebnosti, 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 neobvezno dejanje stanja je v eni transakciji podatkovne zbirke omejeno z neprosojnim lastnikom,
preverjenim upravljanim ključem API in natančno aktivno generacijo. displayName je samo obrezano konfigurirano
ime povezave; kadar varno konfigurirano ime ne obstaja, je null. OmniRoute nikoli ne nadomesti imena z
e-poštnim naslovom ali ustvarjeno identiteto računa. Vrednost ponudnika je neobčutljiva oznaka za prikaz in nikoli
ustvarjeni identifikator združljivega ponudnika. Poverilnice, žetoni, piškotki, neobdelani ID-ji povezav ali ključev
API, zgoščene vrednosti lastnikov, skrivnosti za omejevanje in notranji podatki o usmerjanju so izključeni.
Iskanja z napačnim ključem, napačnim lastnikom, zastarelo generacijo, manjkajočim, poteklim, sproščenim ali
razveljavljenim stanjem vsa vrnejo isto napako 409 LEASE_FENCE_STALE brez metapodatkov o povezavi. Odjemalec,
ki je prejel odgovor o čakanju na zmogljivost, nima aktivne vezave, ki bi jo lahko pregledal. Ko usmerjanje preklopi
aktivni najem, ista generacija ostane veljavna, stanje pa atomsko vrne novo vezavo, nikoli stare. Obstoječi odjemalci
ostanejo nespremenjeni, saj odgovori za pridobitev, podaljšanje, sprostitev in čakanje ohranijo svoje prejšnje oblike.
Ta strežniška pogodba ne spremeni standardnega OpenAI Codex /status. Standardni Codex trenutno poroča o svojem
ponudniku modela ter vgrajenem stanju preverjanja pristnosti in računa, vendar ne izrisuje poljubnih metapodatkov
računov po meri ponudnika; poznejša integracija odjemalca mora poklicati to dejanje in se odločiti, kako bo prikazala
connection.displayName.
Vsak upravljani zahtevek za izvajanje sklepanja nato posreduje obe nadzorni glavi:
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
Natančni lastnik, generacija, aktivna povezava in preverjeni ključ API se preverijo neposredno pred vsakim podprtim poskusom pri izvornem ponudniku. Ponovna uporaba lastnika in generacije z drugim ključem ne uspe, tudi če ta ključ dovoljuje isto povezavo. Neobdelani lastniki se ne shranjujejo, beležijo, hranijo v posnetku zahteve ali posredujejo izvornemu ponudniku.
Začasna zasedenost 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 odgovor pomeni samo, da množica običajno upravičenih povezav ni bila prazna in da je vsako prosto kandidatko zasedal tuji aktivni najem. Nepodprti modeli/ponudniki, neusklajenost pravilnika, ohlajanje, kvota, stanje zdravja in druge običajne napake upravičenosti ohranijo svoje obstoječe odgovore OmniRoute.
x-omniroute-compression
Preglasitev načrta stiskanja za posamezno zahtevo. Najvišja prednost — preglasi preglasitev kombinacije usmerjanja, aktivni profil, samodejni sprožilec in ploščni privzeti profil. Vrednosti:
| Vrednost | Učinek |
|---|---|
off |
Za to zahtevo ni stiskanja. |
default |
Privzeti profil, izpeljan iz plošče (prezre aktivni profil). Izgubni mehanizmi ostanejo izključeni. |
safe |
Samo odstranjevanje dvojnikov in združevanje presledkov. |
allow-lossy |
Za to zahtevo ohrani načrt upravljavca, vključno s povzetki in preoblikovanjem sloga. |
engine:<id> |
En sam mehanizem, ko je omogočen, npr. engine:rtk. Izrecna vključitev tega mehanizma za posamezno zahtevo. |
<combo> |
Poimenovana kombinacija, najprej primerjana po imenu (brez upoštevanja velikosti črk), nato po ID-ju. |
Opombe:
- Neznane vrednosti se prezrejo (zahteva ni nikoli zavrnjena); razreševanje se nadaljuje po običajnem prednostnem vrstnem redu upravljavca.
- Če ima več kombinacij isto ime, za deterministično ujemanje posredujte id kombinacije.
- Kombinacije, katere ime je
offalidefault, ni mogoče izbrati po imenu (ti ključni besedi se interpretirata najprej); na takšno kombinacijo se sklicujte z njenim ID-jem. - Glavno stikalo stiskanja je stroga omejitev: ko je stiskanje globalno onemogočeno, ga ta glava ne more omogočiti.
Uporabljeni načrt je vrnjen v glavi odgovora:
X-OmniRoute-Compression: <mode>; source=<source>
kjer je <source> ena od vrednosti 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 so v obliki provider/model (primer: jina-ai/jina-embeddings-v5-omni-small). Tudi goli ID-ji Jina modelov, ki se pojavijo v registru (na primer jina-embeddings-v5-text-small, jina-reranker-v3.5), se razrešijo. Jina embed/rerank/classify/segment najprej uporabljajo poverilnice nadzorne plošče jina-ai; JINA_AI_API_KEY je nadomestna možnost samo, če ključ nadzorne plošče ne obstaja. Kartica jina-reader je namenjena samo Readerju / r.jina.ai (POST /v1/web/fetch) in nikoli ne zagotavlja vdelav ali ponovnega razvrščanja.
Modeli registra, ki oglašujejo podporo za večmodalnost, sprejemajo tudi do 32 strukturiranih elementov, neodvisnih od ponudnika. Vrste predstavnostnih elementov so text, image, audio, video in document. Njihov 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 družinski vzdevek jina-ai/jina-embeddings-v5-omni → omni-small) sprejema tudi izvorne dokumente Jina EmbeddingsV5Request in jih posreduje nespremenjene 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 neobdelani base64. OmniRoute teh objektov ne pretvori v nize in ne pridobiva izvornih URL-jev slik — Jina sama pridobi javne predstavnosti. 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 predstavnosti morajo biti javni 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 vstavijo v zahtevo, preden se ta pošlje ponudniku. Jina izvorni elementi{image:"https://..."}se po istem preverjanju javnega HTTPS posredujejo nespremenjeni; URL pridobi Jina. - Vgrajena predstavnost 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, določen s ključem predstavnosti (
text/image/audio/video/pdf), pri čemer se za vgrajeno predstavnost uporabijo podatkovni URI-ji; en vektor na element najvišje ravni. - Družina Gemini Embedding 2: ena matrika najvišje ravni postane ena izvorna zahteva
models/{model}:embedContentzcontent.parts(textaliinline_data). - llama.cpp (
llama-cpp/<model>, kateri koli model, ki ga je naložil lokalni strežnik): kanonični elementitextpostanejo navadni nizi, elementiimage/audio/videopa vsak svoj objekt{"content": [part]}, pri čemer se uporabijo deli vsebine za klepet strežnika llama-server (image_url,input_audioz oblikamiwav/mp3/flac,input_video) z vgrajenimi podatki; en vektor na element najvišje ravni. Strežnik mora delovati z možnostma--embedding --mmproj …; brez projektorja sam zavrne predstavnost.documentni podprt. - Neznani/dinamični modeli brez izrecnih metapodatkov o modalnostih zavrnejo strukturirani vnos 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 modelov/modalnosti vrnejo HTTP 400, namesto da bi se element prisilno pretvoril. Dodatna polja, ki niso vhodna, se pri podedovanih zahtevah z nizi/žetoni še naprej posredujejo nespremenjena.
# Seznam vseh modelov 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": "A beautiful sunset over mountains",
"size": "1024x1024"
}
Razpoložljivi ponudniki vključujejo OpenAI (GPT slika 2), xAI (Grok slika), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana,OpenRouter ,ZenMux , SD WebUI (lokalno), ComfyUI (lokalno).
n vrne slike n v data[]. Ponudniki, katerih navzgor API vrne eno sliko na klic (Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik, NVIDIA NIM, Cloudflare Workers AI), prejmejo n ločene navzgornje klice, največ 4 v letu. Fiksni seed je izravnan z indeksom klica (seed, seed + 1, …), zato se slike razlikujejo, vendar ostanejo ponovljive. n je omejen na 10. Zahteva kot celota ne uspe, če kateri koli klic ne uspe. Seznam razpršenih formatov je SINGLE_IMAGE_FANOUT_FORMATS in open-sse/handlers/imageGeneration/fanOut.ts.
ZenMux ponovno uporabi obstoječo povezavo API-ključa in sprejme predpone zenmux/ ali zm/ :
zenmux/openai/gpt-image-2uporablja ZenMux-jeve slike OpenAI API. Možnosti vključujejosize,quality,n,output_format,output_compression,backgroundinresponse_format.- Drugi založniki, kot je
zm/meta/muse-image-1.0, uporabljajo ZenMux-jevo končno točko Vertex AI:predict.nse preslika vsampleCount,aspect_ratiovaspectRatioinimage_size(1K,2K,4K) vsampleImageSize. Pikselsizezagotavlja samo razmerje stranic, ne pa tudi zajamčenih dimenzij slikovnih pik. Podprta razmerja, ločljivosti in števila se razlikujejo glede na model. zm/inclusionai/ming-image-0.1-designizbere svoje dimenzije. Izpustitesize,aspect_ratioinimage_size; eksplicitne vrednosti vrnejo HTTP 400. PNG, JPEG in WebP lahko zahtevate zoutput_format.
Ta integracija podpira ustvarjanje besedila v sliko, ne pa urejanja referenčne slike. Izhod vozlišč je normaliziran na data[].b64_json; response_format: "url" vrne navzgor HTTPS URL ali podatke base64 URL, ko so na voljo samo bajti slike. izhodi Empty/filtered vrnejo napako namesto praznega uspeha. Dostop do modela je odvisen od računa ZenMux. Oglejte si slike ZenMux Vertex API in OpenAI API.
Povezava za prijavo Microsoft 365 Copilot služi copilot-m365-web/m365-copilot-image prek Copilot-jevega vgrajenega orodja za slike: en obrat Copilot na sliko (n 1–4), size usmerja samo orientacijo in slike vrne v vrstici (b64_json ali podatkovni URL za response_format: "url"). Glej Microsoft 365 Copilot.
# List all image models
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 samostojni mistral-ocr-latest) |
Sinhrono — odgovor se vrne neposredno iz enega nadrejenega klica. |
azure-document-intelligence |
prebuilt-read |
azure-document-intelligence/prebuilt-read |
Asinhroni nadrejeni klic (analyze + polling) — 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 preverjanje pristnosti/URL glejte spodaj. |
Vsi trije ponudniki odgovorijo z istim telesom v obliki Mistrala:
{
"pages": [{ "index": 0, "markdown": "# Extracted text..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
Potek preverjanja stanja za Azure Document Intelligence
API analyze storitve Azure Document Intelligence je asinhron: začetna zahteva vrne glavo
Operation-Location namesto telesa, rezultat pa je treba pridobiti s preverjanjem stanja. Upravljalnik
(open-sse/handlers/ocr.ts) preverja ta URL vsako sekundo, največ 30-krat, hitro prekine (in
ne nadaljuje preverjanja) ob odgovoru preverjanja stanja, ki ni ok, ali ob stanju "failed",
ter vrne 504, če operacija po izteku dovoljenega števila poskusov še vedno poteka. Končni odgovor
Azure se pred vrnitvijo klicatelju normalizira v isto obliko pages/markdown, kot jo uporablja
Mistral, zato odjemalski kodi ni treba posebej obravnavati ponudnika.
Preverjanje pristnosti in razreševanje končne točke Vertex AI DeepSeek OCR
vertex-deepseek-ocr ponovno uporabi isto preverjanje pristnosti Vertex AI, ki ga OmniRoute že podpira
za promet klepeta/slik (open-sse/executors/vertex.ts): ključ API povezave je bodisi poverilnica
JSON računa storitve (zamenjana za kratkotrajni žeton za dostop OAuth prek toka JWT-bearer)
bodisi že izdan žeton za dostop OAuth, ki se uporabi nespremenjen. URL nadrejene končne točke je
generična partnerska končna točka Vertex openapi/chat/completions, ustvarjena iz projekta in
regije povezave — izrecno podana providerSpecificData.project/providerSpecificData.region ima
vedno prednost; sicer se projekt izpelje iz project_id JSON računa storitve, regija pa je privzeto
us-central1. Obe razrešitvi potekata v open-sse/handlers/ocr.ts
(resolveVertexOcrAccessToken, resolveVertexOcrBaseUrl), uporabljata pa ju
src/app/api/v1/ocr/route.ts pred posredovanjem v handleOcr.
Seznam modelov
GET /v1/models
Authorization: Bearer your-api-key
→ Vrne vse modele za klepet, vdelave in slike ter kombinacije v obliki OpenAI
Cene modelov (pricing)
Vnos vsebuje objekt pricing, ko OmniRoute pozna ceno modela. Cena izvira iz cenika, ki ga
uporablja obračun stroškov: vgrajenih privzetih vrednosti, sinhroniziranih cen in
preglasitev, nastavljenih prek /api/pricing. To so cene po ceniku, zato ponudniki naročnin
prav tako prikazujejo ceno na žeton.
"pricing": {
"prompt": "0.000005",
"completion": "0.000025",
"input_cache_read": "0.0000005",
"input_cache_write": "0.00000625",
"input": 5,
"output": 25,
"cached": 0.5,
"cache_creation": 6.25
}
| Polja | Enota | Opombe |
|---|---|---|
prompt, completion, input_cache_read, input_cache_write |
USD na žeton, decimalni niz | Združljivo z OpenRouter, nikoli v eksponentnem zapisu. Polji za predpomnilnik se pojavita samo, ko obstaja cena predpomnilnika. |
input, output, cached, cache_creation |
USD na 1M žetonov, število | Polja iz prejšnjih različic kataloga, ohranjena za obstoječe odjemalce. reasoning in long_context se prav tako pojavita, ko ju vsebuje cenovna vrstica. |
- Kombinacije vsebujejo ceno svojega prvega vidnega cilja. Vgrajene kombinacije
auto/*izberejo cilj ob času zahteve, zato nimajopricing. - Brezplačni modeli prikazujejo
"0"(in0), ko je njihova cena nič. Model brez cenovne vrstice prav tako prikazuje"0", ko ga katalog označuje kot brezplačnega (free: true) ali ko je naveden v vgrajenem katalogu brezplačnih modelov. - Neznana cena: vnos nima ključa
pricing. - Ponudniki z obračunom po kreditih (na primer Kiro) obračunavajo na zahtevo in ne po žetonih. Njihovi vnosi ohranijo številska polja na 1M, ki so jih imeli prej, in ne vsebujejo nizov s ceno na žeton.
- Različice (ID-ji z naporom sklepanja, vzdevki brez razmišljanja ter zrcala odkrivanja in prehoda) kopirajo ceno modela, na katerega usmerjajo.
- Polja vsebujejo samo osnovne cene. Stopnje za dolg kontekst (številsko polje
long_context) in množilniki ravni storitve (na primer Codex fast ali flex) ne spremenijopromptalicompletion. - Objekt je enak za vse načine preverjanja pristnosti, vključno z zahtevo v slogu Anthropic z
x-api-keyinanthropic-version(odgovor ostane{ "object": "list", "data": [...] }). Implementacija:src/app/api/v1/models/catalogPricing.ts.
Predpone ID-jev modelov (?prefix=)
Večina modelov je oglaševana z predpono ponudnika. Katero predpono prejmete, določa
zastavica funkcije MODELS_CATALOG_PREFIX_MODE, preglasite pa jo lahko za posamezno
zahtevo s parametrom poizvedbe — uporabno za odjemalca, ki želi čist seznam, ne da bi
spreminjal nastavitev strežnika za vse druge:
GET /v1/models?prefix=alias # en ID na model — predpona kratkega 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 | Ustvari | Opombe |
|---|---|---|
dual |
cc/claude-sonnet-4-6 in claude/claude-sonnet-4-6 |
Privzeto. Oba ID-ja usmerjata na isti model; ohranjena sta zato, da konfiguracije odjemalcev, ki so imele trdo kodirano katero koli obliko, še naprej delujejo. Katalog se približno podvoji. |
alias |
cc/claude-sonnet-4-6 |
En vnos na model. Ponudniki brez ločenega vzdevka še vedno ustvarijo 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/…) tukaj prav tako ustvarijo svoj enotni ID, zato se nič ne izgubi. |
Zrcalo v načinu dual je mogoče prepoznati tudi brez parametra poizvedbe: vsebuje polje
parent, ki kaže na primarni ID.
Odjemalci, ki izrisujejo izbirnik modelov, naj zahtevajo ?prefix=alias — to počne
razširitev OmniCopilot za VS Code.
Filtri odkrivanja (?capability=, ?min_context=, ?kind=, ?q=)
GET /v1/models podpira neobvezne filtre odkrivanja. Brez katerega koli od njih ostane
odgovor nespremenjen. Zožijo katalog, ki ga klicatelj že vidi (dovoljenja ključa API se
uporabijo najprej), in se izvedejo pred ostranjevanjem v slogu OpenAI z limit / after:
GET /v1/models?capability=vision&capability=tool_calling # vsaka navedena zmožnost mora biti true
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding # katalog `type`; vrstice brez njega so `chat`
GET /v1/models?q=sonnet&limit=10 # ujemanje brez razlikovanja velikosti črk v ID-ju ali imenu
| Parameter | Vrednosti |
|---|---|
capability |
attachment, reasoning, structured_output, temperature, thinking, tool_calling, vision |
min_context |
ne-negativno 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 ne-negativno celo število (na primer 1.5),
vrne HTTP 400, sporočilo pa vsebuje veljavne vrednosti. Implementacija:
src/app/api/v1/models/catalogFilters.ts.
Kratek seznam modelov (POST /v1/models/query)
POST /v1/models/query vrne kratek, determinističen seznam iz istega kataloga, z enakim
preverjanjem pristnosti in vidnostjo glede na 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 sprejemata matriko ali z vejicami ločen
niz; max_output se primerja z max_output_tokens. Rezultati so razvrščeni po owned_by in 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.
Posamično skriti modeli za klepet
Model, označen kot Skrit na strani ponudnika, je izključen iz kataloga in pri izrecni zahtevi
zavrnjeno vrne HTTP 404 / model_not_found. Preverjanje uporablja razrešenega ponudnika in model,
vključno z vzdevki ponudnikov, predponami vozlišč združljivih ponudnikov in privzetimi povezavami.
Kombinacija preskoči skrite cilje in lahko uporabi vidnega sorodnega modela; ko ne ostane noben
izvedljiv cilj, vrne isto kodo napake. Razkritje začne veljati pri naslednji zahtevi. Preglasitve
vidnosti, omejene samo na slike, ne skrijejo modela za klepet z istim ID-jem.
Ta nastavitev posameznega modela je ločena od
seznamov dovoljenih/zavrnjenih izpostavljenih modelov, ki filtrirajo
oglaševanje kataloga in kandidate za samodejno usmerjanje, pri tem pa ohranijo izrecno usmerjanje.
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 oglašuje 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 doda blok thinking) se razreši nazaj
v dejanski <provider>/<model>, pri čemer je razmišljanje onemogočeno — thinking:{type:"disabled"} na poti
/v1/messages oziroma se polji reasoning/reasoning_effort odstranita na poti
/v1/chat/completions. Različica je navedena samo za modele družine Claude, ki podpirajo razmišljanje
in upoštevajo disabled (zato so na primer izključeni modeli, ki podpirajo samo prilagodljivo
razmišljanje in zavrnejo disabled). Upravljavci lahko različico za posamezen model prisilijo v
vklop ali izklop prek ModelSpec.noThinkingAlias.
Manifest vtičnika ponudnika
GET /api/v1/provider-plugin-manifest
Vrne manifest vtičnika ponudnika, varen za uporabo v JSON, ki ga uporabljajo Bifrost, CLIProxyAPI in prihodnji stranski usmerjevalniki. Odziv je ustvarjen iz registra ponudnikov TypeScript in namerno izključuje skrivnosti odjemalcev OAuth, razreševanje izvajalnega okolja, funkcije izvajalnikov, glave zahtev in podatke o računih.
To končno točko uporabite, ko se stranski proces izvaja zunaj glavnega procesa in ne more neposredno uvoziti
open-sse/config/providerPluginManifestRegistry.ts.
Ustvarjanje zvoka ElevenLabs
V OmniRoute konfigurirajte povezavo ponudnika elevenlabs s svojim ključem API ElevenLabs.
Odjemalci se avtenticirajo s svojim ključem OmniRoute (Authorization: Bearer $OMNIROUTE_API_KEY);
prehod posreduje shranjeni ključ ponudnika kot xi-api-key. Ključa ElevenLabs nikoli ne pošiljajte
kot žeton bearer prehoda.
| Metoda | Pot | Odziv | Kategorija končne točke ključa API |
|---|---|---|---|
| POST | /v1/sound-generation |
Izvorni zvočni bajti | elevenlabs |
| POST | /v1/music |
Izvorni zvočni bajti | music |
| POST | /v1/music/stream |
Pretočni zvočni bajti | music |
| POST | /v1/music/detailed |
Izvorni večdelni zvok in načrt kompozicije | music |
| POST | /v1/music/detailed/stream |
Izvorni metapodatki SSE in zvočni izseki | music |
| POST | /v1/music/plan |
Načrt kompozicije JSON | music |
Te končne točke dopolnjujejo obstoječe poti /v1/audio/speech, /v1/audio/transcriptions,
/v1/voices, /v1/text-to-speech/{voiceId} in /v1/speech-to-text. Izvorna polja JSON
in parametri poizvedbe, kot sta output_format in enable_logging, se ohranijo.
Odzivi /v1/music/detailed ohranijo svoje večdelne razmejitve; razčlenite jih kot večdelne.
/v1/music/detailed/stream vrne text/event-stream z metapodatki kompozicije in
zvočnimi izseki base64 v dogodkih SSE. Vseh šest poti podpira predhodne zahtevke CORS.
export OMNIROUTE_BASE_URL="http://localhost:20128"
export OMNIROUTE_API_KEY="your-omniroute-api-key"
# Kratek zvočni učinek. Trajanje: od 0,5 do 30 sekund.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/sound-generation?output_format=mp3_44100_128" \
-H "Authorization: Bearer $OMNIROUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"A single soft bell chime","duration_seconds":1,"model_id":"eleven_text_to_sound_v2"}' \
--output effect.mp3
# Trajanje glasbe je izraženo v milisekundah: od 3000 do 600000.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music?output_format=mp3_44100_128" \
-H "Authorization: Bearer $OMNIROUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt":"Gentle instrumental piano","music_length_ms":10000,"force_instrumental":true,"model_id":"music_v1"}' \
--output music.mp3
Za postopno dostavo zvoka uporabite /v1/music/stream z istim telesom JSON. Kompozicija sprejme natanko eno od možnosti prompt ali composition_plan; /v1/music/plan zahteva prompt
in po izbiri sprejme source_composition_plan. Izvorne sheme ohranijo dodatna
polja ponudnika, tako da različice načrtov kompozicije in možnosti natančnega prilagajanja dosežejo ElevenLabs.
Poenotena končna točka /v1/music/generations sprejema tudi
elevenlabs/music_v1, elevenlabs/music_v2 in elevenlabs/music_v2_5. Z aktivno povezavo ElevenLabs
so ti modeli izpostavljeni v katalogu glasbe. Ta končna točka vrne
{"created":...,"data":[{"b64_json":"...","format":"mp3"}]}. Njeno polje duration je izraženo v
sekundah in se preslika v music_length_ms; izrecno navedeni music_length_ms ima prednost.
instrumental se preslika v force_instrumental, pri čemer ima izvorno polje prednost.
Za pretakanje uporabite izvorne končne točke za pretakanje, za zahteve, ki jih vodi samo načrt kompozicije,
pa izvorno končno točko kompozicije.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music/generations" \
-H "Authorization: Bearer $OMNIROUTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"elevenlabs/music_v1","prompt":"Gentle instrumental piano","duration":10,"instrumental":true}'
Omejitve končne točke, modela, proračuna in povezave se uveljavijo pred klicem navzgor. Izvorne
poti vrnejo statusne kode in telesa napak navzgor brez sprememb, vključno z 402 za omejitev načrta
in 429 za omejitev kvote. Glave character-cost, song-id, request-id in retry-after
se ohranijo, kadar so prisotne. Pozitivno stanje brezplačnih dobroimetij ne zagotavlja dostopa do vsakega
glasbenega modela, izhodnega formata ali funkcije API: ElevenLabs za vsako zahtevo določi upravičenost.
Poenotena končna točka ohrani statusne kode napak v standardiziranem ovoju napake OmniRoute.
Pogodbe ponudnika: zvočni učinki, glasbena kompozicija in podrobnosti pretočne glasbe.
Združljivostne končne točke
| Metoda | Pot | Oblika |
|---|---|---|
| POST | /v1/chat/completions |
OpenAI |
| POST | /v1/messages |
Anthropic |
| POST | /v1/responses |
OpenAI Responses |
| POST | /v1/embeddings |
OpenAI |
| POST | /v1/images/generations |
OpenAI Images |
| POST | /v1/images/edits |
OpenAI Images (urejanje/inpainting) |
| POST | /v1/videos/generations |
Ustvarjanje videoposnetkov v slogu OpenAI |
| POST | /v1/music/generations |
Ustvarjanje glasbe v slogu OpenAI |
| POST | /v1/audio/transcriptions |
OpenAI Audio (STT) |
| POST | /v1/audio/speech |
OpenAI TTS (vrne telo zvočnega posnetka) |
| POST | /v1/rerank |
Preurejanje v slogu Cohere/Voyage |
| POST | /v1/classify |
Jina classify (api.jina.ai) |
| POST | /v1/segment |
Jina segmenter (segment.jina.ai) |
| POST | /v1/moderations |
OpenAI Moderations |
| GET | /v1/models |
OpenAI |
| POST | /v1/models/query |
Filtriran 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 s žetonom |
| POST | /api/v1/vscode/{token}/responses |
Vzdevek OpenAI Responses s žetonom |
| POST | /api/v1/vscode/{token}/api/chat |
Vzdevek Ollama s žetonom |
| GET | /api/v1/vscode/{token}/api/tags |
Vzdevek oznak Ollama s žetonom |
Vse poti POST imajo enako obliko: Bearer your-api-key + telo JSON, potrjeno z Zodom (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema itd.; glejte src/shared/validation/schemas.ts). Ob neuspešnem preverjanju sheme se vrne napaka 4xx.
Za odjemalce, ki ne morejo dodati Authorization: Bearer ..., OmniRoute sprejema ključe API tudi v URL-ju prek združljivosti z nizom poizvedbe (?token=..., ?apiKey=..., ?api_key=..., ?key=...) ali prek namenskih končnih točk /api/v1/vscode/{token}/..., ki so dokumentirane spodaj.
# Preurejanje (ponudnik iz registra v oblaku ali vozlišče ponudnika, združljivo z OpenAI, kot "<prefix>/<model>")
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Jina classify (poverilnice Foundation API)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Jina segmenter
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 zahtevane oblike)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# Soniox TTS zahteva jezik in glas: `language` je privzeto nastavljen na "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 image=@input.png -F prompt="..." -F mask=@mask.png
# 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 ponovno razvrščanje:
POST /v1/rerankusmerja tudi na vozlišča ponudnikov, združljiva z OpenAI (oMLX, vLLM, Infinity, TEI za prehodom, …), 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 imena gostiteljev, ki jih upravljavec navede vOMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS(npr. ime storitve Docker/Compose, kot jehttp://reranker:8080/v1; ta vozlišča se kličejo neposredno, nikoli prekHTTP(S)_PROXYali fiksiranega posredniškega strežnika povezave). Vozlišča na katerem koli drugem gostitelju — računalnik v lokalnem omrežju ali vrstnik Tailscale — so upravičena le, ko upravljavec omogoči zastavico funkcijeRERANK_REMOTE_PROVIDER_NODESin osnovni URL vozlišča prestane pravilnik za odhodne URL-je ponudnika (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS/OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS). Korak ponovnega razvrščanja pomnilniškega mehanizma kliče to pot prek povratne zanke, zato isto pravilo velja zarerankProviderModelv nastavitvah pomnilnika.Oblike lokalnega strežnika: vozlišče se kliče na
<base>/v1/rerankin ob odgovoru 404 na<base>/rerank(Infinity, TEI). Telo zahteve navzgor vsebuje obe obliki zapisa Cohere/OpenAI (documents,return_documents) in obliko zapisa TEI (texts,return_text), odgovor navzgor pa se normalizira v ovojnico Cohere: goli seznam TEI[{index, score, text}],{results: [{index, score}]}iz tankih prehodov in{data: [...]}v slogu Voyage se odjemalcu vrnejo kot{results: [{index, relevance_score, document?}]}, razvrščeni po oceni in omejeni natop_n.
Odkrivanje vozlišč ponudnikov: modeli na vozlišču ponudnika, združljivem z OpenAI, se prikažejo v
GET /v1/modelspod predpono vozlišča. Vrstice brez metapodatkov o končni točki (kar je običajno pri lokalnih seznamih/v1/models) podedujejoapiTypevozlišča, zato so modeli vozliščaembeddingsvrstetype: "embedding", modeli vozliščarerankpa vrstetype: "rerank"in ne privzeto vrste chat; izrecno navedenasupportedEndpointsv 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
Predpona ponudnika se samodejno doda, če manjka. Neujemajoči se modeli vrnejo 400.
API datotek
Končna točka za datoteke, združljiva z OpenAI, za paketne vhode/izhode in nalaganje datotek glede na namen.
| Method | Path | Description |
|---|---|---|
| POST | /v1/files |
Naloži datoteko (multipart: file, purpose, expires_after[anchor], expires_after[seconds]) — največ 512 MiB |
| GET | /v1/files |
Izpiše datoteke za preverjeni ključ API |
| GET | /v1/files/[id] |
Pridobi metapodatke datoteke |
| DELETE | /v1/files/[id] |
Izbriše datoteko |
| GET | /v1/files/[id]/content |
Pretaka vsebino neobdelane datoteke nazaj |
Preverjanje pristnosti: ključ API Bearer — datoteke so omejene na posamezen ključ API prek getApiKeyRequestScope. Ključ
lahko vidi, prenese in izbriše samo svoje datoteke; seja nadzorne plošče brez ključa bere celoten
primerek; datoteka brez lastnika (naložena anonimno ali prek seje nadzorne plošče) je zavrnjena za vsakega
klicatelja, ki ni seja. GET /v1/files anonimnega klicatelja — in posredovani ključ, ki ga ni mogoče
razrešiti — zavrne z 401, tudi ko je REQUIRE_API_KEY=false, namesto da bi izpisal datoteke vseh najemnikov
(GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).
API paketov
Paketna obdelava, združljiva z OpenAI.
| Method | Path | Description |
|---|---|---|
| POST | /v1/batches |
Ustvari paket — telo preveri v1BatchCreateSchema (input_file_id, endpoint, completion_window) |
| GET | /v1/batches |
Izpiše pakete |
| GET | /v1/batches/[id] |
Pridobi stanje paketa in request_counts |
| DELETE | /v1/batches/[id] |
Izbriše končan ali neuspešen paket |
| POST | /v1/batches/[id]/cancel |
Prekliče paket v obdelavi |
Preverjanje pristnosti: ključ API Bearer. Paketi so omejeni na posamezen ključ API v skladu z istim pravilom
treh možnosti kot datoteke: samo lastni ključ, seja nadzorne plošče za celoten primerek, zapisi z ničelnim lastnikom pa so zavrnjeni za vsakega
klicatelja, ki ni seja (pri pridobivanju, brisanju, preklicu in preverjanju input_file_id pri ustvarjanju).
GET /v1/batches anonimnega klicatelja zavrne z 401, tudi ko je REQUIRE_API_KEY=false.
Iskanje API
abstrakcija ponudnika Web/search (Tavily, Brave, Exa, Serper itd.).
| Metoda | Pot | Opis |
|---|---|---|
| GET | /v1/search |
Seznam zmožnosti + konfiguriranih ponudnikov iskanja |
| POST | /v1/search |
Izvedite iskalno poizvedbo — body, ki jo potrdi v1SearchSchema, podpira caching/coalescing |
| GET | /v1/search/analytics |
Statistika hit/latency/cache za posameznega ponudnika |
Auth: Nosilni ključ API (extractApiKey + isValidApiKey). Politika iskanja, uveljavljena prek enforceApiKeyPolicy.
Samodejna izbira: brez provider najprej teče najcenejši ponudnik s konfigurirano povezavo, naslednji najcenejši pa je failover. Brezplačni ponudniki v zadnji sili (duckduckgo-free) se uporabljajo le, če ni konfigurirano nič drugega. Samostojno gostujoči SearXNG se šteje kot konfiguriran, ko njegova povezava shrani pravi baseUrl (ne kataloški privzeti http://localhost:8888/search): nato se uvrsti kot ponudnik z vrednostjo 0 $ pred ponudniki s ključi, pri čemer je najcenejši ponudnik s ključi kot samodejni preklop, vključno s tem, ko SearXNG odgovori 400, 401, 403 ali 404. baseUrl, ki ni veljaven http(s) URL ali kaže na naslov metapodatkov v oblaku ne šteje. Povezava SearXNG, ki shrani žeton, je tako uvrščena samo pred https:// ali povratno http://. Prek oddaljenega navadnega http:// ni nikoli samodejni preklop in ostane zadnja možnost, ki se uporablja le, če ni konfiguriran noben drug ponudnik ali ko je zahtevano po imenu, tako da v teh dveh primerih pošlje žeton v čistem besedilu.
Exa in Tavily provider_options
Exa in Tavily bereta polja, specifična za ponudnika, iz vrečke z imenskim prostorom: provider_options.exa (ali provider_options["exa-search"]) in provider_options.tavily (ali provider_options["tavily-search"]). Posredovani so samo spodnji ključi. Vsak se preveri glede na lastno shemo Zod v open-sse/handlers/search/providerOptionsPassthrough.ts in ključ z napačnim tipom se izpusti. Vsi drugi ključi so prezrti, vključno z auth, base URL, stream in outputSchema. Ploščati 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 (ploski primitivi), startPublishedDate, endPublishedDate |
contents.{text, highlights, summary, extras, livecrawlTimeout, maxAgeHours} združeno s privzetim { 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 |
— |
Vedno zmagajo generična polja: query, max_results, filters (domene), country in tema, izpeljana iz search_type. Na Exa search_type: "news" ohrani category: "news". Tavily sprejema tudi search_type: "finance" (topic: "finance").
Strošek iskanja Firecrawl se zabeleži na začeti blok 10 vrnjenih rezultatov, 0,002 USD (2 kredita) na blok in vsaj en blok na klic ( zaračunavanje Firecrawl ): 11 rezultatov stane 0,004 USD.
Generični time_range zdaj doseže oba ponudnika: Exa dobi startPublishedDate (ISO timestamp), Tavily pa start_date (YYYY-MM-DD). Eksplicitni datum v provider_options preglasi preslikanega.
Rezultati Exa ohranjajo id, highlights (vsak poudarek, ne le prvi, uporabljen kot snippet), highlight_scores, summary, subpages, entities in extras v provider_raw. Rezultati Tavily ohranjajo images in favicon.
Stroški iskanja povezav so zabeleženi pri 0,005 USD za depth fast in standard ter 0,05 USD za deep ( Cene povezav ), ne glede na to, ali depth izvira iz provider_options ali nastavitev povezave.
Exa type: "lite" (Exa 3.0) sprejme manjši nabor polj in zavrne celotno zahtevo, ko je nastavljeno katero koli drugo polje. Za lite additionalQueries, systemPrompt in vsi ključi contents razen text in highlights opuščeni pred klicem. Zastareli subpages, subpageTarget, highlights.numSentences in highlights.highlightsPerUrl se ne posredujejo več.
Stroškovno računovodstvo je pavšalni register costPerQuery, razen za Exa, ki sledi lastnim cenam Exa: 0,007 USD na klic za auto (in podedovano fast) ali 0,004 USD za lite (in podedovano instant), ki zajema 10 rezultatov; 0,001 za vsak nadaljnji rezultat; in 0,001 na vrnjen rezultat, ko je nastavljen contents.summary. Tavily je zabeležen pri 1 kreditu (0,008 USD) za search_depth basic, fast in ultra-fast ter 2 kredita (0,016 USD) za advanced ( krediti Tavily API ). Klic z auto_parameters: true, ki ga Tavily nadgradi na naprednega, se še vedno beleži pri 1 kreditu.
API za pridobivanje spletnih vsebin
Izvleče vsebino iz URL-ja prek konfiguriranega ponudnika za pridobivanje spletnih vsebin (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract).
Parallel Extract (parallel-search, isti ključ API kot pri Parallel Search) vrne samo Markdown — katera koli druga
vrednost format povzroči napako 400 — vsebino pa omeji na 100.000 znakov. Ko ciljne strani same ni mogoče
izvleči, jo nadrejena storitev sporoči znotraj HTTP 200;
OmniRoute to prikaže kot 422 s fiksnim sporočilom.
| Metoda | Pot | Opis |
|---|---|---|
| POST | /v1/web/fetch |
Pridobi/strga URL — telo se preveri glede na v1WebFetchSchema |
Preverjanje pristnosti: ključ API Bearer (extractApiKey + isValidApiKey). Pravilnik se uveljavi prek enforceApiKeyPolicy.
Nadomestna možnost, upoštevajoč kvoto (#8297): kadar ni podan izrecni provider, se po skupini
(firecrawl → jina-reader → tavily-search → tinyfish → nimble-search →
parallel-search) hodi v nespremenljivem
vrstnem redu prednosti (najprej se zapolni prvi) — ponudnik, pri katerem je dosežena omejitev hitrosti, vendar je konfiguriran, se preskoči
namesto prekinitve zahteve, napaka nadrejene storitve, ki jo je mogoče znova poskusiti, oziroma napaka zaradi kvote
(HTTP 429 vedno; 402/403 pri Firecrawl/Tavily/TinyFish za brezplačne pakete v slogu kvot —
ne pri Jina Reader in nikoli pri navadni napačni zahtevi 400), pa se posreduje naslednjemu še nepreizkušenemu ponudniku z veljavnimi poverilnicami v času zahteve. Ko so vsi ponudniki
v skupini izčrpani, končna točka vrne en sam 429 (z glavo Retry-After)
namesto prejšnjega splošnega 400. Ko je izrecno zahtevan provider, tiha nadomestna možnost
ne obstaja — ponudnik, pri katerem je dosežena omejitev hitrosti ali ki odpove, prikaže lastno napako (429, če je dosežena omejitev hitrosti, sicer status nadrejene storitve).
Pretakanje prek WebSocketov
GET /v1/ws?handshake=1
Preveri rokovanje za nadgradnjo povezave WebSocket in vrne primer sporočil žičnega protokola (request, cancel). Dejanske okvirje WS obravnava priloženi strežnik WS zunaj usmerjevalne tabele Next.js.
Preverjanje pristnosti: ključ API Bearer med rokovanjem.
API Responses prek WebSocketa (samo codex)
# Isti gostitelj:vrata kot pri API-ju HTTP (privzeto 20128); nadgradi 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" } ] }
Posrednik 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 se preveri pristnost in pripravi prek notranjega mostu codex-responses-ws, izbere povezavo OAuth codex in tunelira do
wss://chatgpt.com/backend-api/codex/responses
prek prenosa 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 (privzeto je, kadar obstaja app/server-ws.mjs).
ID modela: uporabite goli ID ChatGPT (brez predpone codex/)
Odjemalec Codex CLI preverja ime modela na strani odjemalca, ko
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 goli ID (npr. gpt-5.5). Most OmniRoute je namenjen samo codexu, zato goli ID znova razreši kot model codex
(resolveCodexWsModelInfo) pred tuneliranjem v nadrejeno storitev — čeprav bi se goli
gpt-5.5 prek HTTP sicer usmeril k drugemu ponudniku.
Konfiguriranje OpenAI Codex CLI
Codex CLI usmerite na OmniRoute tako, da v ~/.codex/config.toml dodate ponudnika po meri s podporo za WebSocket
(uporabite ločen CODEX_HOME, da ne posegate v obstoječo konfiguracijo):
model = "gpt-5.5" # goli 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 WS se izpelje (v produkciji uporabite https/wss)
wire_api = "responses" # edina podprta vrednost od februarja 2026
supports_websockets = true # omogoči prenos 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 v WebSocket, OmniRoute pa povezavo tunelira do izbrane povezave OAuth codex. Preverjeno od začetka do konca z lokalnim strežnikom: ChatGPT vrne
codex.rate_limits + response.created in pretaka dokončanje.
Poročanje o kvotah in težavah
| Metoda | Pot | Opis |
|---|---|---|
| GET | /v1/quotas/check |
Predhodno preveri kvoto za provider + accountId pred izdajo registriranega ključa |
| POST | /v1/issues/report |
Prijavi neuspešno izdajo kvote/ključa v GitHub (zahteva GITHUB_ISSUES_REPO + žeton) |
Overjanje: API-ključ Bearer (isAuthenticated).
Obnovitev seje kvote (izbirno)
Nestreaming zahteva POST /v1/chat/completions ali POST /v1/responses, ki ne uspe
zaradi končne napake kvote (402/429/503), katere telo navaja, da je kvota ali dobroimetje
izčrpano, se lahko odloži in pozneje znova predvaja, namesto da bi vrnila napako. Klicatelj to
omogoči za posamezno zahtevo s tremi glavami:
| Glava | Vrednost |
|---|---|
x-omniroute-quota-recovery |
auto |
x-omniroute-session |
ID seje, [A-Za-z0-9._:-]{1,128} |
x-omniroute-recovery-turn |
ID obrata, enoličen znotraj seje (isto pravilo) |
Upravičeni so samo obrati z stream: false, brez orodij, zgodovine orodij ali
previous_response_id ter brez pripetega x-omniroute-connection, nastavljena pa mora biti
tudi STORAGE_ENCRYPTION_KEY (zahteva se šifrirano shrani za največ 24 ur). Odgovor je nato
202 z recovery.poll; poizvedite z GET /v1/quota-recoveries/{id} (202, dokler čaka,
200 z obnovljenim telesom po dokončanju) ali prekličite z DELETE. Vstopnice so vidne samo
API-ključu, ki jih je ustvaril. Ponovitev, pri kateri izid ni zanesljiv, se konča v stanju
needs_confirmation, namesto da bi bila poslana dvakrat. Vir: src/lib/quota/quotaSessionRecovery.ts.
Samopostrežna uporaba (/api/usage/om-usage)
Vsak ključ API lahko bere** svoje** uporaba in kvote — brez avtorizacije upravljanja. To je končna točka, ki jo odjemalec (CLI, plošča OmniCopilot ) uporablja, da imetniku ključa pokaže svojo porabo.
# Text form (the historical contract — plain text for a terminal)
curl -H "Authorization: Bearer <your-api-key>" \
http://localhost:20128/api/usage/om-usage
# Structured form — what a UI consumes
curl -H "Authorization: Bearer <your-api-key>" \
"http://localhost:20128/api/usage/om-usage?format=json"
Ključ mora imeti**allowUsageCommand** omogočeno (privzeto izklopljeno — upravljalnik ključev API na nadzorni plošči ga preklopi po ključu). Brez tega končna točka odgovori 403.
?format=json vrne diskriminirano obliko, tako da klicatelj nikoli ne prebere podatkovnega polja z zavrnitve. Ob uspehu:
{
"allowed": true,
// present only when the key opted into per-key usage limits (daily/weekly/5-hour USD):
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// the selected provider quota snapshot, or null when nothing is cached yet:
"provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */} },
// every connection's snapshot, so a UI can render several providers side by side:
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
Ob zavrnitvi (401 slab ključ / 403 ni dovoljeno) ista pot vrne { "allowed": false, "error": { "message": "…" } } — prisoten, vendar prazen personal/provider (ključ je dovoljen, nič še ni naučeno) je drugačno stanje od zavrnitve in ju razlikuje samo oblika JSON.
Auth: klicateljev lastni nosilni ključ API, preverjen z isValidApiKey — to ni upravljalna površina (/api/keys/…), ki ostane za requireManagementAuth.
Odstotki neobdelanih kvot v primerjavi s prilagojenimi odstotki kvote
Pri uporabi /api/usage/om-usage morajo klicatelji upoštevati razliko med odstotki, ki jih predstavlja** izpis navadnega besedila** in strukturirano** izhod JSON** :
| Vidik | Format navadnega besedila (/api/usage/om-usage / @@om-usage) |
format JSON (?format=json) |
|---|---|---|
| Izhodno polje | NN% left (npr. 20% left) |
provider.quotas / providers[].quotas |
| Merjenje | Uporabni dodatek, prilagojen mejni vrednosti : preostala zmogljivost nad mejno vrednostjo | Raw upstream kvota : neprilagojena meritev ponudnika |
| Merjenje meje | Prilagojeno prek effectiveRemainingPercent(), tako da se zaščitena rezerva bere kot 0% left |
Brez (neobdelane vrednosti posnetkov, kot jih je sporočil ponudnik) |
| Podatki o pragu | Vključeno v prikazani odstotek | Shranjeno v quotaWindowThresholds na povezavo (ali privzete nastavitve strežnika) |
| Primarni potrošnik | Interaktivni CLIs, terminalski pozivi, človeški operaterji | Programske integracije, nadzorne plošče, analitika, sledilniki zaračunavanja |
Formula za prilagoditev izklopa
OmniRoute podpira proaktivne omejitve kvot za preprečevanje izčrpanja navzgor (konfigurirano prek povezave quotaWindowThresholds, privzetih nastavitev ponudnika ali globalnih nastavitev odpornosti). Ko je mejni prag (npr. cutoff = 25%) aktiven v oknu kvote, upodabljalnik besedila izračuna preostalo dovoljeno vrednost kot:
- Če
remaining <= cutoff: vrne0%. - Če
remaining > cutoff: vrne((remaining - cutoff) / (100 - cutoff)) * 100.
Izpis oblikovanega besedila to zaokroži na najbližje celo število (Math.round(...)).
Ilustrativni primer
Razmislite o oknu ponudnika z** 60 % surove uporabe** (torej** 40 % surove preostale kvote** ) in konfigurirano** 25 % preostale kvote** prag:
| Zastopanje | Izračun | Preostalo | Implicitno uporabljeno |
|---|---|---|---|
Surovi JSON (?format=json) |
Posnetek navzgor (quotas[window]) |
40% | 60% |
Oblika besedila (NN% left) |
((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100 |
20% | 80 % (če se izračuna 100 - remaining) |
- Zakaj besedilo prikazuje 20 % levo: Od 40 % fizične kvote, ki je ostala na računu, je 25 % rezerviranih s politiko izključitve. Klicatelj ima na voljo samo 15 % od 75 % uporabnega prostora, preden usmerjevalnik preneha usmerjati na to povezavo. Skaliranje zagotavlja izčrpanost povezovalnih signalov (
0% left) točno takrat, ko bo usmerjanje prenehalo. - Zakaj JSON ohranja neobdelane vrednosti: Koristni tovor JSON vrne natančen posnetek ponudnika (
UsageSnapshot), tako da imajo zunanja orodja dostop do zemeljske uporabe navzgor in ravni povezavequotaWindowThresholdsbrez skaliranja z izgubo na strani strežnika.
Smernice za migracijo potrošnikov
Če je zunanja integracija (kot je vtičnik urejevalnika ali razširitev agenta) predhodno postrgala končno točko besedila (NN% left) in izračunala uporabljeni odstotek kot 100 - NN, selitev na ?format=json pomeni:
- Branje neobdelanih vrednosti JSON bo odražalo** dejanska poraba navzgor** (60 % uporabljenih v zgornjem primeru).
- Če želi integracija ohraniti semantiko uporabne dovoljene končne točke besedila, lahko ovrednoti efektivno preostalo formulo na strani odjemalca z uporabo
quotaWindowThresholdsza 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 semantičnega predpomnilnika postreže odgovor iz predpomnilnika brez klica
upstreama, zato je sporočena X-OmniRoute-Response-Latency skoraj ničelna
(ne glede na prvotno zakasnitev upstreama). Odjemalci, občutljivi na zakasnitev
(izvajanje primerjalnih testov, spremljanje p50/p99), naj preverijo odzivno glavo
X-OmniRoute-Cache-Latency:
| Vrednost | Pomen |
|---|---|
synthetic |
Odgovor je bil postrežen iz predpomnilnika; zakasnitev ni dejanski čas upstreama |
| (absent) | Odgovor iz dejanskega klica upstreama |
Obhod predpomnilnika za posamezen ključ
Ključi API-ja lahko izključijo branje iz semantičnega predpomnilnika prek cacheDefaultMode:
| Vrednost | Vedenje |
|---|---|
legacy |
Običajno vedenje predpomnilnika (privzeto) |
bypass |
Preskoči iskanje v predpomnilniku; vedno pokliče upstream |
Nastavite pri ustvarjanju ključa (POST /api/keys) ali posodobitvi (PATCH /api/keys/[id]):
{ "cacheDefaultMode": "bypass" }
Obhod predpomnilnika za posamezno zahtevo
Vsaka zahteva lahko obide predpomnilnik ne glede na nastavitve ključa:
X-OmniRoute-No-Cache: true
Združljivost upravljanja CLIProxyAPI
OmniRoute odgovarja na tri upravljavske končne točke CLIProxyAPI,
ki jih nadzorne plošče uporabe kličejo za branje omejitev naročnin Claude in Codex
(na primer vir omejitev uporabe cliproxy v T3 Code). Osnovni URL odjemalca nastavite na
OmniRoute in uporabite ključ API-ja z obsegom manage kot njegov upravljavski ključ. Poti so
na voljo na /v0/management/* in /api/v0/management/*.
| Metoda | Pot | Opis |
|---|---|---|
| GET | /v0/management/auth-files |
Povezave OAuth Claude in Codex kot { files: [{ id, auth_index, provider, email, disabled, id_token }] }. Brez žetonov |
| POST | /v0/management/api-call |
Telo { auth_index, method, url, header?, data? }. Pošlje eno zahtevo z dovoljenega seznama z žetonom računa in vrne { status_code, body } |
| POST | /v0/management/reset-quota |
Telo { auth_index }. Počisti ohlajanje povezave, zaklepe modelov in ohlajanja Codexa za posamezne obsege enega računa |
auth_indexje ID povezave OmniRoute.providerjeclaudealicodex(samo povezave OAuth; ponudnik ključev API-jaanthropicni naveden). Pri Codexu jeid_token.chatgpt_account_idshranjeni ID delovnega prostora,plan_typepa shranjeni načrt.api-callni generični posrednik. Sprejema samo ClaudeGET https://api.anthropic.com/api/oauth/usagein CodexGET https://chatgpt.com/backend-api/wham/usage,GET .../wham/rate-limit-reset-creditsterPOST .../wham/rate-limit-reset-credits/consume, pri čemer je vsaka zahteva dovoljena samo za račun ustreznega ponudnika. Vse drugo vrne403, ne da bi vzpostavilo stik z upstreamom. GlavaAuthorizationklicatelja (vključno z ogrado$TOKEN$) je prezrta: OmniRoute vstavi žeton za dostop povezave, ga pred tem osveži, če je blizu poteka veljavnosti, in posreduje samo glave z dovoljenega seznama (anthropic-beta;OpenAI-Beta,Originator,Chatgpt-Account-Id;Accept,Content-Type). ČeChatgpt-Account-Idmanjka, se privzeto uporabi shranjeni ID delovnega prostora. Zahteve potečejo po 15 sekundah in uporabljajo posredniški strežnik povezave.reset-quotapusti končna stanja (banned,expired,credits_exhausted) nespremenjena. Neznanauth_indexvrne404.
Preverjanje pristnosti: seja nadzorne plošče ali ključ API-ja z obsegom manage, zahtevano
tudi, ko je prijava onemogočena (poti so v ALWAYS_PROTECTED_API_PATHS). Ključi, namenjeni samo
inferenci, prejmejo 403. Vir:
src/lib/cliproxyCompat/managementApi.ts.
Nadzorna plošča in upravljanje
Poti upravljanja (/api/* razen javnega auth/login) so** ne** avtoriziran z običajnimi sklepnimi ključi API. Družine poverilnic, obsegi in primeri kodrov: Preverjanje pristnosti upravljanja.
Preverjanje pristnosti
| 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 prijavo: samo za operaterja, ko geslo obstaja (seja nadzorne plošče, lokalni CLI ali prijava onemogočena — API ključi in žetoni oma_ dobijo 403); seja nadzorne plošče pošlje currentPassword za zamenjavo gesla |
Upravljanje ponudnika
| Končna točka | Metoda | Opis |
|---|---|---|
/api/providers |
GET/POST | Seznam / ustvarjanje ponudnikov |
/api/providers/[id] |
GET/PUT/DELETE | Upravljanje ponudnika |
/api/providers/[id]/test |
POST | Preizkusite povezavo ponudnika |
/api/providers/[id]/models |
GET | Seznam modelov ponudnikov |
/api/providers/validate |
POST | Preverite konfiguracijo ponudnika |
/api/providers/bulk |
POST | Množično dodajanje ključev API za ponudnika ONE |
/api/providers/import |
POST | Uvozite heterogenega ponudnika LIST iz razčlenjene datoteke CSV/JSON (#6836); rezultati delne napake na vrstico |
/api/provider-nodes* |
Različne | Upravljanje vozlišča ponudnika |
/api/provider-models |
GET/POST/PUT/PATCH/DELETE | Modeli po meri in preglasitve posameznih modelov (dodaj, posodobi, hide/show, izbriši) |
/api/provider-models/validate-and-add |
POST | Preverjeno z upravljanjem, preverjanje stroge povezave po izbiri in registracija atomskega modela po meri; glejte Preverjanje modela |
Za modele synced/imported PUT /api/provider-models sprejema provider, modelId in maxOutputTokenOverride: pozitivno celo število nastavi omejitev ročnega izhodnega žetona, null pa jo počisti, da obnovi privzeto. GET /api/provider-models?provider=<provider> vrne te vrednosti v modelOutputOverrides, vključno z modeli brez vrstice modela po meri. Preglasitev uporablja zmogljivost max_output_tokens med izvajanjem in preživi ponovno sinhronizacijo modela. Stran ponudnika, združljiva z OpenAI, ponuja enake kontrole edit/clear in označuje modele z eksplicitno podporo za vid.
Na vozlišču združljivega ponudnika pisalne poti (POST, PUT, PATCH, DELETE in /api/provider-models/validate-and-add) shranijo ID modela kot goli ID navzgor: ID, prilepljen iz seznama s predpono, ima vse vodilne sklade lastne predpone vozlišča strnjene, odzivi pa odražajo shranjeni ID. Poševni ID-ji kanoničnih ponudnikov (npr. nvidia/nemotron-…) so shranjeni dobesedno. /v1/models nikoli ne odda zloženega ID-ja <prefix>/<prefix>/<model>.
Vozlišča za dokončanje klepeta po meri prilagodijo izrecno utemeljitev zavrnitev navzgornjemu zaledju. Uspešen preizkus povezave samodejno izbere kontrolnike predloge za klepet za vsak natančen model ID katerega vnos /models dokazuje priznano vrednost owned_by : vllm, sglang ali llamacpp. Transparentni ovoji, združljivi z OpenAI, lahko ohranijo izvirni vnos modela znotraj ugnezdenega predmeta openai ; zaznavanje sledi do trem takim ovojnicam. Modeli z manjkajočim, neznanim ali spornim lastništvom ohranjajo običajno vedenje OpenAI. Zaznavanje ponovno uporabi obstoječo kataloško zahtevo, ne ustvari žetonov dokončanja in je razveljavljeno, ko se končna točka povezave spremeni.
Če želite pripeti vedenje za zaledje, ki ne izpostavlja teh metapodatkov, uporabite obstoječo delno posodobitev ponudnika API:
{
"providerSpecificData": {
"reasoningControl": "chat-template"
}
}
Pošljite to telo z PUT /api/providers/<connection-id>. Pri tej povezavi se eksplicitno razmišljanje none pošlje kot chat_template_kwargs.thinking=false in chat_template_kwargs.enable_thinking=false. Eksplicitne izvorne vrednosti predloge ostanejo verodostojne, razen če pravilo sklepanja na strani strežnika zahteva trud. Nastavitev velja le, če povezava po meri, združljiva z OpenAI, odpošlje telo dokončanja klepeta; Zahteve za odzive in navadni ponudniki ohranjajo svojo izvirno obliko zahtev. Nastavite reasoningControl na openai, da prisilite običajni prehod OpenAI reasoning_effort, ali izpustite it/set it na null da uporabite samodejno zaznavanje.
Klasifikator samodejnega načina kode Claude zahteva, da je privzeto izvorno razmišljanje onemogočeno, če ne vsebuje eksplicitnih kontrolnikov sklepanja. Zaznavanje uporablja sistemski marker klasifikatorja v zahtevah Claude-formata, ne imen modelov ali omejitev dokončanja. Eksplicitni kontrolniki telesa, podprte glave effort/thinking, pravila usmerjanja in rešeno prizadevanje modela ohranjajo svojo obstoječo prednost. Obe stopnji klasifikatorja ohranita svoje pozive, omejitve dokončanja, zaustavitvena zaporedja in dejanske sodbe o dovoljenjih navzgor; druga stopnja lahko še vedno ustvari svoje zahtevano vidno razmišljanje kot običajno besedilo.
OAuth teče
| Končna točka | Metoda | Opis |
|---|---|---|
/api/oauth/[provider]/[action] |
Različne | OAuth, specifičen za ponudnika |
Usmerjanje in konfiguracija
| Končna točka | Metoda | Opis |
|---|---|---|
/api/models |
GET/PUT | Posodobitev seznama modelov/vzdevkov |
/api/models/alias |
GET/POST | Vzdevki modelov |
/api/models/catalog |
GET | Vsi modeli po ponudniku tipa + |
/api/combos* |
Različne | Kombinirano upravljanje |
/api/keys* |
Različne | upravljanje ključev API |
/api/pricing |
GET | Cene modela |
Izvor omejitve modela
GET /api/models?withLimits=1 (tudi true; 0/false ali če ga izpustite, ohrani privzeto koristno obremenitev nespremenjeno) doda contextWindow, maxInputTokens, maxOutputTokens in objekt capsSource v vsako vrstico modela. capsSource poimenuje pravilo, ki je zagotovilo vsako omejitev, tako da je mogoče presenetljivo omejitev (na primer 128 k na modelu 1M) izslediti do njenega izvora. Razrešene vrednosti so enake tistim, ki jih uporablja usmerjanje; zastavica samo dodaja polja in nikoli ne spremeni vrednosti. Vsaka druga vrednost withLimits je zavrnjena z 400.
vrednost capsSource |
Izvor |
|---|---|
override:context |
Trajna preglasitev kontekstnega okna (model_context_overrides) |
override:max_input / override:max_output |
Vztrajna preglasitev zmogljivosti max_input_tokens / max_output_tokens |
static-authoritative:<provider>/<model> |
Statična verodostojna kontekstno-okenska tabela |
synced:<provider>/<model> |
models.dev sinhronizirana vrstica zmogljivosti |
registry:<provider>/<model> |
Vpis v register ponudnikov |
spec:<model> |
Statični model spec |
predpona effort-base: |
Vrstica, izposojena iz osnovnega modela različice s končnico napora |
none |
Noben vir ne navede omejitve (vrednost je null) |
Implementacija: getResolvedModelCapabilitiesWithLimitSources() v src/lib/modelCapabilities.ts in prednostne verige v src/lib/modelCapabilityLimits.ts.
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 | Poraba na povezavo |
/api/usage/token-limits |
GET/POST/DELETE | Proračuni z omejitvijo žetona na ključ API |
/api/usage/model-latency-stats |
GET | Rolling per-provider/model latency agregat (avg/p50/p95/p99, stopnja uspešnosti); filtri: windowHours/minSamples/maxRows/provider/model (#6873) |
/api/usage/cache-health |
GET | Povzetek stanja hitrega predpomnilnika glede na razmerje call_logs — write/read, porazdelitev velikosti zapisa p50/p90/p99, koncentracijo težkega pisanja, razdelitev na model in razsodbo healthy/degraded/thrash/no-data ; poizvedbeni parametri range (1h| 24h| 7d| 30d, privzeto 24h) in neobvezno model (#8827) |
ključna dovoljenja API
PATCH /api/keys/{id} posodobi dovoljenja obstoječega ključa. Kot vsaka pot /api/keys* potrebuje pooblastilo za upravljanje (glejte Preverjanje pristnosti upravljanja ), ne ključa za sklepanje. Pošljite samo polja, ki jih želite spremeniti; zahteva z nobenim od njih je zavrnjena z No valid fields to update. Sprejemljiva polja definira updateKeyPermissionsSchema v src/shared/validation/schemas/keys.ts.
| Polje | Vrsta | Opombe |
|---|---|---|
name |
niz, 1-200 znakov | |
isActive |
logično | |
isBanned |
logično | |
expiresAt |
ISO 8601 datetime ali null |
null počisti potek |
modelAccessMode |
all | restricted |
allowedModels mora biti prazno, ko je način all |
allowedModels, blockedModels |
niz nizov, do 1000 | |
allowedCombos |
niz nizov, do 500 | Vrata, katere kombinacije lahko kliče ključ; neposredne modele ureja modelAccessMode / allowedModels |
connectionAccessMode |
all | restricted |
allowedConnections ne sme biti prazen pri restricted in prazen pri all |
allowedConnections |
niz UUIDs, do 100 | |
allowAutoCombos |
logično | false zavrne zahteve za modele auto/* s tem ključem; dovoljeni so ključi, ki ga nikoli ne nastavijo |
catalogScope |
all | combos | models |
Kaj navaja GET /v1/models za ta ključ (samo kombinacije, samo modeli ali oboje); ne spremeni tega, kar lahko ključ kliče |
forcedModel |
niz do 300 znakov ali null |
Usmerja zahteve za klepet v ta model/combo prek X-Route-Model in body.model; še vedno veljajo omejitve ključa |
noLog, autoResolve |
logično | |
throttleDelayMs |
celo število, 0-300000 | |
maxSessions |
celo število, 0-10000 | |
rateLimits |
niz { limit, window } (pozitivna cela števila, do 50) ali null |
null briše meje |
accessSchedule |
urnik objekt ali null |
null počisti urnik |
scopes |
niz nizov, do 32 | |
allowedEndpoints |
niz nizov, do 20 | |
streamDefaultMode |
legacy | json |
|
cacheDefaultMode |
legacy | bypass |
Glejte Obhod predpomnilnika na ključ |
compressionEnabled |
logično | |
codexServiceMode |
enega od načinov storitve Codex | |
disableNonPublicModels |
logično | |
allowUsageCommand |
logično | |
usageLimitEnabled |
logično | |
dailyUsageLimitUsd, weeklyUsageLimitUsd |
število >= 0 ali null |
|
fiveHourUsageLimitUsd |
število >= 0 ali null |
Tekoči 5-urni proračun USD, uveljavljen kot dnevne in tedenske omejitve (usageLimitEnabled, UNPRICED_USAGE_BUDGET_POLICY). retry-after je, ko se najstarejša poraba v oknu postara, zaradi česar lahko ostane ključ, ki je daleč nad svojo omejitvijo, še vedno blokiran. |
chaosModeEnabled |
logično |
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 varnostne politike (requireLogin, newPassword, oidc*, corsOrigins, bruteForceProtection) potrebujejo currentPassword in poverilnico operaterja — API ključi in žetoni oma_ dobijo 403; vsaka mutacija potrebuje obseg žetona dostopa admin |
/api/settings/proxy |
GET/PUT | Konfiguracija omrežnega proxyja |
/api/settings/proxy/test |
POST | Preizkusite proxy povezavo |
/api/settings/ip-filter |
GET/PUT | IP allowlist/blocklist |
/api/settings/thinking-budget |
GET/PUT | Thinking/reasoning** zahteva** način prepisovanja (prehodni / samodejni odstranjevanje / po meri / prilagodljiv). Neodvisno od kompresije. Glej 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 | Počistite vrstice dnevnika zahtev in lokalne artefakte 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 pravila Caveman |
/api/context/caveman/config |
GET/PUT | Vzdevek nastavitev, specifičen za jamskega človeka |
/api/context/rtk/config |
GET/PUT | Nastavitve, specifične za RTK, vključno s filtri po meri in ohranjanjem surovega izhoda |
/api/context/rtk/filters |
GET | katalog filtrov RTK in diagnostika filtrov po meri |
/api/context/rtk/test |
POST | Zaženite RTK preview/test proti koristnemu besedilu |
/api/context/rtk/raw-output/[id] |
GET | Branje ohranjenega redigiranega neobdelanega izpisa z ID-jem kazalca |
/api/context/combos |
GET/POST | Kompresijska kombinacija list/create |
/api/context/combos/[id] |
GET/PUT/DELETE | Kompresijska kombinacija detail/update/delete |
/api/context/combos/[id]/assignments |
GET/PUT | Dodelite kompresijske kombinacije usmerjevalnim kombinacijam |
/api/context/analytics |
GET | Vzdevek za analizo stiskanja |
Spremljanje
| Končna točka | Metoda | Opis |
|---|---|---|
/api/sessions |
GET | Sledenje aktivnim sejam |
/api/rate-limits |
GET | Omejitve obrestne mere na račun |
/api/monitoring/health |
GET | Pregled zdravstvenega stanja ponudnika + (catalogCount, configuredCount, activeCount, monitoredCount). Upravljalni pogled vključuje credentialHealth: probe-cache skalarje, failedConnections ko je failed>0, in staleDbNonOkCount (SQLite lepljivi test_status, ne merilnik). Glej MONITORING_GUIDE.md. |
/api/cache/stats |
GET/DELETE | Statistika predpomnilnika / počisti |
/api/modality-bridge/stats |
GET | attempts v pomnilniku, uspehi/bridged, napake, zadetki v predpomnilniku, totalLatencyMs, latencySamples, vzorčno označen averageLatencyMs in čas zadnje uporabe (ponastavitev ob ponovnem zagonu; avtorizacija upravljanja) |
/api/modality-bridge/video/runtime |
GET | Strogo preverjanje zaupanja vredne povratne zanke pred upravljanjem auth/probe; razpoložljivost in različice prečiščenega FFmpeg/ffprobe (brez trgovine) |
/api/modality-bridge/video/extract |
POST | Notranji posrednik bajtov s preverjeno pristnostjo in povratno zanko; 50 MiB vhod, omejen queue/32 MiB izhod, 503 zmogljivost, 499 odklop, 504 rok; ni javno nalaganje API |
Vrtanje video okvirja
GET /api/v1/video-bridge/drilldown prebere nepregledno ročico, vezano na najemnika, vrnjeno v x-omniroute-video-drilldown po izrecno odobreni zahtevi Video Bridge. Tako reads kot DELETE vedno zahtevata veljaven ključ API in operaterjevo neodvisno dovoljenje modalityBridgeVideoDrilldownRemoteEnabled. Zadrževanje proizvodnje dodatno zahteva modalityBridgeVideoDrilldownEnabled in strogi drilldown: true na del. Če ima ključ neprazen seznam dovoljenih končnih točk, mora vsebovati video za GET in DELETE, ne glede na to, ali klicatelj uporablja /v1 ali /api/v1.
GET poizvedba: zahtevano handle; izbirni variant (preview, standard, detail), limit (1–8; starejši frames je sprejet, vendar ga ni mogoče kombinirati z limit), page na osnovi nič in start/end sekunde. Ko sta podani obe meji fokusa, mora biti end večji od start. poizvedbeni ključi Duplicate/unknown so zavrnjeni. Uspešni odgovori vsebujejo derivation, durationSeconds, frames, hasMore, page, variant in neobvezno focusWindow; JSON brez shranjevanja je omejen na 32 MiB, vključno z Base64. Prevelik izhod vrne 413; zahtevajte manj okvirjev.
DELETE /api/v1/video-bridge/drilldown?handle=... vrne { "removed": 0|1 }. Neznan, potekel in navzkrižni ključ GETs so nerazločljivi odgovori 404; križni ključ DELETE ne more odstraniti vnosa lastnika. Onemogočen dostop vrne 403, preverjanje pristnosti missing/invalid 401, neveljavne poizvedbe 400, preklic 499 in začasne napake 503. Ročaji so lokalni za proces, potečejo po desetih minutah in ne preživijo ponovnega zagona. Novi ročaji uporabljajo v1. in 32-bajtni naključni žeton Base64URL ; ohranjeni so le zgoščeni žetoni. Podedovani 64-hex žetoni ostajajo sintaktično berljivi zaradi združljivosti. Za podrobnosti o soglasju, kvotah in izpeljavi različic glejte Varovalne ograje Video Bridge.
Varnostno kopiranje in Export/Import
| Končna točka | Metoda | Opis |
|---|---|---|
/api/db-backups |
GET | Seznam razpoložljivih varnostnih kopij |
/api/db-backups |
PUT | Ustvarite ročno varnostno kopijo |
/api/db-backups |
POST | Obnovi iz določene varnostne kopije |
/api/db-backups |
PATCH | Shrani nastavitve hrambe varnostne kopije (samo za operaterja) |
/api/db-backups |
DELETE | Obrezovanje shranjenih varnostnih kopij na nastavitve hrambe (samo za operaterja) |
/api/db-backups/export |
GET | Prenesite zbirko podatkov kot datoteko .sqlite |
/api/db-backups/import |
POST | Naložite datoteko .sqlite, da zamenjate bazo podatkov (?dryRun=true preverja samo) |
/api/db-backups/exportAll |
GET | Prenesite celotno varnostno kopijo kot arhiv .tar.gz |
/api/db-backups/export, /api/db-backups/exportAll in /api/settings/export-json izročijo vse shranjene poverilnice, zato zahtevajo sejo na nadzorni plošči ali lokalni CLI (ali prijava onemogočena). ključi API katerega koli obsega in žetoni dostopa oma_ dobijo 403. Obnovitve imajo isto mejo: POST /api/db-backups/import (vključno dryRun=true ), POST /api/db-backups (obnovitev po ID-ju) in POST /api/settings/import-json nadomestijo živo zbirko podatkov ali nastavitve, tako da poverilnica stroja tudi tam dobi 403 ; omniroute sync import pošlje lokalno poverilnico CLI. Enako velja za DELETE /api/db-backups (izrezovanje shranjenih varnostnih kopij) in PATCH /api/db-backups (nastavitve hrambe: vztrajne vrednosti poganjajo samodejno izrezovanje po vsaki varnostni kopiji). Izpis (GET) in ustvarjanje ročne varnostne kopije (PUT) ohranjata običajno avtorizacijo upravljanja.
Sinhronizacija v oblaku
| Končna točka | Metoda | Opis |
|---|---|---|
/api/sync/cloud |
Različne | Operacije sinhronizacije v oblaku |
/api/sync/initialize |
POST | Inicializacija sinhronizacije |
/api/cloud/* |
Različne | Upravljanje v oblaku |
Tuneli
| Končna točka | Metoda | Opis |
|---|---|---|
/api/tunnels/cloudflared |
GET | Preberite stanje Cloudflare Quick Tunnel install/runtime za nadzorno ploščo |
/api/tunnels/cloudflared |
POST | Omogoči ali onemogoči Cloudflare Quick Tunnel (action=enable/disable) |
/api/tunnels/ngrok |
GET | Preberite stanje izvajalnega časa tunela ngrok za nadzorno ploščo |
/api/tunnels/ngrok |
POST | Omogoči ali onemogoči tunel ngrok (action=enable/disable) |
CLI
| Končna točka | Metoda | Opis |
|---|---|---|
/api/cli-tools/claude-settings |
GET | status Claude CLI |
/api/cli-tools/codex-settings |
GET | status Codex CLI |
/api/cli-tools/droid-settings |
GET | Stanje Droid CLI |
/api/cli-tools/openclaw-settings |
GET | status OpenClaw CLI |
/api/cli-tools/runtime/[toolId] |
GET | Generično izvajalno CLI |
odgovori CLI vključujejo: installed, runnable, command, commandPath, runtimeMode, reason.
ACP
| Končna točka | Metoda | Opis |
|---|---|---|
/api/acp/agents |
GET | Seznam vseh zaznanih agentov (vgrajena + po meri) s statusom |
/api/acp/agents |
POST | Dodajte agenta po meri ali predpomnilnik zaznavanja osvežitve |
/api/acp/agents |
DELETE | Odstranite agenta po meri s parametrom poizvedbe id |
odziv GET vključuje agents[] (id, ime, binarno, različica, nameščeno, protokol, isCustom) in summary (skupaj, nameščeno, notFound, builtIn, po meri).
Odpornost in meje hitrosti
| Končna točka | Metoda | Opis |
|---|---|---|
/api/resilience |
GET/PATCH | čakalna vrsta zahtev Get/update, ohlajanje povezave, prekinitev ponudnika in nastavitve čakanja |
/api/resilience/reset |
POST | Ponastavite odklopnike ponudnika |
/api/resilience/model-cooldowns |
GET | Seznam aktivnih zaklepanja na (ponudnika, povezavo, model), razvrščenih po preostalem času |
/api/resilience/model-cooldowns |
DELETE | Počistite zaklepanje modela — body {provider, model} ali {all: true}, da izbrišete vse |
/api/rate-limits |
GET/POST | Status omejitve stopnje na račun (GET) ali preklop zaščite omejitve stopnje za povezavo (POST {connectionId, enabled}). Podprta pot pisanja za rateLimitProtection (nikoli spremenjena prek PUT /api/providers/[id]). Opomba: enabled: false onemogoči eksplicitno zaščito, vendar ne izključi aktivne povezave s ključem API iz globalne varnostne mreže za samodejno omogočanje (autoEnableApiKeyProviders). |
/api/rate-limit |
GET | Konfiguracija globalne omejitve hitrosti (zastarelo; vzdevek /api/rate-limits) |
Vse štiri poti
/api/resilience/*zahtevajo** upravljanje avt** (requireManagementAuth). Glejte Odpornost (razširjeno) za popolno razčlenitev prekinitve ponudnika v primerjavi z ohlajanjem povezave v primerjavi z zaklepom modela.
Evals
| Končna točka | Metoda | Opis |
|---|---|---|
/api/evals |
GET/POST | Seznam eval paketov / zagon ocene |
Politike
| Končna točka | Metoda | Opis |
|---|---|---|
/api/policies |
GET/POST/DELETE | Upravljanje politik usmerjanja |
Skladnost
| Končna točka | Metoda | Opis |
|---|---|---|
/api/compliance/audit-log |
GET | Dnevnik revizije skladnosti (zadnji N) |
v1beta (združljivo z Gemini)
| Končna točka | Metoda | Opis |
|---|---|---|
/v1beta/models |
GET | Seznam modelov v formatu Gemini |
/v1beta/models/{...path} |
POST | končna točka Gemini generateContent |
Te končne točke zrcalijo format GeminiAPI za odjemalce, ki pričakujejo izvorno združljivost Gemini SDK.
Notranji / sistemski APIs
| Končna točka | Metoda | Opis |
|---|---|---|
/api/init |
GET | Zaženite storitve sinhronizacije v ozadju (preverjanje upravljanja) |
/api/tags |
GET | Oznake modela, združljive z Ollama (za odjemalce Ollama ) |
/api/restart |
POST | Sproži eleganten ponovni zagon strežnika |
/api/shutdown |
POST | Sproži natančno zaustavitev strežnika |
/api/system/env/repair |
POST | Popravi spremenljivke okolja ponudnika OAuth |
/api/system/version |
GET | različica Current/latest, stanje posodobitve, kanal izdaje |
/api/system/version |
POST | Zaženite posodobitev z upoštevanjem uvajanja na najnovejšo različico |
Opomba: Te končne točke uporablja interno sistem ali za združljivost odjemalca 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 spremenljivke okolja 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 za izdajo
GET /api/system/version
Pot upravljanja samo s povratno zanko (admin auth). Vrne tekočo različico, zadnjo objavljeno različico in stanje samodejne posodobitve. releaseChannel in channels sta aditivna polja (rail 3.8.54); channel ohrani svoj pomen — način uvajanja, ki ga uporablja program za posodabljanje 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— npm kanal tekoče gradnje:nightlyza različice-nightly.*,nextza druge predizdaje (-rc.*,-beta.*,-alpha.*),ltsza stabilno različico starejše odchannels.latest, sicerlatest. Ista pravila kotscripts/release/dist-tag.mjs, ki izbere oznako dist-npm ob času objave.channels— je objavil glavo vsake oznake dist iznpm view omniroute dist-tags(nadomestni register HTTP ), predpomnjen z istim 10-minutnim TTL kotlatest.latestje vedno prisoten (vrne se na poljelatest, nato"unavailable");next,nightlyinltsse prikažejo le, če ta oznaka dist obstaja. ZahtevaCache-Control: no-cacheosveži obe iskanji.
Model kanala (latest = v3 do 4.0 GA, next = rc, nightly = develop gradnje, lts = v3 popravki po 4.0 GA) je opisan v docs/ops/RELEASE_STRATEGY.md.
Prepisovanje 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 izvozijo model drugega ponudnika, uporabljajo kvalificiran ID
(openrouter/deepgram/nova-3).
Zahteva:
curl -X POST http://localhost:20128/v1/audio/transcriptions \
-H "Authorization: Bearer your-api-key" \
-F "file=@recording.mp3" \
-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 z golim
deepgram/nova-3 ne uporablja OpenRouterja.
Podprti formati: mp3, wav, m4a, flac, ogg, webm.
Gemini Live (gemini/gemini-3.5-transcribe-live): prepisovanje v načinu datoteke prek Gemini Live
WebSocket (zahteva ključ API-ja Gemini). Datoteka se s programom ffmpeg
pretvori v mono PCM pri 16 kHz (ffmpeg mora biti na PATH, razen če je datoteka že mono PCM WAV pri 16 kHz), nato se
pretaka v sejo, končno besedilo pa se vrne kot { "text": "..." }. Izbirna polja obrazca language in prompt se posredujejo naprej. Omejitve: pri nalaganju datotek, večjih od 25 MiB, ali dekodiranem zvoku, daljšem od 10 minut, API vrne
413; če pretvorba traja več kot 60 s, se prekine in API vrne 504. Ključ API-ja se pošlje samo v glavi
x-goog-api-key, nikoli v URL-ju WebSocket.
Združljivost z Ollamo
Za odjemalce, ki uporabljajo format API-ja Ollama:
# Končna točka za klepet (format Ollama)
POST /v1/api/chat
# Seznam modelov (format Ollama)
GET /api/tags
Zahteve se samodejno prevedejo med formatoma Ollama in notranjimi formati.
Tokenizirani vzdevki VS Code / vzdevki brez glav
Te vzdevke uporabite, kadar integracija ne more dodati glave Authorization in mora imeti ključ API-ja vdelan v osnovni URL.
# Vzdevek kataloga v slogu OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# Vzdevka za klepet v slogu OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Vzdevka 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:
- Tokenizirani vzdevki ponovno uporabljajo iste obravnavalnike kot
/v1/*in/api/tags; oblike odgovorov ostanejo enake. - Kadar odjemalec podpira glave po meri, raje uporabite
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 združljivosti, 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):apiKeyIdje obvezen; vsaj eden oddailyLimitUsd,weeklyLimitUsdalimonthlyLimitUsdmora biti večji od nič. Izbirna polja:warningThreshold(0–1),resetInterval(daily|weekly|monthly),resetTime(HH:MM). Zastarela oblika{keyId, limit, period}vrne400 Bad Request.
Omejitve žetonov
Proračuni žetonov na ključ API (ločeni od zgoraj omenjenega proračuna, izraženega v USD). Uveljavljajo se neposredno na poti zahtevka: ko trenutna poraba v oknu za ključ doseže njegovo omejitev, se zahteve zavrnejo z 429 Too Many Requests. Omejitve je mogoče omejiti na določen model, provider ali jih uporabiti globalno za celoten ključ; kadar se z zahtevo ujema več omejitev, velja najbolj restriktivna.
# Izpiši omejitve žetonov ključa (vključuje porabo v živem 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):apiKeyIdinscopeType(model|provider|global) sta obvezna.scopeValueje obvezen, razen če jescopeTypeenakglobal(npr. ID modela za obsegmodel, ID ponudnika za obsegprovider).tokenLimitmora biti pozitivno celo število (pretvori se iz niza). Izbirno:id(izpustite pri ustvarjanju, navedite pri posodabljanju),resetInterval(daily|weekly|monthly, privzetomonthly),resetTime(HH:MM),enabled(privzetotrue). OdgovoriGETvsako omejitev obogatijo s podatkitokensUsed,remaining,windowStart,periodStartAtinnextResetAt. To je končna točka upravljavskega razreda (preverjanje pristnosti se centralno uveljavlja v avtentikacijskem cevovodu).
Obdelava zahtev
- Odjemalec pošlje zahtevo na
/v1/* - Upravljalnik poti pokliče
handleChat,handleEmbedding,handleAudioTranscriptionalihandleImageGeneration - Model se razreši (neposredni ponudnik/model ali vzdevek/kombinacija)
- Poverilnice se izberejo iz lokalne zbirke podatkov s filtriranjem razpoložljivosti računov
- Za klepet:
handleChatCorepreveri semantični/podpisni predpomnilnik in razreši nastavitve stiskanja kombinacije - Proaktivno stiskanje se izvede pred prevajanjem za ponudnika, kadar je omogočeno (
lite, Caveman, RTK ali zloženo) - Izvajalnik ponudnika pošlje zahtevo navzgor
- Odgovor se prevede nazaj v obliko odjemalca (klepet) ali vrne nespremenjen (vdelave/slike/zvok)
- Zabeležijo se poraba, analitika stiskanja in dnevniki zahtev
- Pri napakah se uporabi nadomestni postopek v skladu s pravili kombinacije
Celoten arhitekturni sklic: 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 preusmerjanje ID-ja modela v slogu OpenAI na kombinacijo.
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/model-combo-mappings |
Izpiš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 eno 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
Odhodne naročnine na spletne kavlje za dogodke OmniRoute (dokončanje zahtevka, izčrpanje kvote, rotacija ključa itd.).
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/webhooks |
Seznam spletnih kavljev (skrivnosti so maskirane v obliko <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šlji preskusni tovor na URL spletnega kavlja in vrni stanje dostave |
Preverjanje pristnosti: upravljavska seja/ključ API (requireManagementAuth).
Registrirani ključi (samodejno upravljanje)
Uporablja ga podsistem za samodejno upravljanje ključev za izdajanje in rotacijo ključev API pri zalednem ponudniku/računu, z dnevnimi/urnimi kvotami.
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/v1/registered-keys |
Seznam registriranih ključev (prikazana je samo maskirana predpona) |
| POST | /api/v1/registered-keys |
Izdaj nov registrirani ključ — telo: {name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}. Vrne surovi ključ enkrat. Ob zavrnitvi zaradi kvote vrne 429. |
| GET | /api/v1/registered-keys/[id] |
Pridobi metapodatke registriranega ključa (brez surovega ključa) |
| DELETE | /api/v1/registered-keys/[id] |
Prekliči 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) — isti varnostni mehanizem 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. Oglejte si tudi /v1/quotas/check in /v1/issues/report.
Protokol agentov
Naloge agentov v oblaku (Claude Code, Codex Cloud, OpenHands itd.), izvedene na daljavo v imenu uporabnikov OmniRoute.
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/v1/agents/tasks |
Prikaže seznam nalog — izbirno ?provider=, ?status=, ?limit= (1–500, privzeto 50) |
| POST | /api/v1/agents/tasks |
Ustvari nalogo — telo preveri CreateCloudAgentTaskSchema (providerId, prompt, source, options?). Vrne 201 z ovojnico naloge |
| DELETE | /api/v1/agents/tasks?id=... |
Izbriše nalogo |
| GET | /api/v1/agents/tasks/[id] |
Prebere nalogo — sinhrono osveži stanje iz nadrejenega agenta v oblaku, ko je nastavljen external_id |
| POST | /api/v1/agents/tasks/[id] |
Dejanja glede na diskriminator: {action: "approve"}, {action: "message", message} ali {action: "cancel"} |
| DELETE | /api/v1/agents/tasks/[id] |
Izbriše določeno nalogo po ID-ju |
Preverjanje pristnosti: za vsako metodo je zahtevano upravljavsko preverjanje pristnosti (
requireCloudAgentManagementAuth). Pred različico v3.8.0 te poti niso zahtevale preverjanja pristnosti — glejte commit588a0333za spremembo, ki ni združljiva s prejšnjimi različicami.
# Ustvari nalogo 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 posredniki
Odhodni posredniki HTTP(S)/SOCKS, ki jih je mogoče dodeliti ponudnikom, računom ali globalno.
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/v1/management/proxies |
Prikaže seznam posrednikov (z ?id= vrne enega; z ?id=&where_used=1 vrne graf dodelitev) |
| POST | /api/v1/management/proxies |
Ustvari posrednika — telo preveri createProxyRegistrySchema |
| PATCH | /api/v1/management/proxies |
Posodobi posrednika — telo preveri updateProxyRegistrySchema (zahteva id) |
| DELETE | /api/v1/management/proxies?id=...&force=1 |
Izbriše posrednika (uporabite force=1, da odstranite dodelitve) |
| GET | /api/v1/management/proxies/assignments |
Prikaže seznam dodelitev — mogoče je filtrirati po proxy_id, scope, scope_id; podajte resolve_connection_id=<id>, da razrešite aktivni posrednik za povezavo |
| PUT | /api/v1/management/proxies/assignments |
Dodeli — telo preveri proxyAssignmentSchema ({scope, scopeId?, proxyId?}). Počisti predpomnilnik dispečerja |
| PUT | /api/v1/management/proxies/bulk-assign |
Množično dodeli — telo preveri bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?}) |
| GET | /api/v1/management/proxies/health?hours=24 |
Združeno stanje posrednikov (število uspehov/neuspehov, zakasnitev) v določenem časovnem obdobju |
Preverjanje pristnosti: za vsako pot je potrebna upravljavska seja/ključ API (requireManagementAuth).
Opis naloge
POST /api/v1/management/proxies/[id]/assignmentsinPOST /api/v1/management/proxies/[id]/healthzagotavljata ploščati poti/assignmentsin/health, prikazani zgoraj — v kodni zbirki ni podpoti za posamezne ID-je.
Odpornost (razširjeno)
OmniRoute izpostavlja tri neodvisne mehanizme za začasne napake; spodnje upravljavske končne točke operaterjem omogočajo njihovo branje in preglasitev:
| Obseg | Shranjevanje stanja | Branje | Ponastavitev / čiščenje |
|---|---|---|---|
| Prekinjevalnik ponudnika | domain_circuit_breakers + pomnilnik |
/api/monitoring/health |
POST /api/resilience/reset |
| Ohlajanje povezave | rateLimitedUntil v povezavah ponudnikov |
/api/rate-limits, /api/providers/[id] |
(ponovno omogoči se z zakasnitvijo; počisti se prek PUT ponudnika) |
| Zaklep modela | Register razpoložljivosti modelov v pomnilniku | GET /api/resilience/model-cooldowns |
DELETE /api/resilience/model-cooldowns |
PATCH /api/resilience sprejema preglasitve prekinjevalnikov ponudnikov pod providerBreaker.oauth in providerBreaker.apikey. Vsak profil podpira degradationThreshold, failureThreshold in resetTimeoutMs; ista polja so izpostavljena 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"}'
# Počisti vse zaklepe
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
Celoten konceptualni referenčni opis in privzete vrednosti prekinjevalnikov: glejte CLAUDE.md → »Stanje izvajanja odpornosti« in docs/architecture/RESILIENCE_GUIDE.md.
Čakalna vrsta za omejevanje hitrosti in varnostni mehanizem za samodejno omogočanje
- Podprta pot za zapisovanje:
POST /api/rate-limitsz vsebino{"connectionId": "<id>", "enabled": true|false}je podprta upravljavska končna točka za preklapljanje zaščite pred omejevanjem hitrosti za povezavo.PUT /api/providers/[id]namerno ne spreminja ali preklapljarateLimitProtection(#11278). - Semantika
enabled: false: nastavitevenabled: falseodstrani izrecno zaščito za povezavo, vendar aktivne povezave API-ključev ne izloči iz globalnega varnostnega mehanizma za samodejno omogočanje (autoEnableApiKeyProviders = true). VreconcileEnabledConnections(open-sse/services/rateLimitManager.ts), stafalseinundefinedenakovredni; aktivne povezave API-ključev brez izrecne zaščite ostanejo zaščitene v okviru varnostnega mehanizma za samodejno omogočanje. - Globalna onemogočitev: če želite povezave API-ključev izvajati brez čakalnih vrst za omejevanje hitrosti, globalno onemogočite varnostni mehanizem prek
RATE_LIMIT_AUTO_ENABLE=false(okoljska spremenljivka) aliresilienceSettings.requestQueue.autoEnableApiKeyProviders = false(Nastavitve → Odpornost /PATCH /api/resilience).
Zmožnosti
Ogrodje zmožnosti za razširjanje OmniRoute s poljubnimi izvršljivimi obdelovalniki ter integracijami tržnice.
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/skills |
Seznam nameščenih zmožnosti — filtriranje po ?q=, ?mode=on|off|auto, ?source=skillsmp|skillssh|local, s paginacijo |
| GET | /api/skills/[id] |
Pridobi eno zmožnost |
| PUT | /api/skills/[id] |
Posodobi zmožnost (ime, opis, način, shemo, obdelovalnik, oznake) |
| DELETE | /api/skills/[id] |
Odstrani zmožnost |
| POST | /api/skills/install |
Namesti zmožnost iz surovega manifesta — vsebina: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?} |
| GET | /api/skills/executions |
Seznam nedavnih izvajanj zmožnosti (revizijska sled z vhodi/izhodi/trajanjem) |
| GET | /api/skills/marketplace?q=... |
Iskanje/seznam priljubljenih zmožnosti iz tržnice SkillsMP (zahteva nastavitev skillsmpApiKey) |
| POST | /api/skills/marketplace/install |
Namesti zmožnost po ID-ju iz SkillsMP |
| GET | /api/skills/skillssh?q=&limit= |
Iskanje v registru skills.sh |
| POST | /api/skills/skillssh/install |
Namesti zmožnost po ID-ju iz skills.sh |
Overjanje: upravljavska seja/ključ API. Iskalne poti tržnice sprejemajo bodisi upravljavsko overjanje bodisi ključ API Bearer (isAuthenticated).
Pomnilnik
Trajno skladišče pogovornega/dejstvenega pomnilnika, omejeno na ključ API-ja/sejo.
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/memory |
Seznam pomnilnikov — ?apiKeyId=, ?type=, ?sessionId=, ?q=, s paginacijo offset/limit ali page/limit |
| POST | /api/memory |
Ustvari pomnilnik — telo, preverjeno z Zodom: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?} |
| GET | /api/memory/[id] |
Pridobi en pomnilnik |
| DELETE | /api/memory/[id] |
Izbriši pomnilnik |
| GET | /api/memory/health |
Stanje podsistema pomnilnika (povezljivost z DB, zaledje za vdelave, stanje vektorskega indeksa) |
Preverjanje pristnosti: seja/ključ API-ja za upravljanje (requireManagementAuth). type ima naštete vrednosti: 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 transporti (stdio, SSE, streamable-http) in orodji z omejenim obsegom. Spodnje končne točke nadzorne plošče berejo podatke o stanju in reviziji ter posredujejo transporte HTTP.
| Metoda | Pot | Opis | -------------------- |
|---|---|---|---|
| GET | /api/mcp/status |
Utrip, transport, stanje povezave, zadnji klic, najbolj uporabljena orodja, 24-urna stopnja uspešnosti | |
| GET | /api/mcp/tools |
Seznam orodij MCP z name, description, scopes, phase, auditLevel, sourceEndpoints |
|
| GET | /api/mcp/sse |
Odpre tok SSE za transport SSE (vrne 503, če je MCP onemogočen ali se transporta ne ujemata) |
|
| POST | /api/mcp/sse |
Pošlje okvir JSON-RPC prek transporta SSE | |
| GET | /api/mcp/stream |
Odpre stran SSE transporta Streamable HTTP (sporočila, ki jih sproži strežnik) | |
| POST | /api/mcp/stream |
Pošlje okvir JSON-RPC prek transporta Streamable HTTP | |
| DELETE | /api/mcp/stream |
Konča sejo Streamable HTTP | |
| GET | /api/mcp/audit |
Poizveduje dnevnik revizije — ?limit=, ?offset=, ?tool=, `?success=true |
false, ?apiKeyId=` |
| GET | /api/mcp/audit/stats |
Zbrane statistike revizije (skupne vrednosti, stopnja uspešnosti, povprečno trajanje, najbolj uporabljena orodja) |
Preverjanje pristnosti: transporta sse/stream upoštevata za MCP značilno površino za preverjanje pristnosti (ključ API-ja Bearer z obsegom mcp); poti status/tools/audit* so berljive z nadzorne plošče (brez dodatnega preverjanja pristnosti, poleg dostopa do gostitelja nadzorne plošče).
Oba transporta HTTP sta omejena z
settings.mcpEnabledinsettings.mcpTransport— neujemanje transporta vrne400, onemogočeno stanje MCP pa vrne503.
Strežnik A2A
OmniRoute izpostavlja končno točko A2A (Agent-to-Agent) JSON-RPC 2.0 in ovoj REST za pregled ter uporabo nadzorne plošče.
JSON-RPC
POST /a2a
Authorization: Bearer your-api-key # neobvezno, 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 glede na settings.a2aEnabled):
| Metoda | Opis |
|---|---|
message/send |
Sinhrono izvajanje veščine; vrne {task, artifacts, metadata} |
message/stream |
Pretočno izvajanje SSE istega nabora veščin |
tasks/get |
Pridobitev opravila prek taskId |
tasks/cancel |
Preklic opravila prek 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 1 h. Preverjanje pristnosti ni zahtevano.
Pomožni REST-klici
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/a2a/status |
Stanje A2A + statistika opravil + povzetek predpomnjene 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žni REST-klic — ustvarite prek JSON-RPC message/send) |
| GET | /api/a2a/tasks/[id] |
Pridobitev enega opravila |
| POST | /api/a2a/tasks/[id]/cancel |
Preklic opravila |
Preverjanje pristnosti: pomožni REST-klici delujejo brez upravljavskega preverjanja pristnosti (berljivi so na nadzorni plošči); pot JSON-RPC /a2a uporablja žeton Bearer OMNIROUTE_API_KEY, če je konfiguriran.
Oblak, evalvacije in ocenjevanje
| Metoda | Pot | Opis | ||
|---|---|---|---|---|
| POST | /api/cloud/auth |
Preveri ključ Bearer in vrne zamaskirane povezave ponudnikov ter 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 |
Izpiše vzdevke modelov, kot so izpostavljeni sinhronizaciji z oblakom | ||
| GET | /api/assess |
Prebere najnovejše kategorizacije ocenjevanja (po ponudniku/modelu) | ||
| POST | /api/assess |
Zažene ocenjevanje — telo: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | /api/evals |
Izpiše vgrajene zbirke evalvacij + najnovejše zagone | ||
| POST | /api/evals |
Sproži zagon evalvacije | ||
| POST | /api/evals/suites |
Ustvari zbirko evalvacij po meri — telo preveri evalSuiteSaveSchema |
||
| GET | /api/evals/suites/[id] |
Pridobi zbirko evalvacij po meri |
Preverjanje pristnosti: /api/cloud/auth neposredno preveri ključ Bearer in vrne zamaskirani ključ ter projectId vsake povezave samo za ključ z obsegom manage / admin; druge poti /api/cloud/*, /api/evals/* in /api/assess zahtevajo upravljavsko sejo/ključ API. POST za /api/assess uporablja validateBody z diskriminirano unijsko shemo obsega.
Upravljanje ACP (Agent Client Protocol)
kot podrejeni procesi. Te končne točke upravljajo zaznavanje agentov ACP in registracijo agentov po meri.
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/acp/agents |
Seznam vseh znanih agentov CLI (vgrajenih in po meri) s stanjem namestitve, različico in dvojiško datoteko |
| POST | /api/acp/agents |
Registracija agenta ACP po meri ali osvežitev predpomnilnika — telo: {id, name, binary, versionCommand, providerAlias, spawnArgs, protocol} ali {action: "refresh"} |
| DELETE | /api/acp/agents |
Odstranitev 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: Zahteva sejo upravljanja (piškotek auth_token na nadzorni plošči) ali ključ API z obsegom upravljanja.
Za vse podrobnosti glejte ogrodje ACP.
Analitika in opazljivost
Končne točke za analitiko v realnem času za spremljanje usmerjanja, stiskanja in
raznolikosti ponudnikov. Te poganjajo strani /dashboard/analytics/*.
Analitika samodejnega usmerjanja
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/analytics/auto-routing |
Zbirna statistika samodejnega usmerjanja: skupno število klicev, porazdelitev strategij, porazdelitev ravni, najpogostejši ponudniki |
| GET | /api/analytics/auto-routing?days=7 |
Statistika za časovno obdobje (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 |
Zbirna statistika stiskanja: prihranjeni žetoni, odstotek 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
}
}
Sledenje raznolikosti ponudnikov
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/analytics/diversity |
Sledenje raznolikosti na podlagi Shannonove entropije: preprečuje posamezne točke odpovedi z merjenjem razpršenosti ponudnikov |
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: Zahteva sejo upravljanja ali ključ API z obsegom upravljanja.
Skrbniške operacije
Končne točke, namenjene samo skrbnikom, za operativno upravljanje.
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/admin/concurrency |
Prebere trenutne omejitve sočasnosti (globalne + za posameznega ponudnika) |
| POST | /api/admin/concurrency |
Posodobi omejitve sočasnosti — telo: {global?: number, perProvider?: Record<string, number>} |
Preverjanje pristnosti: Zahteva skrbniško sejo za upravljanje z obsegom skrbnika.
Upravljanje orodij CLI
Upravljajte orodja CLI, ki se integrirajo z OmniRoute (antigravity, commandCode, devin-cli itd.). Celoten seznam je na voljo v referenci ponudnikov.
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/cli-tools/all-statuses |
Stanje vseh orodij CLI (nameščeno, različica, nazadnje zaznano) |
| GET | /api/cli-tools/status |
Podrobnosti o stanju enega orodja CLI (poizvedba ?tool=) |
| POST | /api/cli-tools/apply |
Zapiše ustvarjeno konfiguracijo orodja (dryRun prikaže predogled; 422 + containerEphemeralTarget pri uporabi vsebnikov; migration zabeleži opombe o starejšem YAML-u Codexa) |
| GET | /api/cli-tools/backups |
Prikaže varnostne kopije konfiguracij orodij CLI |
| POST | /api/cli-tools/backups |
Ustvari varnostno kopijo vseh konfiguracij orodij CLI |
| POST | /api/cli-tools/backups |
Obnovitev: ista končna točka s {tool, backupId} v telesu obnovi to varnostno kopijo |
| GET | /api/cli-tools/antigravity-mitm |
Stanje posredniškega strežnika MITM za Antigravity (orodje CLI »antigravity-mitm«) |
| POST | /api/cli-tools/antigravity-mitm/alias |
Konfigurira vzdevke za antigravity-mitm |
Preverjanje pristnosti: Zahteva sejo za upravljanje.
Veščine agentov
Upravljajte veščine agentov UI (podobno kot uporabniško določeni GPT-ji OpenAI, vendar za agente).
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/agent-skills |
Prikaže vse veščine agentov (vgrajene + uporabniško določene) |
| GET | /api/agent-skills/[id] |
Pridobi določeno veščino agenta |
| POST | /api/agent-skills |
Ustvari uporabniško določeno veščino agenta — telo: {name, description, prompt, model?, temperature?} |
| PUT | /api/agent-skills/[id] |
Posodobi uporabniško določeno veščino agenta |
| DELETE | /api/agent-skills/[id] |
Izbriše uporabniško določeno veščino agenta |
| GET | /api/agent-skills/[id]/raw |
Pridobi neobdelan poziv + metapodatke (brez izvajanja) |
| POST | /api/agent-skills/generate |
Ustvari novo veščino s pomočjo UI iz opisa v naravnem jeziku |
Preverjanje pristnosti: Zahteva sejo za upravljanje ali ključ API z obsegom upravljanja.
Upravljanje predpomnilnika
Upravljajte semantični predpomnilnik in predpomnilnik sklepanja.
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/cache |
Pregled predpomnilnika: skupno število vnosov, stopnja zadetkov, velikost na disku |
| GET | /api/cache/entries |
Seznam predpomnjenih vnosov (s paginacijo) |
| DELETE | /api/cache/entries |
Brisanje vnosov predpomnilnika (filtriranje s parametri 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 |
Počisti predpomnilnik sklepanja — parametri poizvedbe: ?toolCallId=<id> (posamezen), ?provider=<p> ali brez parametrov (vse) |
Avtentikacija: Zahteva upravljavsko sejo.
Pomnilniški sistem
Upravljajte trajni pomnilnik (FTS5 + vektorske vdelave).
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/memory |
Seznam pomnilniških vnosov (filtriranje po obsegu, vrsti in iskalni poizvedbi) |
| POST | /api/memory |
Ustvarjanje novega pomnilniškega vnosa — telo: {scope, type, content, metadata?} |
| GET | /api/memory/[id] |
Pridobivanje določenega pomnilniškega vnosa |
| PUT | /api/memory/[id] |
Posodabljanje pomnilniškega vnosa |
| DELETE | /api/memory/[id] |
Brisanje pomnilniškega vnosa |
| GET | /api/memory?q= |
Iskanje po pomnilniku (FTS5 + vektor) — statistika je vključena v istem odzivu |
Avtentikacija: Zahteva upravljavsko sejo ali ključ API z obsegom upravljanja.
Spletni kavlji
Upravljajte naročnine na spletne kavlje za dogodke.
| Metoda | Pot | Opis |
|---|---|---|
| GET | /api/webhooks |
Seznam vseh naročnin na spletne kavlje |
| POST | /api/webhooks |
Ustvarjanje naročnine na spletni kavelj — telo: {url, events[], secret?, active?} |
| GET | /api/webhooks/[id] |
Pridobivanje določene naročnine na spletni kavelj |
| PUT | /api/webhooks/[id] |
Posodabljanje naročnine na spletni kavelj |
| DELETE | /api/webhooks/[id] |
Brisanje naročnine na spletni kavelj |
| GET | /api/webhooks/[id]/deliveries |
Seznam zgodovine dostav za spletni kavelj (dnevnik uspehov/neuspehov) |
| POST | /api/webhooks/[id]/test |
Pošiljanje preizkusnega dogodka spletnemu kavlju |
Avtentikacija: Zahteva upravljavsko sejo.
Za celoten seznam vrst dogodkov glejte ogrodje spletnih kavljev.
Ogrodje veščin
Upravljanje veščin (ogrodje agentnih razširitev).
| Method | Path | Description |
|---|---|---|
| GET | /api/skills |
Seznam vseh nameščenih veščin (vgrajenih + po meri) |
| POST | /api/skills/install |
Namestitev veščine z lokalne poti ali URL-ja |
| DELETE | /api/skills/[id] |
Odstranitev veščine |
| PUT | /api/skills/[id] |
Omogočanje ali onemogočanje veščine — telo: {enabled?: boolean, mode?: "on" | "off" | "auto"} |
| POST | /api/skills/executions |
Izvedba veščine — telo: {skillName, apiKeyId, input?, sessionId?} |
| GET | /api/skills/executions |
Seznam zgodovine izvajanj za vse veščine (filtriranje z ?apiKeyId=) |
Preverjanje pristnosti: Zahteva sejo za upravljanje ali ključ API z obsegom upravljanja.
Za vse podrobnosti glejte Ogrodje veščin.
Vtičniki
Upravljanje vtičnikov OmniRoute (razširitve tretjih oseb).
| Method | Path | Description |
|---|---|---|
| GET | /api/plugins |
Seznam nameščenih vtičnikov |
| POST | /api/plugins/marketplace/install |
Namestitev vtičnika iz tržnice |
| DELETE | /api/plugins/[name] |
Odstranitev vtičnika |
| POST | /api/plugins/[name]/activate |
Aktiviranje vtičnika |
| POST | /api/plugins/[name]/deactivate |
Deaktiviranje vtičnika |
| GET | /api/plugins/[name]/config |
Pridobitev konfiguracije vtičnika |
| PUT | /api/plugins/[name]/config |
Posodobitev konfiguracije vtičnika |
Preverjanje pristnosti: Zahteva sejo za upravljanje.
Za vse podrobnosti glejte Ogrodje vtičnikov.
Senčno usmerjanje
Senčna primerjava ponudnikov / primerjava A-B ni samostojna površina REST — konfigurira se prek kombiniranega usmerjanja (glejte Samodejna kombinacija). Meritve primerjave za posamezno kombinacijo zagotavlja GET /api/combos/metrics.
Zaščitni mehanizmi
Preglejte izvajalne zaščitne mehanizme (zaznavanje osebnih podatkov, zaznavanje vbrizgavanja pozivov, povezovanje vida). Zaščitni mehanizmi se izvajajo pri vsaki zahtevi; izključitev za posamezen klic se izvede prek glave zahteve x-omniroute-disabled-guardrails — ni trajne možnosti za omogočanje/onemogočanje.
| Method | Path | Description |
|---|---|---|
| GET | /api/guardrails |
Seznam registriranih zaščitnih mehanizmov in njihovega stanja (ime / omogočeno / prioriteta) |
| POST | /api/guardrails/test |
Suhi zagon cevovoda pred klicem nad vzorčnim vnosom — telo: {input, disabledGuardrails?} |
Preverjanje pristnosti: Zahteva sejo za upravljanje.
Za vse podrobnosti glejte Varnost > Zaščitni mehanizmi.
Preverjanje pristnosti
Glejte Preverjanje pristnosti za upravljanje za štiri družine poverilnic (seja nadzorne plošče, lokalni žeton CLI, žeton za dostop oma_live_…, ključ API z obsegom upravljanja) in za informacije o tem, kako se razlikujejo od ključev za sklepanje.
- Poti nadzorne plošče (
/dashboard/*) uporabljajo piškotekauth_token - Prijava uporablja shranjeno zgoščeno vrednost gesla; nadomestna možnost je
INITIAL_PASSWORD - Preklop
requireLoginje mogoče upravljati prek/api/settings/require-login - Poti
/v1/*lahko obvezno zahtevajo nosilni ključ API, ko jeREQUIRE_API_KEY=true - »management token« / »management-scoped API key« v tem sklicu pomeni eno od družin iz tega vodnika — ne nedefinirane dodatne vrste skrivnosti
Nezdružljiva sprememba (v3.8.0) —
/api/v1/agents/tasks/*in končne točke za upravljanje ohlajanja zdaj zahtevajo preverjanje pristnosti za upravljanje (piškotekauth_tokennadzorne plošče ali ključ API z obsegom upravljanja). Odjemalci, ki so te poti prej klicali brez preverjanja pristnosti, bodo prejeli401 Unauthorized. Glejte commit588a0333(fix(auth): require management auth for agent and cooldown APIs).