REST API

شكل الطلب العام، ترويسات المصادقة، وأمثلة تنفيذ النماذج.

​

REST API

استخدم REST API عندما تحتاج خدمتك الخلفية أو worker أو script إلى تشغيل نموذج منشور. المستهلكون يستدعون Gateway العام فقط. لا تستدعِ الخدمات الداخلية مباشرة.

​

Base URL

استخدم رابط Gateway الخاص ببيئتك:

<GATEWAY_URL>/api

في التطوير المحلي يكون Gateway غالباً:

http://localhost:8080/api

​

المصادقة

طلبات server-to-server تستخدم API key:

X-API-Key: <your_api_key>

طلبات المتصفح داخل تطبيق المنتج تستخدم access token للمستخدم:

Authorization: Bearer <access_token>

لا تضع API keys طويلة العمر داخل JavaScript في المتصفح.

لا ترسل API key كـ bearer token. ترويسة Authorization: Bearer <access_token> خاصة بجلسات المتصفح المسجلة الدخول؛ تكاملات المطورين تستخدم X-API-Key.

​

تنفيذ نموذج

curl -X POST "$AIMP_GATEWAY_URL/api/runs" \
  -H "X-API-Key: $AIMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "demo-model",
    "mode": "execute",
    "scope": "playground",
    "input": {
      "text": "Hello"
    },
    "params": {}
  }'

​

حقول الطلب

الحقل	مطلوب	المعنى
model	نعم	slug أو معرف النموذج المنشور.
mode	لا	العملية المطلوب تشغيلها. الافتراضي execute.
scope	أحياناً	مطلوب للعمليات المعتمدة على vector. هو namespace يفصل البيانات المفهرسة.
input	نعم	مدخل النموذج. شكله يعتمد على عقد النموذج.
params	لا	معاملات النموذج. يجب أن تكون JSON object.
options	لا	خيارات تنفيذ مسموحة. لا ترسل hardware_tier؛ العتاد يحدد من الإصدار المنشور.

استخدم params وليس parameters. حقول vector مثل resources وalias وcollection وnamespace تديرها المنصة ولا يجب على العميل إرسالها.

في عمليات index وsearch المعتمدة على vector، استخدم نفس scope للبيانات التي تريد البحث فيها. إذا فهرست صوراً بـ scope: "test"، يجب أن تبحث أيضاً بـ scope: "test". صفحة Knowledge Bases تعرض البيانات حسب النموذج والكولكشن والـ scope.

الـ scope الصحيح يبدأ بحرف أو رقم، ويسمح بالحروف والأرقام و. و_ و-، والحد الأقصى 64 حرفاً.

​

رفع media لمدخلات النماذج

النماذج التي تقبل صوراً أو صوتاً أو فيديو أو ملفات تستعمل media_ref داخل input. ارفع الملف أولاً عبر public media API:

curl -X POST "$AIMP_GATEWAY_URL/api/media/upload/init" \
  -H "X-API-Key: $AIMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "image.png",
    "content_type": "image/png",
    "media_type": "image",
    "size_bytes": 12345
  }'

ارفع bytes الملف إلى upload_url الراجع، ثم أكمل الرفع:

curl -X POST "$AIMP_GATEWAY_URL/api/media/upload/complete" \
  -H "X-API-Key: $AIMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "studio_upload_..."
  }'

استعمل media_ref الراجع داخل POST /api/runs.

​

واجهات مرتبطة

• GET /api/marketplace/models تعرض نماذج Marketplace المنشورة.
• GET /api/marketplace/models/{slug} تعرض تفاصيل نموذج واحد.
• POST /api/media/upload/init يبدأ رفع media للمطورين.
• POST /api/media/upload/complete يرجع media_ref بعد اكتمال الرفع.
• GET /api/billing/wallet تعرض محفظة مساحة العمل الحالية.
• GET /api/billing/usage/summary تعرض ملخص الاستخدام لمساحة العمل.