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

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

API v1
مستقر

توثيق API

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

مقدمة

يتيح VberAI API الوصول إلى خطوط معالجة الذكاء الاصطناعي نفسها التي تشغّل studio — إزالة الخلفية، والقص الفائق، وتوليد الصور والمزيد — على هيئة نقاط نهاية HTTP بسيطة. صادق باستخدام مفتاح API، وأرسل مهمة، ثم اقرأ النتيجة أو استقبلها عبر webhook.

شكل طلب واحد

تأخذ كل خدمة جسم { input } وتعيد مهمة يمكنك استطلاعها أو استقبالها عبر webhook.

نوعان من المفاتيح

مفاتيح شخصية للمطورين الأفراد، ومفاتيح مؤسسية للاستخدام المؤسسي من خادم إلى خادم.

فوترة يمكن التنبؤ بها

تُحجز الأرصدة عند الإرسال وتُسوّى عند النجاح؛ ويُسترد رصيد المهام الفاشلة تلقائيًا.

كيف يعمل

  1. 1صادق باستخدام مفتاح API الخاص بك في ترويسة X-API-Key.
  2. 2أرسل مهمة إلى خدمة بجسم JSON { input }.
  3. 3اقرأ النتيجة ضمن الاستجابة نفسها (الخدمات المتزامنة) أو استطلع المهمة / استقبل webhook (الخدمات غير المتزامنة).
bash
# 1. Submit a job
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"}}'
# => { "data": { "taskId": "...", "status": "queued" } }

# 2. Poll until status is "completed"
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"

المصادقة ومفاتيح API

يُصادَق كل طلب بمفتاح API يُرسل في ترويسة X-API-Key. هناك نوعان من المفاتيح، ويستخدمان مسارات مختلفة — واختيار المسار الخاطئ لنوع مفتاحك هو السبب الأكثر شيوعًا للخطأ 401.

تعامل مع مفاتيح API كما تتعامل مع كلمات المرور. أرسلها من خادمك الخلفي فقط، وقم بتدويرها إذا تسربت، وقيّد المفاتيح المؤسسية بحد إنفاق.

المفاتيح الشخصية — vber_sk_

للمطورين الأفراد. تُنشأ ذاتيًا من صفحة مفاتيح API في حسابك (تتطلب خطة تتضمن وصول API). تُحتسب الفوترة على أرصدتك الشخصية. استخدم مساري /ai/services و /ai/tasks.

المفاتيح المؤسسية — vber_org_sk_

للاستخدام من خادم إلى خادم من قِبل مؤسسة. يصدرها مسؤول المؤسسة في بوابة المؤسسة، وتقتصر على الخدمات المعتمدة لمؤسستك. تُحتسب الفوترة على مجمّع أرصدة مؤسستك. استخدم مسارات /ai/org-services.

الجانبالمفتاح الشخصيالمفتاح المؤسسي
بادئة المفتاحvber_sk_vber_org_sk_
بادئة المسار/ai/services, /ai/tasks/ai/org-services
كيفية الحصول عليهخدمة ذاتية، إعدادات الحسابمسؤول المؤسسة، بوابة المؤسسة
الفوترة علىالأرصدة الشخصيةأرصدة المؤسسة
الحدودحدود الطلبات لكل دقيقة / لكل يومالتزامن لكل مؤسسة (مخصص)
http
X-API-Key: vber_sk_...        # personal key
X-API-Key: vber_org_sk_...    # enterprise key

عنوان URL الأساسي

text
https://api.vberai.com/api

الطلبات وأوضاع التنفيذ

تأخذ كل خدمة جسم JSON يحتوي على كائن input يحمل معاملات الخدمة. تعتمد طريقة حصولك على النتيجة على وضع تنفيذ الخدمة.

الخدمات المتزامنة

تعيد الخدمات السريعة (مثل الدردشة أو ترجمة النصوص) نتيجتها ضمن الاستجابة نفسها برمز HTTP 200. لا حاجة إلى استطلاع.

الخدمات غير المتزامنة

تعيد الخدمات الأثقل (توليد الصور، والقص، وإزالة الخلفية) رمز HTTP 202 مع taskId. استطلع المهمة أو استقبل النتيجة عبر webhook عند انتهائها.

المفتاح الشخصي

تستخدم المفاتيح الشخصية نقطة نهاية واحدة لكل خدمة: POST /ai/services/{code}/execute. تعيد النتيجة ضمن الاستجابة (200) للخدمات المتزامنة، أو مهمة (202) للخدمات غير المتزامنة — النقطة نفسها في كلتا الحالتين.

المفتاح المؤسسي

تستخدم المفاتيح المؤسسية نقطتَي نهاية: /execute للخدمات المتزامنة و /execute-async للخدمات غير المتزامنة. واستدعاء الخاطئة منهما يعيد 400 يخبرك بأي نقطة نهاية ينبغي استخدامها.
json
{
  "input": {
    "imageUrl": "https://example.com/photo.png"
  },
  "webhookUrl": "https://your-server.com/hook"
}
bash
HTTP 200  # sync: result inline
HTTP 202  # async: { "taskId": "...", "status": "queued" }

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

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

