OmniRoute/docs/i18n/bg/API_REFERENCE.md

# Справка за API

🌐 **Languages:** 🇺🇸 [English](../../API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../pt-BR/API_REFERENCE.md) | 🇪🇸 [Español](../es/API_REFERENCE.md) | 🇫🇷 [Français](../fr/API_REFERENCE.md) | 🇮🇹 [Italiano](../it/API_REFERENCE.md) | 🇷🇺 [Русский](../ru/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../zh-CN/API_REFERENCE.md) | 🇩🇪 [Deutsch](../de/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../in/API_REFERENCE.md) | 🇹🇭 [ไทย](../th/API_REFERENCE.md) | 🇺🇦 [Українська](../uk-UA/API_REFERENCE.md) | 🇸🇦 [العربية](../ar/API_REFERENCE.md) | 🇯🇵 [日本語](../ja/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../vi/API_REFERENCE.md) | 🇧🇬 [Български](../bg/API_REFERENCE.md) | 🇩🇰 [Dansk](../da/API_REFERENCE.md) | 🇫🇮 [Suomi](../fi/API_REFERENCE.md) | 🇮🇱 [עברית](../he/API_REFERENCE.md) | 🇭🇺 [Magyar](../hu/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../id/API_REFERENCE.md) | 🇰🇷 [한국어](../ko/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../ms/API_REFERENCE.md) | 🇳🇱 [Nederlands](../nl/API_REFERENCE.md) | 🇳🇴 [Norsk](../no/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../pt/API_REFERENCE.md) | 🇷🇴 [Română](../ro/API_REFERENCE.md) | 🇵🇱 [Polski](../pl/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../sk/API_REFERENCE.md) | 🇸🇪 [Svenska](../sv/API_REFERENCE.md) | 🇵🇭 [Filipino](../phi/API_REFERENCE.md)

Пълна справка за всички крайни точки на OmniRoute API.

---

## Съдържание

