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

API_REFERENCE (Slovenščina)

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

---

---

title: "Referenca API-ja" version: 3.8.51 lastUpdated: 2026-08-31

Referenca API-ja

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

Temeljna referenca za API OmniRoute. Zajema javni vmesnik /v1 in najpogosteje uporabljene končne točke za upravljanje; strojno berljiva datoteka docs/openapi.yaml in drevo poti v src/app/api/ sta izčrpna vira.

---

Kazalo vsebine

• Dokončanja klepeta
• Ekskluzivni zakupi upravljanih sej
• Vdelave
• Ustvarjanje slik
• OCR dokumentov
• Seznam modelov
• Manifest vtičnika ponudnika
• Končne točke za združljivost
• API za datoteke
• API za pakete
• API za iskanje
• Pretakanje prek WebSocket
• Kvote in poročanje o težavah
• Semantični predpomnilnik
• Nadzorna plošča in upravljanje
• Upravljanje kombinacij
• Spletni kavlji
• Registrirani ključi (samodejno upravljanje)
• Protokol agentov
• Posredniški strežniki za upravljanje
• Odpornost (razširjeno)
• Veščine
• Pomnilnik
• Strežnik MCP
• Strežnik A2A
• Oblak, vrednotenja in ocenjevanje
• Obdelava zahtev
• Preverjanje pristnosti

---

Dokončanja klepeta

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

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

Glave po meri

