واجهة برمجة تطبيقات Sora 2 Pro

دمج واجهة برمجة تطبيقات Sora 2 Pro

أنشئ سير عمل تحويل النص إلى فيديو، والصورة إلى فيديو، ولوحة القصة مع استطلاع متوقع والتحكم في الرصيد.

ما تقدمه واجهة برمجة تطبيقات Sora 2 Pro

كل ما تحتاجه لإطلاق خطوط إنتاج Sora 2 Pro الجاهزة للإنتاج.

خمسة متغيرات للنماذج

اختر sora-2 نص/صورة أو sora-2-pro نص/صورة/لوحة قصة بناءً على الجودة والتكلفة.

دعم لوحة القصة

حدد سرديات متعددة اللقطات باستخدام shots[] ومدد لكل لقطة.

استجابات موحدة

جميع نقاط النهاية تُرجع code/message/data، حتى عندما تكون حالة HTTP هي 200 عند الأخطاء.

المصادقة وعنوان URL الأساسي

عنوان URL الأساسي: https://freesoragenerator.com. قم بالمصادقة باستخدام مفتاح API أو ملف تعريف ارتباط جلسة مسجل الدخول.

  • Authorization: Bearer [TOKEN] (مفتاح API sk- أو JWT)، أو أرسل ملف تعريف ارتباط الجلسة.
  • أرسل Content-Type: application/json مع أجسام POST.
  • معظم الأخطاء لا تزال تُرجع HTTP 200؛ تحقق دائمًا من حقل code.

نقاط النهاية الأساسية

أنشئ المهام باستخدام /sora-pro، ثم استطلع check-result للحالة.

إنشاء مهمة توليد

التحقق من صحة الإدخال، وخصم الرصيد، وإنشاء مهمة، وإرجاع taskId.

الطريقة: POSTالمسار: /api/v1/video/sora-pro

معلمات الحمولة

  • مطلوب. واحد من sora-2-text-to-video، sora-2-image-to-video، sora-2-pro-text-to-video، sora-2-pro-image-to-video، sora-2-pro-storyboard.
  • شرطي. مطلوب لجميع النماذج باستثناء sora-2-pro-storyboard.
  • شرطي. عنوان URL لبيانات Base64 مثل data:image/png;base64,... مطلوب لتحويل الصورة إلى فيديو إذا لم يكن هناك imageUrl.
  • شرطي. عنوان URL للصورة العامة يُستخدم عندما لا يتم توفير imageData.
  • اختياري. portrait أو landscape. الافتراضي: landscape.
  • اختياري. 10 أو 15 أو 25 (لوحة القصة فقط). تختلف الافتراضيات حسب النموذج.
  • اختياري. standard أو high. فقط لنماذج Pro نص/صورة.
  • اختياري. إزالة العلامة المائية للنماذج غير لوحة القصة. الافتراضي: true.
  • شرطي. مطلوب لـ sora-2-pro-storyboard. مصفوفة من '{ Scene, duration }'.

ملاحظات

  • imageData له الأولوية على imageUrl عند توفير كليهما.
  • prompt اختياري للوحة القصة ولا يُرسل إلى المزود؛ استخدم shots للمحتوى.
  • يتم تطبيع nFrames إلى القيم المسموح بها لكل نموذج.
  • removeWatermark افتراضيًا true للنماذج غير لوحة القصة.
  • يجب أن تتضمن shots حقل Scene (بحرف S كبير) ومدة > 0.

طلبات نموذجية

تحويل النص إلى فيديو
curl -X POST https://freesoragenerator.com/api/v1/video/sora-pro \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2-pro-text-to-video",
    "prompt": "A cinematic shot of a futuristic city at sunset.",
    "aspectRatio": "landscape",
    "nFrames": "10",
    "size": "high",
    "removeWatermark": true
  }'
تحويل الصورة إلى فيديو
curl -X POST https://freesoragenerator.com/api/v1/video/sora-pro \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2-image-to-video",
    "prompt": "Turn this image into a dynamic 10s clip.",
    "imageUrl": "https://example.com/reference.png",
    "aspectRatio": "portrait",
    "nFrames": "10"
  }'
لوحة القصة
curl -X POST https://freesoragenerator.com/api/v1/video/sora-pro \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sora-2-pro-storyboard",
    "shots": [
      { "Scene": "Establishing shot of a city skyline at dusk", "duration": 5 },
      { "Scene": "Close-up of a runner splashing through puddles", "duration": 5 }
    ],
    "aspectRatio": "landscape",
    "nFrames": "10"
  }'

