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

188 KiB
Raw Permalink Blame History

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

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čite underscores_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/messages in /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.0000000000 za 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-Hit in X-OmniRoute-Fallback-Attempts (samo, kadar je vrednost > 0), poleg X-OmniRoute-Request-Id in X-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/generations in /v1/moderations (vedno s stroškom 0). Strošek predstavnosti se izračuna glede na posamezno modalnost (na sliko, sekundo, znak ali iskalno enoto), kadar so cene na voljo, sicer je 0 (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 je X-OmniRoute-Response-Cost 0.0000000000 (inkrementalni strošek zagotavljanja zadetka). Izvirni/predvideni strošek je ločeno naveden v X-OmniRoute-Cost-Saved. Odjemalci za obračunavanje naj seštevajo X-OmniRoute-Response-Cost (zadeti vnosi nič ne stanejo); analitika predpomnilnika lahko združi X-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 off ali default, 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}:embedContent z content.parts (text ali inline_data).
  • llama.cpp (llama-cpp/<model>, kateri koli model, ki ga je naložil lokalni strežnik): kanonični elementi text postanejo navadni nizi, elementi image / audio / video pa vsak svoj objekt {"content": [part]}, pri čemer se uporabijo deli vsebine za klepet strežnika llama-server (image_url, input_audio z oblikami wav / 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. document ni 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-2 uporablja ZenMux-jeve slike OpenAI API. Možnosti vključujejo size, quality, n, output_format, output_compression, background in response_format.
  • Drugi založniki, kot je zm/meta/muse-image-1.0, uporabljajo ZenMux-jevo končno točko Vertex AI :predict. n se preslika v sampleCount, aspect_ratio v aspectRatio in image_size (1K, 2K, 4K) v sampleImageSize. Piksel size zagotavlja 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-design izbere svoje dimenzije. Izpustite size, aspect_ratio in image_size; eksplicitne vrednosti vrnejo HTTP 400. PNG, JPEG in WebP lahko zahtevate z output_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 nimajo pricing.
  • Brezplačni modeli prikazujejo "0" (in 0), 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 spremenijo prompt ali completion.
  • Objekt je enak za vse načine preverjanja pristnosti, vključno z zahtevo v slogu Anthropic z x-api-key in anthropic-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/rerank usmerja 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 v OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS (npr. ime storitve Docker/Compose, kot je http://reranker:8080/v1; ta vozlišča se kličejo neposredno, nikoli prek HTTP(S)_PROXY ali 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 funkcije RERANK_REMOTE_PROVIDER_NODES in 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 za rerankProviderModel v nastavitvah pomnilnika.

Oblike lokalnega strežnika: vozlišče se kliče na <base>/v1/rerank in 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 na top_n.

Odkrivanje vozlišč ponudnikov: modeli na vozlišču ponudnika, združljivem z OpenAI, se prikažejo v GET /v1/models pod predpono vozlišča. Vrstice brez metapodatkov o končni točki (kar je običajno pri lokalnih seznamih /v1/models) podedujejo apiType vozlišča, zato so modeli vozlišča embeddings vrste type: "embedding", modeli vozlišča rerank pa vrste type: "rerank" in ne privzeto vrste chat; izrecno navedena supportedEndpoints v sinhronizirani ali ročno dodani vrstici ima še vedno prednost.

Namenske poti ponudnikov

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

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: vrne 0%.
  • Č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 povezave quotaWindowThresholds brez 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 quotaWindowThresholds za preglasitve na ravni povezave.

Semantični predpomnilnik

# Pridobi statistiko predpomnilnika
GET /api/cache/stats

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

Primer odgovora:

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

Vpliv na zakasnitev

ZADETEK 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_index je ID povezave OmniRoute. provider je claude ali codex (samo povezave OAuth; ponudnik ključev API-ja anthropic ni naveden). Pri Codexu je id_token.chatgpt_account_id shranjeni ID delovnega prostora, plan_type pa shranjeni načrt.
  • api-call ni generični posrednik. Sprejema samo Claude GET https://api.anthropic.com/api/oauth/usage in Codex GET https://chatgpt.com/backend-api/wham/usage, GET .../wham/rate-limit-reset-credits ter POST .../wham/rate-limit-reset-credits/consume, pri čemer je vsaka zahteva dovoljena samo za račun ustreznega ponudnika. Vse drugo vrne 403, ne da bi vzpostavilo stik z upstreamom. Glava Authorization klicatelja (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). Če Chatgpt-Account-Id manjka, se privzeto uporabi shranjeni ID delovnega prostora. Zahteve potečejo po 15 sekundah in uporabljajo posredniški strežnik povezave.
  • reset-quota pusti končna stanja (banned, expired, credits_exhausted) nespremenjena. Neznan auth_index vrne 404.

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: nightly za različice -nightly.*, next za druge predizdaje (-rc.*, -beta.*, -alpha.*), lts za stabilno različico starejše od channels.latest, sicer latest. Ista pravila kot scripts/release/dist-tag.mjs, ki izbere oznako dist-npm ob času objave.
  • channels — je objavil glavo vsake oznake dist iz npm view omniroute dist-tags (nadomestni register HTTP ), predpomnjen z istim 10-minutnim TTL kot latest. latest je vedno prisoten (vrne se na polje latest, nato "unavailable"); next, nightly in lts se prikažejo le, če ta oznaka dist obstaja. Zahteva Cache-Control: no-cache osvež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): apiKeyId je obvezen; vsaj eden od dailyLimitUsd, weeklyLimitUsd ali monthlyLimitUsd mora biti večji od nič. Izbirna polja: warningThreshold (0–1), resetInterval (daily | weekly | monthly), resetTime (HH:MM). Zastarela oblika {keyId, limit, period} vrne 400 Bad Request.

Omejitve žetonov

Proračuni žetonov 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): apiKeyId in scopeType (model | provider | global) sta obvezna. scopeValue je obvezen, razen če je scopeType enak global (npr. ID modela za obseg model, ID ponudnika za obseg provider). tokenLimit mora biti pozitivno celo število (pretvori se iz niza). Izbirno: id (izpustite pri ustvarjanju, navedite pri posodabljanju), resetInterval (daily | weekly | monthly, privzeto monthly), resetTime (HH:MM), enabled (privzeto true). Odgovori GET vsako omejitev obogatijo s podatki tokensUsed, remaining, windowStart, periodStartAt in nextResetAt. To je končna točka upravljavskega razreda (preverjanje pristnosti se centralno uveljavlja v avtentikacijskem cevovodu).

