وثائق OpenAPI للمطورين في السعودية

نظرة عامة

BrightAI API توفر مجموعة من خدمات الذكاء الاصطناعي المصممة خصيصاً للسوق السعودي. جميع الخدمات تدعم اللغة العربية بشكل كامل وتتماشى مع رؤية المملكة 2030.

الخوادم المتاحة

خادم التطوير: http://localhost:3000
خادم الإنتاج: https://api.brightai.sa

تنسيق الطلبات والاستجابات

جميع الطلبات يجب أن تكون بتنسيق JSON
جميع الاستجابات بتنسيق JSON
الترميز: UTF-8
Content-Type: application/json

المصادقة

حالياً، API لا يتطلب مصادقة للاستخدام العام. ومع ذلك، يتم تطبيق حدود معدل الطلبات (Rate Limiting) بناءً على عنوان IP.

ملاحظة: في الإصدارات المستقبلية، سيتم إضافة نظام مصادقة باستخدام API Keys.

محادثة ذكية (Chat)

POST /api/ai/chat

إرسال رسالة والحصول على رد من الذكاء الاصطناعي. يدعم المحادثات متعددة الأدوار مع الاحتفاظ بالسياق.

معاملات الطلب

الوصف	النوع	مطلوب؟	المعامل
الرسالة المراد إرسالها (حد أقصى 1000 حرف)	string	نعم	message
سجل المحادثة السابقة (مصفوفة من الرسائل)	array	لا	history
معرف الجلسة للحفاظ على السياق	string	لا	sessionId

مثال على الطلب

{
  "message": "ما هي خدمات BrightAI؟",
  "history": [
    {
      "sender": "user",
      "text": "مرحباً"
    },
    {
      "sender": "bot",
      "text": "مرحباً بك في BrightAI"
    }
  ],
  "sessionId": "session_123456"
}
                

مثال على الاستجابة الناجحة 200

{
  "reply": "BrightAI تقدم مجموعة من خدمات الذكاء الاصطناعي...",
  "sessionId": "session_123456"
}
                

الأخطاء المحتملة

400 NO_MESSAGE: يرجى إدخال رسالة

400 MESSAGE_TOO_LONG: الرسالة طويلة جداً. الحد الأقصى هو 1000 حرف

503 API_NOT_CONFIGURED: خدمة الذكاء الاصطناعي غير متاحة حالياً

بحث ذكي (Search)

POST /api/ai/search

البحث الذكي في محتوى موقع BrightAI باستخدام الذكاء الاصطناعي.

معاملات الطلب

الوصف	النوع	مطلوب؟	المعامل
كلمة البحث (3 أحرف على الأقل)	string	نعم	query

مثال على الطلب

{
  "query": "وكلاء الذكاء الاصطناعي"
}
                

مثال على الاستجابة الناجحة 200

{
  "results": [
    {
      "title": "وكلاء الذكاء الاصطناعي",
      "url": "https://brightai.site/ai-agent",
      "description": "حلول وكلاء ذكية لأتمتة المهام المعقدة"
    },
    {
      "title": "الأتمتة الذكية",
      "url": "https://brightai.site/smart-automation",
      "description": "أتمتة العمليات باستخدام الذكاء الاصطناعي"
    }
  ],
  "query": "وكلاء الذكاء الاصطناعي"
}
                

الأخطاء المحتملة

400 NO_QUERY: يرجى إدخال كلمة البحث

400 QUERY_TOO_SHORT: يجب أن تكون كلمة البحث 3 أحرف على الأقل

503 API_NOT_CONFIGURED: خدمة البحث غير متاحة حالياً

تحليل طبي (Medical)

POST /api/ai/medical

تحليل البيانات الطبية والصور باستخدام الذكاء الاصطناعي.

معاملات الطلب

الوصف	النوع	مطلوب؟	المعامل
مصفوفة من النصوص للتحليل	array[string]	نعم	textParts
مصفوفة من الصور (base64)	array[object]	لا	inlineDataParts
إعدادات التوليد	object	لا	config

بنية inlineDataParts

{
  "mimeType": "image/jpeg",
  "data": "base64_encoded_image_data"
}
                

أنواع الملفات المدعومة

image/jpeg
image/png
image/webp
application/dicom

مثال على الطلب

