pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-19 21:32:20 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
80ea176022d2a627bcd45ca5527c74b7b44da221
OmniRoute/docs/i18n/ms/docs/reference/API_REFERENCE.md
Diego Rodrigues de Sa e Souza b637350680 fix(docs): re-sync the 65 documentation mirror sets; section-level docs pipeline; drift gate blocking (#13940) 
1,104 mirrors rewritten over five passes of run-translation on the 22-source core set: the 14 sources edited since their translation, the 322 mirrors that were still English copies, and the frontmatter the old extractor leaked into the newer locales' bodies. The pipeline now caches per-`## `-section hashes and retranslates only changed sections, never reuses a section that is still English, rebuilds English-copy / leaked mirrors even when the source is unchanged, merges the state on save (parallel runs), and the drift gate (scoped to the core set) is blocking. Final audit: 0 stale, 0 English copies, 0 leaked frontmatter across 1,430 core mirrors.

⚠️ base-red inherited: #12732
2026-09-17 02:55:31 -03:00

1771 lines
121 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API Reference (Bahasa Melayu)
🌐 **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) · 🇱🇹 [lt](../../../lt/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) · 🇲🇹 [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)
---
🌐 **Bahasa:** 🇺🇸 [English](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md)
Rujukan teras untuk API OmniRoute. Ia merangkumi permukaan awam `/v1` dan titik akhir pengurusan yang paling kerap digunakan; fail [`docs/openapi.yaml`](../openapi.yaml) yang boleh dibaca mesin dan pepohon laluan di bawah `src/app/api/` merupakan sumber yang lengkap.
---
## Kandungan
- [Pelengkapan Sembang](#chat-completions)
- [Pajakan Sesi Terurus Eksklusif](#exclusive-managed-session-leases)
- [Pembenaman](#embeddings)
- [Penjanaan Imej](#image-generation)
- [OCR Dokumen](#document-ocr)
- [Senarai Model](#list-models)
- [Manifes Pemalam Penyedia](#provider-plugin-manifest)
- [Titik Akhir Keserasian](#compatibility-endpoints)
- [API Fail](#files-api)
- [API Kelompok](#batches-api)
- [API Carian](#search-api)
- [Penstriman WebSocket](#websocket-streaming)
- [Pelaporan Kuota & Isu](#quotas--issues-reporting)
- [Cache Semantik](#semantic-cache)
- [Papan Pemuka & Pengurusan](#dashboard--management)
- [Pengurusan Kombo](#combo-management)
- [Webhook](#webhooks)
- [Kunci Berdaftar (Pengurusan Automatik)](#registered-keys-auto-management)
- [Protokol Ejen](#agents-protocol)
- [Proksi Pengurusan](#management-proxies)
- [Ketahanan (lanjutan)](#resilience-extended)
- [Kemahiran](#skills)
- [Memori](#memory)
- [Pelayan MCP](#mcp-server)
- [Pelayan A2A](#a2a-server)
- [Awan, Penilaian & Pentaksiran](#cloud-evals--assess)
- [Pemprosesan Permintaan](#request-processing)
- [Pengesahan](#authentication)
---
## Pelengkapan Sembang
```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
}
```
### Pengepala Tersuai
| Pengepala | Arah | Penerangan |
| ------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-OmniRoute-No-Cache` | Permintaan | Tetapkan kepada `true` untuk memintas cache |
| `x-omniroute-no-memory` | Permintaan | Tetapkan kepada `true` untuk melangkau suntikan memori + kemahiran bagi permintaan ini (mencerminkan no-cache; mengelakkan overhed token/kos bagi setiap panggilan) |
| `X-OmniRoute-Progress` | Permintaan | Tetapkan kepada `true` untuk peristiwa kemajuan |
| `X-Session-Id` | Permintaan | Kunci sesi melekat untuk afiniti sesi luaran |
| `x_session_id` | Permintaan | Varian garis bawah turut diterima (HTTP langsung) |
| `X-OmniRoute-Session-Id` | Permintaan | Tag sesi/perbualan yang dibekalkan oleh pemanggil (turut disalurkan kepada memori). Apabila tersedia, disimpan kata demi kata ke `call_logs.session_tag` untuk pengagihan kos bagi setiap sesi (#8249) — tidak pernah dijana apabila tiada |
| `Idempotency-Key` | Permintaan | Kunci penyahduaan (tetingkap 5s) |
| `X-Request-Id` | Permintaan | Kunci penyahduaan alternatif |
| `X-OmniRoute-Cache` | Respons | `HIT` atau `MISS` (tanpa penstriman) |
| `X-OmniRoute-Idempotent` | Respons | `true` jika dinyahduakan |
| `X-OmniRoute-Progress` | Respons | `enabled` jika penjejakan kemajuan diaktifkan |
| `X-OmniRoute-Session-Id` | Respons | ID sesi berkesan yang digunakan oleh OmniRoute |
| `X-OmniRoute-Request-Id` | Respons | ID korelasi permintaan (apabila diketahui) |
| `X-OmniRoute-Version` | Respons | Versi binaan OmniRoute (sentiasa tersedia) |
| `X-OmniRoute-Cost-Saved` | Respons | Amaun USD yang dijimatkan oleh cache apabila berlaku HIT (cache hit sahaja) |
| `X-OmniRoute-Decision` | Respons | Jejak penghalaan: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` ialah strategi kombo, atau `single` untuk permintaan bukan kombo) — sentiasa tersedia dalam respons pelengkapan |
> Nota Nginx: jika anda bergantung pada pengepala garis bawah (contohnya `x_session_id`), dayakan `underscores_in_headers on;`.
> **Pengepala telemetri kos:** respons berjaya tanpa penstriman turut membawa set telemetri kos `X-OmniRoute-*` — `X-OmniRoute-Response-Cost` (USD, tetap 10 tempat perpuluhan; `0.0000000000` untuk percuma/tanpa harga), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit`, dan `X-OmniRoute-Fallback-Attempts` (hanya apabila > 0), serta `X-OmniRoute-Request-Id` dan `X-OmniRoute-Version`. Pengepala ini dipancarkan oleh pelengkapan sembang, `/v1/responses`, `/v1/messages`, **dan titik akhir media** — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations`, dan `/v1/moderations` (kos sentiasa `0`). Kos media dikira mengikut modaliti (setiap imej, setiap saat, setiap aksara, setiap unit carian) apabila harga tersedia; jika tidak, nilainya ialah `0` (teruskan operasi jika gagal).
> **Semantik kos capaian cache:** pada Capaian cache semantik (`X-OmniRoute-Cache-Hit: true`), tiada panggilan huluan dibuat, maka `X-OmniRoute-Response-Cost` ialah `0.0000000000` (kos **tambahan** untuk menyediakan capaian tersebut). Kos asal/kos yang sepatutnya dikenakan dilaporkan secara berasingan dalam `X-OmniRoute-Cost-Saved`. Pengguna pengebilan hendaklah menjumlahkan `X-OmniRoute-Response-Cost` (capaian tidak melibatkan kos); analitik cache boleh mengagregatkan `X-OmniRoute-Cost-Saved`.
## Pajakan Sesi Terurus Eksklusif
Pajakan sesi terurus eksklusif ialah kontrak penghalaan ikut serta yang neutral terhadap klien: satu pemilik aktif
memegang satu sambungan OmniRoute yang layak. Ia tidak memajak model, memerlukan OAuth, mengenal pasti
klien tertentu atau memerlukan penyedia tertentu.
Kunci API yang mengesahkan identiti mesti mempunyai skop `lease:exclusive` dan senarai
`allowedConnections` eksplisit yang tidak kosong. Sempadan mutasi pangkalan data menguatkuasakan kedua-dua medan
secara bersama ketika penciptaan kunci dan kemas kini separa.
```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"}
```
Respons pemerolehan, pembaharuan dan pelepasan yang berjaya mendedahkan cap masa, `state` dan nilai positif tepat
`generation`, tetapi tidak pernah mendedahkan sambungan atau bukti kelayakan yang dipilih. Pembaharuan dan pelepasan membekalkan
generasi dalam badan JSON:
```json
{ "action": "renew", "generation": 1 }
```
```json
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
```
Pemilik pajakan aktif boleh meminta secara eksplisit metadata paparan yang selamat dari segi privasi untuk pengikatan semasanya:
```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"
}
}
```
Tindakan status ikut serta ini dipagari oleh pemilik legap, kunci API terurus yang disahkan dan generasi aktif
yang tepat dalam satu transaksi pangkalan data. `displayName` hanyalah nama sambungan dikonfigurasikan yang telah dirapikan;
nilainya ialah `null` apabila tiada nama dikonfigurasikan yang selamat. OmniRoute tidak pernah menggantikannya dengan
e-mel atau identiti akaun yang dijana. Nilai penyedia ialah label paparan tidak sensitif dan tidak pernah merupakan
pengecam penyedia serasi yang dijana. Bukti kelayakan, token, kuki, ID sambungan atau kunci API mentah,
cincangan pemilik, rahsia pemagaran dan data penghalaan dalaman dikecualikan.
Carian dengan kunci salah, pemilik salah, generasi lapuk, tiada, tamat tempoh, dilepaskan atau dibatalkan semuanya
mengembalikan ralat `409 LEASE_FENCE_STALE` yang sama tanpa metadata sambungan. Klien yang menerima respons menunggu kapasiti tidak mempunyai pengikatan aktif untuk diperiksa. Apabila penghalaan mengalihkan pajakan aktif,
generasi yang sama kekal sah dan status mengembalikan pengikatan baharu secara atomik, bukan yang lama.
Klien sedia ada kekal tidak berubah kerana respons pemerolehan, pembaharuan, pelepasan dan penantian mengekalkan
bentuknya yang terdahulu.
Kontrak pelayan ini tidak mengubah `/status` OpenAI Codex standard. Codex standard pada masa ini melaporkan
penyedia modelnya serta keadaan pengesahan/akaun terbina dalam tetapi tidak memaparkan metadata akaun
penyedia tersuai sewenang-wenangnya; penyepaduan klien pada masa hadapan mesti memanggil tindakan ini dan menentukan cara
untuk memaparkan `connection.displayName`.
Setiap permintaan inferens terurus kemudiannya membekalkan kedua-dua pengepala kawalan:
```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```
Pemilik tepat, generasi, sambungan aktif dan kunci API yang disahkan dipagari serta-merta
sebelum setiap percubaan huluan yang disokong. Memainkan semula pemilik dan generasi dengan kunci lain akan gagal walaupun
kunci tersebut membenarkan sambungan yang sama. Pemilik mentah tidak disimpan secara berterusan, dilog, dikekalkan dalam
petikan permintaan atau dimajukan ke huluan.
Pertikaian sementara mengembalikan HTTP `429` dengan `Retry-After` dan:
```json
{
"state": "WAITING_FOR_CAPACITY",
"error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
"reason": "NO_FREE_ELIGIBLE_CONNECTION",
"retryAfter": 30
}
```
Respons ini hanya bermaksud bahawa set layak biasa tidak kosong dan setiap calon bebas sedang
dipegang oleh pajakan aktif asing. Model/penyedia yang tidak disokong, ketidakpadanan dasar, tempoh bertenang, kuota,
kesihatan dan kegagalan kelayakan biasa yang lain mengekalkan respons OmniRoute sedia ada.
### `x-omniroute-compression`
Penggantian pelan pemampatan bagi setiap permintaan. Keutamaan tertinggi — mengatasi penggantian gabungan penghalaan,
profil aktif, pencetus automatik dan Lalai panel. Nilai:
| Nilai | Kesan |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `off` | Tiada pemampatan untuk permintaan ini. |
| `default` | Profil Lalai yang diperoleh daripada panel (mengabaikan profil aktif). |
| `engine:<id>` | Satu enjin apabila didayakan, cth. `engine:rtk`. |
| `<combo>` | Gabungan bernama, dipadankan mengikut nama (tidak sensitif huruf besar/kecil) terlebih dahulu, kemudian mengikut ID. |
Nota:
- Nilai yang tidak diketahui diabaikan (permintaan tidak pernah ditolak); penyelesaian diteruskan mengikut keutamaan operator biasa.
- Jika berbilang gabungan berkongsi nama, berikan **id** gabungan untuk padanan deterministik.
- Gabungan yang namanya ialah `off` atau `default` tidak boleh dipilih mengikut nama (kata kunci tersebut ditafsirkan terlebih dahulu); rujuk gabungan tersebut melalui ID-nya.
- Suis pemampatan induk ialah gerbang mutlak: apabila pemampatan dilumpuhkan secara global, pengepala ini tidak boleh mendayakannya.
Pelan yang digunakan dicerminkan kembali dalam pengepala respons:
```
X-OmniRoute-Compression: <mode>; source=<source>
```
dengan `<source>` ialah salah satu daripada `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` atau `off`.
---
## Pembenaman
```bash
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "nebius/Qwen/Qwen3-Embedding-8B",
"input": "The food was delicious"
}
```
Penyedia yang tersedia: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.
ID katalog menggunakan format `provider/model` (contoh: `jina-ai/jina-embeddings-v5-omni-small`). ID model Jina tanpa nama penyedia yang terdapat dalam daftar pendaftaran (contohnya `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) turut dapat diselesaikan. Operasi embed/rerank/classify/segment Jina menggunakan kelayakan `jina-ai` daripada papan pemuka terlebih dahulu; `JINA_AI_API_KEY` digunakan sebagai pilihan sandaran hanya apabila tiada kunci papan pemuka tersedia. Kad `jina-reader` hanya untuk Reader / `r.jina.ai` (`POST /v1/web/fetch`) dan tidak pernah menyediakan pembenaman atau penyusunan semula kedudukan.
Model dalam daftar pendaftaran yang menyatakan sokongan multimodal turut menerima sehingga 32 item berstruktur yang neutral penyedia. Jenis item media ialah `text`, `image`, `audio`, `video`, dan `document`. `source` media tersebut sama ada `{"type":"url","url":"https://..."}` atau
`{"type":"base64","data":"...","media_type":"..."}`.
Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`,
dan alias keluarga `jina-ai/jina-embeddings-v5-omni` → omni-small) turut menerima dokumen EmbeddingsV5Request asli Jina dan **memajukannya tanpa perubahan** kepada `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,..." }]
}
]
}
```
Nilai asli `{ image | audio | video | pdf }` boleh berupa URL HTTPS awam, URI `data:`, atau base64 mentah. OmniRoute tidak menukarkan objek tersebut kepada rentetan atau mengambil URL imej asli — Jina mendapatkan media awam itu sendiri. Medan tambahan Jina (`task`, `normalized`, `truncate`, `embedding_type`) dimajukan. SKU Jina teks sahaja masih menolak dokumen bukan teks.
Had keselamatan dan pengangkutan:
- URL media jauh mestilah HTTPS awam. Item kanonik `{type,source:url}` diambil pada bahagian pelayan (pengesahan semula penghalaan semula, tamat masa, had saiz, DNS awam, penetapan sambungan) dan disisipkan sebelum panggilan penyedia. Item asli Jina `{image:"https://..."}` dimajukan seperti sedia ada selepas semakan HTTPS awam yang sama; Jina mengambil URL tersebut.
- Media base64 sebaris dihadkan kepada 8 MiB selepas dinyahkod bagi setiap item dan 16 MiB selepas dinyahkod bagi keseluruhan permintaan.
Terjemahan penyedia (item kanonik tidak pernah dimajukan tanpa perubahan):
- Model multimodal Jina: setiap item peringkat teratas menjadi satu objek berkekunci modaliti (`text` / `image` / `audio` / `video` / `pdf`) yang menggunakan URI data untuk media sebaris; satu vektor bagi setiap item peringkat teratas.
- Keluarga Gemini Embedding 2: satu tatasusunan peringkat teratas menjadi satu permintaan asli `models/{model}:embedContent` dengan `content.parts` (`text` atau `inline_data`).
- Model tidak diketahui/dinamik tanpa metadata modaliti yang jelas menolak input berstruktur dengan 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"
}
```
Gabungan model/modaliti yang tidak disokong mengembalikan HTTP 400 dan bukannya memaksa penukaran item tersebut. Medan sambungan bukan input pada permintaan rentetan/token lama terus diluluskan tanpa perubahan.
```bash
# Senaraikan semua model pembenaman
GET /v1/embeddings
```
---
## Penjanaan Imej
```bash
POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "openai/gpt-image-2",
"prompt": "Matahari terbenam yang indah di sebalik pergunungan",
"size": "1024x1024"
}
```
Penyedia yang tersedia: OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, SD WebUI (setempat), ComfyUI (setempat).
```bash
# Senaraikan semua model imej
GET /v1/images/generations
```
---
## OCR Dokumen
```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` memilih penyedia OCR melalui awalan `provider/model`; id model tanpa awalan (cth.
`mistral-ocr-latest`) dipadankan dengan penyedia berdaftarnya, manakala jika `model` tidak dinyatakan, nilai lalainya ialah
Mistral (`mistral-ocr-latest`). Penyedia berdaftar (`open-sse/config/ocrRegistry.ts`):
| Id penyedia | Id model | Nilai `model` | Catatan |
| ----------------------------- | -------------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (atau `mistral-ocr-latest` tanpa awalan) | Segerak — respons dikembalikan terus daripada satu panggilan huluan. |
| `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | Huluan tak segerak (`analyze` + peninjauan) — lihat di bawah. |
| `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | Segerak, melalui titik akhir rakan kongsi `openapi/chat/completions` Vertex AI — lihat di bawah untuk pengesahan/URL. |
Ketiga-tiga penyedia memberikan respons dalam kandungan berbentuk Mistral yang sama:
```json
{
"pages": [{ "index": 0, "markdown": "# Teks yang diekstrak..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
```
### Aliran peninjauan Azure Document Intelligence
API `analyze` Azure Document Intelligence adalah tak segerak: permintaan awal mengembalikan pengepala
`Operation-Location` dan bukannya kandungan, dan hasilnya mesti ditinjau. Pengendali
(`open-sse/handlers/ocr.ts`) meninjau URL tersebut setiap saat sehingga 30 percubaan, gagal serta-merta (tidak
meneruskan peninjauan) apabila menerima respons peninjauan bukan `ok` atau status `"failed"`, dan mengembalikan `504` jika
operasi masih berjalan selepas had percubaan habis. Respons akhir Azure
dinormalkan kepada bentuk `pages`/`markdown` yang sama seperti yang digunakan oleh Mistral sebelum dikembalikan kepada
pemanggil, jadi kod klien tidak perlu mengendalikan penyedia secara khusus.
### Pengesahan dan peleraian titik akhir OCR DeepSeek Vertex AI
`vertex-deepseek-ocr` menggunakan semula pengesahan Vertex AI yang sama yang sudah disokong oleh OmniRoute untuk
trafik sembang/imej (`open-sse/executors/vertex.ts`): kunci API sambungan sama ada merupakan
kelayakan JSON Service Account (ditukar dengan token akses OAuth jangka pendek melalui aliran JWT-bearer)
atau token akses OAuth sedia ada yang digunakan tanpa perubahan. URL titik akhir huluan ialah titik akhir rakan kongsi
`openapi/chat/completions` generik Vertex, yang dibina daripada projek dan
rantau sambungan — `providerSpecificData.project`/`providerSpecificData.region` yang dinyatakan secara jelas sentiasa diutamakan;
jika tidak, projek diperoleh daripada `project_id` JSON Service Account dan rantau
ditetapkan secara lalai kepada `us-central1`. Kedua-dua peleraian dilakukan dalam `open-sse/handlers/ocr.ts`
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`), yang digunakan oleh
`src/app/api/v1/ocr/route.ts` sebelum dihantar kepada `handleOcr`.
---
## Senaraikan Model
```bash
GET /v1/models
Authorization: Bearer your-api-key
→ Mengembalikan semua model sembang, pembenaman dan imej + gabungan dalam format OpenAI
```
### Awalan ID model (`?prefix=`)
Kebanyakan model dipaparkan di bawah **awalan penyedia**. Awalan yang anda peroleh dikawal oleh
bendera ciri `MODELS_CATALOG_PREFIX_MODE` dan boleh ditindih **bagi setiap permintaan** dengan
parameter pertanyaan — berguna untuk klien yang mahukan senarai yang kemas tanpa mengubah tetapan
seluruh pelayan untuk pengguna lain:
```bash
GET /v1/models?prefix=alias # satu ID bagi setiap model — awalan alias pendek
GET /v1/models?prefix=dual # kedua-dua bentuk (lalai pelayan)
GET /v1/models?prefix=canonical # hanya awalan ID penyedia penuh
```
| Mod | Mengeluarkan | Nota |
| ----------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual` | `cc/claude-sonnet-4-6` **dan** `claude/claude-sonnet-4-6` | **Lalai.** Kedua-dua ID menghala ke model yang sama; dikekalkan supaya konfigurasi klien yang mengekod keras mana-mana bentuk terus berfungsi. Saiz katalog menjadi kira-kira dua kali ganda. |
| `alias` | `cc/claude-sonnet-4-6` | Satu entri bagi setiap model. Penyedia tanpa alias berbeza masih mengeluarkan entri mereka, jadi tiada apa-apa yang hilang. |
| `canonical` | `claude/claude-sonnet-4-6` | Satu entri bagi setiap model di bawah awalan ID penyedia penuh. Penyedia tanpa alias berbeza (cth. `antigravity/…`, `agy/…`) turut mengeluarkan ID tunggal mereka di sini, jadi tiada apa-apa yang hilang. |
Cermin mod `dual` juga boleh dikenal pasti tanpa parameter pertanyaan: ia membawa medan `parent`
yang menunjuk kepada ID utama.
Klien yang memaparkan pemilih model hendaklah meminta `?prefix=alias` — inilah yang dilakukan oleh
[sambungan OmniCopilot VS Code](../guides/VSCODE-COPILOT.md).
### Varian model tanpa pemikiran
Bagi model Claude yang berkeupayaan berfikir, `/v1/models` turut memaparkan varian **tanpa pemikiran** yang ID-nya diawali dengan `claude-3-omniroute-no-thinking/`:
```
claude-3-omniroute-no-thinking/<provider>/<model>
```
Pemilihan ID ini (cth. dalam konfigurasi Claude Code yang sentiasa melampirkan blok `thinking`) akan mengembalikannya kepada `<provider>/<model>` sebenar dengan penaakulan dinyahdayakan — `thinking:{type:"disabled"}` pada laluan `/v1/messages`, atau medan `reasoning`/`reasoning_effort` digugurkan pada laluan `/v1/chat/completions`. Varian ini hanya disenaraikan untuk model keluarga Claude yang menyokong pemikiran **dan** mematuhi `disabled` (jadi, sebagai contoh, model adaptif sahaja yang menolak `disabled` dikecualikan). Pengendali boleh memaksa varian ini dihidupkan atau dimatikan bagi setiap model melalui `ModelSpec.noThinkingAlias`.
---
## Manifes Pemalam Penyedia
```bash
GET /api/v1/provider-plugin-manifest
```
Mengembalikan manifes pemalam penyedia selamat JSON yang digunakan oleh Bifrost, CLIProxyAPI dan
penghala sidecar akan datang. Respons dijana daripada daftar penyedia TypeScript
dan dengan sengaja mengecualikan rahsia klien OAuth, resolusi persekitaran masa jalan,
fungsi pelaksana, pengepala permintaan dan data akaun.
Gunakan titik akhir ini apabila sidecar berjalan di luar proses dan tidak dapat mengimport
`open-sse/config/providerPluginManifestRegistry.ts` secara langsung.
---
## Titik Akhir Keserasian
| Kaedah | Laluan | Format |
| ------ | ----------------------------------------- | ------------------------------------ |
| POST | `/v1/chat/completions` | OpenAI |
| POST | `/v1/messages` | Anthropic |
| POST | `/v1/responses` | Respons OpenAI |
| POST | `/v1/embeddings` | OpenAI |
| POST | `/v1/images/generations` | Imej OpenAI |
| POST | `/v1/images/edits` | Imej OpenAI (edit/inpaint) |
| POST | `/v1/videos/generations` | Penjanaan video gaya OpenAI |
| POST | `/v1/music/generations` | Penjanaan muzik gaya OpenAI |
| POST | `/v1/audio/transcriptions` | Audio OpenAI (STT) |
| POST | `/v1/audio/speech` | TTS OpenAI (mengembalikan isi audio) |
| POST | `/v1/rerank` | Penyusunan semula gaya Cohere/Voyage |
| POST | `/v1/classify` | Pengelasan Jina (`api.jina.ai`) |
| POST | `/v1/segment` | Pensegmen Jina (`segment.jina.ai`) |
| POST | `/v1/moderations` | Moderasi OpenAI |
| GET | `/v1/models` | OpenAI |
| POST | `/v1/messages/count_tokens` | Anthropic |
| GET | `/v1beta/models` | Gemini |
| POST | `/v1beta/models/{...path}` | Gemini generateContent |
| POST | `/v1/api/chat` | Ollama |
| GET | `/api/v1/vscode/{token}/` | Alias katalog OpenAI |
| GET | `/api/v1/vscode/{token}/models` | Alias model OpenAI |
| POST | `/api/v1/vscode/{token}/chat/completions` | Alias bertoken OpenAI |
| POST | `/api/v1/vscode/{token}/responses` | Alias bertoken Respons OpenAI |
| POST | `/api/v1/vscode/{token}/api/chat` | Alias bertoken Ollama |
| GET | `/api/v1/vscode/{token}/api/tags` | Alias teg bertoken Ollama |
Semua laluan POST mengikut bentuk yang sama: `Bearer your-api-key` + isi JSON yang disahkan oleh Zod (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` dan sebagainya, lihat `src/shared/validation/schemas.ts`). 4xx dikembalikan apabila pengesahan skema gagal.
Bagi klien yang tidak dapat melampirkan `Authorization: Bearer ...`, OmniRoute turut menerima kunci API dalam URL sama ada melalui keserasian rentetan pertanyaan (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) atau titik akhir khusus `/api/v1/vscode/{token}/...` yang didokumenkan di bawah.
```bash
# Susun semula
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Pengelasan Jina (kelayakan API Foundation)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Pensegmen Jina
POST /v1/segment { "content": "...", "return_chunks": true }
# Carian Jina (s.jina.ai; alias penyedia: jina-search, jina-ai, jina)
POST /v1/search { "query": "...", "provider": "jina-search" }
# Moderasi
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
# TTS — mengembalikan isi audio/mpeg (atau format yang diminta)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# Edit imej (multipart)
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
# Penjanaan video / muzik (ID model berawalan penyedia)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." }
```
### Laluan Penyedia Khusus
```bash
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
```
Awalan penyedia ditambahkan secara automatik jika tiada. Model yang tidak sepadan mengembalikan `400`.
---
## API Fail
Titik akhir fail yang serasi dengan OpenAI untuk input/output kelompok dan muat naik berdasarkan tujuan fail.
| Kaedah | Laluan | Penerangan |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| POST | `/v1/files` | Muat naik fail (berbilang bahagian: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — maksimum 512 MiB |
| GET | `/v1/files` | Senaraikan fail untuk kunci API yang disahkan |
| GET | `/v1/files/[id]` | Dapatkan metadata fail |
| DELETE | `/v1/files/[id]` | Padam fail |
| GET | `/v1/files/[id]/content` | Strim kembali kandungan mentah fail |
**Pengesahan:** Kunci API Bearer — fail diskopkan mengikut kunci API melalui `getApiKeyRequestScope`. Sesuatu kunci
hanya boleh melihat, memuat turun dan memadam fail miliknya sendiri; sesi papan pemuka tanpa kunci boleh membaca
keseluruhan tika; fail tanpa pemilik (muat naik tanpa nama atau melalui sesi papan pemuka) tidak boleh diakses oleh setiap
pemanggil tanpa sesi. `GET /v1/files` menolak pemanggil tanpa nama — dan kunci yang dikemukakan tetapi
tidak dapat dikenal pasti — dengan `401` walaupun `REQUIRE_API_KEY=false`, dan bukannya menyenaraikan fail
setiap penyewa (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).
---
## API Kelompok
Pemprosesan kelompok yang serasi dengan OpenAI.
| Kaedah | Laluan | Penerangan |
| ------ | ------------------------- | ----------------------------------------------------------------------------------------------------------- |
| POST | `/v1/batches` | Cipta kelompok — isi disahkan oleh `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
| GET | `/v1/batches` | Senaraikan kelompok |
| GET | `/v1/batches/[id]` | Dapatkan status kelompok + `request_counts` |
| DELETE | `/v1/batches/[id]` | Padam kelompok yang telah selesai/gagal |
| POST | `/v1/batches/[id]/cancel` | Batalkan kelompok yang sedang diproses |
**Pengesahan:** Kunci API Bearer. Kelompok diskopkan mengikut kunci API berdasarkan peraturan tiga hala yang sama seperti
fail: kunci sendiri sahaja, sesi papan pemuka merangkumi seluruh tika, rekod tanpa pemilik tidak boleh diakses oleh setiap
pemanggil tanpa sesi (dapatkan, padam, batalkan dan semakan `input_file_id` semasa penciptaan).
`GET /v1/batches` menolak pemanggil tanpa nama dengan `401` walaupun `REQUIRE_API_KEY=false`.
---
## API Carian
Abstraksi penyedia web/carian (Tavily, Brave, Exa, Serper, dll.).
| Kaedah | Laluan | Penerangan |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------- |
| GET | `/v1/search` | Senaraikan penyedia carian yang dikonfigurasikan + keupayaan |
| POST | `/v1/search` | Jalankan pertanyaan carian — badan disahkan oleh `v1SearchSchema`, menyokong cache/penggabungan |
| GET | `/v1/search/analytics` | Statistik hit/kependaman/cache bagi setiap penyedia |
**Pengesahan:** Kunci API Bearer (`extractApiKey` + `isValidApiKey`). Dasar carian dikuatkuasakan melalui `enforceApiKeyPolicy`.
---
## API Pengambilan Web
Ekstrak kandungan daripada URL melalui penyedia pengambilan web yang dikonfigurasikan (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract).
| Kaedah | Laluan | Penerangan |
| ------ | --------------- | -------------------------------------------------------- |
| POST | `/v1/web/fetch` | Ambil/kikis URL — badan disahkan oleh `v1WebFetchSchema` |
**Pengesahan:** Kunci API Bearer (`extractApiKey` + `isValidApiKey`). Dasar dikuatkuasakan melalui `enforceApiKeyPolicy`.
**Sandaran peka kuota (#8297):** apabila tiada `provider` eksplisit diberikan, kumpulan
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) dilalui
mengikut urutan keutamaan tetap
(isi dahulu) — penyedia yang dikonfigurasikan tetapi dikenakan had kadar dilangkau
dan bukannya menghentikan permintaan, manakala kegagalan huluan yang boleh dicuba semula/berkaitan kuota
(HTTP 429 sentiasa; 402/403 untuk peringkat percuma bercorak kuota Firecrawl/Tavily/TinyFish —
bukan untuk Jina Reader, dan tidak sekali-kali untuk permintaan tidak sah 400 biasa) akan beralih kepada
penyedia seterusnya yang belum dicuba dan mempunyai kelayakan pada masa permintaan. Apabila setiap penyedia dalam
kumpulan telah habis dicuba, titik akhir mengembalikan satu `429` (dengan pengepala `Retry-After`)
dan bukannya `400` generik yang terdahulu. Apabila `provider` eksplisit
diminta, **tiada** sandaran senyap — penyedia eksplisit yang dikenakan had kadar atau gagal
akan memaparkan ralatnya sendiri (`429` jika dikenakan had kadar, selainnya status
huluan).
---
## Penstriman WebSocket
```bash
GET /v1/ws?handshake=1
```
Mengesahkan jabat tangan peningkatan WebSocket dan mengembalikan mesej contoh protokol wayar (`request`, `cancel`). Bingkai WS sebenar dikendalikan oleh pelayan WS terbina di luar jadual laluan Next.js.
**Pengesahan:** Kunci API Bearer semasa jabat tangan.
### Responses API melalui WebSocket (codex sahaja)
```bash
# Hos:port yang sama dengan API HTTP (lalai 20128); tingkatkan sambungan:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (atau: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")
# Bingkai pertama MESTILAH response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```
Proksi Responses-API-melalui-WebSocket disambungkan **secara eksklusif kepada `codex`** (bahagian belakang ChatGPT). Ia
mendengar pada port yang sama seperti API/papan pemuka di laluan `/v1/responses`,
`/responses`, dan `/api/v1/responses`. Pada bingkai `response.create` pertama, ia
mengesahkan + menyediakan melalui jambatan dalaman `codex-responses-ws`, memilih
sambungan OAuth codex, dan membuat terowong ke `wss://chatgpt.com/backend-api/codex/responses`
melalui pengangkutan `wreq-js`. **Model bukan codex ditolak** (`codex_ws_provider_required`).
Untuk penghalaan perkongsian kuota, gunakan `model: "qtSd/<group>/codex/<model>"`. Dilaksanakan dalam
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.
**Pengesahan:** Kunci API Bearer semasa jabat tangan. Pelayan HTTP terbina (`server-ws.mjs`)
mestilah titik masuk yang aktif (dan sememangnya begitu secara lalai apabila `app/server-ws.mjs` wujud).
#### ID model: gunakan ID ChatGPT biasa (tanpa awalan `codex/`)
**Codex CLI** OpenAI mengesahkan nama model pada bahagian klien apabila
`supports_websockets = true` dan **menolak ID berawalan penyedia** seperti
`codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). Hantar ID **biasa** (cth. `gpt-5.5`). Jambatan OmniRoute
adalah untuk codex sahaja, jadi ia menyelesaikan semula ID biasa sebagai model codex
(`resolveCodexWsModelInfo`) sebelum membuat terowong ke huluan — walaupun
`gpt-5.5` biasa sebaliknya akan dihalakan kepada penyedia lain melalui HTTP.
#### Mengkonfigurasikan OpenAI Codex CLI
Halakan Codex CLI kepada OmniRoute dengan menambahkan penyedia tersuai yang mempunyai sokongan
WebSocket ke `~/.codex/config.toml` (gunakan `CODEX_HOME` yang berasingan untuk mengelakkan
perubahan pada konfigurasi sedia ada):
```toml
model = "gpt-5.5" # ID biasa — BUKAN "codex/gpt-5.5"
model_provider = "omniroute"
[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1" # tanpa garis miring penutup; URL WS diterbitkan daripadanya (gunakan https/wss dalam pengeluaran)
wire_api = "responses" # satu-satunya nilai yang disokong sejak Feb 2026
supports_websockets = true # mendayakan pengangkutan Responses-melalui-WS
env_key = "OMNIROUTE_API_KEY" # menyimpan kunci API OmniRoute (Bearer)
```
```bash
export OMNIROUTE_API_KEY=sk-... # kunci API OmniRoute (sebarang kunci jika REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```
CLI menaik taraf `base_url + /responses` kepada WebSocket dan OmniRoute membuat terowongnya
ke sambungan OAuth codex yang dipilih. Disahkan dari hujung ke hujung terhadap pelayan
setempat: ChatGPT mengembalikan `codex.rate_limits` + `response.created` dan menstrim
pelengkapan.
---
## Kuota & Pelaporan Isu
| Kaedah | Laluan | Penerangan |
| ------ | ------------------- | -------------------------------------------------------------------------------------------------- |
| GET | `/v1/quotas/check` | Prapengesahan kuota untuk `provider` + `accountId` sebelum mengeluarkan kunci berdaftar |
| POST | `/v1/issues/report` | Laporkan kegagalan kuota/pengeluaran kunci kepada GitHub (memerlukan `GITHUB_ISSUES_REPO` + token) |
**Pengesahan:** Kunci API Bearer (`isAuthenticated`).
---
## Penggunaan layan diri (`/api/usage/om-usage`)
Mana-mana kunci API boleh membaca penggunaan dan kuota **miliknya sendiri** — tanpa pengesahan pengurusan. Ini ialah titik akhir yang digunakan oleh
klien (CLI, panel OmniCopilot) untuk menunjukkan perbelanjaan kepada pemegang kunci.
```bash
# Bentuk teks (kontrak terdahulu — teks biasa untuk terminal)
curl -H "Authorization: Bearer <your-api-key>" \
http://localhost:20128/api/usage/om-usage
# Bentuk berstruktur — yang digunakan oleh UI
curl -H "Authorization: Bearer <your-api-key>" \
"http://localhost:20128/api/usage/om-usage?format=json"
```
Kunci tersebut mesti mengaktifkan **`allowUsageCommand`** (dimatikan secara lalai — pengurus kunci API
papan pemuka menogolnya bagi setiap kunci). Tanpanya, titik akhir memberikan respons `403`.
`?format=json` mengembalikan bentuk terdiskriminasi supaya pemanggil tidak sekali-kali membaca medan data daripada
respons penolakan. Apabila berjaya:
```jsonc
{
"allowed": true,
// hadir hanya apabila kunci mengikut serta dalam had penggunaan setiap kunci (USD harian/mingguan):
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// petikan kuota penyedia yang dipilih, atau null apabila belum ada apa-apa yang dicache:
"provider": {
"connectionId": "…",
"provider": "claude",
"plan": "…",
"quotas": {/* … */},
},
// petikan bagi setiap sambungan, supaya UI boleh memaparkan beberapa penyedia secara bersebelahan:
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
```
Apabila ditolak (`401` kunci tidak sah / `403` tidak dibenarkan), laluan yang sama mengembalikan
`{ "allowed": false, "error": { "message": "…" } }` — `personal`/`provider` yang hadir tetapi kosong
(kunci dibenarkan, tetapi belum memperoleh sebarang data) merupakan keadaan yang berbeza daripada penolakan, dan hanya bentuk JSON
yang membezakannya.
**Pengesahan:** kunci API Bearer milik pemanggil sendiri, disahkan dengan `isValidApiKey` — ini _bukan_
antara muka pengurusan (`/api/keys/…`), yang kekal dilindungi oleh `requireManagementAuth`.
---
## Cache Semantik
```bash
# Dapatkan statistik cache
GET /api/cache/stats
# Kosongkan semua cache
DELETE /api/cache/stats
```
Contoh respons:
```json
{
"semanticCache": {
"memorySize": 42,
"memoryMaxSize": 500,
"dbSize": 128,
"hitRate": 0.65
},
"idempotency": {
"activeKeys": 3,
"windowMs": 5000
}
}
```
### Kesan kependaman
HIT cache semantik menyampaikan respons daripada cache **tanpa panggilan huluan**,
maka `X-OmniRoute-Response-Latency` yang dilaporkan menghampiri sifar
(tanpa mengira kependaman huluan asal). Klien yang sensitif terhadap kependaman
(penanda aras, pemantauan p50/p99) hendaklah memeriksa pengepala respons
`X-OmniRoute-Cache-Latency`:
| Nilai | Maksud |
| ----------- | ------------------------------------------------------------------------ |
| `synthetic` | Respons disampaikan daripada cache; kependaman bukan masa huluan sebenar |
| _(tiada)_ | Respons daripada panggilan huluan sebenar |
### Pintasan cache setiap kunci
Kunci API boleh memilih untuk tidak menggunakan bacaan cache semantik melalui `cacheDefaultMode`:
| Nilai | Tingkah laku |
| -------- | -------------------------------------------------------- |
| `legacy` | Tingkah laku cache biasa (lalai) |
| `bypass` | Langkau carian cache sepenuhnya; sentiasa gunakan huluan |
Tetapkan ketika penciptaan kunci (`POST /api/keys`) atau kemas kini (`PATCH /api/keys/[id]`):
```json
{ "cacheDefaultMode": "bypass" }
```
### Pintasan setiap permintaan
Sebarang permintaan boleh memintas cache tanpa mengira tetapan kunci:
```
X-OmniRoute-No-Cache: true
```
---
## Papan Pemuka & Pengurusan
Laluan pengurusan (`/api/*` kecuali pengesahan/log masuk awam) **tidak** dibenarkan menggunakan
kunci API inferens biasa. Keluarga kelayakan, skop dan contoh curl:
[Pengesahan Pengurusan](../guides/MANAGEMENT-AUTH.md).
### Pengesahan
| Titik Akhir | Kaedah | Penerangan |
| ----------------------------- | ------- | ------------------------- |
| `/api/auth/login` | POST | Log masuk |
| `/api/auth/logout` | POST | Log keluar |
| `/api/settings/require-login` | GET/PUT | Togol keperluan log masuk |
### Pengurusan Penyedia
| Titik Akhir | Kaedah | Penerangan |
| ---------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `/api/providers` | GET/POST | Senaraikan / cipta penyedia |
| `/api/providers/[id]` | GET/PUT/DELETE | Urus penyedia |
| `/api/providers/[id]/test` | POST | Uji sambungan penyedia |
| `/api/providers/[id]/models` | GET | Senaraikan model penyedia |
| `/api/providers/validate` | POST | Sahkan konfigurasi penyedia |
| `/api/providers/bulk` | POST | Tambah kunci API secara pukal untuk SATU penyedia |
| `/api/providers/import` | POST | Import SENARAI penyedia beraneka daripada fail CSV/JSON yang telah dihuraikan (#6836); hasil kegagalan separa bagi setiap baris |
| `/api/provider-nodes*` | Pelbagai | Pengurusan nod penyedia |
| `/api/provider-models` | GET/POST/PATCH/DELETE | Model tersuai (tambah, kemas kini, sembunyikan/tunjukkan, padam) |
### Aliran OAuth
| Titik Akhir | Kaedah | Penerangan |
| -------------------------------- | -------- | --------------------- |
| `/api/oauth/[provider]/[action]` | Pelbagai | OAuth khusus penyedia |
### Penghalaan & Konfigurasi
| Titik Akhir | Kaedah | Penerangan |
| --------------------- | -------- | ------------------------------------- |
| `/api/models/alias` | GET/POST | Alias model |
| `/api/models/catalog` | GET | Semua model mengikut penyedia + jenis |
| `/api/combos*` | Pelbagai | Pengurusan gabungan |
| `/api/keys*` | Pelbagai | Pengurusan kunci API |
| `/api/pricing` | GET | Harga model |
### Penggunaan & Analitis
| Titik akhir | Kaedah | Penerangan |
| -------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history` | GET | Sejarah penggunaan |
| `/api/usage/logs` | GET | Log penggunaan |
| `/api/usage/request-logs` | GET | Log peringkat permintaan |
| `/api/usage/[connectionId]` | GET | Penggunaan bagi setiap sambungan |
| `/api/usage/token-limits` | GET/POST/DELETE | Belanjawan had token bagi setiap kunci API |
| `/api/usage/model-latency-stats` | GET | Agregat kependaman berterusan bagi setiap penyedia/model (purata/p50/p95/p99, kadar kejayaan); penapis: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) |
| `/api/usage/cache-health` | GET | Ringkasan kesihatan cache gesaan berdasarkan `call_logs` — nisbah tulis/baca, taburan saiz tulis p50/p90/p99, kepekatan penulisan berat, pecahan bagi setiap model dan keputusan `healthy`/`degraded`/`thrash`/`no-data`; parameter pertanyaan `range` (`1h`\|`24h`\|`7d`\|`30d`, lalai `24h`) dan `model` pilihan (#8827) |
### Tetapan
| Titik akhir | Kaedah | Penerangan |
| ------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings` | GET/PUT/PATCH | Tetapan umum |
| `/api/settings/proxy` | GET/PUT | Konfigurasi proksi rangkaian |
| `/api/settings/proxy/test` | POST | Uji sambungan proksi |
| `/api/settings/ip-filter` | GET/PUT | Senarai dibenarkan/senarai disekat IP |
| `/api/settings/thinking-budget` | GET/PUT | Mod penulisan semula **permintaan** pemikiran/penaakulan (passthrough / auto-strip / custom / adaptive). Tidak bergantung pada pemampatan. Lihat [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md). |
| `/api/settings/system-prompt` | GET/PUT | Gesaan sistem global |
| `/api/settings/compression` | GET/PUT | Konfigurasi pemampatan global |
| `/api/settings/purge-request-history` | POST | Kosongkan baris log permintaan dan artifak log panggilan setempat |
### Konteks & Pemampatan
| Titik Akhir | Kaedah | Penerangan |
| -------------------------------------- | -------------- | ------------------------------------------------------------------------- |
| `/api/compression/preview` | POST | Pratonton pemampatan off/lite/standard/aggressive/ultra/RTK/stacked |
| `/api/compression/language-packs` | GET | Senaraikan pek bahasa Caveman yang tersedia |
| `/api/compression/rules` | GET | Senaraikan metadata peraturan Caveman |
| `/api/context/caveman/config` | GET/PUT | Alias tetapan khusus Caveman |
| `/api/context/rtk/config` | GET/PUT | Tetapan khusus RTK, termasuk penapis tersuai dan pengekalan output mentah |
| `/api/context/rtk/filters` | GET | Katalog penapis RTK dan diagnostik penapis tersuai |
| `/api/context/rtk/test` | POST | Jalankan pratonton/ujian RTK terhadap muatan teks |
| `/api/context/rtk/raw-output/[id]` | GET | Baca output mentah tersunting yang dikekalkan mengikut ID penuding |
| `/api/context/combos` | GET/POST | Senaraikan/cipta kombo pemampatan |
| `/api/context/combos/[id]` | GET/PUT/DELETE | Butiran/kemas kini/padam kombo pemampatan |
| `/api/context/combos/[id]/assignments` | GET/PUT | Tetapkan kombo pemampatan kepada kombo penghalaan |
| `/api/context/analytics` | GET | Alias analitik pemampatan |
### Pemantauan
| Titik Akhir | Kaedah | Penerangan |
| ------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions` | GET | Penjejakan sesi aktif |
| `/api/rate-limits` | GET | Had kadar bagi setiap akaun |
| `/api/monitoring/health` | GET | Semakan kesihatan + ringkasan penyedia (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Paparan pengurusan merangkumi `credentialHealth`: nilai skalar cache prob, `failedConnections` apabila `failed>0`, dan `staleDbNonOkCount` (`test_status` melekat SQLite, bukan tolok). Lihat [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/api/cache/stats` | GET/DELETE | Statistik cache / kosongkan |
| `/api/modality-bridge/stats` | GET | `attempts` dalam memori, kejayaan/`bridged`, kegagalan, capaian cache, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` berasaskan bilangan sampel, dan masa penggunaan terakhir (ditetapkan semula apabila dimulakan semula; pengesahan pengurusan) |
| `/api/modality-bridge/video/runtime` | GET | Semakan gelung balik dipercayai yang ketat sebelum pengesahan/prob pengurusan; ketersediaan dan versi FFmpeg/ffprobe yang disanitasi (no-store) |
| `/api/modality-bridge/video/extract` | POST | Broker bait gelung balik dipercayai dalaman yang disahkan; input 50 MiB, baris gilir terhad/output 32 MiB, kapasiti `503`, pemutusan sambungan `499`, tarikh akhir `504`; bukan API muat naik awam |
### Sandaran & Eksport/Import
| Titik Akhir | Kaedah | Penerangan |
| --------------------------- | ------ | -------------------------------------------------------- |
| `/api/db-backups` | GET | Senaraikan sandaran yang tersedia |
| `/api/db-backups` | PUT | Cipta sandaran manual |
| `/api/db-backups` | POST | Pulihkan daripada sandaran tertentu |
| `/api/db-backups/export` | GET | Muat turun pangkalan data sebagai fail .sqlite |
| `/api/db-backups/import` | POST | Muat naik fail .sqlite untuk menggantikan pangkalan data |
| `/api/db-backups/exportAll` | GET | Muat turun sandaran penuh sebagai arkib .tar.gz |
### Penyegerakan Awan
| Titik Akhir | Kaedah | Penerangan |
| ---------------------- | -------- | ------------------------- |
| `/api/sync/cloud` | Pelbagai | Operasi penyegerakan awan |
| `/api/sync/initialize` | POST | Mulakan penyegerakan |
| `/api/cloud/*` | Pelbagai | Pengurusan awan |
### Terowong
| Titik Akhir | Kaedah | Penerangan |
| -------------------------- | ------ | ---------------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET | Baca status pemasangan/masa jalan Cloudflare Quick Tunnel untuk papan pemuka |
| `/api/tunnels/cloudflared` | POST | Dayakan atau nyahdayakan Cloudflare Quick Tunnel (`action=enable/disable`) |
| `/api/tunnels/ngrok` | GET | Baca status masa jalan ngrok Tunnel untuk papan pemuka |
| `/api/tunnels/ngrok` | POST | Dayakan atau nyahdayakan ngrok Tunnel (`action=enable/disable`) |
### Alat CLI
| Titik Akhir | Kaedah | Penerangan |
| ---------------------------------- | ------ | ------------------- |
| `/api/cli-tools/claude-settings` | GET | Status CLI Claude |
| `/api/cli-tools/codex-settings` | GET | Status CLI Codex |
| `/api/cli-tools/droid-settings` | GET | Status CLI Droid |
| `/api/cli-tools/openclaw-settings` | GET | Status CLI OpenClaw |
| `/api/cli-tools/runtime/[toolId]` | GET | Masa jalan CLI umum |
Respons CLI merangkumi: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.
### Ejen ACP
| Titik Akhir | Kaedah | Penerangan |
| ----------------- | ------ | ---------------------------------------------------------------------------- |
| `/api/acp/agents` | GET | Senaraikan semua ejen yang dikesan (terbina dalam + tersuai) berserta status |
| `/api/acp/agents` | POST | Tambah ejen tersuai atau segarkan semula cache pengesanan |
| `/api/acp/agents` | DELETE | Alih keluar ejen tersuai menggunakan parameter pertanyaan `id` |
Respons GET merangkumi `agents[]` (id, name, binary, version, installed, protocol, isCustom) dan `summary` (total, installed, notFound, builtIn, custom).
### Ketahanan & Had Kadar
| Titik Akhir | Kaedah | Penerangan |
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------- |
| `/api/resilience` | GET/PATCH | Dapatkan/kemas kini baris gilir permintaan, tempoh bertenang sambungan, pemutus penyedia dan tetapan menunggu |
| `/api/resilience/reset` | POST | Tetapkan semula pemutus litar penyedia |
| `/api/resilience/model-cooldowns` | GET | Senaraikan sekatan aktif bagi setiap (penyedia, sambungan, model), disusun mengikut baki masa |
| `/api/resilience/model-cooldowns` | DELETE | Kosongkan sekatan model — isi `{provider, model}` atau `{all: true}` untuk memadamkan semuanya |
| `/api/rate-limits` | GET | Status had kadar bagi setiap akaun |
| `/api/rate-limit` | GET | Konfigurasi had kadar global |
> Keempat-empat laluan `/api/resilience/*` memerlukan **pengesahan pengurusan** (`requireManagementAuth`). Lihat [Ketahanan (lanjutan)](#resilience-extended) untuk huraian penuh tentang pemutus penyedia berbanding tempoh bertenang sambungan berbanding sekatan model.
### Penilaian
| Titik Akhir | Kaedah | Penerangan |
| ------------ | -------- | ---------------------------------------------- |
| `/api/evals` | GET/POST | Senaraikan suit penilaian / jalankan penilaian |
### Dasar
| Titik Akhir | Kaedah | Penerangan |
| --------------- | --------------- | --------------------- |
| `/api/policies` | GET/POST/DELETE | Urus dasar penghalaan |
### Pematuhan
| Titik Akhir | Kaedah | Penerangan |
| --------------------------- | ------ | -------------------------------- |
| `/api/compliance/audit-log` | GET | Log audit pematuhan (N terakhir) |
### v1beta (Serasi dengan Gemini)
| Titik Akhir | Kaedah | Penerangan |
| -------------------------- | ------ | ------------------------------------ |
| `/v1beta/models` | GET | Senaraikan model dalam format Gemini |
| `/v1beta/models/{...path}` | POST | Titik akhir `generateContent` Gemini |
Titik akhir ini mencerminkan format API Gemini untuk klien yang memerlukan keserasian SDK Gemini natif.
### API Dalaman / Sistem
| Titik akhir | Kaedah | Penerangan |
| ------------------------ | ------ | --------------------------------------------------------------- |
| `/api/init` | GET | Semakan permulaan aplikasi (digunakan pada pelaksanaan pertama) |
| `/api/tags` | GET | Tag model yang serasi dengan Ollama (untuk klien Ollama) |
| `/api/restart` | POST | Cetuskan mula semula pelayan secara tertib |
| `/api/shutdown` | POST | Cetuskan penutupan pelayan secara tertib |
| `/api/system/env/repair` | POST | Baiki pemboleh ubah persekitaran penyedia OAuth |
> **Nota:** Titik akhir ini digunakan secara dalaman oleh sistem atau untuk keserasian klien Ollama. Titik akhir ini biasanya tidak dipanggil oleh pengguna akhir.
### Pembaikan Persekitaran OAuth _(v3.6.1+)_
```bash
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
```
Membaiki pemboleh ubah persekitaran OAuth yang hilang atau rosak untuk penyedia tertentu. Mengembalikan:
```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"
}
```
---
## Transkripsi Audio
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```
Transkripsikan fail audio menggunakan mana-mana penyedia STT yang dikonfigurasikan. Segmen laluan pertama memilih penyedia natif (`openai/…`, `deepgram/…`). Gerbang yang mengeksport semula model vendor lain menggunakan id berkelayakan
(`openrouter/deepgram/nova-3`).
**Permintaan:**
```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"
```
**Respons:**
```json
{
"text": "Helo, ini ialah kandungan audio yang telah ditranskripsikan.",
"task": "transcribe",
"language": "en",
"duration": 12.5
}
```
**Contoh id model:** `openai/whisper-1` (memerlukan kunci OpenAI),
`openrouter/deepgram/nova-3` (memerlukan kunci OpenRouter),
`deepgram/nova-3` (memerlukan kunci Deepgram natif). Permintaan
`deepgram/nova-3` biasa **tidak** menggunakan OpenRouter.
**Format yang disokong:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.
---
## Keserasian Ollama
Untuk klien yang menggunakan format API Ollama:
```bash
# Titik akhir sembang (format Ollama)
POST /v1/api/chat
# Penyenaraian model (format Ollama)
GET /api/tags
```
Permintaan diterjemahkan secara automatik antara format Ollama dengan format dalaman.
## Alias VS Code Bertoken / Tanpa Pengepala
Gunakan alias ini apabila sesuatu integrasi tidak dapat menyuntik pengepala `Authorization` dan memerlukan kunci API dibenamkan dalam URL asas.
```bash
# Alias katalog gaya OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models
# Alias sembang gaya OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses
# Alias gaya Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```
Contoh:
```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"}]}'
```
Catatan:
- Alias bertoken menggunakan semula pengendali yang sama seperti `/v1/*` dan `/api/tags`; bentuk respons kekal sama.
- Utamakan `Authorization: Bearer ...` apabila klien menyokong pengepala tersuai.
- Token berasaskan URL mungkin muncul dalam log proksi songsang, sejarah pelayar dan telemetri di luar OmniRoute. Anggap token tersebut sebagai pilihan keserasian, bukan mod pengesahan lalai.
---
## Telemetri
```bash
# Dapatkan ringkasan telemetri kependaman (p50/p95/p99 bagi setiap penyedia)
GET /api/telemetry/summary
```
**Respons:**
```json
{
"providers": {
"claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
"github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
}
}
```
---
## Bajet
```bash
# Dapatkan status bajet untuk semua kunci API
GET /api/usage/budget
# Tetapkan atau kemas kini bajet
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"
}
```
> **Catatan skema** (`setBudgetSchema`): `apiKeyId` diperlukan; sekurang-kurangnya satu daripada `dailyLimitUsd`, `weeklyLimitUsd` atau `monthlyLimitUsd` mestilah lebih besar daripada sifar. Medan pilihan: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Bentuk legasi `{keyId, limit, period}` mengembalikan `400 Bad Request`.
## Had Token
Bajet **token** bagi setiap kunci API (berbeza daripada Bajet berasaskan USD di atas). Dikuatkuasakan secara terus pada laluan permintaan: apabila penggunaan tetingkap semasa sesuatu kunci mencapai hadnya, permintaan ditolak dengan `429 Too Many Requests`. Had boleh dikhususkan kepada `model` tertentu, `provider`, atau digunakan secara `global` merentas kunci tersebut; apabila beberapa had sepadan dengan sesuatu permintaan, had yang paling ketat akan digunakan.
```bash
# Senaraikan had token sesuatu kunci (termasuk penggunaan tetingkap semasa)
GET /api/usage/token-limits?apiKeyId=key-123
# Cipta atau kemas kini had token
POST /api/usage/token-limits
Content-Type: application/json
{
"apiKeyId": "key-123",
"scopeType": "model",
"scopeValue": "openai/gpt-4o",
"tokenLimit": 1000000,
"resetInterval": "monthly",
"enabled": true
}
# Padam had token mengikut id
DELETE /api/usage/token-limits?id=tl-abc
```
> **Nota skema** (`setTokenLimitSchema`): `apiKeyId` dan `scopeType` (`model` | `provider` | `global`) diperlukan. `scopeValue` diperlukan melainkan `scopeType` ialah `global` (contohnya id model untuk skop `model`, id penyedia untuk skop `provider`). `tokenLimit` mestilah integer positif (ditukar secara paksa daripada rentetan). Pilihan: `id` (abaikan untuk mencipta, sertakan untuk mengemas kini), `resetInterval` (`daily` | `weekly` | `monthly`, lalai `monthly`), `resetTime` (`HH:MM`), `enabled` (lalai `true`). Respons `GET` memperkaya setiap had dengan `tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, dan `nextResetAt`. Ini ialah titik akhir kelas pengurusan (pengesahan dikuatkuasakan secara berpusat oleh talian paip authz).
## Pemprosesan Permintaan
1. Klien menghantar permintaan kepada `/v1/*`
2. Pengendali laluan memanggil `handleChat`, `handleEmbedding`, `handleAudioTranscription`, atau `handleImageGeneration`
3. Model ditentukan (penyedia/model langsung atau alias/kombo)
4. Bukti kelayakan dipilih daripada DB setempat dengan penapisan ketersediaan akaun
5. Untuk sembang: `handleChatCore` menyemak cache semantik/tandatangan dan menentukan tetapan pemampatan kombo
6. Pemampatan proaktif dijalankan sebelum penterjemahan penyedia apabila didayakan (`lite`, Caveman, RTK, atau bertindan)
7. Pelaksana penyedia menghantar permintaan ke huluan
8. Respons diterjemahkan kembali kepada format klien (sembang) atau dikembalikan seadanya (pembenaman/imej/audio)
9. Penggunaan, analitik pemampatan, dan log permintaan direkodkan
10. Sandaran digunakan apabila berlaku ralat mengikut peraturan kombo
Rujukan seni bina penuh: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)
---
## Pengurusan Kombo
Kombo penghalaan aras lebih tinggi (yang telah diringkaskan di bawah `/api/combos*`) juga boleh dipetakan 1:1 daripada corak id model, membolehkan pengalihan telus bagi id model gaya OpenAI kepada kombo.
| Kaedah | Laluan | Penerangan |
| ------ | -------------------------------- | ----------------------------------------------------------------------------------- |
| GET | `/api/model-combo-mappings` | Senaraikan semua pemetaan model→kombo |
| POST | `/api/model-combo-mappings` | Cipta pemetaan — kandungan: `{pattern, comboId, priority?, enabled?, description?}` |
| GET | `/api/model-combo-mappings/[id]` | Dapatkan satu pemetaan |
| PUT | `/api/model-combo-mappings/[id]` | Kemas kini medan bagi pemetaan sedia ada |
| DELETE | `/api/model-combo-mappings/[id]` | Alih keluar pemetaan |
**Pengesahan:** sesi/kunci API pengurusan (`requireManagementAuth`).
---
## Webhook
Langganan webhook keluar untuk acara OmniRoute (penyelesaian permintaan, kehabisan kuota, penggiliran kunci, dan sebagainya).
| Kaedah | Laluan | Penerangan |
| ------ | ------------------------- | --------------------------------------------------------------------- |
| GET | `/api/webhooks` | Senaraikan webhook (rahsia disamarkan sebagai `<prefix>...`) |
| POST | `/api/webhooks` | Cipta webhook — badan: `{url, events?: ["*"], secret?, description?}` |
| GET | `/api/webhooks/[id]` | Dapatkan webhook |
| PUT | `/api/webhooks/[id]` | Kemas kini url/events/secret/description |
| DELETE | `/api/webhooks/[id]` | Alih keluar webhook |
| POST | `/api/webhooks/[id]/test` | Hantar muatan ujian ke URL webhook dan kembalikan status penghantaran |
**Pengesahan:** sesi pengurusan/kunci API (`requireManagementAuth`).
---
## Kunci Berdaftar (Pengurusan Automatik)
Digunakan oleh subsistem pengurusan kunci automatik untuk mengeluarkan dan menggilirkan kunci API melalui penyedia/akaun sandaran, dengan kuota harian/setiap jam.
| Kaedah | Laluan | Penerangan |
| ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/registered-keys` | Senaraikan kunci berdaftar (awalan disamarkan sahaja) |
| POST | `/api/v1/registered-keys` | Keluarkan kunci berdaftar baharu — badan: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Mengembalikan kunci mentah **sekali sahaja**. Mengembalikan `429` jika kuota ditolak. |
| GET | `/api/v1/registered-keys/[id]` | Dapatkan metadata kunci berdaftar (tanpa bahan mentah) |
| DELETE | `/api/v1/registered-keys/[id]` | Batalkan kunci berdaftar |
| POST | `/api/v1/registered-keys/[id]/revoke` | Titik akhir pembatalan eksplisit (kesan yang sama seperti DELETE) |
**Pengesahan:** Kunci API Bearer (`isAuthenticated`). Lihat juga `/v1/quotas/check` dan `/v1/issues/report`.
---
## Protokol Ejen
Tugas ejen awan (Claude Code, Codex Cloud, OpenHands, dll.) yang dilaksanakan dari jauh bagi pihak pengguna OmniRoute.
| Kaedah | Laluan | Penerangan |
| ------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/agents/tasks` | Senaraikan tugas — `?provider=`, `?status=`, `?limit=` adalah pilihan (1–500, lalai 50) |
| POST | `/api/v1/agents/tasks` | Cipta tugas — isi disahkan oleh `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). Mengembalikan `201` dengan sampul tugas |
| DELETE | `/api/v1/agents/tasks?id=...` | Padam tugas |
| GET | `/api/v1/agents/tasks/[id]` | Baca tugas — menyegarkan status secara segerak daripada ejen awan huluan apabila `external_id` ditetapkan |
| POST | `/api/v1/agents/tasks/[id]` | Tindakan berpilih: `{action: "approve"}`, `{action: "message", message}`, atau `{action: "cancel"}` |
| DELETE | `/api/v1/agents/tasks/[id]` | Padam tugas tertentu mengikut id |
> **Pengesahan:** pengesahan pengurusan diperlukan untuk setiap kaedah (`requireCloudAgentManagementAuth`). Sebelum v3.8.0, kaedah ini tidak memerlukan pengesahan — lihat komit `588a0333` untuk perubahan yang memecahkan keserasian.
```bash
# Cipta tugas awan Claude Code
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":"..."}}'
```
---
## Proksi Pengurusan
Proksi HTTP(S)/SOCKS keluar yang boleh diperuntukkan kepada penyedia, akaun atau secara global.
| Kaedah | Laluan | Penerangan |
| ------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/management/proxies` | Senaraikan proksi (dengan `?id=` mengembalikan satu; dengan `?id=&where_used=1` mengembalikan graf peruntukan) |
| POST | `/api/v1/management/proxies` | Cipta proksi — isi disahkan oleh `createProxyRegistrySchema` |
| PATCH | `/api/v1/management/proxies` | Kemas kini proksi — isi disahkan oleh `updateProxyRegistrySchema` (memerlukan `id`) |
| DELETE | `/api/v1/management/proxies?id=...&force=1` | Padam proksi (gunakan `force=1` untuk menanggalkan peruntukan) |
| GET | `/api/v1/management/proxies/assignments` | Senaraikan peruntukan — boleh ditapis mengikut `proxy_id`, `scope`, `scope_id`; berikan `resolve_connection_id=<id>` untuk menentukan proksi aktif bagi sambungan |
| PUT | `/api/v1/management/proxies/assignments` | Peruntukkan — isi disahkan oleh `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). Mengosongkan cache penghantar |
| PUT | `/api/v1/management/proxies/bulk-assign` | Peruntukkan secara pukal — isi disahkan oleh `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) |
| GET | `/api/v1/management/proxies/health?hours=24` | Agregat kesihatan proksi (bilangan berjaya/gagal, kependaman) sepanjang suatu tempoh |
**Pengesahan:** sesi pengurusan/kunci API diperlukan pada setiap laluan (`requireManagementAuth`).
> `POST /api/v1/management/proxies/[id]/assignments` dan `POST /api/v1/management/proxies/[id]/health` dalam penerangan tugas disediakan oleh laluan rata `/assignments` dan `/health` yang ditunjukkan di atas — tiada sublaluan khusus bagi setiap id dalam pangkalan kod.
---
## Ketahanan (lanjutan)
OmniRoute menyediakan tiga mekanisme kegagalan sementara yang bebas antara satu sama lain; titik akhir pengurusan di bawah membolehkan pengendali membaca dan mengatasinya:
| Skop | Storan keadaan | Baca | Tetapkan semula / kosongkan |
| -------------------------- | ------------------------------------------ | ----------------------------------------- | --------------------------------------------------------------- |
| Pemutus penyedia | `domain_circuit_breakers` + dalam memori | `/api/monitoring/health` | `POST /api/resilience/reset` |
| Tempoh bertenang sambungan | `rateLimitedUntil` pada sambungan penyedia | `/api/rate-limits`, `/api/providers/[id]` | (didayakan semula secara malas; kosongkan melalui PUT penyedia) |
| Sekatan model | Pendaftar ketersediaan model dalam memori | `GET /api/resilience/model-cooldowns` | `DELETE /api/resilience/model-cooldowns` |
`PATCH /api/resilience` menerima penggantian pemutus penyedia di bawah `providerBreaker.oauth` dan `providerBreaker.apikey`. Setiap profil menyokong `degradationThreshold`, `failureThreshold`, dan `resetTimeoutMs`; medan yang sama tersedia dalam Papan Pemuka → Tetapan → Ketahanan.
```bash
# Kosongkan sekatan untuk satu model
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"}'
# Kosongkan semua sekatan
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
-H "Cookie: auth_token=..." \
-d '{"all":true}'
```
Untuk rujukan konseptual penuh dan nilai lalai pemutus, lihat [`CLAUDE.md`](../../CLAUDE.md) → "Keadaan Masa Jalan Ketahanan".
---
## Kemahiran
Rangka kerja kemahiran untuk memperluas OmniRoute dengan pengendali boleh laksana tersuai, serta integrasi pasaran.
| Kaedah | Laluan | Penerangan |
| ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/skills` | Senaraikan kemahiran yang dipasang — boleh ditapis mengikut `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, dengan penomboran halaman |
| GET | `/api/skills/[id]` | Dapatkan satu kemahiran |
| PUT | `/api/skills/[id]` | Kemas kini kemahiran (nama, penerangan, mod, skema, pengendali, tag) |
| DELETE | `/api/skills/[id]` | Nyahpasang kemahiran |
| POST | `/api/skills/install` | Pasang kemahiran daripada manifes mentah — isi: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
| GET | `/api/skills/executions` | Senaraikan pelaksanaan kemahiran terkini (jejak audit dengan input/output/tempoh) |
| GET | `/api/skills/marketplace?q=...` | Carian/senarai popular daripada pasaran SkillsMP (memerlukan tetapan `skillsmpApiKey`) |
| POST | `/api/skills/marketplace/install` | Pasang kemahiran mengikut id daripada SkillsMP |
| GET | `/api/skills/skillssh?q=&limit=` | Cari dalam pendaftar skills.sh |
| POST | `/api/skills/skillssh/install` | Pasang kemahiran mengikut id daripada skills.sh |
**Pengesahan:** sesi pengurusan/kunci API. Laluan carian pasaran menerima sama ada pengesahan pengurusan atau kunci API Bearer (`isAuthenticated`).
---
## Memori
Storan memori perbualan/fakta yang berterusan, dengan skop bagi setiap kunci API / sesi.
| Kaedah | Laluan | Penerangan |
| ------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/memory` | Senaraikan memori — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, dengan penomboran halaman `offset/limit` atau `page/limit` |
| POST | `/api/memory` | Cipta memori — kandungan permintaan disahkan oleh Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET | `/api/memory/[id]` | Dapatkan satu memori |
| DELETE | `/api/memory/[id]` | Padam memori |
| GET | `/api/memory/health` | Kesihatan subsistem memori (kesambungan DB, bahagian belakang pembenaman, status indeks vektor) |
**Pengesahan:** sesi pengurusan/kunci API (`requireManagementAuth`). Enum `type`: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (lihat `MemoryType` dalam `src/lib/memory/types.ts`).
---
## Pelayan MCP
OmniRoute disertakan dengan pelayan Model Context Protocol terbenam yang mempunyai 3 pengangkutan (stdio, SSE, streamable-http) dan alat dengan skop tertentu. Titik akhir papan pemuka di bawah membaca data status/audit dan memproksikan pengangkutan HTTP.
| Kaedah | Laluan | Penerangan |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Denyutan, pengangkutan, keadaan dalam talian, panggilan terakhir, alat teratas, kadar kejayaan 24 jam |
| GET | `/api/mcp/tools` | Senarai alat MCP dengan `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
| GET | `/api/mcp/sse` | Buka strim SSE untuk pengangkutan SSE (mengembalikan `503` jika MCP dilumpuhkan atau pengangkutan tidak sepadan) |
| POST | `/api/mcp/sse` | Hantar bingkai JSON-RPC melalui pengangkutan SSE |
| GET | `/api/mcp/stream` | Buka bahagian SSE bagi pengangkutan HTTP Boleh Distrim (mesej yang dimulakan oleh pelayan) |
| POST | `/api/mcp/stream` | Hantar bingkai JSON-RPC melalui pengangkutan HTTP Boleh Distrim |
| DELETE | `/api/mcp/stream` | Tamatkan sesi HTTP Boleh Distrim |
| GET | `/api/mcp/audit` | Kueri log audit — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | Statistik audit agregat (jumlah, kadar kejayaan, purata tempoh, alat teratas) |
**Pengesahan:** pengangkutan `sse`/`stream` mematuhi permukaan pengesahan khusus MCP (kunci API Bearer dengan skop `mcp`); laluan `status`/`tools`/`audit*` boleh dibaca daripada papan pemuka (tiada pengesahan tambahan diperlukan selain daripada dapat mencapai hos papan pemuka).
> Kedua-dua pengangkutan HTTP dikawal oleh `settings.mcpEnabled` dan `settings.mcpTransport` — ketidakpadanan pengangkutan mengembalikan `400`, manakala keadaan MCP yang dilumpuhkan mengembalikan `503`.
---
## Pelayan A2A
OmniRoute menyediakan titik akhir A2A (Ejen-ke-Ejen) JSON-RPC 2.0 serta pembalut REST untuk tujuan pemeriksaan/papan pemuka.
### JSON-RPC
```bash
POST /a2a
Authorization: Bearer your-api-key # pilihan melainkan OMNIROUTE_API_KEY ditetapkan
Content-Type: application/json
{
"jsonrpc": "2.0",
"id": 1,
"method": "message/send",
"params": {
"skill": "smart-routing",
"messages": [{"role": "user", "content": "Route this coding task"}]
}
}
```
Kaedah yang disokong (semuanya bergantung pada `settings.a2aEnabled`):
| Kaedah | Penerangan |
| ---------------- | -------------------------------------------------------------------------- |
| `message/send` | Pelaksanaan kemahiran segerak; mengembalikan `{task, artifacts, metadata}` |
| `message/stream` | Pelaksanaan penstriman SSE bagi set kemahiran yang sama |
| `tasks/get` | Dapatkan tugas berdasarkan `taskId` |
| `tasks/cancel` | Batalkan tugas berdasarkan `taskId` |
Kemahiran terbina dalam: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.
### Kad Ejen
```bash
GET /.well-known/agent.json
```
Mengembalikan kad ejen A2A awam (nama, penerangan, keupayaan, katalog kemahiran, skema pengesahan) — dicache secara awam selama 1j. Pengesahan tidak diperlukan.
### Pembantu REST
| Kaedah | Laluan | Penerangan |
| ------ | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/a2a/status` | Status A2A didayakan + statistik tugas + ringkasan kad ejen yang dicache |
| GET | `/api/a2a/tasks` | Senaraikan tugas — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST | `/api/a2a/tasks` | (Tidak dilaksanakan sebagai pembantu REST — cipta melalui JSON-RPC `message/send`) |
| GET | `/api/a2a/tasks/[id]` | Dapatkan satu tugas |
| POST | `/api/a2a/tasks/[id]/cancel` | Batalkan tugas |
**Pengesahan:** pembantu REST berjalan tanpa pengesahan pengurusan (boleh dibaca oleh papan pemuka); laluan JSON-RPC `/a2a` menggunakan Bearer `OMNIROUTE_API_KEY` jika dikonfigurasikan.
---
## Awan, Penilaian & Pentaksiran
| Kaedah | Laluan | Penerangan |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Sahkan kunci Bearer dan kembalikan sambungan penyedia yang disamarkan + alias model untuk klien penyegerakan awan |
| POST | `/api/cloud/credentials/update` | Kemas kini kelayakan yang disulitkan untuk penyedia yang disegerakkan dengan awan |
| POST | `/api/cloud/model/resolve` | Petakan ID model logik kepada penyedia/model konkrit menggunakan jadual penghalaan setempat |
| GET | `/api/cloud/models/alias` | Senaraikan alias model seperti yang didedahkan kepada penyegerakan awan |
| GET | `/api/assess` | Baca pengkategorian pentaksiran terkini (mengikut penyedia/model) |
| POST | `/api/assess` | Jalankan pentaksiran — isi: `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Senaraikan suit penilaian terbina dalam + pelaksanaan terkini |
| POST | `/api/evals` | Cetuskan pelaksanaan penilaian |
| POST | `/api/evals/suites` | Cipta suit penilaian tersuai — isi disahkan oleh `evalSuiteSaveSchema` |
| GET | `/api/evals/suites/[id]` | Dapatkan suit penilaian tersuai |
**Pengesahan:** `/api/cloud/auth` mengesahkan kunci Bearer secara langsung; laluan `/api/cloud/*`, `/api/evals/*`, dan `/api/assess` yang lain memerlukan sesi pengurusan/kunci API. POST `/api/assess` menggunakan `validateBody` dengan skema skop kesatuan berbeza.
## Pengurusan ACP (Agent Client Protocol)
sebagai proses anak. Titik akhir ini mengurus pengesanan ejen ACP dan pendaftaran ejen
tersuai.
| Kaedah | Laluan | Penerangan |
| ------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/acp/agents` | Senaraikan semua ejen CLI yang diketahui (terbina dalam + tersuai) berserta status pemasangan, versi dan perduaan |
| POST | `/api/acp/agents` | Daftarkan ejen ACP tersuai atau segarkan semula cache — isi: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` atau `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Alih keluar ejen ACP tersuai — parameter pertanyaan: `?id=<agentId>` |
**Contoh respons** (`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
}
```
**Pengesahan:** Memerlukan sesi pengurusan (kuki `auth_token` papan pemuka) atau
kunci API dengan skop pengurusan.
Lihat [Rangka Kerja ACP](../frameworks/ACP.md) untuk butiran lengkap.
---
## Analitik & Kebolehcerapan
Titik akhir analitik masa nyata untuk memantau penghalaan, pemampatan dan kepelbagaian
penyedia. Titik akhir ini menguasakan halaman `/dashboard/analytics/*`.
### Analitik penghalaan automatik
| Kaedah | Laluan | Penerangan |
| ------ | ------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/auto-routing` | Statistik penghalaan automatik agregat: jumlah panggilan, taburan strategi, taburan peringkat, penyedia teratas |
| GET | `/api/analytics/auto-routing?days=7` | Statistik mengikut tetingkap masa (lalai 24j) |
**Contoh respons**:
```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 }
]
}
```
### Analitik pemampatan
| Kaedah | Laluan | Penerangan |
| ------ | ---------------------------- | ------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/compression` | Statistik pemampatan agregat: token dijimatkan, % penjimatan, taburan mod, penggunaan enjin |
**Contoh respons**:
```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
}
}
```
### Penjejakan kepelbagaian penyedia
| Kaedah | Laluan | Penerangan |
| ------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/analytics/diversity` | Penjejakan kepelbagaian berasaskan entropi Shannon: mencegah titik kegagalan tunggal dengan mengukur taburan penggunaan penyedia |
**Contoh respons**:
```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"]
}
```
**Pengesahan:** Memerlukan sesi pengurusan atau kunci API dengan skop pengurusan.
---
## Operasi Pentadbir
Titik akhir khusus pentadbir untuk pengurusan operasi.
| Kaedah | Laluan | Penerangan |
| ------ | ------------------------ | -------------------------------------------------------------------------------------------- |
| GET | `/api/admin/concurrency` | Baca had konkurensi semasa (global + mengikut penyedia) |
| POST | `/api/admin/concurrency` | Kemas kini had konkurensi — badan: `{global?: number, perProvider?: Record<string, number>}` |
**Pengesahan:** Memerlukan sesi pengurusan dengan skop pentadbir.
---
## Pengurusan Alat CLI
Urus alat CLI yang berintegrasi dengan OmniRoute (antigravity, chipotle, commandCode,
devin-cli, dll.). Lihat [Rujukan Penyedia](./PROVIDER_REFERENCE.md) untuk senarai penuh.
| Kaedah | Laluan | Penerangan |
| ------ | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cli-tools/all-statuses` | Status semua alat CLI (dipasang, versi, kali terakhir dilihat) |
| GET | `/api/cli-tools/status` | Butiran status untuk satu alat CLI (pertanyaan `?tool=`) |
| POST | `/api/cli-tools/apply` | Tulis konfigurasi terjana alat (`dryRun` menyediakan pratonton; `422` + `containerEphemeralTarget` apabila dikontena; `migration` mencatatkan YAML Codex legasi) |
| GET | `/api/cli-tools/backups` | Senaraikan sandaran konfigurasi alat CLI |
| POST | `/api/cli-tools/backups` | Cipta sandaran bagi semua konfigurasi alat CLI |
| POST | `/api/cli-tools/backups` | Pulihkan: titik akhir yang sama dengan `{tool, backupId}` dalam badan akan memulihkan sandaran tersebut |
| GET | `/api/cli-tools/antigravity-mitm` | Status proksi MITM Antigravity (alat CLI "antigravity-mitm") |
| POST | `/api/cli-tools/antigravity-mitm/alias` | Konfigurasikan alias antigravity-mitm |
**Pengesahan:** Memerlukan sesi pengurusan.
---
## Kemahiran Ejen
Urus kemahiran ejen AI (serupa dengan GPT tersuai OpenAI tetapi untuk ejen).
| Kaedah | Laluan | Penerangan |
| ------ | ---------------------------- | ----------------------------------------------------------------------------------------- |
| GET | `/api/agent-skills` | Senaraikan semua kemahiran ejen (terbina dalam + tersuai) |
| GET | `/api/agent-skills/[id]` | Dapatkan kemahiran ejen tertentu |
| POST | `/api/agent-skills` | Cipta kemahiran ejen tersuai — badan: `{name, description, prompt, model?, temperature?}` |
| PUT | `/api/agent-skills/[id]` | Kemas kini kemahiran ejen tersuai |
| DELETE | `/api/agent-skills/[id]` | Padam kemahiran ejen tersuai |
| GET | `/api/agent-skills/[id]/raw` | Dapatkan gesaan mentah + metadata (tanpa pelaksanaan) |
| POST | `/api/agent-skills/generate` | Jana kemahiran baharu menggunakan AI daripada penerangan bahasa semula jadi |
**Pengesahan:** Memerlukan sesi pengurusan atau kunci API dengan skop pengurusan.
---
## Pengurusan Cache
Urus cache semantik dan cache penaakulan.
| Kaedah | Laluan | Penerangan |
| ------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/cache` | Gambaran keseluruhan cache: jumlah entri, kadar padanan, saiz pada cakera |
| GET | `/api/cache/entries` | Senaraikan entri yang dicache (dengan penomboran halaman) |
| DELETE | `/api/cache/entries` | Padam entri cache (tapis mengikut parameter pertanyaan) |
| GET | `/api/cache/stats` | Statistik cache terperinci (mengikut penyedia, mengikut model) |
| GET | `/api/cache/reasoning` | Status cache penaakulan (untuk main semula penaakulan) |
| DELETE | `/api/cache/reasoning` | Kosongkan cache penaakulan — parameter pertanyaan: `?toolCallId=<id>` (tunggal) atau `?provider=<p>` atau tanpa parameter (semua) |
**Pengesahan:** Memerlukan sesi pengurusan.
---
## Sistem Memori
Urus memori berterusan (FTS5 + pembenaman vektor).
| Kaedah | Laluan | Penerangan |
| ------ | ------------------ | -------------------------------------------------------------------------- |
| GET | `/api/memory` | Senaraikan entri memori (tapis mengikut skop, jenis, pertanyaan carian) |
| POST | `/api/memory` | Cipta entri memori baharu — isi: `{scope, type, content, metadata?}` |
| GET | `/api/memory/[id]` | Dapatkan entri memori tertentu |
| PUT | `/api/memory/[id]` | Kemas kini entri memori |
| DELETE | `/api/memory/[id]` | Padam entri memori |
| GET | `/api/memory?q=` | Cari memori (FTS5 + vektor) — statistik disertakan dalam respons yang sama |
**Pengesahan:** Memerlukan sesi pengurusan atau kunci API dengan skop pengurusan.
---
## Webhook
Urus langganan webhook untuk acara.
| Kaedah | Laluan | Penerangan |
| ------ | ------------------------------- | ---------------------------------------------------------------------- |
| GET | `/api/webhooks` | Senaraikan semua langganan webhook |
| POST | `/api/webhooks` | Cipta langganan webhook — isi: `{url, events[], secret?, active?}` |
| GET | `/api/webhooks/[id]` | Dapatkan langganan webhook tertentu |
| PUT | `/api/webhooks/[id]` | Kemas kini langganan webhook |
| DELETE | `/api/webhooks/[id]` | Padam langganan webhook |
| GET | `/api/webhooks/[id]/deliveries` | Senaraikan sejarah penghantaran untuk webhook (log kejayaan/kegagalan) |
| POST | `/api/webhooks/[id]/test` | Hantar acara ujian kepada webhook |
**Pengesahan:** Memerlukan sesi pengurusan.
Lihat [Rangka Kerja Webhook](../frameworks/WEBHOOKS.md) untuk jenis acara yang lengkap.
---
## Rangka Kerja Skills
Urus Skills (rangka kerja sambungan berasaskan ejen).
| Kaedah | Laluan | Penerangan |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------- |
| GET | `/api/skills` | Senaraikan semua skill yang dipasang (terbina dalam + tersuai) |
| POST | `/api/skills/install` | Pasang skill daripada laluan setempat atau URL |
| DELETE | `/api/skills/[id]` | Nyahpasang skill |
| PUT | `/api/skills/[id]` | Dayakan atau nyahdayakan skill — isi: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST | `/api/skills/executions` | Laksanakan skill — isi: `{skillName, apiKeyId, input?, sessionId?}` |
| GET | `/api/skills/executions` | Senaraikan sejarah pelaksanaan untuk semua skill (tapis mengikut `?apiKeyId=`) |
**Pengesahan:** Memerlukan sesi pengurusan atau kunci API dengan skop pengurusan.
Lihat [Rangka Kerja Skills](../frameworks/SKILLS.md) untuk butiran lengkap.
---
## Plugin
Urus plugin OmniRoute (sambungan pihak ketiga).
| Kaedah | Laluan | Penerangan |
| ------ | ---------------------------------- | ---------------------------------- |
| GET | `/api/plugins` | Senaraikan plugin yang dipasang |
| POST | `/api/plugins/marketplace/install` | Pasang plugin daripada marketplace |
| DELETE | `/api/plugins/[name]` | Nyahpasang plugin |
| POST | `/api/plugins/[name]/activate` | Aktifkan plugin |
| POST | `/api/plugins/[name]/deactivate` | Nyahaktifkan plugin |
| GET | `/api/plugins/[name]/config` | Dapatkan konfigurasi plugin |
| PUT | `/api/plugins/[name]/config` | Kemas kini konfigurasi plugin |
**Pengesahan:** Memerlukan sesi pengurusan.
Lihat [Rangka Kerja Plugin](../frameworks/PLUGIN_SDK.md) untuk butiran lengkap.
---
## Penghalaan Bayangan
Perbandingan bayangan / A-B bagi penyedia **bukan permukaan REST kendiri** — ia dikonfigurasikan melalui penghalaan kombo (lihat [Auto-Combo](../routing/AUTO-COMBO.md)). Metrik perbandingan bagi setiap kombo disediakan oleh `GET /api/combos/metrics`.
---
## Kawalan Keselamatan
Periksa kawalan keselamatan masa jalan (pengesanan PII, pengesanan suntikan gesaan, perantaraan visi). Kawalan keselamatan dijalankan pada setiap permintaan; pengecualian bagi setiap panggilan dilakukan melalui pengepala permintaan `x-omniroute-disabled-guardrails` — tiada permukaan daya/nyahdaya yang disimpan.
| Kaedah | Laluan | Penerangan |
| ------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
| GET | `/api/guardrails` | Senaraikan kawalan keselamatan yang didaftarkan dan statusnya (nama / didayakan / keutamaan) |
| POST | `/api/guardrails/test` | Jalankan percubaan kering bagi saluran paip prapanggilan pada input sampel — isi: `{input, disabledGuardrails?}` |
**Pengesahan:** Memerlukan sesi pengurusan.
Lihat [Keselamatan > Kawalan Keselamatan](../security/GUARDRAILS.md) untuk butiran lengkap.
---
---
## Pengesahan
Lihat [Pengesahan Pengurusan](../guides/MANAGEMENT-AUTH.md) untuk empat
keluarga bukti kelayakan (sesi papan pemuka, token CLI setempat, Token Akses
`oma_live_…`, kunci API berskop pengurusan) dan perbezaannya daripada kunci inferens.
- Laluan papan pemuka (`/dashboard/*`) menggunakan kuki `auth_token`
- Log masuk menggunakan cincangan kata laluan yang disimpan; sandaran kepada `INITIAL_PASSWORD`
- `requireLogin` boleh ditogol melalui `/api/settings/require-login`
- Laluan `/v1/*` secara pilihan memerlukan kunci API Bearer apabila `REQUIRE_API_KEY=true`
- "token pengurusan" / "kunci API berskop pengurusan" dalam rujukan ini bermaksud salah satu keluarga dalam panduan tersebut — bukan jenis rahsia tambahan yang tidak ditakrifkan
> **Perubahan yang memecahkan keserasian (v3.8.0)** — `/api/v1/agents/tasks/*` dan titik akhir pengurusan tempoh bertenang kini memerlukan **pengesahan pengurusan** (kuki `auth_token` papan pemuka atau kunci API berskop pengurusan). Klien yang sebelum ini memanggil laluan ini tanpa pengesahan akan menerima `401 Unauthorized`. Lihat komit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).
Reference in New Issue View Git Blame Copy Permalink