Glava	Smer	Opis
X-OmniRoute-No-Cache	Zahteva	Nastavite na true, da zaobidete predpomnilnik
x-omniroute-no-memory	Zahteva	Nastavite na true, da za to zahtevo preskočite vstavljanje pomnilnika in veščin (enako kot brez predpomnilnika; s tem se izognete režijskim žetonom in stroškom na posamezen klic)
X-OmniRoute-Progress	Zahteva	Nastavite na true za dogodke napredka
X-Session-Id	Zahteva	Ključ lepljive seje za zunanjo afiniteto sej
x_session_id	Zahteva	Sprejeta je tudi različica s podčrtajem (neposredni HTTP)
X-OmniRoute-Session-Id	Zahteva	Oznaka seje/pogovora, ki jo poda klicatelj (uporablja jo tudi pomnilnik). Ko je prisotna, se dobesedno shrani v call_logs.session_tag za pripisovanje stroškov po sejah (#8249) — če ni prisotna, se nikoli ne ustvari samodejno
Idempotency-Key	Zahteva	Ključ za odstranjevanje dvojnikov (5-sekundno okno)
X-Request-Id	Zahteva	Alternativni ključ za odstranjevanje dvojnikov
X-OmniRoute-Cache	Odgovor	HIT ali MISS (brez pretakanja)
X-OmniRoute-Idempotent	Odgovor	true, če je bil dvojnik odstranjen
X-OmniRoute-Progress	Odgovor	enabled, če je sledenje napredku vklopljeno
X-OmniRoute-Session-Id	Odgovor	Dejanski ID seje, ki ga uporablja OmniRoute
X-OmniRoute-Request-Id	Odgovor	Korelacijski ID zahteve (če je znan)
X-OmniRoute-Version	Odgovor	Različica graditve OmniRoute (vedno prisotna)
X-OmniRoute-Cost-Saved	Odgovor	Znesek v USD, ki ga je predpomnilnik pri zadetku HIT prihranil (samo zadetki predpomnilnika)
X-OmniRoute-Decision	Odgovor	Sled usmerjanja: strategy=<name>; provider=<alias>; latency_ms=<n> (<name> je strategija kombinacije oziroma single za zahtevo brez kombinacije) — vedno prisotna v odgovorih ob dokončanju

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

Glave telemetrije stroškov: uspešni odgovori brez pretakanja vsebujejo tudi nabor telemetrije stroškov X-OmniRoute-* — X-OmniRoute-Response-Cost (USD, fiksno 10 decimalnih mest; 0.0000000000 za brezplačne postavke oziroma postavke brez določene cene), X-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out, X-OmniRoute-Model, X-OmniRoute-Provider, X-OmniRoute-Latency-Ms, X-OmniRoute-Cache-Hit in X-OmniRoute-Fallback-Attempts (samo kadar je > 0), skupaj z X-OmniRoute-Request-Id in X-OmniRoute-Version. Te glave ustvarjajo dokončanja klepeta, /v1/responses, /v1/messages in končne točke za predstavnostne vsebine — /v1/embeddings, /v1/images/generations, /v1/audio/speech, /v1/audio/transcriptions, /v1/rerank, /v1/videos/generations, /v1/music/generations in /v1/moderations (strošek je vedno 0). Strošek predstavnostnih vsebin se izračuna glede na modalnost (na sliko, sekundo, znak oziroma iskalno enoto), kadar so cene na voljo, sicer je 0 (odprto delovanje ob napaki).

Semantika stroškov zadetka predpomnilnika: pri zadetku semantičnega predpomnilnika HIT (X-OmniRoute-Cache-Hit: true) se nadrejeni klic ne izvede, zato je X-OmniRoute-Response-Cost enak 0.0000000000 (inkrementalni strošek posredovanja zadetka). Izvirni oziroma predvideni strošek je naveden ločeno v X-OmniRoute-Cost-Saved. Odjemalci obračunavanja morajo seštevati X-OmniRoute-Response-Cost (zadetki ne stanejo nič); analitika predpomnilnika lahko združuje X-OmniRoute-Cost-Saved.

Ekskluzivni upravljani zakupi sej

Ekskluzivni upravljani zakup sej je izbirna pogodba o usmerjanju, neodvisna od odjemalca: en aktiven lastnik ima v zakupu eno ustrezno povezavo OmniRoute. Ne daje v zakup modela, ne zahteva OAuth, ne identificira določenega odjemalca in ne zahteva določenega ponudnika.

API-ključ za preverjanje pristnosti mora imeti obseg lease:exclusive in izrecen neprazen seznam allowedConnections. Meja mutacij zbirke podatkov uveljavlja obe polji skupaj pri ustvarjanju ključa in delnih posodobitvah.

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

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

Uspešni odgovori za pridobitev, podaljšanje in sprostitev razkrijejo časovne žige, state in natančno pozitivno vrednost generation, vendar nikoli izbrane povezave ali poverilnic. Pri podaljšanju in sprostitvi se vrednost generation navede v telesu JSON:

{ "action": "renew", "generation": 1 }

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

Lastnik aktivnega zakupa lahko izrecno zahteva prikazne metapodatke svoje trenutne vezave, ki ne ogrožajo zasebnosti:

{ "action": "status", "generation": 1 }

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

To izbirno dejanje za stanje je v eni transakciji zbirke podatkov zavarovano z neprozornim lastnikom, overjenim upravljanim API-ključem in natančno aktivno vrednostjo generation. displayName je samo obrezano konfigurirano ime povezave; če varno konfigurirano ime ne obstaja, je njegova vrednost null. OmniRoute ga nikoli ne nadomesti z e-poštnim naslovom ali ustvarjeno identiteto računa. Vrednost ponudnika je neobčutljiva prikazna oznaka in nikoli ustvarjen identifikator združljivega ponudnika. Poverilnice, žetoni, piškotki, neobdelani identifikatorji povezav ali API-ključev, zgoščene vrednosti lastnikov, skrivnosti za zavarovanje in notranji podatki o usmerjanju so izključeni.

Poizvedbe z napačnim ključem, napačnim lastnikom, zastarelo vrednostjo generation ter poizvedbe za manjkajoče, potekle, sproščene ali razveljavljene zakupe vrnejo isto napako 409 LEASE_FENCE_STALE brez metapodatkov povezave. Odjemalec, ki je prejel odgovor o čakanju na zmogljivost, nima aktivne vezave, ki bi jo lahko pregledal. Ko usmerjanje spremeni vezavo aktivnega zakupa, ista vrednost generation ostane veljavna, stanje pa atomsko vrne novo vezavo in nikoli stare. Obstoječi odjemalci ostanejo nespremenjeni, ker odgovori za pridobitev, podaljšanje, sprostitev in čakanje ohranijo svoje prejšnje oblike.

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

Vsaka upravljana zahteva za sklepanje nato navede obe nadzorni glavi:

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

Natančen lastnik, vrednost generation, aktivna povezava in overjeni API-ključ so zavarovani neposredno pred vsakim podprtim poskusom pri nadrejeni storitvi. Ponovna uporaba lastnika in vrednosti generation z drugim ključem ne uspe, tudi če ta ključ dovoljuje isto povezavo. Neobdelani podatki o lastnikih se ne shranjujejo, beležijo, ohranjajo v posnetku zahteve ali posredujejo nadrejeni storitvi.

Začasna prezasedenost 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 običajna množica ustreznih povezav ni bila prazna in da je vsak prosti kandidat pripadal tujemu aktivnemu zakupu. Nepodprti modeli/ponudniki, neujemanje pravilnikov, obdobje ohlajanja, kvota, stanje ustreznosti in druge običajne napake pri preverjanju ustreznosti ohranijo obstoječe odgovore OmniRoute.

x-omniroute-compression

Preglasitev načrta stiskanja za posamezno zahtevo. Ima najvišjo prednost — preglasi preglasitev usmerjevalne kombinacije, aktivni profil, samodejni sprožilec in privzeto nastavitev na plošči. Vrednosti:

Vrednost	Učinek
off	Brez stiskanja za to zahtevo.
default	Profil Default, izpeljan iz plošče (prezre aktivni profil).
engine:<id>	En sam omogočen mehanizem, npr. engine:rtk.
<combo>	Poimenovana kombinacija, ki se najprej ujema po imenu (brez razlikovanja med velikimi in malimi črkami), nato po id.

Opombe:

• Neznane vrednosti so prezrte (zahteva ni nikoli zavrnjena); razreševanje se nadaljuje po običajnem prednostnem vrstnem redu operatorjev.
• Če ima več kombinacij isto ime, za deterministično ujemanje navedite id kombinacije.
• Kombinacije z imenom off ali default ni mogoče izbrati po imenu (ti ključni besedi se razložita najprej); tako kombinacijo navedite z njenim id.
• Glavno stikalo za stiskanje je stroga omejitev: ko je stiskanje globalno onemogočeno, ga ta glava ne more omogočiti.

Uporabljeni načrt se ponovi 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.

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

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

Jina v5 Omni (jina-ai/jina-embeddings-v5-omni-small, jina-ai/jina-embeddings-v5-omni-nano in vzdevek družine jina-ai/jina-embeddings-v5-omni → omni-small) sprejme tudi Jina izvorne dokumente EmbeddingsV5Request ter jih nespremenjene posreduje na https://api.jina.ai/v1/embeddings:

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

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

Varnostne in transportne omejitve:

• URL-ji oddaljenih predstavnostnih vsebin morajo biti javni in uporabljati HTTPS. Kanonični elementi {type,source:url} se pridobijo na strani strežnika (ponovno preverjanje preusmeritev, časovna omejitev, omejitve velikosti, javni DNS, pripenjanje povezave) ter vključijo neposredno pred klicem ponudnika. Izvorni elementi Jina {image:"https://..."} se posredujejo nespremenjeni po enakem preverjanju javnega HTTPS-ja; Jina pridobi URL.
• Predstavnostne vsebine base64 v zahtevi so omejene na 8 MiB dekodiranih podatkov na element in 16 MiB dekodiranih podatkov v celotni zahtevi.

Pretvorba za ponudnika (kanonični elementi se nikoli ne posredujejo nespremenjeni):

• Večmodalni modeli Jina: vsak element na najvišji ravni postane en objekt s ključem modalnosti (text / image / audio / video / pdf), ki za neposredno vključene predstavnostne vsebine uporablja URI-je data; en vektor na element najvišje ravni.
• Družina Gemini Embedding 2: eno polje najvišje ravni postane ena izvorna zahteva models/{model}:embedContent z content.parts (text ali inline_data).
• Neznani/dinamični modeli brez izrecnih metapodatkov o modalnosti zavrnejo strukturiran vnos z napako HTTP 400.

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}

