واجهة قوالب FreeRap

المصادقة

أرسل ترويسة Authorization إلى واجهتي المهام باستخدام مفتاح sk_ الكامل من الإعدادات ← API. يعاد HTTP 401 عند غياب المفتاح أو عدم صلاحيته. لا تكشف المفتاح في كود المتصفح.

Authorization: Bearer <API_KEY>

قواعد الواجهة

يوفر القالب النص والفيديو المرجعي والموسيقى. يرسل العميل الصورة المرجعية وإعدادات التوليد. لا تُدعم عناوين الاستدعاء الراجع؛ استعلم عن المهمة للحصول على النتيجة.

تعيد الطلبات الناجحة HTTP 200 وcode 0 وmessage ok وكائن data. تعيد أخطاء الطلب code -1 وmessage. قد يشير data.status إلى فشل التوليد رغم نجاح الاستعلام.

إنشاء مهمة

يبدأ توليد فيديو غير متزامن لقالب نشط. يؤكد HTTP 200 إنشاء المهمة، ويكون الفيديو قيد المعالجة.

الترويسات المطلوبة: Authorization: Bearer <API_KEY> وContent-Type: application/json.

معاملات المسار

جسم الطلب

تستخدم التكاملات الجديدة reference_image_urls وmodel وresolution. الحقول التالية مشتركة بين جميع القوالب.

رد ناجح

القيم للتوضيح فقط. مبلغ 30 رصيدًا ليس سعرًا ثابتًا؛ اعتمد على السعر الذي يعيده طلبك.

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "credits_estimate": 30,
    "credits_charged": 30
  }
}

curl --request POST \
  'https://freerapvideo.com/api/v1/templates/YOUR_TEMPLATE_SLUG/generations' \
  --header "Authorization: Bearer $FREERAP_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "reference_image_urls": ["https://cdn.example.com/image-1.jpg", "https://cdn.example.com/image-2.jpg", "https://cdn.example.com/image-3.jpg"],
    "model": "pro",
    "resolution": "720p"
  }'

الاستعلام عن مهمة

يعيد حالة مهمة أُنشئت عبر API وتخص مستخدم المفتاح. لا يوجد جسم للطلب. استخدم مفتاح الإنشاء أو مفتاحًا صالحًا آخر للمستخدم نفسه.

رد ناجح

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "success",
    "campaign": "bulin",
    "costCredits": 30,
    "credits_estimate": 30,
    "credits_charged": 30,
    "createdAt": "2026-10-31T00:00:00.000Z",
    "videos": [
      "https://media.example.com/generated/video.mp4"
    ]
  }
}

حالات المهمة

استعلم كل 30 ثانية تقريبًا وتوقف عند الحالة النهائية. انتهاء مهلة الاستعلام لا يعني فشل التوليد؛ استعلم عن المهمة نفسها مجددًا.

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "failed",
    "campaign": "bulin",
    "costCredits": 0,
    "credits_estimate": 30,
    "credits_charged": 0,
    "createdAt": "2026-10-31T00:00:00.000Z",
    "videos": [],
    "error": "Video generation failed."
  }
}

الأخطاء

تستخدم أخطاء الطلب حالة HTTP خارج 2xx والجسم التالي. تكون code دائمًا -1؛ ميّز الفئات بحالة HTTP. message نص توضيحي وليس معرّف خطأ ثابتًا للبرامج.

{
  "code": -1,
  "message": "Insufficient credits."
}

الأرصدة والحدود

تُحجز الأرصدة عند الإنشاء. أثناء pending أوprocessing تساوي credits_charged قيمة credits_estimate. عند النجاح يُحتفظ بالمبلغ. عند الفشل أو الإلغاء يُرد الحجز بعد خصم رسوم الفشل إن ضُبطت، وافتراضيًا هي 0. تعرض credits_charged في الحالة النهائية المبلغ المحتفظ به.

يسمح كل مفتاح بما يصل إلى 30 مهمة pending أوprocessing. على كل نسخة خادم، الحد هو طلب إنشاء واحد وخمسة استعلامات في الثانية لكل مفتاح. قد يتضمن HTTP 429 ترويسة Retry-After بالثواني؛ إن غابت، انتظر قبل إعادة المحاولة.