Obdelava zahtev

  1. Odjemalec pošlje zahtevo na /v1/*
  2. Upravljalnik poti pokliče handleChat, handleEmbedding, handleAudioTranscription ali handleImageGeneration
  3. Model se razreši (neposredni ponudnik/model ali vzdevek/kombinacija)
  4. Poverilnice se izberejo iz lokalne zbirke podatkov s filtriranjem razpoložljivosti računov
  5. Za klepet: handleChatCore preveri semantični/podpisni predpomnilnik in razreši nastavitve stiskanja kombinacije
  6. Proaktivno stiskanje se izvede pred prevajanjem za ponudnika, kadar je omogočeno (lite, Caveman, RTK ali zloženo)
  7. Izvajalnik ponudnika pošlje zahtevo navzgor
  8. Odgovor se prevede nazaj v obliko odjemalca (klepet) ali vrne nespremenjen (vdelave/slike/zvok)
  9. Zabeležijo se poraba, analitika stiskanja in dnevniki zahtev
  10. 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 commit 588a0333 za 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]/assignments in POST /api/v1/management/proxies/[id]/health zagotavljata ploščati poti /assignments in /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-limits z 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 preklaplja rateLimitProtection (#11278).
  • Semantika enabled: false: nastavitev enabled: false odstrani izrecno zaščito za povezavo, vendar aktivne povezave API-ključev ne izloči iz globalnega varnostnega mehanizma za samodejno omogočanje (autoEnableApiKeyProviders = true). V reconcileEnabledConnections (open-sse/services/rateLimitManager.ts), sta false in undefined enakovredni; 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) ali resilienceSettings.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.mcpEnabled in settings.mcpTransport — neujemanje transporta vrne 400, onemogočeno stanje MCP pa vrne 503.


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škotek auth_token
  • Prijava uporablja shranjeno zgoščeno vrednost gesla; nadomestna možnost je INITIAL_PASSWORD
  • Preklop requireLogin je mogoče upravljati prek /api/settings/require-login
  • Poti /v1/* lahko obvezno zahtevajo nosilni ključ API, ko je REQUIRE_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škotek auth_token nadzorne plošče ali ključ API z obsegom upravljanja). Odjemalci, ki so te poti prej klicali brez preverjanja pristnosti, bodo prejeli 401 Unauthorized. Glejte commit 588a0333 (fix(auth): require management auth for agent and cooldown APIs).