واجهة VberAI API هي واجهة HTTP بنمط RESTful لتضمين قدرات الذكاء الاصطناعي من VberAI (اليوم: القص الفائق بالذكاء الاصطناعي) في تطبيقاتك وألعابك وخطوط الأتمتة لديك. تعتمد المصادقة على مفاتيح API مع طلبات موقّعة؛ ورموز الأخطاء الشائعة موحّدة؛ وتُدفع الفوترة لكل طلب بأرصدة VberAI.
API v1
مستقر
توثيق API
أنشئ الصور، وأزل الخلفيات، وشغّل خطوط معالجة الذكاء الاصطناعي في VberAI مباشرةً عبر HTTP — باستخدام مفاتيح API الشخصية أو المؤسسية.
قص عالي الجودة يفصل الموضوع عن خلفيته ويعيد نتيجة قص نظيفة. غير متزامن — أرسل، ثم استطلع أو انتظر webhook.
التسعير
يُسعّر وفق أطول ضلع في الإخراج (مستويات حسب البُعد — مثلًا 512 px بـ 2 من الأرصدة، و 1024 px بـ 10). استدعِ نقطة النهاية /cost للمبلغ الدقيق قبل تشغيل مهمة.
المعاملات
المعامل
النوع
مطلوب
الوصف
source_type
string
نعم
إحدى القيمتين "url" (حيث input_value هو رابط صورة http(s) عام) أو "base64" (حيث input_value سلسلة base64 أو data: URL).
input_value
string
نعم
الصورة المصدر: رابط http(s) عندما تكون source_type هي "url"، أو بيانات صورة base64 عندما تكون source_type هي "base64".
width
number
نعم
العرض المستهدف بالبكسل (64–2048).
height
number
نعم
الارتفاع المستهدف بالبكسل (64–2048).
seed
number
لا
اختياري. seed عددي صحيح ثابت لإخراج قابل لإعادة الإنتاج؛ ويُستخدم seed عشوائي عند إغفاله.
الاستطلاع والنتائج
تعيد المهام غير المتزامنة taskId. استطلع المهمة حتى يصبح status لها قيمة نهائية، ثم اقرأ النتيجة. يعتمد المسار الذي تستطلعه على نوع مفتاحك — وهذا أهم شيء يجب ضبطه بشكل صحيح.
الإجراء
المفتاح الشخصي
المفتاح المؤسسي
استطلاع حالة المهمة
GET /ai/tasks/{taskId}
GET /ai/org-services/tasks/{taskId}
إعادة توقيع روابط تنزيل جديدة
اقرأ من استجابة status
GET /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.
عندما تكون status هي completed، يحمل result.assets صور الإخراج. يحتوي كل asset على url (رابط تنزيل موقّع مسبقًا تنتهي صلاحيته)، و mimeType و index؛ وتظهر width و height و size و expiresAt عند توفرها. اجلب عناوين URL فورًا — إذ يمكن للمفاتيح المؤسسية إعادة طلب روابط جديدة من نقطة النهاية /outputs.
عند الاكتمال، يحمل result.assets صورة/صور إخراج القص.
مرّر webhookUrl عامًا عبر HTTPS (و webhookSecret اختياريًا) عند إرسال المهمة. تقرأ المفاتيح المؤسسية هذه القيم من المستوى الأعلى للجسم؛ بينما تقرأها المفاتيح الشخصية من options.
إذا عيّنت webhookSecret، يتضمن كل تسليم ترويسة X-Webhook-Signature — وهي HMAC-SHA256 لحمولة JSON الخام، مُرمّزة بالنظام السداسي عشري. أعد حسابها باستخدام سرّك وقارنها قبل الوثوق بالحمولة. تحمل عمليات التسليم أيضًا X-Idempotency-Key (taskId + status) لتتمكن من تجاهل التكرارات.