# مرجع واجهة برمجة التطبيقات

🌐 **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`        | طلب     | مفتاح Dedup (نافذة 5 ثواني)                 |
| `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`      | أوبن آي               |
| مشاركة   | `/v1/messages`              | انثروبي               |
| مشاركة   | `/v1/responses`             | ردود OpenAI           |
| مشاركة   | `/v1/embeddings`            | أوبن آي               |
| مشاركة   | `/v1/images/generations`    | أوبن آي               |
| احصل على | `/v1/models`                | أوبن آي               |
| مشاركة   | `/v1/messages/count_tokens` | انثروبي               |
| احصل على | `/v1beta/models`            | الجوزاء               |
| مشاركة   | `/v1beta/models/{...path}`  | الجوزاء توليد المحتوى |
| مشاركة   | `/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/*`         | متنوع   | إدارة السحابة            |

### أدوات سطر الأوامر

| نقطة النهاية                       | الطريقة  | الوصف               |
| ---------------------------------- | -------- | ------------------- |
| `/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]`  | احصل على | وقت تشغيل CLI العام |

تتضمن استجابات واجهة سطر الأوامر: `installed`، `runnable`، `command`، `commandPath`، `runtimeMode`، `reason`.

### المرونة وحدود الأسعار

| نقطة النهاية            | الطريقة        | الوصف                                |
| ----------------------- | -------------- | ------------------------------------ |
| `/api/resilience`       | الحصول على/وضع | الحصول على/تحديث ملفات تعريف المرونة |
| `/api/resilience/reset` | مشاركة         | إعادة ضبط قواطع الدائرة              |
| `/api/rate-limits`      | احصل على       | حالة حد المعدل لكل حساب              |
| `/api/rate-limit`       | احصل على       | تكوين حد المعدل العالمي              |

### التقييم

| نقطة النهاية | الطريقة          | الوصف                                 |
| ------------ | ---------------- | ------------------------------------- |
| `/api/evals` | الحصول على/النشر | قائمة مجموعات التقييم / تشغيل التقييم |

### السياسات

| نقطة النهاية    | الطريقة            | الوصف                |
| --------------- | ------------------ | -------------------- |
| `/api/policies` | الحصول على/نشر/حذف | إدارة سياسات التوجيه |

###الامتثال

| نقطة النهاية                | الطريقة  | الوصف                        |
| --------------------------- | -------- | ---------------------------- |
| `/api/compliance/audit-log` | احصل على | سجل تدقيق الامتثال (آخر رقم) |

### v1beta (متوافق مع الجوزاء)

| نقطة النهاية               | الطريقة  | الوصف                                  |
| -------------------------- | -------- | -------------------------------------- |
| `/v1beta/models`           | احصل على | قائمة النماذج بصيغة الجوزاء            |
| `/v1beta/models/{...path}` | مشاركة   | الجوزاء `generateContent` نقطة النهاية |

تعكس نقاط النهاية هذه تنسيق Gemini API للعملاء الذين يتوقعون توافق Gemini SDK الأصلي.

### واجهات برمجة التطبيقات الداخلية / النظام

| نقطة النهاية    | الطريقة  | الوصف                                              |
| --------------- | -------- | -------------------------------------------------- |
| `/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`.

---

## التوافق مع أولاما

بالنسبة للعملاء الذين يستخدمون تنسيق واجهة برمجة تطبيقات Olma:

```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. يتم تطبيق الإجراء الاحتياطي على الأخطاء وفقًا لقواعد التحرير والسرد

مرجع البنية الكاملة: [**OMNI_TOKEN_119**](ARCHITECTURE.md)

---

## المصادقة

- تستخدم مسارات لوحة المعلومات (`/dashboard/*`) ملف تعريف الارتباط `auth_token`
- يستخدم تسجيل الدخول تجزئة كلمة المرور المحفوظة؛ الرجوع إلى `INITIAL_PASSWORD`
- `requireLogin` قابل للتبديل عبر `/api/settings/require-login`
- تتطلب مسارات `/v1/*` بشكل اختياري مفتاح Bearer API عندما `REQUIRE_API_KEY=true`