VberAI API — مرجع RESTful للمطوّرين

واجهة VberAI API هي واجهة HTTP بنمط RESTful لتضمين قدرات الذكاء الاصطناعي من VberAI (اليوم: القص الفائق بالذكاء الاصطناعي) في تطبيقاتك وألعابك وخطوط الأتمتة لديك. تعتمد المصادقة على مفاتيح API مع طلبات موقّعة؛ ورموز الأخطاء الشائعة موحّدة؛ وتُدفع الفوترة لكل طلب بأرصدة VberAI.

API v1
مستقر

توثيق API

أنشئ الصور، وأزل الخلفيات، وشغّل خطوط معالجة الذكاء الاصطناعي في VberAI مباشرةً عبر HTTP — باستخدام مفاتيح API الشخصية أو المؤسسية.

إزالة الخلفية

ai-image-bg-remove

أزل الخلفية من صورة وأعد قصًا بخلفية شفافة. غير متزامن — أرسل، ثم استطلع أو انتظر webhook.

التسعير

رسم ثابت لكل صورة. استدعِ نقطة النهاية /cost للمبلغ الدقيق.

المعاملات

المعاملالنوعمطلوبالوصف
imageUrlstringنعمرابط http(s) عام للصورة المراد معالجتها. هذا هو input الوحيد الذي تقبله الخدمة — فهي لا تقبل base64 ولا source_type.
widthnumberلااختياري. يُستخدم فقط كقيمة احتياطية لمساحة الفوترة عندما يتعذر اكتشاف دقة المصدر؛ ولا يغيّر الإخراج.
heightnumberلااختياري. يُستخدم فقط كقيمة احتياطية لمساحة الفوترة عندما يتعذر اكتشاف دقة المصدر؛ ولا يغيّر الإخراج.

الاستطلاع والنتائج

تعيد المهام غير المتزامنة taskId. استطلع المهمة حتى يصبح status لها قيمة نهائية، ثم اقرأ النتيجة. يعتمد المسار الذي تستطلعه على نوع مفتاحك — وهذا أهم شيء يجب ضبطه بشكل صحيح.

الإجراءالمفتاح الشخصيالمفتاح المؤسسي
استطلاع حالة المهمةGET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
إعادة توقيع روابط تنزيل جديدةاقرأ من استجابة statusGET /ai/org-services/tasks/{taskId}/outputs

يجب على المفاتيح المؤسسية استطلاع مسار /ai/org-services

مفتاح مؤسسي (vber_org_sk_) يُرسل إلى مسار شخصي /ai/tasks يعيد 401 INVALID_API_KEY — إذ تقبل المسارات الشخصية المفاتيح الشخصية فقط. استطلع دائمًا المهام المؤسسية على /ai/org-services/tasks/{taskId}. أما cancel و batch-status فمتاحان للمفتاح الشخصي فقط.

تمر المهمة عبر هذه القيم. توقف عن الاستطلاع بمجرد وصولك إلى حالة نهائية: completed أو failed أو cancelled أو timeout.

createdqueueddispatchingsubmittedprocessingcompletedfailedcancelledtimeout

عندما تكون status هي completed، يحمل result.assets صور الإخراج. يحتوي كل asset على url (رابط تنزيل موقّع مسبقًا تنتهي صلاحيته)، و mimeType و index؛ وتظهر width و height و size و expiresAt عند توفرها. اجلب عناوين URL فورًا — إذ يمكن للمفاتيح المؤسسية إعادة طلب روابط جديدة من نقطة النهاية /outputs.

عند الاكتمال، يحمل result.assets صورة القص بخلفية شفافة.

مهمة مكتملة

json
{
  "success": true,
  "data": {
    "taskId": "6a97e277a148c970dd545f40",
    "serviceCode": "ai-image-bg-remove",
    "status": "completed",
    "creditsEstimated": 10,
    "creditsActual": 10,
    "outputCount": 1,
    "result": {
      "type": "images",
      "assets": [
        {
          "index": 0,
          "url": "https://assets.vberai.org/tmp/user-assets/.../0.png?signature=...",
          "mimeType": "image/png",
          "expiresAt": "2026-01-22T10:30:12.000Z"
        }
      ]
    },
    "completedAt": "2026-01-15T10:30:12.000Z"
  }
}

Webhooks

مرّر webhookUrl عامًا عبر HTTPS (و webhookSecret اختياريًا) عند إرسال المهمة. تقرأ المفاتيح المؤسسية هذه القيم من المستوى الأعلى للجسم؛ بينما تقرأها المفاتيح الشخصية من options.

إذا عيّنت webhookSecret، يتضمن كل تسليم ترويسة X-Webhook-Signature — وهي HMAC-SHA256 لحمولة JSON الخام، مُرمّزة بالنظام السداسي عشري. أعد حسابها باستخدام سرّك وقارنها قبل الوثوق بالحمولة. تحمل عمليات التسليم أيضًا X-Idempotency-Key (taskId + status) لتتمكن من تجاهل التكرارات.

POST/ai/services/ai-image-bg-remove/execute
bash
curl -X POST https://api.vberai.com/api/ai/services/ai-image-bg-remove/execute \
  -H "X-API-Key: vber_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"imageUrl": "https://example.com/photo.png"}}'
bash
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"