{
  "textParts": ["قم بتحليل هذه الصورة الطبية"],
  "inlineDataParts": [
    {
      "mimeType": "image/jpeg",
      "data": "/9j/4AAQSkZJRgABAQAA..."
    }
  ],
  "config": {
    "temperature": 0.2,
    "max_output_tokens": 2048
  }
}
                

مثال على الاستجابة الناجحة 200

{
  "text": "التحليل الطبي: الصورة تظهر..."
}
                

الأخطاء المحتملة

400 MISSING_TEXT: الرجاء تقديم نص للتحليل

400 INVALID_IMAGE_DATA: بيانات الصورة غير صالحة

400 UNSUPPORTED_FILE_TYPE: نوع الملف غير مدعوم

503 SERVICE_UNAVAILABLE: خدمة الذكاء الاصطناعي غير متاحة حالياً

تلخيص نصوص (Summary)

POST /api/ai/summary

توليد ملخص موجز وجذاب للنصوص الطويلة باللغة العربية.

معاملات الطلب

الوصف	النوع	مطلوب؟	المعامل
النص المراد تلخيصه (حد أقصى 5000 حرف)	string	نعم	text

مثال على الطلب

{
  "text": "نص طويل يحتاج إلى تلخيص..."
}
                

مثال على الاستجابة الناجحة 200

{
  "summary": "الملخص: النص يتحدث عن...",
  "timestamp": 1234567890
}
                

Cache Headers

يدعم هذا Endpoint التخزين المؤقت (Caching). ستحصل على أحد هذه Headers:

X-Cache: HIT - الاستجابة من Cache
X-Cache: MISS - استجابة جديدة من API

الأخطاء المحتملة

400 MISSING_TEXT: يجب تقديم نص للتلخيص

503 API_NOT_CONFIGURED: خدمة الذكاء الاصطناعي غير متاحة حالياً

500 SUMMARY_ERROR: حدث خطأ أثناء إنشاء الملخص

أكواد الأخطاء

جميع الأخطاء تُرجع بتنسيق موحد يحتوي على:

{
  "error": "رسالة الخطأ بالعربية",
  "errorCode": "ERROR_CODE",
  "timestamp": 1234567890
}
            

أخطاء المدخلات (4xx)

NO_MESSAGE / NO_QUERY / MISSING_TEXT
400 يجب تقديم البيانات المطلوبة

MESSAGE_TOO_LONG / QUERY_TOO_LONG
400 المدخلات تتجاوز الحد المسموح

QUERY_TOO_SHORT
400 كلمة البحث قصيرة جداً (3 أحرف على الأقل)

INVALID_REQUEST
400 طلب غير صالح

INVALID_IMAGE_DATA
400 بيانات الصورة غير صالحة

UNSUPPORTED_FILE_TYPE
400 نوع الملف غير مدعوم

RATE_LIMIT_EXCEEDED
429 تم تجاوز الحد المسموح من الطلبات

أخطاء الخادم (5xx)

API_NOT_CONFIGURED / SERVICE_UNAVAILABLE
503 خدمة الذكاء الاصطناعي غير متاحة حالياً

API_ERROR / ANALYSIS_ERROR / SUMMARY_ERROR
500 حدث خطأ أثناء المعالجة

NETWORK_ERROR
500 خطأ في الاتصال بالشبكة

TIMEOUT_ERROR
500 انتهت مهلة الطلب

UNKNOWN_ERROR
500 حدث خطأ غير متوقع

حدود الاستخدام (Rate Limits)

لضمان جودة الخدمة لجميع المستخدمين، يتم تطبيق حدود معدل الطلبات التالية:

الوصف	الحد	النطاق الزمني
جميع Endpoints	30 طلب	دقيقة واحدة

Response Headers

عند تجاوز الحد، ستحصل على:

Status Code: 429 Too Many Requests
Error Code: RATE_LIMIT_EXCEEDED
Retry-After: عدد الثواني قبل المحاولة مرة أخرى

Request/Response Schemas

ChatRequest Schema

{
  "message": "string (required, max 1000 chars)",
  "history": [
    {
      "sender": "user | bot",
      "text": "string"
    }
  ],
  "sessionId": "string (optional)"
}
            

ChatResponse Schema

{
  "reply": "string",
  "sessionId": "string"
}
            

SearchRequest Schema

{
  "query": "string (required, min 3 chars)"
}
            

SearchResponse Schema

{
  "results": [
    {
      "title": "string",
      "url": "https://brightai.site/string",
      "description": "string"
    }
  ],
  "query": "string"
}
            