Nepodprte kombinacije modela in modalnosti vrnejo HTTP 400, namesto da bi element prisilno pretvorile. Razširitvena polja zunaj vnosa v podedovanih zahtevah z nizi/žetoni se še naprej posredujejo nespremenjena.

# Prikaži vse modele vdelav
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: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, OpenRouter, SD WebUI (lokalno), ComfyUI (lokalno).

# Seznam vseh slikovnih modelov
GET /v1/images/generations

---

OCR dokumentov

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

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

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

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

Vsi trije ponudniki odgovorijo z enakim telesom v obliki Mistral:

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

Potek preverjanja stanja Azure Document Intelligence

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

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

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

---

Seznam modelov

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

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

Predpone ID-jev modelov (?prefix=)

Večina modelov je objavljena s predpono ponudnika. Uporabljeno predpono določa funkcijska zastavica MODELS_CATALOG_PREFIX_MODE, vendar jo je mogoče preglasiti za posamezno zahtevo s parametrom poizvedbe — uporabno za odjemalca, ki želi pregleden seznam, ne da bi spremenil nastavitev za celoten strežnik in vse druge uporabnike:

GET /v1/models?prefix=alias        # en ID na model — kratka predpona vzdevka
GET /v1/models?prefix=dual         # obe obliki (privzeta nastavitev strežnika)
GET /v1/models?prefix=canonical    # samo polna predpona ID-ja ponudnika