أي مسار تستطلع

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

يجب على المفاتيح المؤسسية استطلاع مسار /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.

bash
# personal
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"

# enterprise
curl https://api.vberai.com/api/ai/org-services/tasks/{taskId} \
  -H "X-API-Key: vber_org_sk_YOUR_ORG_KEY"

مهمة مكتملة

json
{
  "success": true,
  "data": {
    "taskId": "6a97e277a148c970dd545f40",
    "serviceCode": "super-matting",
    "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"
  }
}

Idempotency

تتيح لك Idempotency إعادة محاولة الإرسال بأمان بعد خطأ في الشبكة دون إنشاء مهمة مكررة أو تحميلك رسومًا مرتين.

المفاتيح المؤسسية

أرسل ترويسة Idempotency-Key اختيارية (قيمة تولّدها بنفسك، حتى 200 حرف — و UUID مثالي) على /execute-async. إعادة المحاولة بالمفتاح نفسه تعيد المهمة الأصلية بدلًا من إنشاء مهمة جديدة. يقوم الخادم بإزالة التكرار فقط؛ ولا يولّد المفتاح نيابةً عنك.

المفاتيح الشخصية

لا تدعم طلبات مفتاح API الشخصي حاليًا مفتاح idempotency. أعد المحاولة فقط بعد التأكد من أن الطلب السابق لم ينشئ مهمة (بالاستطلاع باستخدام taskId الذي استلمته).

http
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Webhooks

بدلًا من الاستطلاع، يمكنك جعل VberAI يرسل النتيجة عبر POST إلى خادمك عندما تصل المهمة إلى حالة نهائية.

إعداد webhook

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

التحقق من التوقيع

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

تُعاد محاولة عمليات التسليم الفاشلة عدة مرات مع تراجع تدريجي. استجب برمز 2xx للإقرار بالاستلام.
json
{
  "input": { "imageUrl": "https://example.com/photo.png" },
  "webhookUrl": "https://your-server.com/hook",
  "webhookSecret": "whsec_your_secret"
}

التحقق من webhook (Node.js)

javascript
import crypto from "node:crypto";

function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return signature === expected;
}

