Skip to content

Latest commit

 

History

History
441 lines (327 loc) · 19.4 KB

API_REFERENCE.md

File metadata and controls

441 lines (327 loc) · 19.4 KB

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

🌐 Languages: 🇺🇸 English | 🇧🇷 Português (Brasil) | 🇪🇸 Español | 🇫🇷 Français | 🇮🇹 Italiano | 🇷🇺 Русский | 🇨🇳 中文 (简体) | 🇩🇪 Deutsch | 🇮🇳 हिन्दी | 🇹🇭 ไทย | 🇺🇦 Українська | 🇸🇦 العربية | 🇯🇵 日本語 | 🇻🇳 Tiếng Việt | 🇧🇬 Български | 🇩🇰 Dansk | 🇫🇮 Suomi | 🇮🇱 עברית | 🇭🇺 Magyar | 🇮🇩 Bahasa Indonesia | 🇰🇷 한국어 | 🇲🇾 Bahasa Melayu | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇵🇹 Português (Portugal) | 🇷🇴 Română | 🇵🇱 Polski | 🇸🇰 Slovenčina | 🇸🇪 Svenska | 🇵🇭 Filipino

مرجع كامل لجميع نقاط نهاية OmniRoute API.

جدول المحتويات

إكمالات الدردشة

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 إذا تم تتبع التقدم على

التضمينات

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.

# List all embedding models
GET /v1/embeddings

توليد الصور

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.

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

قائمة النماذج

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 أولاما

مسارات موفر مخصصة

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

تتم إضافة بادئة الموفر تلقائيًا في حالة فقدانها. تُرجع النماذج غير المتطابقة 400.

ذاكرة التخزين المؤقت الدلالية

# Get cache stats
GET /api/cache

# Clear all caches
DELETE /api/cache

مثال الاستجابة:

{
  "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. لا يتم استدعاؤها عادة من قبل المستخدمين النهائيين.

النسخ الصوتي

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

قم بنسخ الملفات الصوتية باستخدام Deepgram أو AssemblyAI.

الطلب:

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

الرد:

{
  "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:

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

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

تتم ترجمة الطلبات تلقائيًا بين تنسيقات Ollama والتنسيقات الداخلية.

القياس عن بعد

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

الرد:

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

الميزانية

# 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"
}

توفر النموذج

# 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

المصادقة

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