Način	Odda	Opombe
dual	cc/claude-sonnet-4-6 in claude/claude-sonnet-4-6	Privzeto. Oba ID-ja usmerjata na isti model; ohranjena sta zato, da konfiguracije odjemalcev, ki imajo eno od oblik zapisano neposredno, še naprej delujejo. Približno podvoji katalog.
alias	cc/claude-sonnet-4-6	En vnos na model. Ponudniki brez ločenega vzdevka še vedno oddajo svoj vnos, zato se nič ne izgubi.
canonical	claude/claude-sonnet-4-6	En vnos na model s polno predpono ID-ja ponudnika. Ponudniki brez ločenega vzdevka (npr. antigravity/…, agy/…) tudi tukaj oddajo svoj edini ID, zato se nič ne izgubi.

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

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

Različice modelov brez razmišljanja

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

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

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

---

Manifest vtičnika ponudnika

GET /api/v1/provider-plugin-manifest

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

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

---

Združljivostne končne točke

Metoda	Pot	Oblika
POST	/v1/chat/completions	OpenAI
POST	/v1/messages	Anthropic
POST	/v1/responses	Odgovori OpenAI
POST	/v1/embeddings	OpenAI
POST	/v1/images/generations	Slike OpenAI
POST	/v1/images/edits	Slike OpenAI (urejanje/zapolnjevanje)
POST	/v1/videos/generations	Ustvarjanje videoposnetkov v slogu OpenAI
POST	/v1/music/generations	Ustvarjanje glasbe v slogu OpenAI
POST	/v1/audio/transcriptions	Zvok OpenAI (STT)
POST	/v1/audio/speech	OpenAI TTS (vrne telo z zvokom)
POST	/v1/rerank	Prerazvrščanje v slogu Cohere/Voyage
POST	/v1/classify	Razvrščanje Jina (api.jina.ai)
POST	/v1/segment	Razčlenjevalnik Jina (segment.jina.ai)
POST	/v1/moderations	Moderiranje OpenAI
GET	/v1/models	OpenAI
POST	/v1/messages/count_tokens	Anthropic
GET	/v1beta/models	Gemini
POST	/v1beta/models/{...path}	Gemini generateContent
POST	/v1/api/chat	Ollama
GET	/api/v1/vscode/{token}/	Vzdevek kataloga OpenAI
GET	/api/v1/vscode/{token}/models	Vzdevek modelov OpenAI
POST	/api/v1/vscode/{token}/chat/completions	Vzdevek OpenAI z žetonom
POST	/api/v1/vscode/{token}/responses	Vzdevek odgovorov OpenAI z žetonom
POST	/api/v1/vscode/{token}/api/chat	Vzdevek Ollama z žetonom
GET	/api/v1/vscode/{token}/api/tags	Vzdevek oznak Ollama z žetonom

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

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

# Prerazvrščanje
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

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

