mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-09-20 22:02:19 +03:00
58f88a83e4
Batch 3 (last) of the locale-expansion plan: ha, yo, ig, am, uz, ka, hy on every surface — dashboard catalog, docs mirror (22-file core + llm.txt + CHANGELOG), CLI catalog, README flag block, locale tables and 🌐 language bars. Also closes the key gap the batch-1 (43 keys) and batch-2 (10 keys) catalogs carried since their base merges, fixes the Igbo "Model" copy and allowlists the Uzbek cognate. Translation-ratio baseline covers 65 locales. ⚠️ base-red inherited: #12732
1786 lines
127 KiB
Markdown
1786 lines
127 KiB
Markdown
# API_REFERENCE (Lietuvių)
|
||
|
||
🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)
|
||
|
||
---
|
||
|
||
---
|
||
|
||
title: "API žinynas"
|
||
version: 3.8.51
|
||
lastUpdated: 2026-08-31
|
||
---
|
||
|
||
# API žinynas
|
||
|
||
🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)
|
||
|
||
Pagrindinis „OmniRoute“ API žinynas. Jame aprašoma viešoji `/v1` sąsaja ir dažniausiai naudojami valdymo galiniai taškai; išsamiausi šaltiniai yra mašininiu būdu nuskaitomas failas [`docs/openapi.yaml`](../openapi.yaml) ir maršrutų medis kataloge `src/app/api/`.
|
||
|
||
---
|
||
|
||
## Turinys
|
||
|
||
- [Pokalbių užbaigimai](#chat-completions)
|
||
- [Išskirtinės valdomų sesijų nuomos](#exclusive-managed-session-leases)
|
||
- [Įterpiniai](#embeddings)
|
||
- [Vaizdų generavimas](#image-generation)
|
||
- [Dokumentų OCR](#document-ocr)
|
||
- [Modelių sąrašas](#list-models)
|
||
- [Teikėjo papildinio manifestas](#provider-plugin-manifest)
|
||
- [Suderinamumo galiniai taškai](#compatibility-endpoints)
|
||
- [Failų API](#files-api)
|
||
- [Paketinių užduočių API](#batches-api)
|
||
- [Paieškos API](#search-api)
|
||
- [WebSocket srautinis perdavimas](#websocket-streaming)
|
||
- [Kvitų ir problemų ataskaitos](#quotas--issues-reporting)
|
||
- [Semantinė podėlio atmintinė](#semantic-cache)
|
||
- [Valdymo skydelis ir administravimas](#dashboard--management)
|
||
- [Derinių valdymas](#combo-management)
|
||
- [Žiniatinklio kabliai](#webhooks)
|
||
- [Registruoti raktai (automatinis valdymas)](#registered-keys-auto-management)
|
||
- [Agentų protokolas](#agents-protocol)
|
||
- [Valdymo tarpiniai serveriai](#management-proxies)
|
||
- [Atsparumas (išplėstinis)](#resilience-extended)
|
||
- [Įgūdžiai](#skills)
|
||
- [Atmintis](#memory)
|
||
- [MCP serveris](#mcp-server)
|
||
- [A2A serveris](#a2a-server)
|
||
- [Debesija, vertinimai ir įvertinimas](#cloud-evals--assess)
|
||
- [Užklausų apdorojimas](#request-processing)
|
||
- [Autentifikavimas](#authentication)
|
||
|
||
---
|
||
|
||
## Pokalbių užbaigimai
|
||
|
||
```bash
|
||
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
|
||
}
|
||
```
|
||
|
||
### Pasirinktinės antraštės
|
||
|
||
| Antraštė | Kryptis | Aprašymas |
|
||
| ------------------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `X-OmniRoute-No-Cache` | Užklausa | Nustatykite `true`, kad apeitumėte podėlį |
|
||
| `x-omniroute-no-memory` | Užklausa | Nustatykite `true`, kad šiai užklausai nebūtų įterpiama atmintis ir įgūdžiai (atitinka podėlio išjungimą; išvengiama kiekvieno iškvietimo žetonų ir sąnaudų pridėtinės išlaidos) |
|
||
| `X-OmniRoute-Progress` | Užklausa | Nustatykite `true`, kad gautumėte eigos įvykius |
|
||
| `X-Session-Id` | Užklausa | Pastovus sesijos raktas išoriniam sesijos susiejimui |
|
||
| `x_session_id` | Užklausa | Taip pat priimamas variantas su pabraukimo brūkšniais (tiesioginis HTTP) |
|
||
| `X-OmniRoute-Session-Id` | Užklausa | Skambinančiojo pateikta sesijos / pokalbio žyma (taip pat naudojama atminčiai). Jei ji pateikta, pažodžiui išsaugoma `call_logs.session_tag`, kad būtų galima priskirti sąnaudas sesijai (#8249) — jei nepateikta, ji niekada nesugeneruojama |
|
||
| `Idempotency-Key` | Užklausa | Dubliavimo šalinimo raktas (5 s intervalas) |
|
||
| `X-Request-Id` | Užklausa | Alternatyvus dubliavimo šalinimo raktas |
|
||
| `X-OmniRoute-Cache` | Atsakymas | `HIT` arba `MISS` (ne srautiniu režimu) |
|
||
| `X-OmniRoute-Idempotent` | Atsakymas | `true`, jei dublikatas pašalintas |
|
||
| `X-OmniRoute-Progress` | Atsakymas | `enabled`, jei įjungtas eigos stebėjimas |
|
||
| `X-OmniRoute-Session-Id` | Atsakymas | Faktinis sesijos ID, kurį naudoja OmniRoute |
|
||
| `X-OmniRoute-Request-Id` | Atsakymas | Užklausos koreliacijos ID (kai žinomas) |
|
||
| `X-OmniRoute-Version` | Atsakymas | OmniRoute komponavimo versija (visada pateikiama) |
|
||
| `X-OmniRoute-Cost-Saved` | Atsakymas | USD suma, kurios išvengta dėl podėlio `HIT` (tik podėlio pataikymų atveju) |
|
||
| `X-OmniRoute-Decision` | Atsakymas | Maršruto parinkimo seka: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` yra derinio strategija arba `single`, jei užklausa nėra derinys) — visada pateikiama užbaigimo atsakymuose |
|
||
|
||
> Pastaba dėl Nginx: jei naudojate antraštes su pabraukimo brūkšniais (pavyzdžiui, `x_session_id`), įjunkite `underscores_in_headers on;`.
|
||
|
||
> **Sąnaudų telemetrijos antraštės:** sėkminguose ne srautiniu režimu pateikiamuose atsakymuose taip pat yra `X-OmniRoute-*` sąnaudų telemetrijos rinkinys — `X-OmniRoute-Response-Cost` (USD, fiksuota 10 dešimtainių skilčių; `0.0000000000`, jei nemokama arba neįkainota), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit` ir `X-OmniRoute-Fallback-Attempts` (tik kai > 0), taip pat `X-OmniRoute-Request-Id` ir `X-OmniRoute-Version`. Jas pateikia pokalbių užbaigimai, `/v1/responses`, `/v1/messages` **ir medijos galiniai taškai** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` ir `/v1/moderations` (sąnaudos visada `0`). Kai prieinamos kainos, medijos sąnaudos apskaičiuojamos pagal modalumą (už vaizdą, sekundę, simbolį ar paieškos vienetą), kitu atveju jos yra `0` (klaidos atveju veikimas tęsiamas).
|
||
|
||
> **Podėlio pataikymo sąnaudų semantika:** semantinio podėlio `HIT` (`X-OmniRoute-Cache-Hit: true`) atveju išorinis iškvietimas neatliekamas, todėl `X-OmniRoute-Response-Cost` yra `0.0000000000` (pataikymo aptarnavimo **prieauginės** sąnaudos). Pradinės arba galėjusios susidaryti sąnaudos atskirai pateikiamos `X-OmniRoute-Cost-Saved`. Atsiskaitymo sistemų naudotojai turėtų sumuoti `X-OmniRoute-Response-Cost` (pataikymai nieko nekainuoja); podėlio analizė gali agreguoti `X-OmniRoute-Cost-Saved`.
|
||
|
||
## Išskirtinės valdomų seansų nuomos
|
||
|
||
Išskirtinė valdomų seansų nuoma yra pasirenkama, nuo kliento nepriklausoma maršruto parinkimo sutartis: vienas aktyvus savininkas
|
||
valdo vieną tinkamą „OmniRoute“ ryšį. Ji nenuomoja modelio, nereikalauja „OAuth“, neidentifikuoja
|
||
konkretaus kliento ir nereikalauja konkretaus teikėjo.
|
||
|
||
Autentifikavimui naudojamas API raktas turi turėti sritį `lease:exclusive` ir aiškiai nurodytą netuščią
|
||
`allowedConnections` sąrašą. Duomenų bazės keitimo riba užtikrina, kad abu laukai būtų pateikti kartu
|
||
kuriant raktą ir atliekant dalinius atnaujinimus.
|
||
|
||
```http
|
||
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"}
|
||
```
|
||
|
||
Sėkminguose įgijimo, atnaujinimo ir atlaisvinimo atsakymuose pateikiamos laiko žymos, `state` ir tiksli teigiama
|
||
`generation`, tačiau niekada nepateikiamas pasirinktas ryšys ar prisijungimo duomenys. Atnaujinant ir atlaisvinant
|
||
generacija pateikiama JSON turinyje:
|
||
|
||
```json
|
||
{ "action": "renew", "generation": 1 }
|
||
```
|
||
|
||
```json
|
||
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
|
||
```
|
||
|
||
Aktyvios nuomos savininkas gali aiškiai paprašyti privatumą išsaugančių dabartinio susiejimo rodymo metaduomenų:
|
||
|
||
```json
|
||
{ "action": "status", "generation": 1 }
|
||
```
|
||
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
}
|
||
```
|
||
|
||
Šis pasirenkamas būsenos veiksmas vienoje duomenų bazės operacijoje apsaugomas neskaidriu savininko identifikatoriumi, autentifikuotu valdomu API raktu ir tikslia
|
||
aktyvia generacija. `displayName` yra tik apkarpytas sukonfigūruoto
|
||
ryšio pavadinimas; kai saugaus sukonfigūruoto pavadinimo nėra, jo reikšmė yra `null`. „OmniRoute“ niekada jo nepakeičia
|
||
el. pašto adresu ar sugeneruota paskyros tapatybe. Teikėjo reikšmė yra nejautri rodymo žyma ir niekada nėra
|
||
sugeneruotas suderinamo teikėjo identifikatorius. Prisijungimo duomenys, prieigos raktai, slapukai, neapdoroti ryšio ar API
|
||
rakto identifikatoriai, savininko maišos, apsaugos paslaptys ir vidiniai maršruto parinkimo duomenys neįtraukiami.
|
||
|
||
Užklausos su netinkamu raktu, netinkamu savininku, pasenusia generacija, taip pat nerastos, pasibaigusios, atlaisvintos ar panaikintos nuomos
|
||
grąžina tą pačią `409 LEASE_FENCE_STALE` klaidą be ryšio metaduomenų. Klientas, gavęs laukimo dėl pajėgumo atsakymą, neturi aktyvaus susiejimo, kurį galėtų patikrinti. Kai maršruto parinkimas pakeičia aktyvios nuomos ryšį,
|
||
ta pati generacija lieka galioti, o būsenos veiksmas atomiškai grąžina naują susiejimą, niekada ne senąjį.
|
||
Esami klientai lieka nepakeisti, nes įgijimo, atnaujinimo, atlaisvinimo ir laukimo atsakymų
|
||
ankstesnė struktūra išlieka.
|
||
|
||
Ši serverio sutartis nekeičia standartinės „OpenAI Codex“ `/status` funkcijos. Šiuo metu standartinė „Codex“ pateikia savo
|
||
modelio teikėją ir integruotą autentifikavimo bei paskyros būseną, tačiau neatvaizduoja pasirinktinių
|
||
teikėjo paskyros metaduomenų; būsima kliento integracija turės iškviesti šį veiksmą ir nuspręsti, kaip
|
||
rodyti `connection.displayName`.
|
||
|
||
Tada kiekvienoje valdomoje išvedimo užklausoje pateikiamos abi valdymo antraštės:
|
||
|
||
```http
|
||
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
|
||
X-OmniRoute-Lease-Generation: 1
|
||
```
|
||
|
||
Tikslaus savininko, generacijos, aktyvaus ryšio ir autentifikuoto API rakto atitiktis patikrinama prieš pat
|
||
kiekvieną palaikomą bandymą kreiptis į aukštesnio lygio paslaugą. Pakartotinai panaudojus savininką ir generaciją su kitu raktu, užklausa nepavyksta net
|
||
kai tas raktas leidžia naudoti tą patį ryšį. Neapdoroti savininko identifikatoriai nėra saugomi, registruojami žurnaluose, išlaikomi
|
||
užklausos momentinėje kopijoje ar persiunčiami aukštesnio lygio paslaugai.
|
||
|
||
Laikinas užimtumas grąžina HTTP `429` su `Retry-After` ir:
|
||
|
||
```json
|
||
{
|
||
"state": "WAITING_FOR_CAPACITY",
|
||
"error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
|
||
"reason": "NO_FREE_ELIGIBLE_CONNECTION",
|
||
"retryAfter": 30
|
||
}
|
||
```
|
||
|
||
Šis atsakymas reiškia tik tai, kad įprastas tinkamų ryšių rinkinys nebuvo tuščias, o kiekvienas laisvas kandidatas buvo
|
||
užimtas kitos aktyvios nuomos. Nepalaikomi modeliai ar teikėjai, strategijos neatitiktis, laukimo laikotarpis, kvota,
|
||
būklė ir kitos įprastos tinkamumo klaidos išlaiko esamus „OmniRoute“ atsakymus.
|
||
|
||
### `x-omniroute-compression`
|
||
|
||
Suspaudimo plano pakeitimas konkrečiai užklausai. Turi aukščiausią prioritetą — yra viršesnis už maršruto parinkimo derinio
|
||
pakeitimą, aktyvų profilį, automatinį paleidiklį ir skydelio numatytąją nuostatą. Reikšmės:
|
||
|
||
| Reikšmė | Poveikis |
|
||
| ------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `off` | Šiai užklausai suspaudimas netaikomas. |
|
||
| `default` | Iš skydelio gautas numatytasis profilis (aktyvus profilis ignoruojamas). |
|
||
| `engine:<id>` | Vienas modulis, kai jis įjungtas, pvz., `engine:rtk`. |
|
||
| `<combo>` | Pavadintas derinys, pirmiausia sutapatinamas pagal pavadinimą (neatsižvelgiant į raidžių registrą), tada pagal identifikatorių. |
|
||
|
||
Pastabos:
|
||
|
||
- Nežinomos reikšmės ignoruojamos (užklausa niekada neatmetama); parinkimas tęsiamas pagal įprastą operatorių pirmumo tvarką.
|
||
- Jei keli deriniai turi tą patį pavadinimą, deterministiniam sutapatinimui perduokite derinio **id**.
|
||
- Derinio, kurio pavadinimas yra `off` arba `default`, negalima pasirinkti pagal pavadinimą (šie raktažodžiai interpretuojami pirmiausia); tokį derinį nurodykite pagal jo identifikatorių.
|
||
- Pagrindinis suspaudimo jungiklis yra absoliutus apribojimas: kai suspaudimas išjungtas visuotinai, ši antraštė negali jo įjungti.
|
||
|
||
Pritaikytas planas pakartojamas atsakymo antraštėje:
|
||
|
||
```
|
||
X-OmniRoute-Compression: <mode>; source=<source>
|
||
```
|
||
|
||
kur `<source>` yra viena iš šių reikšmių: `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` arba `off`.
|
||
|
||
---
|
||
|
||
## Vektorinės reprezentacijos
|
||
|
||
```bash
|
||
POST /v1/embeddings
|
||
Authorization: Bearer your-api-key
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"model": "nebius/Qwen/Qwen3-Embedding-8B",
|
||
"input": "The food was delicious"
|
||
}
|
||
```
|
||
|
||
Galimi teikėjai: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.
|
||
|
||
Katalogo ID yra `provider/model` formato (pavyzdžiui, `jina-ai/jina-embeddings-v5-omni-small`). Taip pat atpažįstami registre esantys Jina modelių ID be teikėjo prefikso (pavyzdžiui, `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`). Jina vektorizavimo, perrikiavimo, klasifikavimo ir segmentavimo funkcijos pirmiausia naudoja valdymo skydelyje esančius `jina-ai` prisijungimo duomenis; `JINA_AI_API_KEY` naudojamas kaip atsarginis variantas tik tada, kai valdymo skydelyje nėra rakto. `jina-reader` kortelė skirta tik Reader / `r.jina.ai` (`POST /v1/web/fetch`) ir niekada neteikia vektorizavimo ar perrikiavimo paslaugų.
|
||
|
||
Registro modeliai, kuriems nurodytas daugiarūšio turinio palaikymas, taip pat priima iki 32 nuo teikėjo nepriklausomų struktūrizuotų
|
||
elementų. Medijos elementų tipai yra `text`, `image`, `audio`, `video` ir `document`. Jų medijos `source`
|
||
yra arba `{"type":"url","url":"https://..."}`, arba
|
||
`{"type":"base64","data":"...","media_type":"..."}`.
|
||
|
||
Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`
|
||
ir šeimos alternatyvusis pavadinimas `jina-ai/jina-embeddings-v5-omni` → omni-small) taip pat priima Jina vietinio
|
||
EmbeddingsV5Request formato dokumentus ir **persiunčia juos nepakeistus** į `https://api.jina.ai/v1/embeddings`:
|
||
|
||
```json
|
||
{
|
||
"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,..." }]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
Vietinio formato `{ image | audio | video | pdf }` reikšmė gali būti viešas HTTPS URL, `data:` URI arba neapdorotas
|
||
base64. OmniRoute nekonvertuoja šių objektų į eilutes ir neatsisiunčia vietinio formato vaizdų URL — Jina pati gauna
|
||
viešai pasiekiamą mediją. Papildomi Jina laukai (`task`, `normalized`, `truncate`, `embedding_type`) yra
|
||
persiunčiami. Tik tekstui skirti Jina variantai ir toliau atmeta netekstinius dokumentus.
|
||
|
||
Saugumo ir perdavimo apribojimai:
|
||
|
||
- Nuotolinės medijos URL turi būti vieši HTTPS adresai. Kanoninio formato `{type,source:url}` elementai atsisiunčiami
|
||
serverio pusėje (pakartotinai tikrinant peradresavimus, taikant skirtąjį laiką ir dydžio ribas, naudojant viešą DNS bei
|
||
fiksuojant ryšį) ir įterpiami prieš kreipiantis į teikėją. Vietinio Jina formato `{image:"https://..."}` elementai persiunčiami nepakeisti
|
||
atlikus tą patį viešo HTTPS adreso patikrinimą; URL atsisiunčia Jina.
|
||
- Įterptos base64 medijos iškoduotas dydis ribojamas iki 8 MiB vienam elementui ir iki 16 MiB visai užklausai.
|
||
|
||
Pritaikymas teikėjui (kanoninio formato elementai niekada nepersiunčiami nepakeisti):
|
||
|
||
- Jina daugiarūšiai modeliai: kiekvienas aukščiausio lygio elementas tampa vienu pagal modalumą susietu objektu
|
||
(`text` / `image` / `audio` / `video` / `pdf`), įterptai medijai naudojant duomenų URI; kiekvienam
|
||
aukščiausio lygio elementui pateikiamas vienas vektorius.
|
||
- Gemini Embedding 2 šeima: vienas aukščiausio lygio masyvas tampa viena vietinio formato
|
||
`models/{model}:embedContent` užklausa su `content.parts` (`text` arba `inline_data`).
|
||
- Nežinomi arba dinaminiai modeliai be aiškių modalumo metaduomenų atmeta struktūrizuotą įvestį, grąžindami HTTP 400.
|
||
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
```
|
||
|
||
Nepalaikomi modelio ir modalumo deriniai grąžina HTTP 400, užuot priverstinai konvertavę elementą. Kiti nei input
|
||
senųjų eilučių ar prieigos raktų užklausų išplėtimo laukai ir toliau persiunčiami nepakeisti.
|
||
|
||
```bash
|
||
# Išvardyti visus vektorizavimo modelius
|
||
GET /v1/embeddings
|
||
```
|
||
|
||
---
|
||
|
||
## Vaizdų generavimas
|
||
|
||
```bash
|
||
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"
|
||
}
|
||
```
|
||
|
||
Galimi teikėjai: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (vietinis), ComfyUI (vietinis).
|
||
|
||
```bash
|
||
# Išvardyti visus vaizdų modelius
|
||
GET /v1/images/generations
|
||
```
|
||
|
||
---
|
||
|
||
## Dokumentų OCR
|
||
|
||
```bash
|
||
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` parenka OCR teikėją pagal `provider/model` prefiksą; modelio ID be prefikso (pvz.,
|
||
`mistral-ocr-latest`) susiejamas su registruotu jo teikėju, o jei `model` nenurodytas, pagal
|
||
numatytuosius nustatymus naudojamas Mistral (`mistral-ocr-latest`). Registruoti teikėjai (`open-sse/config/ocrRegistry.ts`):
|
||
|
||
| Teikėjo ID | Modelio ID | `model` reikšmė | Pastabos |
|
||
| ----------------------------- | -------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (arba `mistral-ocr-latest` be prefikso) | Sinchroninis — atsakymas grąžinamas tiesiogiai iš vienintelės išorinės užklausos. |
|
||
| `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Asinchroninė išorinė paslauga (`analyze` + būsenos tikrinimas) — žr. toliau. |
|
||
| `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Sinchroninis, naudojantis Vertex AI partnerio galiniu tašku `openapi/chat/completions` — autentifikavimas ir URL aprašyti toliau. |
|
||
|
||
Visi trys teikėjai pateikia tokios pačios Mistral formos atsako turinį:
|
||
|
||
```json
|
||
{
|
||
"pages": [{ "index": 0, "markdown": "# Extracted text..." }],
|
||
"model": "mistral-ocr-latest",
|
||
"usage_info": { "pages_processed": 1 }
|
||
}
|
||
```
|
||
|
||
### Azure Document Intelligence būsenos tikrinimo eiga
|
||
|
||
Azure Document Intelligence `analyze` API yra asinchroninė: pradinė užklausa vietoje atsako turinio
|
||
grąžina `Operation-Location` antraštę, todėl rezultatą reikia periodiškai tikrinti. Apdorojimo programa
|
||
(`open-sse/handlers/ocr.ts`) tikrina tą URL kas sekundę, atlikdama iki 30 bandymų, iškart nutraukia darbą
|
||
(nebetęsia tikrinimo), jei tikrinimo atsakymas nėra `ok` arba būsena yra `"failed"`, ir grąžina `504`, jei
|
||
išnaudojus visus bandymus operacija vis dar vykdoma. Prieš grąžinant klientui, galutinis Azure atsakymas
|
||
normalizuojamas į tą pačią `pages`/`markdown` formą, kurią naudoja Mistral, todėl kliento kode nereikia
|
||
atskirai apdoroti kiekvieno teikėjo.
|
||
|
||
### Vertex AI DeepSeek OCR autentifikavimas ir galinio taško nustatymas
|
||
|
||
`vertex-deepseek-ocr` pakartotinai naudoja tą patį Vertex AI autentifikavimą, kurį OmniRoute jau palaiko
|
||
pokalbių ir vaizdų srautui (`open-sse/executors/vertex.ts`): ryšio API raktas yra arba
|
||
paslaugos paskyros JSON kredencialas (naudojant JWT nešėjo prieigos rakto gavimo eigą pakeičiamas į
|
||
trumpalaikį OAuth prieigos raktą), arba jau išduotas OAuth prieigos raktas, naudojamas toks, koks yra.
|
||
Išorinės paslaugos galinio taško URL yra bendrasis Vertex partnerio galinis taškas
|
||
`openapi/chat/completions`, sudaromas pagal ryšio projektą ir regioną — aiškiai nurodyti
|
||
`providerSpecificData.project`/`providerSpecificData.region` visada turi pirmenybę;
|
||
kitu atveju projektas nustatomas pagal paslaugos paskyros JSON lauką `project_id`, o numatytasis
|
||
regionas yra `us-central1`. Abu nustatymai atliekami faile `open-sse/handlers/ocr.ts`
|
||
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`) ir naudojami
|
||
`src/app/api/v1/ocr/route.ts` prieš perduodant vykdymą funkcijai `handleOcr`.
|
||
|
||
---
|
||
|
||
## Modelių sąrašas
|
||
|
||
```bash
|
||
GET /v1/models
|
||
Authorization: Bearer your-api-key
|
||
|
||
→ Grąžina visus pokalbių, įterpinių ir vaizdų modelius bei jų derinius OpenAI formatu
|
||
```
|
||
|
||
### Modelių ID prefiksai (`?prefix=`)
|
||
|
||
Dauguma modelių pateikiami su **teikėjo prefiksu**. Naudojamą prefiksą valdo
|
||
`MODELS_CATALOG_PREFIX_MODE` funkcijos vėliavėlė, kurią galima perrašyti **kiekvienai užklausai atskirai**
|
||
naudojant užklausos parametrą — tai naudinga klientui, norinčiam gauti tvarkingą sąrašą nekeičiant bendro
|
||
serverio nustatymo visiems kitiems:
|
||
|
||
```bash
|
||
GET /v1/models?prefix=alias # po vieną ID kiekvienam modeliui — trumpasis pseudonimo prefiksas
|
||
GET /v1/models?prefix=dual # abi formos (numatytoji serverio reikšmė)
|
||
GET /v1/models?prefix=canonical # tik visas teikėjo ID prefiksas
|
||
```
|
||
|
||
| Režimas | Pateikia | Pastabos |
|
||
| ----------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `dual` | `cc/claude-sonnet-4-6` **ir** `claude/claude-sonnet-4-6` | **Numatytasis.** Abu ID nukreipiami į tą patį modelį; tai išlaikyta, kad klientų konfigūracijos, kuriose tiesiogiai įrašyta kuri nors forma, ir toliau veiktų. Katalogas tampa maždaug dvigubai didesnis. |
|
||
| `alias` | `cc/claude-sonnet-4-6` | Po vieną įrašą kiekvienam modeliui. Teikėjai, neturintys atskiro pseudonimo, vis tiek pateikia savo įrašą, todėl niekas neprarandama. |
|
||
| `canonical` | `claude/claude-sonnet-4-6` | Po vieną įrašą kiekvienam modeliui su visu teikėjo ID prefiksu. Teikėjai, neturintys atskiro pseudonimo (pvz., `antigravity/…`, `agy/…`), čia taip pat pateikia savo vienintelį ID, todėl niekas neprarandama. |
|
||
|
||
`dual` režimo dubliuojamą įrašą galima atpažinti ir be užklausos parametro: jame yra `parent`
|
||
laukas, nurodantis pagrindinį ID.
|
||
|
||
Klientai, rodantys modelio pasirinkimo sąrašą, turėtų pateikti užklausą su `?prefix=alias` — būtent taip daro
|
||
[OmniCopilot VS Code plėtinys](../guides/VSCODE-COPILOT.md).
|
||
|
||
### Modelių variantai be mąstymo
|
||
|
||
Mąstymą palaikantiems Claude modeliams `/v1/models` taip pat pateikia **nemąstantį** variantą, kurio ID prasideda prefiksu `claude-3-omniroute-no-thinking/`:
|
||
|
||
```
|
||
claude-3-omniroute-no-thinking/<provider>/<model>
|
||
```
|
||
|
||
Pasirinkus šį ID (pvz., Claude Code konfigūracijoje, kuri visada prideda `thinking` bloką), jis nukreipiamas atgal į tikrąjį `<provider>/<model>`, išjungus samprotavimą — `/v1/messages` kelyje naudojama `thinking:{type:"disabled"}`, o `/v1/chat/completions` kelyje pašalinami `reasoning` / `reasoning_effort` laukai. Šis variantas pateikiamas tik tiems Claude šeimos modeliams, kurie palaiko mąstymą **ir** priima `disabled` (todėl, pvz., tik adaptyvųjį režimą palaikantys modeliai, atmetantys `disabled`, neįtraukiami). Operatoriai gali priverstinai įjungti arba išjungti šį variantą kiekvienam modeliui naudodami `ModelSpec.noThinkingAlias`.
|
||
|
||
---
|
||
|
||
## Teikėjo papildinio manifestas
|
||
|
||
```bash
|
||
GET /api/v1/provider-plugin-manifest
|
||
```
|
||
|
||
Grąžina JSON saugų teikėjo papildinio manifestą, naudojamą Bifrost, CLIProxyAPI ir
|
||
būsimų pagalbinių maršruto parinktuvų. Atsakymas generuojamas iš TypeScript teikėjų
|
||
registro ir sąmoningai neapima OAuth kliento paslapčių, vykdymo aplinkos
|
||
nustatymo, vykdytojo funkcijų, užklausų antraščių ir paskyrų duomenų.
|
||
|
||
Naudokite šį galinį tašką, kai pagalbinis procesas vykdomas atskirai ir negali tiesiogiai importuoti
|
||
`open-sse/config/providerPluginManifestRegistry.ts`.
|
||
|
||
---
|
||
|
||
## Suderinamumo galiniai taškai
|
||
|
||
| Metodas | Kelias | Formatas |
|
||
| ------- | ----------------------------------------- | -------------------------------------------------------- |
|
||
| POST | `/v1/chat/completions` | OpenAI |
|
||
| POST | `/v1/messages` | Anthropic |
|
||
| POST | `/v1/responses` | OpenAI Responses |
|
||
| POST | `/v1/embeddings` | OpenAI |
|
||
| POST | `/v1/images/generations` | OpenAI Images |
|
||
| POST | `/v1/images/edits` | OpenAI Images (redagavimas / užpildymas) |
|
||
| POST | `/v1/videos/generations` | OpenAI stiliaus vaizdo įrašų generavimas |
|
||
| POST | `/v1/music/generations` | OpenAI stiliaus muzikos generavimas |
|
||
| POST | `/v1/audio/transcriptions` | OpenAI Audio (kalbos atpažinimas) |
|
||
| POST | `/v1/audio/speech` | OpenAI TTS (grąžina garso turinį) |
|
||
| POST | `/v1/rerank` | Cohere/Voyage stiliaus perrikiavimas |
|
||
| POST | `/v1/classify` | Jina klasifikavimas (`api.jina.ai`) |
|
||
| POST | `/v1/segment` | Jina segmentuotuvas (`segment.jina.ai`) |
|
||
| POST | `/v1/moderations` | OpenAI Moderations |
|
||
| 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}/` | OpenAI katalogo alternatyvusis kelias |
|
||
| GET | `/api/v1/vscode/{token}/models` | OpenAI modelių alternatyvusis kelias |
|
||
| POST | `/api/v1/vscode/{token}/chat/completions` | OpenAI alternatyvusis kelias su prieigos raktu |
|
||
| POST | `/api/v1/vscode/{token}/responses` | OpenAI Responses alternatyvusis kelias su prieigos raktu |
|
||
| POST | `/api/v1/vscode/{token}/api/chat` | Ollama alternatyvusis kelias su prieigos raktu |
|
||
| GET | `/api/v1/vscode/{token}/api/tags` | Ollama žymų alternatyvusis kelias su prieigos raktu |
|
||
|
||
Visų POST maršrutų struktūra yra vienoda: `Bearer your-api-key` + Zod patikrintas JSON turinys (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` ir kt.; žr. `src/shared/validation/schemas.ts`). Nepavykus schemos patikrai, grąžinamas 4xx.
|
||
|
||
Klientams, kurie negali pridėti `Authorization: Bearer ...`, OmniRoute taip pat priima API raktus URL adrese: naudodama užklausos eilutės suderinamumo parametrus (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) arba toliau aprašytus specialiuosius `/api/v1/vscode/{token}/...` galinius taškus.
|
||
|
||
```bash
|
||
# Perrikiavimas
|
||
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
|
||
|
||
# Jina klasifikavimas (Foundation API prisijungimo duomenys)
|
||
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
|
||
|
||
# Jina segmentuotuvas
|
||
POST /v1/segment { "content": "...", "return_chunks": true }
|
||
|
||
# Jina paieška (s.jina.ai; teikėjo alternatyvūs pavadinimai: jina-search, jina-ai, jina)
|
||
POST /v1/search { "query": "...", "provider": "jina-search" }
|
||
|
||
# Moderavimas
|
||
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
|
||
|
||
# TTS — grąžina audio/mpeg (arba prašomo formato) turinį
|
||
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
|
||
|
||
# Vaizdo redagavimas (multipart)
|
||
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
|
||
|
||
# Vaizdo įrašų / muzikos generavimas (modelio ID su teikėjo priešdėliu)
|
||
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
|
||
POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." }
|
||
```
|
||
|
||
### Specialieji teikėjų maršrutai
|
||
|
||
```bash
|
||
POST /v1/providers/{provider}/chat/completions
|
||
POST /v1/providers/{provider}/embeddings
|
||
POST /v1/providers/{provider}/images/generations
|
||
```
|
||
|
||
Jei teikėjo priešdėlio nėra, jis pridedamas automatiškai. Neatitinkantys modeliai grąžina `400`.
|
||
|
||
---
|
||
|
||
## Failų API
|
||
|
||
Su OpenAI suderinamas failų galinis taškas, skirtas paketinei įvesčiai / išvesčiai ir failams pagal paskirtį įkelti.
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
|
||
| POST | `/v1/files` | Įkelti failą (kelių dalių forma: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — daugiausia 512 MiB |
|
||
| GET | `/v1/files` | Pateikti autentifikuoto API rakto failų sąrašą |
|
||
| GET | `/v1/files/[id]` | Gauti failo metaduomenis |
|
||
| DELETE | `/v1/files/[id]` | Ištrinti failą |
|
||
| GET | `/v1/files/[id]/content` | Srautu grąžinti neapdorotą failo turinį |
|
||
|
||
**Autentifikavimas:** API raktas su „Bearer“ schema — failų prieiga kiekvienam API raktui apribojama naudojant `getApiKeyRequestScope`.
|
||
|
||
---
|
||
|
||
## Paketų API
|
||
|
||
Su OpenAI suderinamas paketinis apdorojimas.
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
||
| POST | `/v1/batches` | Sukurti paketą — turinys tikrinamas naudojant `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
|
||
| GET | `/v1/batches` | Pateikti paketų sąrašą |
|
||
| GET | `/v1/batches/[id]` | Gauti paketo būseną ir `request_counts` |
|
||
| DELETE | `/v1/batches/[id]` | Ištrinti užbaigtą arba nepavykusį paketą |
|
||
| POST | `/v1/batches/[id]/cancel` | Atšaukti vykdomą paketą |
|
||
|
||
**Autentifikavimas:** API raktas su „Bearer“ schema. Paketų prieiga apribojama pagal API raktą.
|
||
|
||
---
|
||
|
||
## Paieškos API
|
||
|
||
Žiniatinklio / paieškos teikėjų abstrakcija („Tavily“, „Brave“, „Exa“, „Serper“ ir kt.).
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/v1/search` | Pateikti sukonfigūruotų paieškos teikėjų ir jų galimybių sąrašą |
|
||
| POST | `/v1/search` | Vykdyti paieškos užklausą — turinys tikrinamas naudojant `v1SearchSchema`, palaikomas podėlis / užklausų sujungimas |
|
||
| GET | `/v1/search/analytics` | Pateikti kiekvieno teikėjo rezultatų, delsos ir podėlio statistiką |
|
||
|
||
**Autentifikavimas:** API raktas su „Bearer“ schema (`extractApiKey` + `isValidApiKey`). Paieškos politika taikoma naudojant `enforceApiKeyPolicy`.
|
||
|
||
---
|
||
|
||
## Web Fetch API
|
||
|
||
Gaukite turinį iš URL naudodami sukonfigūruotą žiniatinklio turinio gavimo teikėją („Firecrawl“, „Jina
|
||
Reader“, „Tavily Extract“, „TinyFish Fetch“, „Nimble Extract“).
|
||
|
||
| Metodas | Kelias | Aprašas |
|
||
| ------- | --------------- | ------------------------------------------------------------------------------------- |
|
||
| POST | `/v1/web/fetch` | Gauna / išrenka turinį iš URL — užklausos turinys tikrinamas pagal `v1WebFetchSchema` |
|
||
|
||
**Autentifikavimas:** „Bearer“ API raktas (`extractApiKey` + `isValidApiKey`). Politika taikoma per `enforceApiKeyPolicy`.
|
||
|
||
**Kvotas įvertinantis atsarginis perjungimas (#8297):** kai aiškus `provider` nenurodytas, telkinys
|
||
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) pereinamas
|
||
fiksuota prioriteto tvarka (pirmiausia užpildant aukščiausio prioriteto teikėją) — sukonfigūruotas teikėjas, kurio užklausų dažnis apribotas, praleidžiamas,
|
||
užuot iš karto nutraukus užklausą, o pakartotinai bandytina / su kvota susijusi aukštesnio lygmens paslaugos klaida
|
||
(HTTP 429 visada; 402/403 „Firecrawl“ / „Tavily“ / „TinyFish“ kvotos tipo nemokamuose planuose —
|
||
ne „Jina Reader“ atveju ir niekada paprastos 400 netinkamos užklausos atveju) užklausos vykdymo metu perduodama
|
||
kitam dar nebandytam teikėjui, kuriam yra prisijungimo duomenys. Kai visi telkinio teikėjai
|
||
išnaudoti, galinis taškas grąžina vieną `429` (su `Retry-After`
|
||
antrašte), o ne ankstesnį bendrąjį `400`. Kai aiškiai nurodomas `provider`,
|
||
**tylus atsarginis perjungimas nevykdomas** — teikėjo, kurio užklausų dažnis apribotas arba kuris sutriko, klaida
|
||
grąžinama tiesiogiai (`429`, jei užklausų dažnis apribotas, kitu atveju — aukštesnio lygmens paslaugos
|
||
būsena).
|
||
|
||
---
|
||
|
||
## Srautinis perdavimas per WebSocket
|
||
|
||
```bash
|
||
GET /v1/ws?handshake=1
|
||
```
|
||
|
||
Patikrina WebSocket protokolo pakeitimo užmezgimo užklausą ir grąžina perdavimo protokolo pavyzdinius pranešimus (`request`, `cancel`). Faktinius WS kadrus apdoroja komplekte esantis WS serveris už Next.js maršrutų lentelės ribų.
|
||
|
||
**Autentifikavimas:** „Bearer“ API raktas užmezgant ryšį.
|
||
|
||
### Responses API per WebSocket (tik codex)
|
||
|
||
```bash
|
||
# Tas pats pagrindinis kompiuteris ir prievadas kaip HTTP API (numatytasis 20128); pakeiskite ryšio protokolą:
|
||
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
|
||
# (arba: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
|
||
|
||
# Pirmasis kadras PRIVALO būti response.create:
|
||
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
|
||
```
|
||
|
||
Responses API per WebSocket tarpinis serveris susietas **tik su `codex`** (ChatGPT
|
||
vidine sistema). Jis klausosi tame pačiame prievade kaip API / valdymo skydelis, keliuose `/v1/responses`,
|
||
`/responses` ir `/api/v1/responses`. Gavęs pirmąjį `response.create` kadrą, jis
|
||
atlieka autentifikavimą ir paruošimą per vidinį `codex-responses-ws` tiltą, pasirenka
|
||
codex OAuth ryšį ir tuneliuoja į `wss://chatgpt.com/backend-api/codex/responses`
|
||
naudodamas `wreq-js` transportą. **Ne codex modeliai atmetami** (`codex_ws_provider_required`).
|
||
Maršruto parinkimui pagal bendrinamą kvotą naudokite `model: "qtSd/<group>/codex/<model>"`. Įgyvendinta
|
||
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.
|
||
|
||
**Autentifikavimas:** „Bearer“ API raktas užmezgant ryšį. Komplekte esantis HTTP serveris (`server-ws.mjs`)
|
||
turi būti aktyvus įėjimo taškas (pagal numatytuosius nustatymus taip ir yra, kai egzistuoja `app/server-ws.mjs`).
|
||
|
||
#### Modelio ID: naudokite nepapildytą ChatGPT ID (be `codex/` prefikso)
|
||
|
||
OpenAI **Codex CLI** tikrina modelio pavadinimą kliento pusėje, kai
|
||
`supports_websockets = true`, ir **atmeta teikėjo prefiksą turinčius ID**, pvz.,
|
||
`codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with
|
||
a ChatGPT account`). Siųskite **nepapildytą** ID (pvz., `gpt-5.5`). OmniRoute tiltas
|
||
skirtas tik codex, todėl prieš tuneliuojant į aukštesnio lygmens paslaugą nepapildytas ID iš naujo susiejamas su codex modeliu
|
||
(`resolveCodexWsModelInfo`) — nors nepapildytas
|
||
`gpt-5.5` naudojant HTTP kitu atveju būtų nukreiptas kitam teikėjui.
|
||
|
||
#### OpenAI Codex CLI konfigūravimas
|
||
|
||
Nukreipkite Codex CLI į OmniRoute, į `~/.codex/config.toml` pridėdami pasirinktinį teikėją, palaikantį WebSocket
|
||
(naudokite atskirą `CODEX_HOME`, kad nepakeistumėte
|
||
esamos konfigūracijos):
|
||
|
||
```toml
|
||
model = "gpt-5.5" # nepapildytas ID — NE "codex/gpt-5.5"
|
||
model_provider = "omniroute"
|
||
|
||
[model_providers.omniroute]
|
||
name = "OmniRoute (WS)"
|
||
base_url = "http://localhost:20128/v1" # be baigiamojo pasvirojo brūkšnio; WS URL išvedamas automatiškai (gamybinėje aplinkoje naudokite https/wss)
|
||
wire_api = "responses" # vienintelė palaikoma reikšmė nuo 2026 m. vasario
|
||
supports_websockets = true # įjungia Responses per WS transportą
|
||
env_key = "OMNIROUTE_API_KEY" # saugo OmniRoute API raktą („Bearer“)
|
||
```
|
||
|
||
```bash
|
||
export OMNIROUTE_API_KEY=sk-... # OmniRoute API raktas (bet kuris raktas, jei REQUIRE_API_KEY=false)
|
||
codex exec "Responda apenas: PONG"
|
||
```
|
||
|
||
CLI pakeičia `base_url + /responses` ryšį į WebSocket, o OmniRoute tuneliuoja jį
|
||
į pasirinktą codex OAuth ryšį. Visas procesas patikrintas naudojant vietinį
|
||
serverį: ChatGPT grąžina `codex.rate_limits` + `response.created` ir srautiniu būdu perduoda
|
||
užbaigtą atsakymą.
|
||
|
||
---
|
||
|
||
## Kvotų ir problemų pranešimai
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ------------------- | -------------------------------------------------------------------------------------------------- |
|
||
| GET | `/v1/quotas/check` | Iš anksto patikrinti `provider` + `accountId` kvotą prieš išduodant registruotą raktą |
|
||
| POST | `/v1/issues/report` | Pranešti GitHub apie kvotos / rakto išdavimo klaidą (reikia `GITHUB_ISSUES_REPO` + prieigos rakto) |
|
||
|
||
**Autentifikavimas:** Bearer API raktas (`isAuthenticated`).
|
||
|
||
---
|
||
|
||
## Savitarnos naudojimo duomenys (`/api/usage/om-usage`)
|
||
|
||
Bet kuris API raktas gali peržiūrėti **savo paties** naudojimo duomenis ir kvotas — valdymo autentifikavimas nereikalingas. Šią galinę prieigą
|
||
klientas (CLI, OmniCopilot skydelis) naudoja rakto turėtojo išlaidoms rodyti.
|
||
|
||
```bash
|
||
# Tekstinė forma (istorinė sutartis — paprastasis tekstas terminalui)
|
||
curl -H "Authorization: Bearer <jūsų-api-raktas>" \
|
||
http://localhost:20128/api/usage/om-usage
|
||
|
||
# Struktūrizuota forma — skirta naudotojo sąsajai
|
||
curl -H "Authorization: Bearer <jūsų-api-raktas>" \
|
||
"http://localhost:20128/api/usage/om-usage?format=json"
|
||
```
|
||
|
||
Raktui turi būti įjungtas **`allowUsageCommand`** (pagal numatytuosius nustatymus išjungtas — prietaisų skydelio API raktų
|
||
tvarkytuvėje jis perjungiamas kiekvienam raktui atskirai). Jei jis neįjungtas, galinė prieiga atsako `403`.
|
||
|
||
`?format=json` grąžina atskiriamą struktūrą, todėl kvietėjas niekada neskaito duomenų lauko iš
|
||
atmetimo atsakymo. Sėkmės atveju:
|
||
|
||
```jsonc
|
||
{
|
||
"allowed": true,
|
||
// pateikiama tik tada, kai raktui įjungti individualūs naudojimo apribojimai (dienos / savaitės USD):
|
||
"personal": {
|
||
"dailySpentUsd": 1.25,
|
||
"dailyLimitUsd": 5,
|
||
"dailyResetAtIso": "…",
|
||
"weeklySpentUsd": 8,
|
||
"weeklyLimitUsd": 20,
|
||
"weeklyResetAtIso": "…" /* … */,
|
||
},
|
||
// pasirinkto teikėjo kvotos momentinė kopija arba null, kai talpykloje dar nieko nėra:
|
||
"provider": {
|
||
"connectionId": "…",
|
||
"provider": "claude",
|
||
"plan": "…",
|
||
"quotas": {/* … */},
|
||
},
|
||
// kiekvieno ryšio momentinė kopija, kad naudotojo sąsajoje būtų galima greta rodyti kelis teikėjus:
|
||
"providers": [
|
||
{ "connectionId": "…", "provider": "claude" /* … */ },
|
||
{ "provider": "codex" /* … */ },
|
||
],
|
||
}
|
||
```
|
||
|
||
Atmetimo atveju (`401` netinkamas raktas / `403` neleidžiama) tas pats maršrutas grąžina
|
||
`{ "allowed": false, "error": { "message": "…" } }` — pateiktas, bet tuščias `personal` / `provider`
|
||
(raktas leidžiamas, tačiau dar nėra gauta duomenų) yra kitokia būsena nei atmetimas, ir jas atskiria tik JSON forma.
|
||
|
||
**Autentifikavimas:** paties kvietėjo Bearer API raktas, patikrintas naudojant `isValidApiKey` — tai _nėra_
|
||
valdymo sąsaja (`/api/keys/…`), kuri tebėra apsaugota naudojant `requireManagementAuth`.
|
||
|
||
---
|
||
|
||
## Semantinė talpykla
|
||
|
||
```bash
|
||
# Gauti talpyklos statistiką
|
||
GET /api/cache/stats
|
||
|
||
# Išvalyti visas talpyklas
|
||
DELETE /api/cache/stats
|
||
```
|
||
|
||
Atsakymo pavyzdys:
|
||
|
||
```json
|
||
{
|
||
"semanticCache": {
|
||
"memorySize": 42,
|
||
"memoryMaxSize": 500,
|
||
"dbSize": 128,
|
||
"hitRate": 0.65
|
||
},
|
||
"idempotency": {
|
||
"activeKeys": 3,
|
||
"windowMs": 5000
|
||
}
|
||
}
|
||
```
|
||
|
||
### Poveikis delsai
|
||
|
||
Semantinės talpyklos PATAIKYMO atveju atsakymas pateikiamas iš talpyklos **be iškvietimo į pirminę paslaugą**,
|
||
todėl nurodyta `X-OmniRoute-Response-Latency` reikšmė yra artima nuliui
|
||
(nepriklausomai nuo pradinės pirminės paslaugos delsos). Delsai jautrūs klientai
|
||
(našumo testavimas, p50 / p99 stebėjimas) turėtų tikrinti
|
||
`X-OmniRoute-Cache-Latency` atsakymo antraštę:
|
||
|
||
| Reikšmė | Reikšmė |
|
||
| ----------- | ------------------------------------------------------------------------------- |
|
||
| `synthetic` | Atsakymas pateiktas iš talpyklos; delsa nėra tikrasis pirminės paslaugos laikas |
|
||
| _(nėra)_ | Atsakymas gautas iš tikro iškvietimo į pirminę paslaugą |
|
||
|
||
### Talpyklos apėjimas pagal raktą
|
||
|
||
API raktams galima išjungti skaitymą iš semantinės talpyklos naudojant `cacheDefaultMode`:
|
||
|
||
| Reikšmė | Veikimas |
|
||
| -------- | ------------------------------------------------------------------------- |
|
||
| `legacy` | Įprastas talpyklos veikimas (numatytasis) |
|
||
| `bypass` | Visiškai praleisti paiešką talpykloje; visada kreiptis į pirminę paslaugą |
|
||
|
||
Nustatoma kuriant raktą (`POST /api/keys`) arba atnaujinant (`PATCH /api/keys/[id]`):
|
||
|
||
```json
|
||
{ "cacheDefaultMode": "bypass" }
|
||
```
|
||
|
||
### Apėjimas pagal užklausą
|
||
|
||
Bet kuri užklausa gali apeiti talpyklą neatsižvelgiant į rakto nustatymus:
|
||
|
||
```
|
||
X-OmniRoute-No-Cache: true
|
||
```
|
||
|
||
---
|
||
|
||
## Valdymo skydelis ir administravimas
|
||
|
||
Administravimo maršrutai (`/api/*`, išskyrus viešą autentifikavimą / prisijungimą) **nėra** autorizuojami
|
||
įprastais išvadų API raktais. Kredencialų grupės, aprėptys ir curl pavyzdžiai:
|
||
[Administravimo autentifikavimas](../guides/MANAGEMENT-AUTH.md).
|
||
|
||
### Autentifikavimas
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| ----------------------------- | ------- | ---------------------------------------------- |
|
||
| `/api/auth/login` | POST | Prisijungti |
|
||
| `/api/auth/logout` | POST | Atsijungti |
|
||
| `/api/settings/require-login` | GET/PUT | Įjungti arba išjungti prisijungimo reikalavimą |
|
||
|
||
### Teikėjų valdymas
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| ---------------------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `/api/providers` | GET/POST | Išvardyti / sukurti teikėjus |
|
||
| `/api/providers/[id]` | GET/PUT/DELETE | Valdyti teikėją |
|
||
| `/api/providers/[id]/test` | POST | Patikrinti ryšį su teikėju |
|
||
| `/api/providers/[id]/models` | GET | Išvardyti teikėjo modelius |
|
||
| `/api/providers/validate` | POST | Patikrinti teikėjo konfigūraciją |
|
||
| `/api/providers/bulk` | POST | Masiškai pridėti VIENO teikėjo API raktus |
|
||
| `/api/providers/import` | POST | Importuoti nevienalytį teikėjų SĄRAŠĄ iš išanalizuoto CSV/JSON failo (#6836); pateikiami kiekvienos eilutės dalinio nepavykimo rezultatai |
|
||
| `/api/provider-nodes*` | Įvairūs | Teikėjo mazgų valdymas |
|
||
| `/api/provider-models` | GET/POST/PATCH/DELETE | Pasirinktiniai modeliai (pridėti, atnaujinti, paslėpti / rodyti, pašalinti) |
|
||
|
||
### OAuth srautai
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| -------------------------------- | ------- | ----------------------- |
|
||
| `/api/oauth/[provider]/[action]` | Įvairūs | Teikėjui būdingas OAuth |
|
||
|
||
### Maršrutų parinkimas ir konfigūracija
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| --------------------- | -------- | ----------------------------------- |
|
||
| `/api/models/alias` | GET/POST | Modelių alternatyvieji pavadinimai |
|
||
| `/api/models/catalog` | GET | Visi modeliai pagal teikėją ir tipą |
|
||
| `/api/combos*` | Įvairūs | Derinių valdymas |
|
||
| `/api/keys*` | Įvairūs | API raktų valdymas |
|
||
| `/api/pricing` | GET | Modelių kainodara |
|
||
|
||
### Naudojimas ir analizė
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `/api/usage/history` | GET | Naudojimo istorija |
|
||
| `/api/usage/logs` | GET | Naudojimo žurnalai |
|
||
| `/api/usage/request-logs` | GET | Užklausų lygmens žurnalai |
|
||
| `/api/usage/[connectionId]` | GET | Kiekvieno ryšio naudojimas |
|
||
| `/api/usage/token-limits` | GET/POST/DELETE | Kiekvieno API rakto žetonų limitų biudžetai |
|
||
| `/api/usage/model-latency-stats` | GET | Slenkamasis kiekvieno teikėjo / modelio delsos suvestinis rodiklis (avg/p50/p95/p99, sėkmės rodiklis); filtrai: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) |
|
||
| `/api/usage/cache-health` | GET | Užklausų podėlio būklės suvestinė pagal `call_logs` — rašymo / skaitymo santykis, p50/p90/p99 rašymo dydžio pasiskirstymas, intensyvaus rašymo koncentracija, išskaidymas pagal modelį ir `healthy`/`degraded`/`thrash`/`no-data` įvertis; užklausos parametrai `range` (`1h`\|`24h`\|`7d`\|`30d`, numatytoji reikšmė `24h`) ir pasirinktinis `model` (#8827) |
|
||
|
||
### Nuostatos
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| `/api/settings` | GET/PUT/PATCH | Bendrosios nuostatos |
|
||
| `/api/settings/proxy` | GET/PUT | Tinklo įgaliotojo serverio konfigūracija |
|
||
| `/api/settings/proxy/test` | POST | Patikrinti ryšį su įgaliotuoju serveriu |
|
||
| `/api/settings/ip-filter` | GET/PUT | Leidžiamų / blokuojamų IP adresų sąrašas |
|
||
| `/api/settings/thinking-budget` | GET/PUT | Mąstymo / samprotavimo **užklausos** perrašymo režimas (perduoti nepakeistą / automatiškai pašalinti / pasirinktinis / adaptyvusis). Nepriklauso nuo glaudinimo. Žr. [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). |
|
||
| `/api/settings/system-prompt` | GET/PUT | Visuotinė sistemos užklausa |
|
||
| `/api/settings/compression` | GET/PUT | Visuotinė glaudinimo konfigūracija |
|
||
| `/api/settings/purge-request-history` | POST | Išvalyti užklausų žurnalo eilutes ir vietinius iškvietimų žurnalo artefaktus |
|
||
|
||
### Kontekstas ir glaudinimas
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| -------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------- |
|
||
| `/api/compression/preview` | POST | Peržiūrėti išjungto / lengvo / standartinio / agresyvaus / ultra / RTK / sudėtinio glaudinimo rezultatą |
|
||
| `/api/compression/language-packs` | GET | Išvardyti pasiekiamus Caveman kalbų paketus |
|
||
| `/api/compression/rules` | GET | Išvardyti Caveman taisyklių metaduomenis |
|
||
| `/api/context/caveman/config` | GET/PUT | Caveman būdingų nuostatų alternatyvusis pavadinimas |
|
||
| `/api/context/rtk/config` | GET/PUT | RTK būdingos nuostatos, įskaitant pasirinktinius filtrus ir neapdorotos išvesties išsaugojimą |
|
||
| `/api/context/rtk/filters` | GET | RTK filtrų katalogas ir pasirinktinių filtrų diagnostika |
|
||
| `/api/context/rtk/test` | POST | Paleisti RTK peržiūrą / testą naudojant tekstinę naudingąją apkrovą |
|
||
| `/api/context/rtk/raw-output/[id]` | GET | Perskaityti išsaugotą nuasmenintą neapdorotą išvestį pagal rodyklės id |
|
||
| `/api/context/combos` | GET/POST | Glaudinimo derinių sąrašas / kūrimas |
|
||
| `/api/context/combos/[id]` | GET/PUT/DELETE | Glaudinimo derinio informacija / atnaujinimas / pašalinimas |
|
||
| `/api/context/combos/[id]/assignments` | GET/PUT | Priskirti glaudinimo derinius maršrutų parinkimo deriniams |
|
||
| `/api/context/analytics` | GET | Alternatyvusis glaudinimo analizės pavadinimas |
|
||
|
||
### Stebėsena
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| ------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| `/api/sessions` | GET | Aktyvių seansų stebėjimas |
|
||
| `/api/rate-limits` | GET | Kiekvienos paskyros spartos apribojimai |
|
||
| `/api/monitoring/health` | GET | Būklės patikra ir teikėjų suvestinė (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`) |
|
||
| `/api/cache/stats` | GET/DELETE | Podėlio statistika / išvalymas |
|
||
| `/api/modality-bridge/stats` | GET | Atmintyje laikomi `attempts`, sėkmingi bandymai / `bridged`, nesėkmės, podėlio pataikymai, `totalLatencyMs`, `latencySamples`, pagal imčių skaičių apskaičiuotas `averageLatencyMs` ir paskutinio naudojimo laikas (nustatoma iš naujo paleidus; administravimo autentifikavimas) |
|
||
| `/api/modality-bridge/video/runtime` | GET | Griežta patikimo grįžtamojo ryšio sąsajos patikra prieš administravimo autentifikavimą / zondavimą; išvalyta FFmpeg/ffprobe pasiekiamumo ir versijų informacija (no-store) |
|
||
| `/api/modality-bridge/video/extract` | POST | Vidinis autentifikuotas patikimos grįžtamojo ryšio sąsajos baitų tarpininkas; 50 MiB įvestis, ribota eilė / 32 MiB išvestis, `503` pajėgumas, `499` atsijungimas, `504` terminas; tai nėra vieša įkėlimo API |
|
||
|
||
### Atsarginės kopijos ir eksportavimas / importavimas
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| --------------------------- | ------- | ----------------------------------------------------- |
|
||
| `/api/db-backups` | GET | Išvardyti pasiekiamas atsargines kopijas |
|
||
| `/api/db-backups` | PUT | Sukurti rankinę atsarginę kopiją |
|
||
| `/api/db-backups` | POST | Atkurti iš konkrečios atsarginės kopijos |
|
||
| `/api/db-backups/export` | GET | Atsisiųsti duomenų bazę kaip .sqlite failą |
|
||
| `/api/db-backups/import` | POST | Įkelti .sqlite failą duomenų bazei pakeisti |
|
||
| `/api/db-backups/exportAll` | GET | Atsisiųsti visą atsarginę kopiją kaip .tar.gz archyvą |
|
||
|
||
### Sinchronizavimas su debesija
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| ---------------------- | ------- | -------------------------------------- |
|
||
| `/api/sync/cloud` | Įvairūs | Sinchronizavimo su debesija operacijos |
|
||
| `/api/sync/initialize` | POST | Inicijuoti sinchronizavimą |
|
||
| `/api/cloud/*` | Įvairūs | Debesijos valdymas |
|
||
|
||
### Tuneliai
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| -------------------------- | ------- | ----------------------------------------------------------------------------- |
|
||
| `/api/tunnels/cloudflared` | GET | Nuskaityti Cloudflare Quick Tunnel diegimo / vykdymo būseną valdymo skydeliui |
|
||
| `/api/tunnels/cloudflared` | POST | Įjungti arba išjungti Cloudflare Quick Tunnel (`action=enable/disable`) |
|
||
| `/api/tunnels/ngrok` | GET | Nuskaityti ngrok Tunnel vykdymo būseną valdymo skydeliui |
|
||
| `/api/tunnels/ngrok` | POST | Įjungti arba išjungti ngrok Tunnel (`action=enable/disable`) |
|
||
|
||
### CLI įrankiai
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| ---------------------------------- | ------- | ---------------------------- |
|
||
| `/api/cli-tools/claude-settings` | GET | Claude CLI būsena |
|
||
| `/api/cli-tools/codex-settings` | GET | Codex CLI būsena |
|
||
| `/api/cli-tools/droid-settings` | GET | Droid CLI būsena |
|
||
| `/api/cli-tools/openclaw-settings` | GET | OpenClaw CLI būsena |
|
||
| `/api/cli-tools/runtime/[toolId]` | GET | Bendroji CLI vykdymo aplinka |
|
||
|
||
CLI atsakymai apima: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
|
||
|
||
### ACP agentai
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| ----------------- | ------- | -------------------------------------------------------------------------- |
|
||
| `/api/acp/agents` | GET | Išvardyti visus aptiktus agentus (integruotus ir pasirinktinius) su būsena |
|
||
| `/api/acp/agents` | POST | Pridėti pasirinktinį agentą arba atnaujinti aptikimo podėlį |
|
||
| `/api/acp/agents` | DELETE | Pašalinti pasirinktinį agentą pagal `id` užklausos parametrą |
|
||
|
||
GET atsakymas apima `agents[]` (id, name, binary, version, installed, protocol, isCustom) ir `summary` (total, installed, notFound, builtIn, custom).
|
||
|
||
### Atsparumas ir spartos apribojimai
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
|
||
| `/api/resilience` | GET/PATCH | Gauti / atnaujinti užklausų eilės, ryšio atvėsimo, teikėjo grandinės pertraukiklio ir laukimo nuostatas |
|
||
| `/api/resilience/reset` | POST | Iš naujo nustatyti teikėjo grandinės pertraukiklius |
|
||
| `/api/resilience/model-cooldowns` | GET | Išvardyti aktyvius kiekvieno (teikėjo, ryšio, modelio) blokavimus, surikiuotus pagal likusį laiką |
|
||
| `/api/resilience/model-cooldowns` | DELETE | Išvalyti modelio blokavimą — turinys `{provider, model}` arba `{all: true}`, kad būtų išvalyta viskas |
|
||
| `/api/rate-limits` | GET | Kiekvienos paskyros spartos apribojimo būsena |
|
||
| `/api/rate-limit` | GET | Visuotinė spartos apribojimo konfigūracija |
|
||
|
||
> Visiems keturiems `/api/resilience/*` maršrutams būtinas **administravimo autentifikavimas** (`requireManagementAuth`). Išsamų teikėjo grandinės pertraukiklio, ryšio atvėsimo ir modelio blokavimo skirtumų aprašymą žr. [Atsparumas (išplėstinis)](#resilience-extended).
|
||
|
||
### Vertinimai
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| -------------- | -------- | ------------------------------------------------- |
|
||
| `/api/evals` | GET/POST | Išvardyti vertinimo rinkinius / vykdyti vertinimą |
|
||
|
||
### Politika
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| --------------- | --------------- | ----------------------------------- |
|
||
| `/api/policies` | GET/POST/DELETE | Valdyti maršrutų parinkimo politiką |
|
||
|
||
### Atitiktis
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| --------------------------- | ------- | ------------------------------------------ |
|
||
| `/api/compliance/audit-log` | GET | Atitikties audito žurnalas (paskutiniai N) |
|
||
|
||
### v1beta (suderinama su Gemini)
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| -------------------------- | ------- | --------------------------------------- |
|
||
| `/v1beta/models` | GET | Išvardyti modelius Gemini formatu |
|
||
| `/v1beta/models/{...path}` | POST | Gemini `generateContent` galinis taškas |
|
||
|
||
Šie galiniai taškai atkartoja Gemini API formatą klientams, kuriems būtinas vietinis suderinamumas su Gemini SDK.
|
||
|
||
### Vidinės / sistemos API
|
||
|
||
| Galinis taškas | Metodas | Aprašymas |
|
||
| ------------------------ | ------- | ----------------------------------------------------------------- |
|
||
| `/api/init` | GET | Programos inicijavimo patikra (naudojama pirmą kartą paleidžiant) |
|
||
| `/api/tags` | GET | Su Ollama suderinamos modelių žymos (Ollama klientams) |
|
||
| `/api/restart` | POST | Inicijuoti sklandų serverio paleidimą iš naujo |
|
||
| `/api/shutdown` | POST | Inicijuoti sklandų serverio išjungimą |
|
||
| `/api/system/env/repair` | POST | Taisyti OAuth teikėjo aplinkos kintamuosius |
|
||
|
||
> **Pastaba:** šiuos galinius taškus sistema naudoja viduje arba suderinamumui su Ollama klientais užtikrinti. Galutiniai naudotojai paprastai jų nekviečia.
|
||
|
||
### OAuth aplinkos taisymas _(v3.6.1+)_
|
||
|
||
```bash
|
||
POST /api/system/env/repair
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"provider": "claude-code"
|
||
}
|
||
```
|
||
|
||
Pataiso trūkstamus arba sugadintus konkretaus teikėjo OAuth aplinkos kintamuosius. Grąžina:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
|
||
"backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Garso transkripcija
|
||
|
||
```bash
|
||
POST /v1/audio/transcriptions
|
||
Authorization: Bearer your-api-key
|
||
Content-Type: multipart/form-data
|
||
```
|
||
|
||
Transkribuokite garso failus naudodami bet kurį sukonfigūruotą STT teikėją. Pirmasis kelio
|
||
segmentas parenka savąjį teikėją (`openai/…`, `deepgram/…`). Tinklų sąsajos, kurios
|
||
pakartotinai eksportuoja kito tiekėjo modelį, naudoja kvalifikuotą ID
|
||
(`openrouter/deepgram/nova-3`).
|
||
|
||
**Užklausa:**
|
||
|
||
```bash
|
||
curl -X POST http://localhost:20128/v1/audio/transcriptions \
|
||
-H "Authorization: Bearer your-api-key" \
|
||
-F "file=@recording.mp3" \
|
||
-F "model=openai/whisper-1"
|
||
```
|
||
|
||
**Atsakymas:**
|
||
|
||
```json
|
||
{
|
||
"text": "Hello, this is the transcribed audio content.",
|
||
"task": "transcribe",
|
||
"language": "en",
|
||
"duration": 12.5
|
||
}
|
||
```
|
||
|
||
**Modelių ID pavyzdžiai:** `openai/whisper-1` (reikalingas OpenAI raktas),
|
||
`openrouter/deepgram/nova-3` (reikalingas OpenRouter raktas),
|
||
`deepgram/nova-3` (reikalingas savasis Deepgram raktas). Neapibrėžta
|
||
`deepgram/nova-3` užklausa **nenaudoja** OpenRouter.
|
||
|
||
**Palaikomi formatai:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
|
||
|
||
---
|
||
|
||
## Suderinamumas su Ollama
|
||
|
||
Klientams, naudojantiems Ollama API formatą:
|
||
|
||
```bash
|
||
# Pokalbių galinis taškas (Ollama formatas)
|
||
POST /v1/api/chat
|
||
|
||
# Modelių sąrašas (Ollama formatas)
|
||
GET /api/tags
|
||
```
|
||
|
||
Užklausos automatiškai konvertuojamos tarp Ollama ir vidinių formatų.
|
||
|
||
## Žetoniniai VS Code / antraštės nereikalaujantys alternatyvūs adresai
|
||
|
||
Naudokite šiuos alternatyvius adresus, kai integracija negali įterpti `Authorization` antraštės ir API raktą reikia įtraukti į bazinį URL.
|
||
|
||
```bash
|
||
# OpenAI stiliaus katalogo alternatyvus adresas
|
||
GET /api/v1/vscode/{token}/
|
||
GET /api/v1/vscode/{token}/models
|
||
|
||
# OpenAI stiliaus pokalbių alternatyvūs adresai
|
||
POST /api/v1/vscode/{token}/chat/completions
|
||
POST /api/v1/vscode/{token}/responses
|
||
|
||
# Ollama stiliaus alternatyvūs adresai
|
||
POST /api/v1/vscode/{token}/api/chat
|
||
GET /api/v1/vscode/{token}/api/tags
|
||
```
|
||
|
||
Pavyzdys:
|
||
|
||
```bash
|
||
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"}]}'
|
||
```
|
||
|
||
Pastabos:
|
||
|
||
- Žetoniniai alternatyvūs adresai pakartotinai naudoja tas pačias apdorojimo funkcijas kaip `/v1/*` ir `/api/tags`; atsakymų struktūra išlieka tokia pati.
|
||
- Kai klientas palaiko pasirinktines antraštes, pirmenybę teikite `Authorization: Bearer ...`.
|
||
- URL esantys žetonai gali būti matomi atvirkštinio tarpinio serverio žurnaluose, naršyklės istorijoje ir telemetrijoje už OmniRoute ribų. Laikykite juos suderinamumo parinktimi, o ne numatytuoju autentifikavimo režimu.
|
||
|
||
---
|
||
|
||
## Telemetrija
|
||
|
||
```bash
|
||
# Gauti delsos telemetrijos suvestinę (kiekvieno teikėjo p50/p95/p99)
|
||
GET /api/telemetry/summary
|
||
```
|
||
|
||
**Atsakymas:**
|
||
|
||
```json
|
||
{
|
||
"providers": {
|
||
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
|
||
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Biudžetas
|
||
|
||
```bash
|
||
# Gauti visų API raktų biudžeto būseną
|
||
GET /api/usage/budget
|
||
|
||
# Nustatyti arba atnaujinti biudžetą
|
||
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"
|
||
}
|
||
```
|
||
|
||
> **Schemos pastabos** (`setBudgetSchema`): `apiKeyId` yra privalomas; bent viena iš `dailyLimitUsd`, `weeklyLimitUsd` arba `monthlyLimitUsd` reikšmių turi būti didesnė už nulį. Neprivalomi laukai: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Naudojant pasenusią struktūrą `{keyId, limit, period}`, grąžinamas atsakymas `400 Bad Request`.
|
||
|
||
## Žetonų limitai
|
||
|
||
Kiekvienam API raktui taikomi **žetonų** biudžetai (atskiri nuo pirmiau aprašyto USD pagrįsto biudžeto). Jie tikrinami tiesiogiai užklausos apdorojimo kelyje: kai rakto naudojimas dabartiniame laikotarpyje pasiekia nustatytą limitą, užklausos atmetamos pateikiant `429 Too Many Requests`. Limitai gali būti taikomi konkrečiam `model`, `provider` arba visam raktui `global` mastu; kai užklausą atitinka keli limitai, taikomas griežčiausias.
|
||
|
||
```bash
|
||
# Pateikti rakto žetonų limitų sąrašą (įskaitant dabartinio laikotarpio naudojimą)
|
||
GET /api/usage/token-limits?apiKeyId=key-123
|
||
|
||
# Sukurti arba atnaujinti žetonų limitą
|
||
POST /api/usage/token-limits
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"apiKeyId": "key-123",
|
||
"scopeType": "model",
|
||
"scopeValue": "openai/gpt-4o",
|
||
"tokenLimit": 1000000,
|
||
"resetInterval": "monthly",
|
||
"enabled": true
|
||
}
|
||
|
||
# Ištrinti žetonų limitą pagal id
|
||
DELETE /api/usage/token-limits?id=tl-abc
|
||
```
|
||
|
||
> **Schemos pastabos** (`setTokenLimitSchema`): `apiKeyId` ir `scopeType` (`model` | `provider` | `global`) yra privalomi. `scopeValue` yra privalomas, nebent `scopeType` yra `global` (pvz., modelio id, kai taikymo sritis yra `model`, arba teikėjo id, kai taikymo sritis yra `provider`). `tokenLimit` turi būti teigiamas sveikasis skaičius (konvertuojamas iš eilutės). Neprivalomi laukai: `id` (praleiskite kurdami, pateikite atnaujindami), `resetInterval` (`daily` | `weekly` | `monthly`, numatytoji reikšmė `monthly`), `resetTime` (`HH:MM`), `enabled` (numatytoji reikšmė `true`). `GET` atsakymai kiekvieną limitą papildo laukais `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` ir `nextResetAt`. Tai yra valdymo klasės galinis taškas (autentifikavimą centralizuotai užtikrina autorizavimo procesas).
|
||
|
||
## Užklausų apdorojimas
|
||
|
||
1. Klientas siunčia užklausą į `/v1/*`
|
||
2. Maršruto apdorojimo priemonė iškviečia `handleChat`, `handleEmbedding`, `handleAudioTranscription` arba `handleImageGeneration`
|
||
3. Nustatomas modelis (tiesioginis teikėjas / modelis arba pseudonimas / derinys)
|
||
4. Prisijungimo duomenys parenkami iš vietinės DB, atsižvelgiant į paskyros pasiekiamumo filtravimą
|
||
5. Pokalbiams: `handleChatCore` patikrina semantinę / parašo podėlį ir nustato derinio glaudinimo nuostatas
|
||
6. Kai įjungta, prieš konvertuojant į teikėjo formatą atliekamas išankstinis glaudinimas (`lite`, Caveman, RTK arba kelių metodų derinys)
|
||
7. Teikėjo vykdyklė išsiunčia užklausą aukštesnio lygio paslaugai
|
||
8. Atsakymas konvertuojamas atgal į kliento formatą (pokalbiams) arba grąžinamas nepakeistas (įterpiniams / vaizdams / garsui)
|
||
9. Įrašomi naudojimo duomenys, glaudinimo analizės duomenys ir užklausų žurnalai
|
||
10. Įvykus klaidoms, pagal derinio taisykles taikomas atsarginis variantas
|
||
|
||
Išsamus architektūros aprašas: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)
|
||
|
||
---
|
||
|
||
## Derinių valdymas
|
||
|
||
Aukštesnio lygio maršruto parinkimo deriniai (jau apibendrinti skiltyje `/api/combos*`) taip pat gali būti susieti santykiu 1:1 pagal modelio id šabloną, todėl OpenAI stiliaus modelio id galima skaidriai nukreipti į derinį.
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | -------------------------------- | ------------------------------------------------------------------------------------ |
|
||
| GET | `/api/model-combo-mappings` | Pateikti visų modelio→derinio susiejimų sąrašą |
|
||
| POST | `/api/model-combo-mappings` | Sukurti susiejimą — turinys: `{pattern, comboId, priority?, enabled?, description?}` |
|
||
| GET | `/api/model-combo-mappings/[id]` | Gauti vieną susiejimą |
|
||
| PUT | `/api/model-combo-mappings/[id]` | Atnaujinti esamo susiejimo laukus |
|
||
| DELETE | `/api/model-combo-mappings/[id]` | Pašalinti susiejimą |
|
||
|
||
**Autentifikavimas:** valdymo seansas / API raktas (`requireManagementAuth`).
|
||
|
||
---
|
||
|
||
## Webhook’ai
|
||
|
||
Siunčiamų „OmniRoute“ įvykių (užklausos užbaigimo, kvotos išnaudojimo, rakto pasukimo ir kt.) webhook prenumeratos.
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ------------------------- | --------------------------------------------------------------------------------- |
|
||
| GET | `/api/webhooks` | Pateikti webhook’ų sąrašą (paslaptys užmaskuojamos kaip `<prefix>...`) |
|
||
| POST | `/api/webhooks` | Sukurti webhook’ą — turinys: `{url, events?: ["*"], secret?, description?}` |
|
||
| GET | `/api/webhooks/[id]` | Gauti webhook’ą |
|
||
| PUT | `/api/webhooks/[id]` | Atnaujinti url/events/secret/description |
|
||
| DELETE | `/api/webhooks/[id]` | Pašalinti webhook’ą |
|
||
| POST | `/api/webhooks/[id]/test` | Nusiųsti bandomąją naudingąją apkrovą webhook’o URL ir grąžinti pristatymo būseną |
|
||
|
||
**Autentifikavimas:** valdymo sesija / API raktas (`requireManagementAuth`).
|
||
|
||
---
|
||
|
||
## Užregistruoti raktai (automatinis valdymas)
|
||
|
||
Naudojama automatinio raktų valdymo posistemėje, kad būtų išduodami ir pasukami API raktai, susieti su pagrindiniu teikėju / paskyra ir turintys dienos bei valandos kvotas.
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| GET | `/api/v1/registered-keys` | Pateikti užregistruotų raktų sąrašą (rodomas tik užmaskuotas prefiksas) |
|
||
| POST | `/api/v1/registered-keys` | Išduoti naują užregistruotą raktą — turinys: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Neužmaskuotas raktas grąžinamas **vieną kartą**. Atmetus dėl kvotos, grąžinamas `429`. |
|
||
| GET | `/api/v1/registered-keys/[id]` | Gauti užregistruoto rakto metaduomenis (be neužmaskuoto rakto duomenų) |
|
||
| DELETE | `/api/v1/registered-keys/[id]` | Atšaukti užregistruotą raktą |
|
||
| POST | `/api/v1/registered-keys/[id]/revoke` | Aiškiai nurodyta atšaukimo galinė prieiga (poveikis toks pats kaip DELETE) |
|
||
|
||
**Autentifikavimas:** „Bearer“ API raktas (`isAuthenticated`). Taip pat žr. `/v1/quotas/check` ir `/v1/issues/report`.
|
||
|
||
---
|
||
|
||
## Agentų protokolas
|
||
|
||
Debesijos agentų užduotys („Claude Code“, „Codex Cloud“, „OpenHands“ ir kt.), nuotoliniu būdu vykdomos „OmniRoute“ naudotojų vardu.
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/v1/agents/tasks` | Užduočių sąrašas — pasirenkami `?provider=`, `?status=`, `?limit=` (1–500, numatytoji reikšmė – 50) |
|
||
| POST | `/api/v1/agents/tasks` | Sukurti užduotį — turinį patikrina `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Grąžina `201` su užduoties apvalkalu |
|
||
| DELETE | `/api/v1/agents/tasks?id=...` | Ištrinti užduotį |
|
||
| GET | `/api/v1/agents/tasks/[id]` | Gauti užduotį — sinchroniškai atnaujina būseną iš pirminio debesijos agento, kai nustatytas `external_id` |
|
||
| POST | `/api/v1/agents/tasks/[id]` | Atskiriamasis veiksmas: `{action: "approve"}`, `{action: "message", message}` arba `{action: "cancel"}` |
|
||
| DELETE | `/api/v1/agents/tasks/[id]` | Ištrinti konkrečią užduotį pagal id |
|
||
|
||
> **Autentifikavimas:** kiekvienam metodui būtinas valdymo autentifikavimas (`requireCloudAgentManagementAuth`). Iki v3.8.0 autentifikavimas nebuvo taikomas — apie nesuderinamą pakeitimą žr. įraše `588a0333`.
|
||
|
||
```bash
|
||
# Sukurti „Claude Code“ debesijos užduotį
|
||
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":"..."}}'
|
||
```
|
||
|
||
---
|
||
|
||
## Valdymo tarpiniai serveriai
|
||
|
||
Išeinantiems HTTP(S)/SOCKS ryšiams skirti tarpiniai serveriai, kuriuos galima priskirti teikėjams, paskyroms arba visuotinai.
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/v1/management/proxies` | Tarpinių serverių sąrašas (su `?id=` grąžina vieną; su `?id=&where_used=1` grąžina priskyrimų grafą) |
|
||
| POST | `/api/v1/management/proxies` | Sukurti tarpinį serverį — turinį patikrina `createProxyRegistrySchema` |
|
||
| PATCH | `/api/v1/management/proxies` | Atnaujinti tarpinį serverį — turinį patikrina `updateProxyRegistrySchema` (būtinas `id`) |
|
||
| DELETE | `/api/v1/management/proxies?id=...&force=1` | Ištrinti tarpinį serverį (naudokite `force=1`, kad pašalintumėte priskyrimus) |
|
||
| GET | `/api/v1/management/proxies/assignments` | Priskyrimų sąrašas — galima filtruoti pagal `proxy_id`, `scope`, `scope_id`; perduokite `resolve_connection_id=<id>`, kad nustatytumėte aktyvų ryšio tarpinį serverį |
|
||
| PUT | `/api/v1/management/proxies/assignments` | Priskirti — turinį patikrina `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Išvalo dispečerio podėlį |
|
||
| PUT | `/api/v1/management/proxies/bulk-assign` | Masinis priskyrimas — turinį patikrina `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) |
|
||
| GET | `/api/v1/management/proxies/health?hours=24` | Suvestinė tarpinio serverio būklė per nurodytą laikotarpį (sėkmingų / nesėkmingų užklausų skaičius, delsa) |
|
||
|
||
**Autentifikavimas:** kiekvienam maršrutui būtina valdymo sesija / API raktas (`requireManagementAuth`).
|
||
|
||
> Užduoties apraše nurodytus `POST /api/v1/management/proxies/[id]/assignments` ir `POST /api/v1/management/proxies/[id]/health` aptarnauja pirmiau parodyti plokščios struktūros maršrutai `/assignments` ir `/health` — kodų bazėje nėra atskirų kiekvienam id skirtų antrinių maršrutų.
|
||
|
||
---
|
||
|
||
## Atsparumas (išplėstinis)
|
||
|
||
„OmniRoute“ suteikia tris nepriklausomus laikinųjų trikčių valdymo mechanizmus; toliau nurodyti valdymo galiniai taškai leidžia operatoriams peržiūrėti ir pakeisti jų būseną:
|
||
|
||
| Apimtis | Būsenos saugojimo vieta | Peržiūra | Nustatymas iš naujo / išvalymas |
|
||
| ------------------------------- | ------------------------------------------------ | ----------------------------------------- | --------------------------------------------------- |
|
||
| Teikėjo grandinės pertraukiklis | `domain_circuit_breakers` + atmintyje | `/api/monitoring/health` | `POST /api/resilience/reset` |
|
||
| Ryšio laukimo laikotarpis | `rateLimitedUntil` teikėjo ryšiuose | `/api/rate-limits`, `/api/providers/[id]` | (vėl įjungiama atidėtai; išvaloma teikėjo PUT būdu) |
|
||
| Modelio blokavimas | Atmintyje esantis modelių pasiekiamumo registras | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` |
|
||
|
||
`PATCH /api/resilience` priima teikėjo grandinės pertraukiklio perrašymus laukuose `providerBreaker.oauth` ir `providerBreaker.apikey`. Kiekviename profilyje galima naudoti `degradationThreshold`, `failureThreshold` ir `resetTimeoutMs`; tie patys laukai pateikiami skiltyje Valdymo skydas → Nustatymai → Atsparumas.
|
||
|
||
```bash
|
||
# Išvalyti vieno modelio blokavimą
|
||
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"}'
|
||
|
||
# Išvalyti visus blokavimus
|
||
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
|
||
-H "Cookie: auth_token=..." \
|
||
-d '{"all":true}'
|
||
```
|
||
|
||
Išsamią koncepcinę informaciją ir numatytąsias grandinės pertraukiklio reikšmes žr. [`CLAUDE.md`](../../CLAUDE.md) → „Atsparumo vykdymo aplinkos būsena“.
|
||
|
||
---
|
||
|
||
## Įgūdžiai
|
||
|
||
Sistema, skirta „OmniRoute“ plėsti pasirinktinėmis vykdomosiomis apdorojimo programomis, taip pat integracijomis su prekyvietėmis.
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/skills` | Pateikia įdiegtų įgūdžių sąrašą — galima filtruoti pagal `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, palaikomas puslapiavimas |
|
||
| GET | `/api/skills/[id]` | Gauna vieną įgūdį |
|
||
| PUT | `/api/skills/[id]` | Atnaujina įgūdį (pavadinimą, aprašymą, režimą, schemą, apdorojimo programą, žymas) |
|
||
| DELETE | `/api/skills/[id]` | Pašalina įgūdį |
|
||
| POST | `/api/skills/install` | Įdiegia įgūdį iš neapdoroto manifesto — užklausos turinys: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
|
||
| GET | `/api/skills/executions` | Pateikia naujausių įgūdžių vykdymų sąrašą (audito seka su įvestimis, išvestimis ir trukme) |
|
||
| GET | `/api/skills/marketplace?q=...` | Paieškos / populiarių įgūdžių sąrašas iš „SkillsMP“ prekyvietės (reikalinga `skillsmpApiKey` nuostata) |
|
||
| POST | `/api/skills/marketplace/install` | Įdiegia įgūdį pagal jo id iš „SkillsMP“ |
|
||
| GET | `/api/skills/skillssh?q=&limit=` | Atlieka paiešką „skills.sh“ registre |
|
||
| POST | `/api/skills/skillssh/install` | Įdiegia įgūdį pagal jo id iš „skills.sh“ |
|
||
|
||
**Autentifikavimas:** valdymo seansas / API raktas. Prekyvietės paieškos maršrutai priima valdymo autentifikavimo duomenis arba „Bearer“ API raktą (`isAuthenticated`).
|
||
|
||
---
|
||
|
||
## Atmintis
|
||
|
||
Nuolatinė pokalbių / faktinės atminties saugykla, kurios apimtis nustatoma pagal API raktą / seansą.
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/memory` | Atminčių sąrašas — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, su puslapių skaidymu naudojant `offset/limit` arba `page/limit` |
|
||
| POST | `/api/memory` | Sukurti atmintį — užklausos turinį tikrina Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
|
||
| GET | `/api/memory/[id]` | Gauti vieną atmintį |
|
||
| DELETE | `/api/memory/[id]` | Ištrinti atmintį |
|
||
| GET | `/api/memory/health` | Atminties posistemės būklė (DB ryšys, vektorinių įterpinių posistemė, vektorinio indekso būsena) |
|
||
|
||
**Autentifikavimas:** valdymo seansas / API raktas (`requireManagementAuth`). `type` išvardijimas: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (žr. `MemoryType`, esantį `src/lib/memory/types.ts`).
|
||
|
||
---
|
||
|
||
## MCP serveris
|
||
|
||
OmniRoute pateikiamas su integruotu Model Context Protocol serveriu, turinčiu 3 transportus (stdio, SSE, streamable-http) ir pagal apimtis apribotus įrankius. Toliau nurodyti valdymo skydelio galiniai taškai nuskaito būsenos / audito duomenis ir veikia kaip HTTP transportų tarpinis serveris.
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
|
||
| GET | `/api/mcp/status` | Periodinis signalas, transportas, prisijungimo būsena, paskutinis iškvietimas, populiariausi įrankiai, sėkmės rodiklis per 24 val. |
|
||
| GET | `/api/mcp/tools` | MCP įrankių sąrašas su `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
|
||
| GET | `/api/mcp/sse` | Atverti SSE srautą SSE transportui (grąžina `503`, jei MCP išjungtas arba transportas neatitinka) |
|
||
| POST | `/api/mcp/sse` | Siųsti JSON-RPC kadrą SSE transportu |
|
||
| GET | `/api/mcp/stream` | Atverti Streamable HTTP transporto SSE pusę (serverio inicijuojami pranešimai) |
|
||
| POST | `/api/mcp/stream` | Siųsti JSON-RPC kadrą Streamable HTTP transportu |
|
||
| DELETE | `/api/mcp/stream` | Užbaigti Streamable HTTP seansą |
|
||
| GET | `/api/mcp/audit` | Pateikti audito žurnalo užklausą — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` |
|
||
| GET | `/api/mcp/audit/stats` | Suvestinė audito statistika (bendri skaičiai, sėkmės rodiklis, vidutinė trukmė, populiariausi įrankiai) |
|
||
|
||
**Autentifikavimas:** `sse` / `stream` transportai naudoja MCP skirtą autentifikavimo sąsają („Bearer“ API raktą su `mcp` apimtimi); `status` / `tools` / `audit*` maršrutai pasiekiami iš valdymo skydelio (pasiekus valdymo skydelio pagrindinį kompiuterį, papildomas autentifikavimas nereikalingas).
|
||
|
||
> Abu HTTP transportai valdomi naudojant `settings.mcpEnabled` ir `settings.mcpTransport` — jei transportas neatitinka, grąžinamas `400`, o jei MCP išjungtas — `503`.
|
||
|
||
---
|
||
|
||
## A2A serveris
|
||
|
||
OmniRoute pateikia A2A (agentų tarpusavio sąveikos) JSON-RPC 2.0 galinį tašką ir REST sąsają, skirtą tikrinimui bei valdymo skydui.
|
||
|
||
### JSON-RPC
|
||
|
||
```bash
|
||
POST /a2a
|
||
Authorization: Bearer your-api-key # neprivaloma, nebent nustatytas 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"}]
|
||
}
|
||
}
|
||
```
|
||
|
||
Palaikomi metodai (visi priklauso nuo `settings.a2aEnabled`):
|
||
|
||
| Metodas | Aprašymas |
|
||
| ---------------- | --------------------------------------------------------------------- |
|
||
| `message/send` | Sinchroninis gebėjimo vykdymas; grąžina `{task, artifacts, metadata}` |
|
||
| `message/stream` | To paties gebėjimų rinkinio srautinis SSE vykdymas |
|
||
| `tasks/get` | Gauti užduotį pagal `taskId` |
|
||
| `tasks/cancel` | Atšaukti užduotį pagal `taskId` |
|
||
|
||
Integruoti gebėjimai: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.
|
||
|
||
### Agento kortelė
|
||
|
||
```bash
|
||
GET /.well-known/agent.json
|
||
```
|
||
|
||
Grąžina viešą A2A agento kortelę (pavadinimą, aprašymą, galimybes, gebėjimų katalogą, autentifikavimo schemą) — ji viešai podėliuojama 1 val. Autentifikavimas nereikalingas.
|
||
|
||
### REST pagalbinės sąsajos
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/a2a/status` | Ar A2A įjungtas + užduočių statistika + podėlyje saugoma agento kortelės santrauka |
|
||
| GET | `/api/a2a/tasks` | Užduočių sąrašas — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
|
||
| POST | `/api/a2a/tasks` | (Neįgyvendinta kaip REST pagalbinė sąsaja — sukurkite per JSON-RPC `message/send`) |
|
||
| GET | `/api/a2a/tasks/[id]` | Gauti vieną užduotį |
|
||
| POST | `/api/a2a/tasks/[id]/cancel` | Atšaukti užduotį |
|
||
|
||
**Autentifikavimas:** REST pagalbinės sąsajos veikia be valdymo autentifikavimo (jas gali skaityti valdymo skydas); JSON-RPC maršrutas `/a2a` naudoja Bearer `OMNIROUTE_API_KEY`, jei jis sukonfigūruotas.
|
||
|
||
---
|
||
|
||
## Debesija, vertinimo testai ir vertinimas
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
|
||
| POST | `/api/cloud/auth` | Patikrinti Bearer raktą ir grąžinti užmaskuotus teikėjų ryšius bei modelių alternatyvius vardus debesijos sinchronizavimo klientams |
|
||
| POST | `/api/cloud/credentials/update` | Atnaujinti užšifruotus debesijoje sinchronizuojamo teikėjo prisijungimo duomenis |
|
||
| POST | `/api/cloud/model/resolve` | Pagal vietinę maršrutizavimo lentelę susieti loginį modelio ID su konkrečiu teikėju ir modeliu |
|
||
| GET | `/api/cloud/models/alias` | Pateikti modelių alternatyvių vardų sąrašą taip, kaip jis prieinamas debesijos sinchronizavimui |
|
||
| GET | `/api/assess` | Nuskaityti naujausias vertinimo kategorijas (pagal teikėją / modelį) |
|
||
| POST | `/api/assess` | Vykdyti vertinimą — turinys: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
|
||
| GET | `/api/evals` | Pateikti integruotų vertinimo testų rinkinių ir naujausių vykdymų sąrašą |
|
||
| POST | `/api/evals` | Paleisti vertinimo testą |
|
||
| POST | `/api/evals/suites` | Sukurti pasirinktinį vertinimo testų rinkinį — turinys tikrinamas naudojant `evalSuiteSaveSchema` |
|
||
| GET | `/api/evals/suites/[id]` | Gauti pasirinktinį vertinimo testų rinkinį |
|
||
|
||
**Autentifikavimas:** `/api/cloud/auth` tiesiogiai patikrina Bearer raktą; kitiems `/api/cloud/*`, `/api/evals/*` ir `/api/assess` maršrutams reikalingas valdymo seansas / API raktas. `/api/assess` POST naudoja `validateBody` su diskriminuotosios sąjungos aprėpties schema.
|
||
|
||
---
|
||
|
||
## ACP (Agent Client Protocol) valdymas
|
||
|
||
kaip antrinius procesus. Šie galiniai taškai valdo ACP agentų aptikimą ir pasirinktinių agentų
|
||
registravimą.
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/acp/agents` | Pateikia visus žinomus CLI agentus (integruotus ir pasirinktinius), jų įdiegimo būseną, versiją ir vykdomąjį failą |
|
||
| POST | `/api/acp/agents` | Užregistruoja pasirinktinį ACP agentą arba atnaujina podėlį — turinys: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` arba `{action: "refresh"}` |
|
||
| DELETE | `/api/acp/agents` | Pašalina pasirinktinį ACP agentą — užklausos parametras: `?id=<agentId>` |
|
||
|
||
**Atsakymo pavyzdys** (`GET /api/acp/agents`):
|
||
|
||
```json
|
||
{
|
||
"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
|
||
}
|
||
```
|
||
|
||
**Autentifikavimas:** reikalingas valdymo seansas (valdymo skydelio `auth_token` slapukas) arba
|
||
valdymo srities API raktas.
|
||
|
||
Išsamią informaciją rasite [ACP sistemos](../frameworks/ACP.md) dokumentacijoje.
|
||
|
||
---
|
||
|
||
## Analitika ir stebimumas
|
||
|
||
Tikrojo laiko analitikos galiniai taškai, skirti maršruto parinkimui, glaudinimui ir teikėjų
|
||
įvairovei stebėti. Jie naudojami `/dashboard/analytics/*` puslapiuose.
|
||
|
||
### Automatinio maršruto parinkimo analitika
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/analytics/auto-routing` | Apibendrinta automatinio maršruto parinkimo statistika: bendras iškvietimų skaičius, strategijų ir lygių pasiskirstymas, populiariausi teikėjai |
|
||
| GET | `/api/analytics/auto-routing?days=7` | Pasirinkto laikotarpio statistika (numatytoji reikšmė – 24 val.) |
|
||
|
||
**Atsakymo pavyzdys**:
|
||
|
||
```json
|
||
{
|
||
"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 }
|
||
]
|
||
}
|
||
```
|
||
|
||
### Glaudinimo analitika
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
||
| GET | `/api/analytics/compression` | Apibendrinta glaudinimo statistika: sutaupyti prieigos raktai, sutaupymo procentas, režimų pasiskirstymas, variklių naudojimas |
|
||
|
||
**Atsakymo pavyzdys**:
|
||
|
||
```json
|
||
{
|
||
"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
|
||
}
|
||
}
|
||
```
|
||
|
||
### Teikėjų įvairovės stebėjimas
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/analytics/diversity` | Šenono entropija pagrįstas įvairovės stebėjimas: matuojant pasiskirstymą tarp teikėjų išvengiama pavienių gedimo taškų |
|
||
|
||
**Atsakymo pavyzdys**:
|
||
|
||
```json
|
||
{
|
||
"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"]
|
||
}
|
||
```
|
||
|
||
**Autentifikavimas:** reikalingas valdymo seansas arba valdymo srities API raktas.
|
||
|
||
---
|
||
|
||
## Administratoriaus operacijos
|
||
|
||
Tik administratoriams skirti operacinio valdymo galiniai taškai.
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ------------------------ | -------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/admin/concurrency` | Gauti dabartinius lygiagretumo apribojimus (visuotinius ir kiekvieno teikėjo) |
|
||
| POST | `/api/admin/concurrency` | Atnaujinti lygiagretumo apribojimus — turinys: `{global?: number, perProvider?: Record<string, number>}` |
|
||
|
||
**Autentifikavimas:** Reikalinga administratoriaus sritį turinti valdymo sesija.
|
||
|
||
---
|
||
|
||
## CLI įrankių valdymas
|
||
|
||
Valdykite CLI įrankius, integruojamus su „OmniRoute“ (antigravity, chipotle, commandCode,
|
||
devin-cli ir kt.). Visą sąrašą rasite [Teikėjų žinyne](./PROVIDER_REFERENCE.md).
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/cli-tools/all-statuses` | Visų CLI įrankių būsena (įdiegimas, versija, kada paskutinį kartą aptiktas) |
|
||
| GET | `/api/cli-tools/status` | Išsami vieno CLI įrankio būsena (`?tool=` užklausa) |
|
||
| POST | `/api/cli-tools/apply` | Įrašyti sugeneruotą įrankio konfigūraciją (`dryRun` pateikia peržiūrą; naudojant konteinerį grąžinama `422` + `containerEphemeralTarget`; `migration` nurodo pasenusį „Codex“ YAML) |
|
||
| GET | `/api/cli-tools/backups` | Pateikti CLI įrankių konfigūracijų atsarginių kopijų sąrašą |
|
||
| POST | `/api/cli-tools/backups` | Sukurti visų CLI įrankių konfigūracijų atsarginę kopiją |
|
||
| POST | `/api/cli-tools/backups` | Atkurti: tas pats galinis taškas atkuria atsarginę kopiją, kai užklausos turinyje pateikiama `{tool, backupId}` |
|
||
| GET | `/api/cli-tools/antigravity-mitm` | „Antigravity“ MITM tarpinio serverio būsena (`antigravity-mitm` CLI įrankis) |
|
||
| POST | `/api/cli-tools/antigravity-mitm/alias` | Konfigūruoti `antigravity-mitm` alternatyviuosius vardus |
|
||
|
||
**Autentifikavimas:** Reikalinga valdymo sesija.
|
||
|
||
---
|
||
|
||
## Agentų įgūdžiai
|
||
|
||
Valdykite DI agentų įgūdžius (panašius į „OpenAI“ pasirinktinius GPT, tačiau skirtus agentams).
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ---------------------------- | ------------------------------------------------------------------------------------------------ |
|
||
| GET | `/api/agent-skills` | Pateikti visų agentų įgūdžių sąrašą (integruotų ir pasirinktinių) |
|
||
| GET | `/api/agent-skills/[id]` | Gauti konkretų agento įgūdį |
|
||
| POST | `/api/agent-skills` | Sukurti pasirinktinį agento įgūdį — turinys: `{name, description, prompt, model?, temperature?}` |
|
||
| PUT | `/api/agent-skills/[id]` | Atnaujinti pasirinktinį agento įgūdį |
|
||
| DELETE | `/api/agent-skills/[id]` | Ištrinti pasirinktinį agento įgūdį |
|
||
| GET | `/api/agent-skills/[id]/raw` | Gauti neapdorotą raginimą ir metaduomenis (nevykdant) |
|
||
| POST | `/api/agent-skills/generate` | Naudojant DI sugeneruoti naują įgūdį iš natūraliosios kalbos aprašymo |
|
||
|
||
**Autentifikavimas:** Reikalinga valdymo sesija arba valdymo srities API raktas.
|
||
|
||
---
|
||
|
||
## Talpyklos valdymas
|
||
|
||
Valdykite semantinę ir samprotavimo talpyklas.
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
|
||
| GET | `/api/cache` | Talpyklos apžvalga: bendras įrašų skaičius, pataikymų dažnis, dydis diske |
|
||
| GET | `/api/cache/entries` | Pateikti talpyklos įrašų sąrašą (su puslapiavimu) |
|
||
| DELETE | `/api/cache/entries` | Ištrinti talpyklos įrašus (filtruojant pagal užklausos parametrus) |
|
||
| GET | `/api/cache/stats` | Išsami talpyklos statistika (pagal teikėją ir modelį) |
|
||
| GET | `/api/cache/reasoning` | Samprotavimo talpyklos būsena (samprotavimo pakartojimui) |
|
||
| DELETE | `/api/cache/reasoning` | Išvalyti samprotavimo talpyklą — užklausos parametrai: `?toolCallId=<id>` (vienas), `?provider=<p>` arba nėra parametrų (visi) |
|
||
|
||
**Autentifikavimas:** reikalingas valdymo seansas.
|
||
|
||
---
|
||
|
||
## Atminties sistema
|
||
|
||
Valdykite nuolatinę atmintį (FTS5 + vektoriniai įterpiniai).
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ------------------ | ---------------------------------------------------------------------------------- |
|
||
| GET | `/api/memory` | Pateikti atminties įrašų sąrašą (filtruojant pagal sritį, tipą, paieškos užklausą) |
|
||
| POST | `/api/memory` | Sukurti naują atminties įrašą — turinys: `{scope, type, content, metadata?}` |
|
||
| GET | `/api/memory/[id]` | Gauti konkretų atminties įrašą |
|
||
| PUT | `/api/memory/[id]` | Atnaujinti atminties įrašą |
|
||
| DELETE | `/api/memory/[id]` | Ištrinti atminties įrašą |
|
||
| GET | `/api/memory?q=` | Ieškoti atmintyje (FTS5 + vektoriai) — statistika įtraukta į tą patį atsakymą |
|
||
|
||
**Autentifikavimas:** reikalingas valdymo seansas arba valdymo sričiai skirtas API raktas.
|
||
|
||
---
|
||
|
||
## Saityno jungtys
|
||
|
||
Valdykite įvykių saityno jungčių prenumeratas.
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ------------------------------- | ----------------------------------------------------------------------------------- |
|
||
| GET | `/api/webhooks` | Pateikti visų saityno jungčių prenumeratų sąrašą |
|
||
| POST | `/api/webhooks` | Sukurti saityno jungties prenumeratą — turinys: `{url, events[], secret?, active?}` |
|
||
| GET | `/api/webhooks/[id]` | Gauti konkrečią saityno jungties prenumeratą |
|
||
| PUT | `/api/webhooks/[id]` | Atnaujinti saityno jungties prenumeratą |
|
||
| DELETE | `/api/webhooks/[id]` | Ištrinti saityno jungties prenumeratą |
|
||
| GET | `/api/webhooks/[id]/deliveries` | Pateikti saityno jungties pristatymų istoriją (sėkmių / nesėkmių žurnalą) |
|
||
| POST | `/api/webhooks/[id]/test` | Išsiųsti bandomąjį įvykį saityno jungčiai |
|
||
|
||
**Autentifikavimas:** reikalingas valdymo seansas.
|
||
|
||
Visus įvykių tipus žr. [Saityno jungčių sistemoje](../frameworks/WEBHOOKS.md).
|
||
|
||
---
|
||
|
||
## Įgūdžių sistema
|
||
|
||
Valdykite įgūdžius (agentinių plėtinių sistemą).
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ------------------------ | -------------------------------------------------------------------------------------------- |
|
||
| GET | `/api/skills` | Pateikti visų įdiegtų įgūdžių sąrašą (integruotų ir pasirinktinių) |
|
||
| POST | `/api/skills/install` | Įdiegti įgūdį iš vietinio kelio arba URL |
|
||
| DELETE | `/api/skills/[id]` | Pašalinti įgūdį |
|
||
| PUT | `/api/skills/[id]` | Įjungti arba išjungti įgūdį — turinys: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
|
||
| POST | `/api/skills/executions` | Vykdyti įgūdį — turinys: `{skillName, apiKeyId, input?, sessionId?}` |
|
||
| GET | `/api/skills/executions` | Pateikti visų įgūdžių vykdymo istoriją (filtruoti pagal `?apiKeyId=`) |
|
||
|
||
**Autentifikavimas:** Reikalinga valdymo sesija arba valdymo apimties API raktas.
|
||
|
||
Išsamią informaciją žr. [Įgūdžių sistema](../frameworks/SKILLS.md).
|
||
|
||
---
|
||
|
||
## Papildiniai
|
||
|
||
Valdykite OmniRoute papildinius (trečiųjų šalių plėtinius).
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ---------------------------------- | ----------------------------------- |
|
||
| GET | `/api/plugins` | Pateikti įdiegtų papildinių sąrašą |
|
||
| POST | `/api/plugins/marketplace/install` | Įdiegti papildinį iš prekyvietės |
|
||
| DELETE | `/api/plugins/[name]` | Pašalinti papildinį |
|
||
| POST | `/api/plugins/[name]/activate` | Aktyvinti papildinį |
|
||
| POST | `/api/plugins/[name]/deactivate` | Išaktyvinti papildinį |
|
||
| GET | `/api/plugins/[name]/config` | Gauti papildinio konfigūraciją |
|
||
| PUT | `/api/plugins/[name]/config` | Atnaujinti papildinio konfigūraciją |
|
||
|
||
**Autentifikavimas:** Reikalinga valdymo sesija.
|
||
|
||
Išsamią informaciją žr. [Papildinių sistema](../frameworks/PLUGIN_SDK.md).
|
||
|
||
---
|
||
|
||
## Šešėlinis maršruto parinkimas
|
||
|
||
Šešėlinis / A-B paslaugų teikėjų palyginimas **nėra atskira REST sąsaja** — jis konfigūruojamas naudojant kombinuotąjį maršruto parinkimą (žr. [Automatiniai deriniai](../routing/AUTO-COMBO.md)). Kiekvieno derinio palyginimo metrikos pateikiamos naudojant `GET /api/combos/metrics`.
|
||
|
||
---
|
||
|
||
## Apsaugos priemonės
|
||
|
||
Peržiūrėkite vykdymo aplinkos apsaugos priemones (PII aptikimą, užklausų injekcijų aptikimą, vaizdinio turinio susiejimą). Apsaugos priemonės vykdomos kiekvienai užklausai; jų galima atsisakyti atskirai kiekvienam iškvietimui naudojant užklausos antraštę `x-omniroute-disabled-guardrails` — nėra išsaugomos įjungimo ar išjungimo sąsajos.
|
||
|
||
| Metodas | Kelias | Aprašymas |
|
||
| ------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| GET | `/api/guardrails` | Pateikti užregistruotų apsaugos priemonių ir jų būsenų sąrašą (pavadinimas / įjungta / prioritetas) |
|
||
| POST | `/api/guardrails/test` | Bandomuoju režimu vykdyti prieš iškvietimą atliekamą apdorojimo seką su pavyzdine įvestimi — turinys: `{input, disabledGuardrails?}` |
|
||
|
||
**Autentifikavimas:** Reikalinga valdymo sesija.
|
||
|
||
Išsamią informaciją žr. [Saugumas > Apsaugos priemonės](../security/GUARDRAILS.md).
|
||
|
||
---
|
||
|
||
---
|
||
|
||
## Autentifikavimas
|
||
|
||
Informaciją apie keturias prisijungimo duomenų grupes (valdymo skydelio seansą, vietinį CLI prieigos raktą, `oma_live_…` prieigos raktą ir valdymo aprėpties API raktą) bei jų skirtumus nuo išvadų generavimo raktų rasite [Valdymo autentifikavimas](../guides/MANAGEMENT-AUTH.md).
|
||
|
||
- Valdymo skydelio maršrutai (`/dashboard/*`) naudoja `auth_token` slapuką
|
||
- Prisijungiant naudojama išsaugota slaptažodžio maiša; jei jos nėra, naudojamas `INITIAL_PASSWORD`
|
||
- `requireLogin` galima perjungti per `/api/settings/require-login`
|
||
- Kai `REQUIRE_API_KEY=true`, `/v1/*` maršrutams gali būti privalomas „Bearer“ API raktas
|
||
- Šiame žinyne „valdymo prieigos raktas“ / „valdymo aprėpties API raktas“ reiškia vieną iš tame vadove aprašytų grupių, o ne neapibrėžtą papildomą slapto rakto tipą
|
||
|
||
> **Nesuderinamas pakeitimas (v3.8.0)** — `/api/v1/agents/tasks/*` ir atvėsimo laikotarpio valdymo galiniai taškai dabar reikalauja **valdymo autentifikavimo** (valdymo skydelio `auth_token` slapuko arba valdymo aprėpties API rakto). Klientai, kurie anksčiau šiuos maršrutus iškviesdavo be autentifikavimo, gaus atsakymą `401 Unauthorized`. Žr. įsipareigojimą `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).
|