- [Chat Completions](#chat-completions)
- [Embeddings](#embeddings)
- [Image Generation](#image-generation)
- [List Models](#list-models)
- [Compatibility Endpoints](#compatibility-endpoints)
- [Semantic Cache](#semantic-cache)
- [Dashboard & Management](#dashboard--management)
- [Request Processing](#request-processing)
- [Authentication](#authentication)

---

## Завършвания на чат

```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
}
```

### Персонализирани заглавки

| Заглавка                 | Посока  | Описание                                   |
| ------------------------ | ------- | ------------------------------------------ |
| `X-OmniRoute-No-Cache`   | Заявка  | Задайте `true` за заобикаляне на кеша      |
| `X-OmniRoute-Progress`   | Заявка  | Задайте `true` за събития за прогрес       |
| `Idempotency-Key`        | Заявка  | Ключ за дедупиране (5s прозорец)           |
| `X-Request-Id`           | Заявка  | Алтернативен дедуп ключ                    |
| `X-OmniRoute-Cache`      | Отговор | `HIT` или `MISS` (без поточно предаване)   |
| `X-OmniRoute-Idempotent` | Отговор | `true` ако е дедупликиран                  |
| `X-OmniRoute-Progress`   | Отговор | `enabled` ако проследяване на напредъка на |

---

## Вграждания

```bash
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "nebius/Qwen/Qwen3-Embedding-8B",
  "input": "The food was delicious"
}
```

Налични доставчици: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA.

```bash
# List all embedding models
GET /v1/embeddings
```

---

## Генериране на изображения

```bash
POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "openai/dall-e-3",
  "prompt": "A beautiful sunset over mountains",
  "size": "1024x1024"
}
```

Налични доставчици: OpenAI (DALL-E), xAI (Grok Image), Together AI (FLUX), Fireworks AI.

```bash
# List all image models
GET /v1/images/generations
```

---

## Списък с модели

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

→ Returns all chat, embedding, and image models + combos in OpenAI format
```

---

## Крайни точки за съвместимост

| Метод      | Път                         | Формат                     |
| ---------- | --------------------------- | -------------------------- |
| ПУБЛИКАЦИЯ | `/v1/chat/completions`      | OpenAI                     |
| ПУБЛИКАЦИЯ | `/v1/messages`              | Антропен                   |
| ПУБЛИКАЦИЯ | `/v1/responses`             | OpenAI отговори            |
| ПУБЛИКАЦИЯ | `/v1/embeddings`            | OpenAI                     |
| ПУБЛИКАЦИЯ | `/v1/images/generations`    | OpenAI                     |
| ВЗЕМЕТЕ    | `/v1/models`                | OpenAI                     |
| ПУБЛИКАЦИЯ | `/v1/messages/count_tokens` | Антропен                   |
| ВЗЕМЕТЕ    | `/v1beta/models`            | Близнаци                   |
| ПУБЛИКАЦИЯ | `/v1beta/models/{...path}`  | Gemini генерира съдържание |
| ПУБЛИКАЦИЯ | `/v1/api/chat`              | Олама                      |

### Специализирани маршрути на доставчик

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

Префиксът на доставчика се добавя автоматично, ако липсва. Несъответстващите модели връщат `400`.

---

## Семантичен кеш

```bash
# Get cache stats
GET /api/cache

# Clear all caches
DELETE /api/cache
```

Пример за отговор:

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

---

## Табло за управление и управление

### Удостоверяване

| Крайна точка                  | Метод         | Описание                           |
| ----------------------------- | ------------- | ---------------------------------- |
| `/api/auth/login`             | ПУБЛИКАЦИЯ    | Вход                               |
| `/api/auth/logout`            | ПУБЛИКАЦИЯ    | Изход                              |
| `/api/settings/require-login` | ВЗЕМИ/ПОСТАВИ | Изисква се превключване на влизане |

### Управление на доставчика

| Крайна точка                 | Метод                            | Описание                                 |
| ---------------------------- | -------------------------------- | ---------------------------------------- |
| `/api/providers`             | ВЗЕМЕТЕ/ПУБЛИКУВАЙТЕ             | Списък / създаване на доставчици         |
| `/api/providers/[id]`        | ПОЛУЧАВАНЕ/ПОСТАВЯНЕ/ИЗТРИВАНЕ   | Управление на доставчик                  |
| `/api/providers/[id]/test`   | ПУБЛИКАЦИЯ                       | Тествайте връзката с доставчик           |
| `/api/providers/[id]/models` | ВЗЕМЕТЕ                          | Избройте модели на доставчици            |
| `/api/providers/validate`    | ПУБЛИКАЦИЯ                       | Проверка на конфигурацията на доставчика |
| `/api/provider-nodes*`       | Различни                         | Управление на възел на доставчик         |
| `/api/provider-models`       | ПОЛУЧАВАНЕ/ПУБЛИКУВАНЕ/ИЗТРИВАНЕ | Персонализирани модели                   |

### OAuth потоци

| Крайна точка                     | Метод    | Описание                       |
| -------------------------------- | -------- | ------------------------------ |
| `/api/oauth/[provider]/[action]` | Различни | Специфичен за доставчика OAuth |

### Маршрутизиране и конфигурация

| Крайна точка          | Метод                | Описание                         |
| --------------------- | -------------------- | -------------------------------- |
| `/api/models/alias`   | ВЗЕМЕТЕ/ПУБЛИКУВАЙТЕ | Псевдоними на модели             |
| `/api/models/catalog` | ВЗЕМЕТЕ              | Всички модели по доставчик + тип |
| `/api/combos*`        | Различни             | Комбо управление                 |
| `/api/keys*`          | Различни             | Управление на API ключове        |
| `/api/pricing`        | ВЗЕМЕТЕ              | Моделна цена                     |

### Използване и анализ

| Крайна точка                | Метод   | Описание                |
| --------------------------- | ------- | ----------------------- |
| `/api/usage/history`        | ВЗЕМЕТЕ | История на използването |
| `/api/usage/logs`           | ВЗЕМЕТЕ | Дневници за използване  |
| `/api/usage/request-logs`   | ВЗЕМЕТЕ | Дневници на ниво заявка |
| `/api/usage/[connectionId]` | ВЗЕМЕТЕ | Използване на връзка    |

### Настройки

| Крайна точка                    | Метод         | Описание                               |
| ------------------------------- | ------------- | -------------------------------------- |
| `/api/settings`                 | ВЗЕМИ/ПОСТАВИ | Общи настройки                         |
| `/api/settings/proxy`           | ВЗЕМИ/ПОСТАВИ | Конфигурация на мрежов прокси          |
| `/api/settings/proxy/test`      | ПУБЛИКАЦИЯ    | Тествайте прокси връзката              |
| `/api/settings/ip-filter`       | ВЗЕМИ/ПОСТАВИ | Списък с разрешени/блокирани IP адреси |
| `/api/settings/thinking-budget` | ВЗЕМИ/ПОСТАВИ | Бюджет на жетон за разсъждение         |
| `/api/settings/system-prompt`   | ВЗЕМИ/ПОСТАВИ | Глобална системна подкана              |

### Мониторинг

| Крайна точка             | Метод                | Описание                      |
| ------------------------ | -------------------- | ----------------------------- |
| `/api/sessions`          | ВЗЕМЕТЕ              | Проследяване на активна сесия |
| `/api/rate-limits`       | ВЗЕМЕТЕ              | Лимити за лихви по сметка     |
| `/api/monitoring/health` | ВЗЕМЕТЕ              | Здравна проверка              |
| `/api/cache`             | ПОЛУЧАВАНЕ/ИЗТРИВАНЕ | Кеш статистики / изчистване   |

### Архивиране и експортиране/импортиране

| Крайна точка                | Метод      | Описание                                         |
| --------------------------- | ---------- | ------------------------------------------------ |
| `/api/db-backups`           | ВЗЕМЕТЕ    | Избройте наличните резервни копия                |
| `/api/db-backups`           | ПОСТАВЕТЕ  | Създайте ръчно архивиране                        |
| `/api/db-backups`           | ПУБЛИКАЦИЯ | Възстановяване от конкретен архив                |
| `/api/db-backups/export`    | ВЗЕМЕТЕ    | Изтегляне на база данни като .sqlite файл        |
| `/api/db-backups/import`    | ПУБЛИКАЦИЯ | Качете .sqlite файл, за да замените базата данни |
| `/api/db-backups/exportAll` | ВЗЕМЕТЕ    | Изтеглете пълното архивиране като .tar.gz архив  |

### Облачно синхронизиране

| Крайна точка           | Метод      | Описание                           |
| ---------------------- | ---------- | ---------------------------------- |
| `/api/sync/cloud`      | Различни   | Операции за синхронизиране в облак |
| `/api/sync/initialize` | ПУБЛИКАЦИЯ | Инициализиране на синхронизиране   |
| `/api/cloud/*`         | Различни   | Облачно управление                 |

### CLI инструменти

| Крайна точка                       | Метод   | Описание               |
| ---------------------------------- | ------- | ---------------------- |
| `/api/cli-tools/claude-settings`   | ВЗЕМЕТЕ | Клод CLI състояние     |
| `/api/cli-tools/codex-settings`    | ВЗЕМЕТЕ | Codex CLI състояние    |
| `/api/cli-tools/droid-settings`    | ВЗЕМЕТЕ | Droid CLI състояние    |
| `/api/cli-tools/openclaw-settings` | ВЗЕМЕТЕ | OpenClaw CLI състояние |
| `/api/cli-tools/runtime/[toolId]`  | ВЗЕМЕТЕ | Generic CLI runtime    |

CLI отговорите включват: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.

### Устойчивост и ограничения на скоростта

| Крайна точка            | Метод         | Описание                                      |
| ----------------------- | ------------- | --------------------------------------------- |
| `/api/resilience`       | ВЗЕМИ/ПОСТАВИ | Вземете/актуализирайте профили за устойчивост |
| `/api/resilience/reset` | ПУБЛИКАЦИЯ    | Нулиране на прекъсвачи                        |
| `/api/rate-limits`      | ВЗЕМЕТЕ       | Състояние на ограничение на лимита по сметка  |
| `/api/rate-limit`       | ВЗЕМЕТЕ       | Конфигурация на глобален лимит на скоростта   |

### Оценки

| Крайна точка | Метод                | Описание                                |
| ------------ | -------------------- | --------------------------------------- |
| `/api/evals` | ВЗЕМЕТЕ/ПУБЛИКУВАЙТЕ | Избройте eval пакети / изпълнете оценка |

### Политики

| Крайна точка    | Метод                            | Описание                                  |
| --------------- | -------------------------------- | ----------------------------------------- |
| `/api/policies` | ПОЛУЧАВАНЕ/ПУБЛИКУВАНЕ/ИЗТРИВАНЕ | Управление на правилата за маршрутизиране |

### Съответствие

| Крайна точка                | Метод   | Описание                                           |
| --------------------------- | ------- | -------------------------------------------------- |
| `/api/compliance/audit-log` | ВЗЕМЕТЕ | Дневник за проверка на съответствието (последно N) |

### v1beta (съвместим с Gemini)

| Крайна точка               | Метод      | Описание                              |
| -------------------------- | ---------- | ------------------------------------- |
| `/v1beta/models`           | ВЗЕМЕТЕ    | Избройте модели във формат Gemini     |
| `/v1beta/models/{...path}` | ПУБЛИКАЦИЯ | Gemini `generateContent` крайна точка |

Тези крайни точки отразяват API формата на Gemini за клиенти, които очакват естествена съвместимост с Gemini SDK.

### Вътрешен/системен API

| Крайна точка    | Метод      | Описание                                                                       |
| --------------- | ---------- | ------------------------------------------------------------------------------ |
| `/api/init`     | ВЗЕМЕТЕ    | Проверка за инициализация на приложението (използва се при първото стартиране) |
| `/api/tags`     | ВЗЕМЕТЕ    | Тагове за модели, съвместими с Ollama (за клиенти на Ollama)                   |
| `/api/restart`  | ПУБЛИКАЦИЯ | Задейства грациозно рестартиране на сървъра                                    |
| `/api/shutdown` | ПУБЛИКАЦИЯ | Задействайте грациозно изключване на сървъра                                   |

> **Забележка:** Тези крайни точки се използват вътрешно от системата или за съвместимост с клиента Ollama. Те обикновено не се извикват от крайните потребители.

---

## Аудио транскрипция

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

Транскрибирайте аудио файлове с помощта на Deepgram или AssemblyAI.

**Заявка:**

```bash
curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@recording.mp3" \
  -F "model=deepgram/nova-3"
```

**Отговор:**

```json
{
  "text": "Hello, this is the transcribed audio content.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}
```

**Поддържани доставчици:** `deepgram/nova-3`, `assemblyai/best`.

**Поддържани формати:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.

---

## Съвместимост с Ollama

За клиенти, които използват API формат на Ollama:

```bash
# Chat endpoint (Ollama format)
POST /v1/api/chat

# Model listing (Ollama format)
GET /api/tags
```

Заявките се превеждат автоматично между Ollama и вътрешни формати.

---

## Телеметрия

```bash
# Get latency telemetry summary (p50/p95/p99 per provider)
GET /api/telemetry/summary
```

**Отговор:**

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

---

## Бюджет

```bash
# Get budget status for all API keys
GET /api/usage/budget

# Set or update a budget
POST /api/usage/budget
Content-Type: application/json

{
  "keyId": "key-123",
  "limit": 50.00,
  "period": "monthly"
}
```

---

## Наличност на модела

```bash
# Get real-time model availability across all providers
GET /api/models/availability

# Check availability for a specific model
POST /api/models/availability
Content-Type: application/json

{
  "model": "claude-sonnet-4-5-20250929"
}
```

---

## Обработка на заявка

1. Клиентът изпраща заявка до `/v1/*`
2. Обработчикът на маршрута извиква `handleChat`, `handleEmbedding`, `handleAudioTranscription` или `handleImageGeneration`
3. Моделът е разрешен (директен доставчик/модел или псевдоним/комбо)
4. Идентификационни данни, избрани от локална база данни с филтриране на наличността на акаунта
5. За чат: `handleChatCore` — откриване на формат, превод, проверка на кеша, проверка на идемпотентност
6. Изпълнителят на доставчика изпраща заявка нагоре по веригата
7. Отговор, преведен обратно във формат на клиента (чат) или върнат такъв, какъвто е (вграждания/изображения/аудио)
8. Записано използване/регистриране
9. Резервният вариант се прилага при грешки според комбо правилата

Пълна справка за архитектурата: [link](ARCHITECTURE.md)

---

## Удостоверяване

- Маршрутите на таблото за управление (`/dashboard/*`) използват бисквитка `auth_token`
- Входът използва запазен хеш на паролата; връщане към `INITIAL_PASSWORD`
- `requireLogin` превключваем чрез `/api/settings/require-login`
- `/v1/*` маршрутите по избор изискват Bearer API ключ, когато `REQUIRE_API_KEY=true`