استجابة نموذجية

{
  "code": 0,
  "message": "ok",
  "data": {
    "taskId": "281e5b0*********************f39b9"
  }
}

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

جلب الحالة والتقدم وعناوين URL للنتائج بواسطة taskId.

الطريقة: POSTالمسار: /api/video-generations/check-result

معلمات الحمولة

  • مطلوب. taskId المُرجع من الإنشاء.

ملاحظات

  • قيم الحالة: pending | running | succeeded | failed | cancelled.
  • result_url و result_urls تُرجع روابط الفيديو النهائية عند الجاهزية.

طلب نموذجي

curl -X POST https://freesoragenerator.com/api/video-generations/check-result \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "281e5b0*********************f39b9"
  }'

استجابة نموذجية

{
  "code": 0,
  "message": "Success",
  "data": {
    "status": "running",
    "progress": 35,
    "result_url": "https://your-domain.com/storage/videos/xxx.mp4",
    "result_urls": [
      "https://your-domain.com/storage/videos/xxx.mp4"
    ],
    "failure_reason": "",
    "error_message": null
  }
}

الحصول على رصيد المستخدم

تحقق من رصيد الرصيد الحالي قبل إرسال المهام.

الطريقة: POSTالمسار: /api/get-user-credits

ملاحظات

  • نقطة نهاية اختيارية؛ مفيدة للتحقق المسبق.
  • تُرجع left_credits وعلامات is_vip.

طلب نموذجي

curl -X POST https://freesoragenerator.com/api/get-user-credits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

استجابة نموذجية

{
  "code": 0,
  "message": "ok",
  "data": {
    "left_credits": 120,
    "is_vip": false
  }
}

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

يتم عرض الأخطاء من خلال حقل code في جسم الاستجابة.

  • 401: غير مصرح
  • 402: رصيد غير كافٍ
  • -1: معلمة نموذج غير صالحة
  • -1: النص المطلوب مطلوب
  • -1: الصورة مطلوبة لتحويل الصورة إلى فيديو
  • -1: اللقطات مطلوبة للوحة القصة
  • -1: فشل في رفع الصورة
  • -1: فشل في إنشاء سجل توليد الفيديو

مرجع الرصيد

يختلف الرصيد حسب النموذج والحجم وnFrames. استخدم هذا الجدول كأساس.

النموذجالمعلماتالرصيد
sora-2-text-to-video1020
sora-2-text-to-video1530
sora-2-image-to-video1020
sora-2-image-to-video1530
sora-2-pro-text-to-videostandard + 10375
sora-2-pro-text-to-videostandard + 15675
sora-2-pro-text-to-videohigh + 10825
sora-2-pro-text-to-videohigh + 151,575
sora-2-pro-image-to-videostandard + 10375
sora-2-pro-image-to-videostandard + 15675
sora-2-pro-image-to-videohigh + 10825
sora-2-pro-image-to-videohigh + 151,575
sora-2-pro-storyboard10375
sora-2-pro-storyboard15675
sora-2-pro-storyboard25675

1. إنشاء المهمة

POST /api/v1/video/sora-pro مع النموذج والحمولة الخاصة بك.

2. تتبع التقدم

استطلع /api/video-generations/check-result حتى تصبح الحالة succeeded أو failed.

3. التحقق من الرصيد

اختياريًا استدعِ /api/get-user-credits قبل إرسال دفعات كبيرة.

الأسئلة الشائعة

هل يمكنني استخدام مفاتيح API أو ملفات تعريف ارتباط الجلسة؟

نعم. أرسل Authorization: Bearer [TOKEN] (مفتاح API أو JWT) أو ملف تعريف ارتباط جلسة مسجل الدخول.

كيف أقوم بتنسيق لقطات لوحة القصة؟

قدم shots كمصفوفة من '{ Scene, duration }' حيث Scene بحرف كبير والمدة بالثواني.

لماذا يختلف الرصيد حسب النموذج؟

يتناسب الرصيد مع nFrames لجميع النماذج؛ نماذج Pro تختلف أيضًا حسب الحجم.

موارد مفيدة

ابدأ مع واجهة برمجة تطبيقات Sora 2 Pro

أنشئ مفتاح API وأطلق أول سير عمل Sora 2 Pro الخاص بك اليوم.