MedicalRequest Schema

{
  "textParts": ["string (required)"],
  "inlineDataParts": [
    {
      "mimeType": "string (image/jpeg, image/png, etc.)",
      "data": "string (base64 encoded)"
    }
  ],
  "config": {
    "temperature": "number (0.0-1.0, default: 0.2)",
    "top_p": "number (default: 0.9)",
    "top_k": "number (default: 40)",
    "max_output_tokens": "number (default: 2048)"
  }
}
            

MedicalResponse Schema

{
  "text": "string"
}
            

SummaryRequest Schema

{
  "text": "string (required, max 5000 chars)"
}
            

SummaryResponse Schema

{
  "summary": "string",
  "timestamp": "number"
}
            

ErrorResponse Schema

{
  "error": "string (Arabic error message)",
  "errorCode": "string (ERROR_CODE)",
  "timestamp": "number (Unix timestamp)",
  "details": "string (only in development mode)"
}
            

أمثلة cURL

Chat Endpoint

curl -X POST http://localhost:3000/api/ai/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "ما هي خدمات BrightAI؟"
  }'
            

Search Endpoint

curl -X POST http://localhost:3000/api/ai/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "وكلاء الذكاء الاصطناعي"
  }'
            

Medical Endpoint

curl -X POST http://localhost:3000/api/ai/medical \
  -H "Content-Type: application/json" \
  -d '{
    "textParts": ["قم بتحليل هذه البيانات الطبية"]
  }'
            

Summary Endpoint

curl -X POST http://localhost:3000/api/ai/summary \
  -H "Content-Type: application/json" \
  -d '{
    "text": "نص طويل يحتاج إلى تلخيص..."
  }'
            

أفضل الممارسات

1. معالجة الأخطاء

تحقق دائماً من HTTP status code
اعرض رسالة الخطأ العربية للمستخدم
استخدم errorCode للمعالجة البرمجية
أعد المحاولة عند حدوث أخطاء 5xx

2. Rate Limiting

احترم حدود معدل الطلبات (30 طلب/دقيقة)
استخدم Retry-After header عند تجاوز الحد
قم بتخزين النتائج مؤقتاً في تطبيقك

3. الأداء

استفد من X-Cache header في Summary endpoint
قلل حجم المدخلات قدر الإمكان
استخدم sessionId للحفاظ على سياق المحادثة

4. الأمان

لا ترسل معلومات حساسة في الطلبات
استخدم HTTPS في الإنتاج
قم بتنظيف المدخلات قبل الإرسال
لا تعرض API keys في الكود العام

متى يكون هذا التوثيق مناسباً لفريقك؟

هذا التوثيق مناسب عندما تكون لديك بوابة رقمية أو نظام تشغيلي داخلي وتريد ربطه مباشرة بخدمات Bright AI بدلاً من العمل اليدوي أو تبادل الملفات بشكل منفصل. الهدف هنا ليس مجرد استدعاء Endpoint، بل بناء مسار تكامل واضح يمكن لفريق التقنية والعمليات والحوكمة تقييمه بسرعة.

حقائق سريعة قبل البدء

ابدأ من حالة استخدام واحدة عالية الأثر مثل التصنيف، التلخيص، أو البحث الداخلي.
حدّد مالكاً واضحاً للتكامل بين التقنية والأعمال قبل الوصول إلى بيئة الإنتاج.
راجع متطلبات الأمان والامتثال مبكراً إذا كانت البيانات حساسة أو منظمة.
استخدم هذا التوثيق مع صفحة الاستشارة التقنية إذا كان القرار ما زال في مرحلة التخطيط.

إذا كان احتياجك أقرب إلى منتج جاهز أو وكيل مُدار، فغالباً ستكون صفحة AI Agent أو نظرة الخدمات نقطة البداية الأنسب قبل النزول إلى مستوى API.

الدعم والتواصل

للحصول على دعم فني أو استفسارات حول API:

الموقع: https://brightai.site
البريد الإلكتروني: yazeed1job@gmail.com
واتساب: +966538229013

التحديثات

تابع صفحة المدونة للحصول على آخر التحديثات والميزات الجديدة:

مدونة BrightAI

وللأسئلة المرتبطة بالجاهزية المؤسسية والحوكمة، راجع أيضاً الأسئلة الشائعة وصفحة التواصل.