الانتقال إلى المحتوى الرئيسي
ستقدم هذه الوثيقة تعليمات دمج واجهة برمجة تطبيقات توليد فيديوهات Sora، والتي يمكن استخدامها لتوليد فيديوهات رسمية من Sora من خلال إدخال معلمات مخصصة.

​
عملية التقديم

لاستخدام واجهة برمجة التطبيقات، يجب أولاً زيارة صفحة واجهة برمجة تطبيقات توليد فيديوهات Sora لتقديم طلب الخدمة المناسبة، بعد دخول الصفحة، انقر على زر “Acquire”، كما هو موضح في الصورة: إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، بعد تسجيل الدخول أو التسجيل، سيتم العودة تلقائيًا إلى الصفحة الحالية. عند التقديم لأول مرة، سيكون هناك حد مجاني متاح، يمكنك استخدام واجهة برمجة التطبيقات مجانًا.

​
الاستخدام الأساسي

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال كلمة التلميح prompt، ومصفوفة روابط الصور المرجعية image_urls، والنموذج model، للحصول على النتائج المعالجة، المحتوى المحدد كما يلي:

يمكنك أن ترى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح واجهة برمجة التطبيقات، يمكنك اختياره مباشرة بعد التقديم.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • model: نموذج توليد الفيديو، والذي يتضمن بشكل رئيسي sora-2 و sora-2-pro، حاليًا يمكن اختيار size و duration للفيديوهات من sora-2 و sora-2-pro، حيث يدعم sora-2-pro مدة الفيديو 25 ثانية، بينما يدعم sora-2 فقط 10 و 15 ثانية.
  • size: دقة مهمة توليد الفيديو، والتي تشمل small و large.
  • image_urls: روابط الصور المرجعية التي تحتاج إلى تحميلها أو مصفوفة الترميز Base64.
  • duration: مدة مهمة توليد الفيديو، والتي تشمل 10 ثوانٍ، 15 ثانية، و 25 ثانية، حاليًا فقط sora-2-pro يدعم 25 ثانية.
  • character_start/character_end: موقع الشخصية في الصورة (0-1)، للتحكم في موقع الموضوع.
  • orientation: اتجاه الصورة، يدعم landscape و portrait و square.
  • prompt: كلمة التلميح.
  • callback_url: URL الذي يحتاج إلى استدعاء النتائج.
بعد الاختيار، يمكنك أن ترى أن الكود المقابل تم إنشاؤه على الجانب الأيمن، كما هو موضح في الصورة:

انقر على زر “Try” لإجراء اختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية: 
{
  "success": true,
  "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33",
  "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01",
  "data": [
    {
      "id": "sora-2:task_01k7770rgsevxsmtpbn7xnm5gh",
      "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k7770rgsevxsmtpbn7xnm5gh%2Ftask_01k7770rgsevxsmtpbn7xnm5gh_genid_0bf958d3-cae7-4298-b7b6-99ae439a1ea6_25_10_10_14_06_975715%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A30%3A38Z&se=2025-10-16T13%3A30%3A38Z&sks=b&skt=2025-10-10T12%3A30%3A38Z&ske=2025-10-16T13%3A30%3A38Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=8ebb0df1-a278-4e2e-9c20-f2d373479b3a&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=jigY6Z5qp8%2BTXYobaW0EAJ4%2Fbx6G7t6V1P0iyDeUq48%3D&az=oaivgprodscus",
      "state": "succeeded"
    }
  ]
}
تتضمن النتيجة العائدة عدة حقول، كما يلي:
  • success: حالة مهمة توليد الفيديو في ذلك الوقت.
  • task_id: معرف مهمة توليد الفيديو في ذلك الوقت.
  • trace_id: معرف تتبع توليد الفيديو في ذلك الوقت.
  • data: قائمة نتائج مهمة توليد الفيديو في ذلك الوقت.
    • id: معرف الفيديو لمهمة توليد الفيديو في ذلك الوقت.
    • video_url: رابط الفيديو لمهمة توليد الفيديو في ذلك الوقت.
    • state: حالة مهمة توليد الفيديو في ذلك الوقت.
يمكنك أن ترى أننا حصلنا على معلومات الفيديو المرضية، كل ما علينا هو الحصول على الفيديو الناتج من رابط الفيديو في data. بالإضافة إلى ذلك، إذا كنت ترغب في توليد الكود المقابل، يمكنك نسخه مباشرة، مثل كود CURL كما يلي: 
curl -X POST 'https://api.acedata.cloud/sora/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "size": "large",
  "duration": 15,
  "orientation": "landscape",
  "prompt": "cat running on the river",
  "model": "sora-2"
}'

