الانتقال إلى المحتوى الرئيسي
تقدم هذه الوثيقة شرحًا لكيفية تكامل واجهة برمجة تطبيقات توليد فيديوهات Sora، والتي تتيح إدخال معلمات مخصصة لتوليد فيديوهات رسمية من Sora. تدعم هذه الواجهة نوعين من الأوضاع:
  • الإصدار 1 (الوضع الكلاسيكي): يدعم معلمات مثل duration (10/15/25 ثانية)، orientation (وضع أفقي/عمودي)، size (وضوح صغير/كبير)، صور مرجعية image_urls، ورابط الشخصية character_url وغيرها.
  • الإصدار 2 (وضع الشركاء): يدعم معلمات مثل seconds (4/8/12 ثانية)، دقة بكسلية size (مثل 1280x720)، صور مرجعية input_reference وغيرها.

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

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

​
الاستخدام الأساسي (الإصدار 1)

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

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

اضغط على زر “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: حالة المهمة.
يمكنك الحصول على فيديو Sora الناتج من خلال رابط الفيديو في 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"
}'

​
مهمة توليد فيديو من صورة (الإصدار 1)

لإجراء مهمة توليد فيديو من صورة، يجب تمرير معلمة 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"
    }
  ]
}
يمكن ملاحظة أن النتيجة تم توليدها باستخدام الصورة المرجعية، والنتيجة مشابهة لما سبق.

​
مهمة توليد فيديو من شخصية (الإصدار 1)

لإجراء مهمة توليد فيديو من شخصية، يجب تمرير معلمة 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"
    }
  ]
}
يمكن ملاحظة أن النتيجة تم توليدها باستخدام شخصية، والنتيجة مشابهة لما سبق.

​
وضع الإصدار 2.0

بالإضافة إلى وضع الإصدار 1.0، تدعم الواجهة أيضًا وضع الإصدار 2.0 من خلال تعيين معلمة version إلى "2.0". يدعم الإصدار 2.0 مدة فيديو أقصر وتحكمًا دقيقًا في الدقة البكسلية.

​
شرح معلمات الإصدار 2.0

المعلمةالنوعإلزاميالوصف
versionstringنعمتعيين إلى "2.0"
promptstringنعمكلمة مفتاحية لتوليد الفيديو
modelstringلاsora-2 (افتراضي) أو sora-2-pro
durationintegerلامدة الفيديو: 4 (افتراضي)، 8، 12 ثانية
sizestringلاالدقة: 720x1280 (افتراضي)، 1280x720، 1024x1792، 1792x1024
image_urlsarrayلامصفوفة روابط الصور المرجعية، تستخدم الصورة الأولى فقط، يجب أن تتطابق أبعاد الصورة مع معلمة size
callback_urlstringلارابط رد الاتصال غير المتزامن

​
مثال أساسي

curl -X POST 'https://api.acedata.cloud/sora/videos' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "version": "2.0",
  "prompt": "cat running on the river",
  "model": "sora-2",
  "duration": 8,
  "size": "1280x720"
}'
كود Python المقابل: 
import requests

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

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

payload = {
    "version": "2.0",
    "prompt": "cat running on the river",
    "model": "sora-2",
    "seconds": 8,
    "size": "1280x720"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
كود JavaScript المقابل: 
const response = await fetch('https://api.acedata.cloud/sora/videos', {
  method: 'POST',
  headers: {
    'accept': 'application/json',
    'authorization': 'Bearer {token}',
    'content-type': 'application/json'
  },
  body: JSON.stringify({
    version: '2.0',
    prompt: 'cat running on the river',
    model: 'sora-2',
    seconds: 8,
    size: '1280x720'
  })
});
const data = await response.json();
console.log(data);
تنسيق النتيجة مماثل للإصدار 1: 
{
  "success": true,
  "task_id": "6bf7fb83-5814-4e3e-a4ad-bfa0c26c0b33",
  "trace_id": "96166698-4b66-478d-a26b-77a7269c9e01",
  "data": [
    {
      "id": "c0cc8dad-0954-421f-be8d-02eb063b3263",
      "video_url": "https://platform.cdn.acedata.cloud/sora/xxxxx.mp4",
      "state": "succeeded"
    }
  ]
}

​
استخدام الصور المرجعية (الإصدار 2.0)

في وضع الإصدار 2.0، يمكن تمرير معلمة image_urls لإدخال صورة مرجعية لتوجيه توليد الفيديو (تستخدم الصورة الأولى فقط): 
import requests

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

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

payload = {
    "version": "2.0",
    "prompt": "a person walking through a beautiful garden",
    "model": "sora-2",
    "duration": 4,
    "size": "1280x720",
    "image_urls": ["https://cdn.acedata.cloud/11wfp4.png"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
ملاحظة: يجب أن تتطابق أبعاد الصورة المرجعية مع معلمة size، على سبيل المثال إذا كانت size تساوي 1280x720، يجب أن تكون أبعاد الصورة 1280×720.

​
مقارنة معلمات الإصدار 1.0 و 2.0

المعلمةالإصدار 1.0الإصدار 2.0
version1.0 (افتراضي)2.0
prompt✅✅
model✅ sora-2 / sora-2-pro✅ sora-2 / sora-2-pro
duration✅ 10/15/25 ثانية✅ 4/8/12 ثانية
orientation✅ landscape/portrait❌
size✅ small/large✅ 720x1280/1280x720/1024x1792/1792x1024
image_urls✅ عدة صور مرجعية✅ تستخدم الصورة الأولى فقط
character_url✅❌
callback_url✅✅

​
رد الاتصال غير المتزامن (Async Callback)

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

بعد الضغط على تشغيل، ستحصل على نتيجة فورية مثل: 
{
  "task_id": "b8976e18-32dc-4718-9ed8-1ea090fcb6ea"
}
بعد فترة قصيرة، يمكنك مراقبة نتيجة توليد الفيديو على الرابط https://webhook.site/eb238c4f-da3b-47a5-a922-a93aa5405daa كما في الصورة: المحتوى كالتالي: 
{
    "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 لإنشاء فيديوهات عبر إدخال كلمات مفتاحية وصور مرجعية. نأمل أن تساعدك هذه الوثيقة في التكامل والاستخدام الأمثل للواجهة. لأي استفسارات، يرجى التواصل مع فريق الدعم الفني لدينا.