# Razčlenjevalnik Jina
POST /v1/segment     { "content": "...", "return_chunks": true }

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

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

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

# 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": "suno/v3.5",   "prompt": "..." }

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 za datoteke

Končna točka za datoteke, združljiva z OpenAI, za paketni vhod/izhod in nalaganje datotek glede na namen.

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

Overjanje: Ključ API vrste Bearer — datoteke so omejene na posamezni ključ API prek getApiKeyRequestScope.

---

API za pakete

Paketna obdelava, združljiva z OpenAI.

Metoda	Pot	Opis
POST	/v1/batches	Ustvari paket — telo preveri v1BatchCreateSchema (input_file_id, endpoint, completion_window)
GET	/v1/batches	Navede pakete
GET	/v1/batches/[id]	Pridobi stanje paketa + request_counts
DELETE	/v1/batches/[id]	Izbriše dokončan/neuspešen paket
POST	/v1/batches/[id]/cancel	Prekliče paket, katerega obdelava poteka

Overjanje: Ključ API vrste Bearer. Paketi so omejeni na posamezni ključ API.

---

API za iskanje

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

Metoda	Pot	Opis
GET	/v1/search	Navede konfigurirane ponudnike iskanja in njihove zmožnosti
POST	/v1/search	Izvede iskalno poizvedbo — telo preveri v1SearchSchema; podpira predpomnjenje/združevanje zahtev
GET	/v1/search/analytics	Statistični podatki o zadetkih/zakasnitvah/predpomnilniku za posameznega ponudnika

Overjanje: Ključ API vrste Bearer (extractApiKey + isValidApiKey). Pravilnik iskanja se uveljavlja prek enforceApiKeyPolicy.

---

API za spletno pridobivanje

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

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

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