​
مهمة توليد الفيديو من الصور

إذا كنت ترغب في توليد فيديو من الصور، يجب أولاً تمرير معلمة image_urls مع روابط الصور المرجعية، يمكنك تحديد المحتوى كما يلي:
  • image_urls: مصفوفة روابط الصور المرجعية المستخدمة في مهمة توليد الفيديو.
مثال على كيفية ملء البيانات كما يلي:

بعد ملء البيانات، تم إنشاء الكود تلقائيًا كما يلي:

الكود المقابل: 
import requests

url = "https://api.acedata.cloud/sora/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "size": "large",
    "duration": 15,
    "orientation": "landscape",
    "prompt": "cat running on the river",
    "model": "sora-2",
    "image_urls": ["https://cdn.acedata.cloud/11wfp4.png"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
عند النقر على التشغيل، يمكنك أن ترى أنه سيتم الحصول على نتيجة على الفور، كما يلي: 
{
  "success": true,
  "task_id": "dd392ff0-dcb7-4c7a-afd0-9bd4f65c803a",
  "trace_id": "04fd151c-e942-4c1c-a6ab-9a1b1fe54172",
  "data": [
    {
      "id": "sora-2:task_01k777af4hfmg9g7yfvwsc6zws",
      "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777af4hfmg9g7yfvwsc6zws%2Ftask_01k777af4hfmg9g7yfvwsc6zws_genid_92bae0c5-1703-4a5f-9d9f-c9ed2f9e7176_25_10_10_14_12_924695%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A37%3A32Z&se=2025-10-16T13%3A37%3A32Z&sks=b&skt=2025-10-10T12%3A37%3A32Z&ske=2025-10-16T13%3A37%3A32Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=5j4dibeaSsDmEka5c%2B9CKHZhRPdqfClQ0tIh03TWXsM%3D&az=oaivgprodscus",
      "state": "succeeded"
    }
  ]
}
يمكن رؤية أن النتيجة الناتجة هي فيديو تم إنشاؤه بواسطة صورة، والنتيجة مشابهة لما سبق.

​
مهمة إنشاء فيديو شخصية

إذا كنت ترغب في إنشاء فيديو شخصية، يجب أولاً تمرير معلمة character_url مع رابط الفيديو المطلوب لإنشاء الشخصية، مع ملاحظة أنه يجب ألا يظهر أي شخص حقيقي في الفيديو، وإلا ستفشل العملية، يمكنك تحديد المحتوى كما يلي:
  • character_url: رابط الفيديو المطلوب لإنشاء الشخصية، مع ملاحظة أنه يجب ألا يظهر أي شخص حقيقي في الفيديو، وإلا ستفشل العملية.
مثال على كيفية التعبئة:

بعد الانتهاء من التعبئة، تم إنشاء الكود تلقائيًا كما يلي:

الكود المقابل: 
import requests

url = "https://api.acedata.cloud/sora/videos"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "size": "small",
    "duration": 10,
    "orientation": "landscape",
    "prompt": "cat running on the river",
    "character_url": "https://cdn.acedata.cloud/pdidf5.mp4",
    "model": "sora-2",
    "character_end": 3,
    "character_start": 1
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
عند الضغط على التشغيل، يمكنك أن ترى أنه سيتم الحصول على نتيجة على الفور، كما يلي: 
{
  "success": true,
  "task_id": "d9bf5461-29b5-47fd-be90-1fe9197df259",
  "trace_id": "b7992643-9207-40d6-956b-7577728acc67",
  "data": [
    {
      "id": "sora-2:task_01k8ykrztefavaypw6xanw305b",
      "video_url": "https://filesystem.site/cdn/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4",
      "state": "succeeded"
    }
  ]
}
يمكن رؤية أن النتيجة الناتجة هي فيديو تم إنشاؤه بواسطة شخصية، والنتيجة مشابهة لما سبق.

​
ردود غير متزامنة

نظرًا لأن وقت إنشاء فيديوهات Sora قد يكون طويلًا نسبيًا، حوالي 1-2 دقيقة، إذا لم يستجب API لفترة طويلة، ستظل طلبات HTTP متصلة، مما يؤدي إلى استهلاك موارد النظام الإضافية، لذا فإن هذا API يوفر أيضًا دعمًا للردود غير المتزامنة. العملية العامة هي: عندما يقوم العميل بإرسال الطلب، يجب تحديد حقل callback_url إضافي، بعد أن يقوم العميل بإرسال طلب API، سيقوم API على الفور بإرجاع نتيجة تحتوي على معلومات حقل task_id، والتي تمثل معرف المهمة الحالية. عند الانتهاء من المهمة، سيتم إرسال نتيجة الفيديو المولد إلى callback_url المحدد من قبل العميل على شكل POST JSON، والتي تتضمن أيضًا حقل task_id، بحيث يمكن ربط نتيجة المهمة بواسطة المعرف. دعونا نفهم كيفية القيام بذلك من خلال مثال. أولاً، ردود Webhook هي خدمة يمكنها استقبال طلبات HTTP، يجب على المطورين استبدالها بعنوان URL الخاص بخادم HTTP الذي قاموا بإنشائه. هنا، لتسهيل العرض، نستخدم موقع Webhook عام https://webhook.site/، عند فتح هذا الموقع، ستحصل على عنوان URL لـ Webhook، كما هو موضح في الصورة: قم بنسخ هذا العنوان URL، يمكنك استخدامه كـ Webhook، والعينة هنا هي https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa. بعد ذلك، يمكننا تعيين الحقل callback_url إلى عنوان URL الخاص بـ Webhook المذكور أعلاه، مع ملء المعلمات المناسبة، كما هو موضح في الصورة:

عند الضغط على التشغيل، يمكنك أن ترى أنه سيتم الحصول على نتيجة على الفور، كما يلي: 
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
بعد لحظات، يمكننا ملاحظة نتيجة إنشاء الأغنية على https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa، كما هو موضح في الصورة: المحتوى كما يلي: 
```json
{
    "success": true,
    "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea",
    "trace_id": "fb751e1e-4705-49ea-9fd4-5024b7865ea2",
    "data": [
        {
            "id": "sora-2:task_01k777hjrbfrgs2060q5zvf2a5",
            "video_url": "https://filesystem.site/gptimage/vg-assets/assets%2Ftask_01k777hjrbfrgs2060q5zvf2a5%2Ftask_01k777hjrbfrgs2060q5zvf2a5_genid_b8e2e5d1-a579-49ca-a21c-cb3869685cce_25_10_10_14_15_147334%2Fvideos%2F00000%2Fsrc.mp4?st=2025-10-10T12%3A38%3A49Z&se=2025-10-16T13%3A38%3A49Z&sks=b&skt=2025-10-10T12%3A38%3A49Z&ske=2025-10-16T13%3A38%3A49Z&sktid=a48cca56-e6da-484e-a814-9c849652bcb3&skoid=aa5ddad1-c91a-4f0a-9aca-e20682cc8969&skv=2019-02-02&sv=2018-11-09&sr=b&sp=r&spr=https%2Chttp&sig=p4aMqXqkP%2FI1IhOVGCB9JL8vUUvfNBBF12ESpKhKXOk%3D&az=oaivgprodscus",
            "state": "succeeded"
        }
    ]
}
يمكنك رؤية أن هناك حقل task_id في النتيجة، بينما الحقول الأخرى مشابهة لما سبق، من خلال هذا الحقل يمكنك ربط المهام.

​
معالجة الأخطاء

عند استدعاء واجهة برمجة التطبيقات، إذا واجهت خطأ، ستقوم واجهة برمجة التطبيقات بإرجاع رمز الخطأ والمعلومات ذات الصلة. على سبيل المثال:
  • 400 token_mismatched : طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 400 api_not_implemented : طلب غير صحيح، ربما بسبب معلمات مفقودة أو غير صالحة.
  • 401 invalid_token : غير مصرح، رمز تفويض غير صالح أو مفقود.
  • 429 too_many_requests : عدد كبير جداً من الطلبات، لقد تجاوزت الحد المسموح به.
  • 500 api_error : خطأ في الخادم الداخلي، حدث خطأ ما في الخادم.

​
مثال على استجابة الخطأ

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

​
الخاتمة

من خلال هذه الوثيقة، لقد فهمت كيفية استخدام واجهة برمجة تطبيقات Sora Videos Generation التي يمكن من خلالها إدخال كلمات تحفيزية وصور مرجعية لإنشاء فيديو. نأمل أن تساعدك هذه الوثيقة في التوصيل والاستخدام الأفضل لهذه الواجهة. إذا كان لديك أي استفسارات، فلا تتردد في الاتصال بفريق الدعم الفني لدينا.