mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-14 02:42:24 +03:00

Files

Diego Rodrigues de Sa e Souza 9debec71ec feat(i18n): 9 new locales — all 24 official EU languages (51 locales) (#13044 )

Batch 1 of the locale expansion: Greek, Croatian, Serbian, Lithuanian, Estonian, Latvian, Slovenian, Maltese and Irish across the dashboard catalog, docs mirrors, CLI catalog, README, locale index and the site. 42 → 51 locales.

Also fixes the ICU literal escape the translation backend dropped around angle placeholders, four translations that invented or renamed a placeholder, the language bars that linked to mirrors that do not exist, and the migration count drift (171 → 172).

⚠️ base-red inherited: #12732 — the four unit shards and Fast Quality Gates fail identically on unrelated PRs cut from the same base.

2026-09-10 10:13:09 -03:00

118 KiB

Raw Blame History

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

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

Odjemalec pošlje zahtevo na /v1/*
Obdelovalnik poti pokliče handleChat, handleEmbedding, handleAudioTranscription ali handleImageGeneration
Model se razreši (neposredni ponudnik/model ali vzdevek/kombinacija)
Poverilnice se izberejo iz lokalne zbirke podatkov s filtriranjem glede na razpoložljivost računa
Za klepet: handleChatCore preveri semantični/podpisni predpomnilnik in razreši nastavitve stiskanja kombinacije
Če je omogočeno, se pred pretvorbo za ponudnika izvede proaktivno stiskanje (lite, Caveman, RTK ali naloženo)
Izvajalnik ponudnika pošlje zahtevo nadrejeni storitvi
Odgovor se pretvori nazaj v obliko odjemalca (klepet) ali vrne nespremenjen (vdelave/slike/zvok)
Zabeležijo se uporaba, analitika stiskanja in dnevniki zahtev
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).

118 KiB Raw Blame History Unescape Escape

API_REFERENCE (Slovenščina)

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

Referenca API-ja

Kazalo vsebine

Dokončanja klepeta

Glave po meri

Ekskluzivni upravljani zakupi sej

x-omniroute-compression

Vdelave

Ustvarjanje slik

OCR dokumentov

Potek preverjanja stanja Azure Document Intelligence

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

Seznam modelov

Predpone ID-jev modelov (?prefix=)

Različice modelov brez razmišljanja

Manifest vtičnika ponudnika

Združljivostne končne točke

Namenske poti ponudnikov

API za datoteke

API za pakete

API za iskanje

API za spletno pridobivanje

Pretakanje prek WebSocket

Responses API prek WebSocket (samo codex)

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

Nastavitev OpenAI Codex CLI

Kvote in poročanje o težavah

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

Semantični predpomnilnik

Vpliv na zakasnitev

Obhod predpomnilnika za posamezni ključ

Obhod za posamezno zahtevo

Nadzorna plošča in upravljanje

Preverjanje pristnosti

Upravljanje ponudnikov

Tokovi OAuth

Usmerjanje in konfiguracija

Uporaba in analitika

Nastavitve

Kontekst in stiskanje

Spremljanje

Varnostno kopiranje in izvoz/uvoz

Sinhronizacija z oblakom

Predori

Orodja CLI

Agenti ACP

Odpornost in omejitve hitrosti

Vrednotenja

Pravilniki

Skladnost

v1beta (združljivo z Gemini)

Notranji/sistemski API-ji

Popravilo okolja OAuth (v3.6.1+)

Prepis zvoka

Združljivost z Ollama

Vzdevki za VS Code z žetonom / brez glave

Telemetrija

Proračun

Omejitve žetonov

Obdelava zahtev

Upravljanje kombinacij

Spletni kavlji

Registrirani ključi (samodejno upravljanje)

Protokol agentov

Upravljavski posredniški strežniki

Odpornost (razširjeno)

Veščine

Pomnilnik

Strežnik MCP

Strežnik A2A

JSON-RPC

Kartica agenta

Pomožne poti REST

Oblak, evalvacije in ocenjevanje

Upravljanje ACP (Agent Client Protocol)

Analitika in opazljivost

Analitika samodejnega usmerjanja

Analitika stiskanja

118 KiB

Raw Blame History

`x-omniroute-compression`

Predpone ID-jev modelov (`?prefix=`)

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

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