Nadomestna možnost z upoštevanjem kvote (#8297): kadar izrecni provider ni podan, se skupina (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) preišče v fiksnem prednostnem vrstnem redu (najprej zapolni prvega) — ponudnik, ki je nastavljen, vendar omejen s hitrostjo, se preskoči, namesto da bi takoj prekinil zahtevo, napaka pri ponudniku višje ravni, ki omogoča ponovni poskus oziroma je povezana s kvoto (HTTP 429 vedno; 402/403 za brezplačne ravni Firecrawl/Tavily/TinyFish s kvotami — ne za Jina Reader in nikoli za običajno neveljavno zahtevo 400), pa med izvajanjem preide na naslednjega še nepreizkušenega ponudnika z nastavljenimi poverilnicami. Ko so izčrpani vsi ponudniki v skupini, končna točka vrne en sam odgovor 429 (z glavo Retry-After) namesto prejšnjega splošnega odgovora 400. Ko je zahtevan izrecni provider, ni tihega preklopa na nadomestnega ponudnika — izrecno izbrani ponudnik, ki je omejen s hitrostjo ali pri katerem pride do napake, posreduje svojo napako (429, če je omejen s hitrostjo, sicer pa stanje ponudnika višje ravni).

---

Pretakanje prek WebSocket

GET /v1/ws?handshake=1

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

Preverjanje pristnosti: Ključ API Bearer med rokovanjem.

Responses API prek WebSocket (samo codex)

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

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

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

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

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

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

Nastavitev OpenAI Codex CLI

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

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

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # brez končne poševnice; URL za WS se izpelje samodejno (v produkciji uporabite https/wss)
wire_api = "responses"                    # edina podprta vrednost od februarja 2026
supports_websockets = true                # omogoči transport Responses prek WS
env_key = "OMNIROUTE_API_KEY"             # vsebuje ključ API OmniRoute (Bearer)

export OMNIROUTE_API_KEY=sk-...           # ključ API OmniRoute (kateri koli ključ, če je REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"

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

---

Kvote in poročanje o težavah

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

Avtentikacija: API-ključ Bearer (isAuthenticated).

---

Samopostrežni pregled porabe (/api/usage/om-usage)

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

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

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

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

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

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

Ob zavrnitvi (401 napačen ključ / 403 ni dovoljeno) ista pot vrne { "allowed": false, "error": { "message": "…" } } — prisoten, vendar prazen personal/provider (ključ je dovoljen, vendar še ni bilo pridobljenih podatkov) predstavlja drugačno stanje kot zavrnitev, razlikuje pa ju samo oblika JSON.

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

---

Semantični predpomnilnik

# Pridobi statistiko predpomnilnika
GET /api/cache/stats

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

Primer odgovora:

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

Vpliv na zakasnitev

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

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

Obhod predpomnilnika za posamezni ključ

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

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

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

{ "cacheDefaultMode": "bypass" }

Obhod za posamezno zahtevo

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

X-OmniRoute-No-Cache: true

---

Nadzorna plošča in upravljanje

Upravljavske poti (/api/*, razen javnega preverjanja pristnosti/prijave) niso avtorizirane z običajnimi ključi API za sklepanje. Družine poverilnic, obsegi in primeri curl: Preverjanje pristnosti za upravljanje.

Preverjanje pristnosti

Končna točka	Metoda	Opis
/api/auth/login	POST	Prijava
/api/auth/logout	POST	Odjava
/api/settings/require-login	GET/PUT	Preklop zahteve po prijavi

Upravljanje ponudnikov

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

Tokovi OAuth

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

Usmerjanje in konfiguracija

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

Uporaba in analitika

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

Nastavitve

Končna točka	Metoda	Opis
/api/settings	GET/PUT/PATCH	Splošne nastavitve
/api/settings/proxy	GET/PUT	Konfiguracija omrežnega posredniškega strežnika
/api/settings/proxy/test	POST	Preizkus povezave s posredniškim strežnikom
/api/settings/ip-filter	GET/PUT	Seznam dovoljenih/blokiranih naslovov IP
/api/settings/thinking-budget	GET/PUT	Način prepisovanja zahtev za razmišljanje/sklepanje (nespremenjen prenos / samodejna odstranitev / po meri / prilagodljivo). Neodvisno od stiskanja. Glejte THINKING_BUDGET.md.
/api/settings/system-prompt	GET/PUT	Globalni sistemski poziv
/api/settings/compression	GET/PUT	Globalna konfiguracija stiskanja
/api/settings/purge-request-history	POST	Brisanje vrstic dnevnika zahtev in lokalnih artefaktov dnevnika klicev

Kontekst in stiskanje

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

Spremljanje

Končna točka	Metoda	Opis
/api/sessions	GET	Spremljanje aktivnih sej
/api/rate-limits	GET	Omejitve hitrosti po računih
/api/monitoring/health	GET	Preverjanje stanja in povzetek ponudnikov (catalogCount, configuredCount, activeCount, monitoredCount)
/api/cache/stats	GET/DELETE	Statistika predpomnilnika / brisanje
/api/modality-bridge/stats	GET	Vpomnilniški attempts, uspehi/bridged, neuspehi, zadetki predpomnilnika, totalLatencyMs, latencySamples, na vzorcih temelječi averageLatencyMs in čas zadnje uporabe (ponastavitev ob vnovičnem zagonu; preverjanje pristnosti za upravljanje)
/api/modality-bridge/video/runtime	GET	Strogo preverjanje zaupanja vrednega povratnega vmesnika pred preverjanjem pristnosti za upravljanje/sondo; sanirane informacije o razpoložljivosti in različicah FFmpeg/ffprobe (brez shranjevanja)
/api/modality-bridge/video/extract	POST	Notranji overjeni posrednik bajtov prek zaupanja vrednega povratnega vmesnika; vhod 50 MiB, omejena čakalna vrsta/izhod 32 MiB, zmogljivost 503, prekinitev povezave 499, rok 504; ni javni API za nalaganje

Varnostno kopiranje in izvoz/uvoz

Končna točka	Metoda	Opis
/api/db-backups	GET	Prikaz seznama razpoložljivih varnostnih kopij
/api/db-backups	PUT	Ustvarjanje ročne varnostne kopije
/api/db-backups	POST	Obnovitev iz določene varnostne kopije
/api/db-backups/export	GET	Prenos zbirke podatkov kot datoteke .sqlite
/api/db-backups/import	POST	Nalaganje datoteke .sqlite za zamenjavo zbirke podatkov
/api/db-backups/exportAll	GET	Prenos celotne varnostne kopije kot arhiva .tar.gz

Sinhronizacija z oblakom

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

Predori

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

Orodja CLI

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

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

Agenti ACP

Končna točka	Metoda	Opis
/api/acp/agents	GET	Prikaz vseh zaznanih agentov (vgrajenih in po meri) s stanjem
/api/acp/agents	POST	Dodajanje agenta po meri ali osvežitev predpomnilnika zaznavanja
/api/acp/agents	DELETE	Odstranitev agenta po meri s parametrom poizvedbe id

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

Odpornost in omejitve hitrosti

Končna točka	Metoda	Opis
/api/resilience	GET/PATCH	Pridobivanje/posodabljanje čakalne vrste zahtev, obdobja ohlajanja povezave, odklopnika ponudnika in nastavitev čakanja
/api/resilience/reset	POST	Ponastavitev odklopnikov ponudnikov
/api/resilience/model-cooldowns	GET	Prikaz aktivnih zaklepov po (ponudniku, povezavi, modelu), razvrščenih po preostalem času
/api/resilience/model-cooldowns	DELETE	Odstranitev zaklepa modela — telo {provider, model} ali {all: true} za izbris vsega
/api/rate-limits	GET	Stanje omejitve hitrosti po računih
/api/rate-limit	GET	Globalna konfiguracija omejitve hitrosti

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

Vrednotenja

Končna točka	Metoda	Opis
/api/evals	GET/POST	Prikaz zbirk vrednotenj / izvedba vrednotenja

Pravilniki

Končna točka	Metoda	Opis
/api/policies	GET/POST/DELETE	Upravljanje pravilnikov usmerjanja

Skladnost

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

v1beta (združljivo z Gemini)

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

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

Notranji/sistemski API-ji

Končna točka	Metoda	Opis
/api/init	GET	Preverjanje inicializacije aplikacije (uporabljeno ob prvem zagonu)
/api/tags	GET	Oznake modelov, združljive z Ollama (za odjemalce Ollama)
/api/restart	POST	Sprožitev nadzorovanega vnovičnega zagona strežnika
/api/shutdown	POST	Sprožitev nadzorovane zaustavitve strežnika
/api/system/env/repair	POST	Popravilo okoljskih spremenljivk ponudnika OAuth

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

Popravilo okolja OAuth (v3.6.1+)

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

{
  "provider": "claude-code"
}

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

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

---

Prepis zvoka

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

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

Zahteva:

curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "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 samo za deepgram/nova-3 ne uporablja OpenRouterja.

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

---

Združljivost z Ollama

Za odjemalce, ki uporabljajo obliko API-ja Ollama:

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

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

Zahteve se samodejno pretvarjajo med obliko Ollama in notranjimi oblikami.

Vzdevki za VS Code z žetonom / brez glave

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

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

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

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

Primer:

curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'

Opombe:

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

---

Telemetrija

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

Odgovor:

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

---

Proračun

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

# Nastavi ali posodobi proračun
POST /api/usage/budget
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "dailyLimitUsd": 5.00,
  "weeklyLimitUsd": 30.00,
  "monthlyLimitUsd": 100.00,
  "warningThreshold": 0.8,
  "resetInterval": "monthly"
}

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

Omejitve žetonov

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

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

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

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

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

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

Obdelava zahtev

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

Celoten opis arhitekture: ARCHITECTURE.md

---

Upravljanje kombinacij

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

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

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

---

Spletni kavlji

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

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

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

---

Registrirani ključi (samodejno upravljanje)

Podsistem za samodejno upravljanje ključev jih uporablja za izdajanje in rotacijo ključev API pri zalednem ponudniku/računu z dnevnimi/urnimi kvotami.

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

Avtentikacija: ključ API Bearer (isAuthenticated). Glejte tudi /v1/quotas/check in /v1/issues/report.

---

Protokol agentov

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

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

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

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

---

Upravljavski posredniški strežniki

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

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

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

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

---

Odpornost (razširjeno)

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

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

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

# Počisti zaklep posameznega modela
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o-mini"}'

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

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

---

Veščine

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

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

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

---

Pomnilnik

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

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

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

---

Strežnik MCP

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

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

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

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

---

Strežnik A2A

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

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # izbirno, razen če je nastavljen OMNIROUTE_API_KEY
Content-Type: application/json

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

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

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

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

Kartica agenta

GET /.well-known/agent.json

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

Pomožne poti REST

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

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

---

Oblak, evalvacije in ocenjevanje

Metoda	Pot	Opis
POST	/api/cloud/auth	Preveri ključ Bearer ter vrne zakrite povezave ponudnikov in vzdevke modelov za odjemalce sinhronizacije z oblakom
POST	/api/cloud/credentials/update	Posodobi šifrirane poverilnice ponudnika, sinhroniziranega z oblakom
POST	/api/cloud/model/resolve	Razreši logični ID modela v konkretnega ponudnika/model z uporabo lokalne usmerjevalne tabele
GET	/api/cloud/models/alias	Navede vzdevke modelov, kot so 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	Navede vgrajene zbirke evalvacij in najnovejše izvedbe
POST	/api/evals	Sproži izvedbo evalvacije
POST	/api/evals/suites	Ustvari zbirko evalvacij po meri — telo je preverjeno z evalSuiteSaveSchema
GET	/api/evals/suites/[id]	Pridobi zbirko evalvacij po meri

Preverjanje pristnosti: /api/cloud/auth neposredno preveri ključ Bearer; druge poti /api/cloud/*, /api/evals/* in /api/assess zahtevajo skrbniško sejo/ključ API. Zahteva POST za /api/assess uporablja validateBody s shemo obsega v obliki diskriminirane unije.

---

Upravljanje ACP (Agent Client Protocol)

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

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

Primer odgovora (GET /api/acp/agents):

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

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

Za vse podrobnosti glejte Ogrodje ACP.

---

Analitika in opazljivost

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

Analitika samodejnega usmerjanja

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

Primer odgovora:

{
  "window": "24h",
  "totalCalls": 1234,
  "strategyBreakdown": {
    "rules": 800,
    "cost": 200,
    "latency": 150,
    "sla-aware": 50,
    "lkgp": 34
  },
  "tierBreakdown": {
    "ultra": 100,
    "pro": 500,
    "standard": 400,
    "free": 234
  },
  "topProviders": [
    { "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
    { "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
  ]
}

Analitika stiskanja

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

Primer odgovora:

{
  "window": "24h",
  "totalOriginalTokens": 5000000,
  "totalCompressedTokens": 3500000,
  "totalSavings": 1500000,
  "savingsPct": 30.0,
  "modeBreakdown": {
    "lite": 400,
    "standard": 600,
    "aggressive": 100,
    "ultra": 50,
    "rtk": 84
  },
  "engineBreakdown": {
    "caveman": 800,
    "rtk": 434
  }
}

Spremljanje raznolikosti ponudnikov

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

Primer odgovora:

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

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

---

Skrbniške operacije

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

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

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

---

Upravljanje orodij CLI

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

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

Preverjanje pristnosti: Zahteva upravljavsko sejo.

---

Veščine agentov

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

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

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

---

Upravljanje predpomnilnika

Upravljajte semantični predpomnilnik in predpomnilnik sklepanja.

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

Preverjanje pristnosti: Zahteva upravljavsko sejo.

---

Pomnilniški sistem

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

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

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

---

Spletni kavlji

Upravljajte naročnine spletnih kavljev na dogodke.

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

Preverjanje pristnosti: Zahteva upravljavsko sejo.

Za vse vrste dogodkov glejte Ogrodje spletnih kavljev.

---

Ogrodje veščin

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

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

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

Za vse podrobnosti glejte Ogrodje veščin.

---

Vtičniki

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

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

Preverjanje pristnosti: Zahtevana je upravljavska seja.

Za vse podrobnosti glejte Ogrodje vtičnikov.

---

Senčno usmerjanje

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

---

Zaščitni mehanizmi

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

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

Preverjanje pristnosti: Zahtevana je upravljavska seja.

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

---

---

Preverjanje pristnosti

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

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

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