app.post("/hook", (req, res) => {
  const sig = req.header("X-Webhook-Signature");
  if (!verify(req.rawBody, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  // req.body: { taskId, serviceCode, status, ... }
  res.status(200).end();
});

الأرصدة والفوترة

تكلّف مهام الذكاء الاصطناعي أرصدة. تنطبق الأسعار نفسها على المفاتيح الشخصية والمؤسسية — وتختلف المحفظة فقط: المفاتيح الشخصية تسحب من أرصدتك الشخصية، والمفاتيح المؤسسية من مجمّع مؤسستك.

الحجز والتسوية والاسترداد

تُحجز الأرصدة عند قبول المهمة وتُسوّى إلى المبلغ الدقيق عند اكتمالها. وإذا فشلت مهمة أو أُلغيت، يُسترد الحجز بالكامل — فلن تُحمّل أبدًا رسومًا مقابل مهمة فاشلة.

كيف تُحسب التكلفة

تعتمد التكلفة على الخدمة. تفرض بعض الخدمات مبلغًا ثابتًا لكل طلب؛ بينما تتناسب أخرى مع دقة الإخراج (لكل بكسل) أو مع أطول ضلع. استدعِ نقطة النهاية cost لمعاينة الرسم الدقيق قبل تشغيل مهمة.

  • •لكل طلب — مبلغ ثابت في كل استدعاء.
  • •لكل بكسل — يتناسب مع width × height للإخراج.
  • •حسب البُعد — يُسعّر وفق أطول ضلع في الإخراج.
bash
curl -X POST https://api.vberai.com/api/ai/services/super-matting/cost \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"width": 1024, "height": 768}}'
json
{
  "success": true,
  "data": {
    "estimatedCredits": 10,
    "pricingType": "custom",
    "pricingMode": "dimension",
    "sufficient": true
  }
}

حدود المعدل

يختلف تحديد المعدل حسب نوع المفتاح. وكلاهما يُضبط لكل خدمة في الواجهة الخلفية — والقيم أدناه تصف الآلية، لا أرقامًا ثابتة.

المفاتيح الشخصية — معدل الطلبات

تُقيَّد المفاتيح الشخصية بعدد الطلبات في الدقيقة وفي اليوم، ويُضبط ذلك لكل خدمة. تحمل كل استجابة الترويسات أدناه لتتمكن من ضبط وتيرة استدعاءاتك.

الترويسةالوصف
X-RateLimit-Limit-Minuteالطلبات المسموح بها في الدقيقة.
X-RateLimit-Remaining-Minuteالطلبات المتبقية في نافذة الدقيقة الحالية.
X-RateLimit-Limit-Dayالطلبات المسموح بها في اليوم.
X-RateLimit-Remaining-Dayالطلبات المتبقية في نافذة اليوم الحالية.
لا توجد ترويسة X-RateLimit-Reset. وعند الخطأ 429، يتضمن جسم الاستجابة retryAfter و resetIn.

المفاتيح المؤسسية — التزامن

لا تُقيَّد المفاتيح المؤسسية بمعدل الطلبات بل بعدد المهام التي يمكن تشغيلها في آنٍ واحد لمؤسستك. والحد مخصص لكل مؤسسة (وقد يكون غير محدود)؛ وتجاوزه يعيد 429 CONCURRENCY_LIMIT_EXCEEDED. ولا تحمل استجابات المؤسسة ترويسات X-RateLimit.

http
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Limit-Day: 2000
X-RateLimit-Remaining-Day: 1997

الأخطاء

يتضمن كل استجابة success و message و timestamp. وعند الفشل، يحدد رمز خطأ المشكلة. تفرّع بناءً على الرمز لا على نص الرسالة — فالرسائل قد تتغير وهي بالإنجليزية فقط.

أين يوجد الرمز

أخطاء المؤسسة متسقة: مشكلات المصادقة تضع الرمز في data.code، بينما تضعه مشكلات الخدمة والفوترة في errorCode على المستوى الأعلى. أما الأخطاء الشخصية فتتباين حسب نقطة النهاية (errorCode على المستوى الأعلى، أو data.code، أو errors.code) — اقرأ الحقل المُشار إليه لكل رمز.

رموز حالة HTTP

الحالةالمعنى
200نجاح — أُعيدت النتيجة ضمن الاستجابة.
202مقبول — أُنشئت مهمة غير متزامنة؛ استطلع أو انتظر webhook.
400طلب خاطئ — input غير صالح، أو نقطة النهاية خاطئة لوضع تنفيذ الخدمة.
401غير مصرّح — مفتاح API مفقود أو مشوّه أو من نوع خاطئ.
402الدفع مطلوب — أرصدة غير كافية.
403ممنوع — قد لا يُسمح لهذا المفتاح أو الحساب باستخدام هذه الخدمة.
404غير موجود — مهمة مجهولة، أو مهمة ليست ملكك.
429طلبات كثيرة جدًا — تم تجاوز حد المعدل أو التزامن.
500خطأ في الخادم — أعد المحاولة؛ ويُسترد رصيد المهمة (إن وُجدت).

رموز الأخطاء الشائعة

الرمزالموقعالمعنى
INSUFFICIENT_CREDITSerrorCodeأرصدة شخصية غير كافية للمهمة.
INSUFFICIENT_ORG_CREDITSerrorCodeأرصدة مؤسسة غير كافية للمهمة.
ORG_API_KEY_REQUIREDdata.codeتتطلب نقطة النهاية هذه مفتاح API مؤسسيًا (X-API-Key).
INVALID_ORG_API_KEYdata.codeالمفتاح المؤسسي مفقود أو مشوّه أو مُلغى.
INVALID_API_KEYdata.codeتنسيق مفتاح API غير صالح — غالبًا مسار شخصي استُدعي بمفتاح مؤسسي (أو العكس).
API_SERVICE_NOT_ALLOWEDerrorCodeمؤسستك غير معتمدة لهذه الخدمة.
ORG_DISABLEDdata.codeحساب المؤسسة معطّل.
CONCURRENCY_LIMIT_EXCEEDEDerrorCodeعدد كبير جدًا من المهام المتزامنة لمؤسستك.
SERVICE_NOT_EXTERNALLY_ACCESSIBLEerrorCodeهذه الخدمة غير متاحة عبر API الخارجي.
TASK_NOT_FOUNDerrorCodeلا توجد مثل هذه المهمة لهذا المفتاح.
json
{
  "success": false,
  "errorCode": "INSUFFICIENT_ORG_CREDITS",
  "message": "Insufficient organization credits",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

توثيق API

تفاصيل ملموسة للطلب والاستجابة لكل خدمة. تعرض الأمثلة نوعَي المفاتيح — اختر التبويب الخاص بالمفتاح الذي لديك. وللاطلاع على المفاهيم التي تعتمد عليها (الاستطلاع، والحالات، والأخطاء، والفوترة)، راجع الأدلة أعلاه.

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

الخدمتان أدناه موثّقتان بالكامل. وللحصول على القائمة الكاملة والحيّة للخدمات التي يمكن لمفتاحك استدعاؤها — ومواصفات معاملات كل خدمة — استعلم من نقاط نهاية الفهرس. وهذا هو المصدر الموثوق، لأن التوفر يعتمد على خطتك واعتمادات مؤسستك.

نقطة النهايةالوصف
GET /ai/servicesاعرض الخدمات التي يمكن لمفتاحك الوصول إليها.
GET /ai/external/services/{code}/specاجلب مواصفات معاملات خدمة واحدة.
bash
curl https://api.vberai.com/api/ai/services \
  -H "X-API-Key: YOUR_API_KEY"