واجهة برمجة تطبيقات توليد فيديوهات Sora - تعليمات الدمج

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

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

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

لاستخدام واجهة برمجة تطبيقات توليد فيديوهات Sora، يجب أولاً الذهاب إلى لوحة تحكم Ace Data Cloud للحصول على رمز API الخاص بك، للاحتفاظ به كنسخة احتياطية.

إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، سيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء سيتم العودة تلقائيًا إلى الصفحة الحالية. يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة. ستمنحك أول عملية تقديم رصيدًا مجانيًا لتجربته؛ وعند نفاد الرصيد يمكنك إعادة شحن الرصيد العام في لوحة التحكم.

📘 الوثائق الكاملة: واجهة برمجة تطبيقات توليد فيديوهات Sora →

الاستخدام الأساسي (النسخة 1)

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

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:

accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
authorization: مفتاح استدعاء API، يمكن اختياره مباشرة بعد التقديم.

بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:

model: نموذج توليد الفيديو، يدعم sora-2 (الوضع القياسي) و sora-2-pro (الوضع عالي الدقة). حيث يمكن لـ sora-2-pro دعم duration لفيديو مدته 25 ثانية، بينما يدعم sora-2 فقط 10 و15 ثانية.
size: دقة الفيديو، small تعني دقة قياسية، و large تعني دقة HD (فقط في النسخة 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: عنوان URL لاسترجاع النتائج بشكل غير متزامن.
async: اختياري، إذا تم تعيينه إلى true، ستعيد الواجهة على الفور task_id، دون الحاجة لتقديم callback_url، ثم يمكن استعلام النتائج من خلال واجهة استعلام المهام المقابلة.
version: إصدار API، "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://platform.cdn.acedata.cloud/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"
}'

مهمة توليد الفيديو من الصور (النسخة 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": "قط يجري على النهر",
    "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://platform.cdn.acedata.cloud/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": "قط يجري على النهر",
    "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://platform.cdn.acedata.cloud/20251101/bee4eeeb4c4660b46dac4548a1ffbc.mp4",
      "state": "succeeded"
    }
  ]
}

يمكنك أن ترى أن التأثير الناتج هو فيديو تم إنشاؤه للشخصية، والنتيجة مشابهة لما سبق.

وضع الإصدار 2.0

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

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

المعلمة	النوع	إلزامية	الشرح
`version`	string	نعم	تعيينها إلى `"2.0"`
`prompt`	string	نعم	كلمة المرور لإنشاء الفيديو
`model`	string	لا	`sora-2` (افتراضي) أو `sora-2-pro`
`duration`	integer	لا	مدة الفيديو: `4` (افتراضي)، `8`، `12` ثانية
`size`	string	لا	الدقة: `720x1280` (افتراضي)، `1280x720`، `1024x1792`، `1792x1024`
`image_urls`	array	لا	مصفوفة URL للصور المرجعية، يتم استخدام الصورة الأولى فقط، يجب أن تتطابق أبعاد الصورة مع معلمة `size`
`callback_url`	string	لا	URL للرد غير المتزامن

مثال أساسي

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": "قط يجري على النهر",
  "model": "sora-2",
  "duration": 8,
  "size": "1280x720"
}'

الكود المقابل بلغة بايثون:

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": "قط يجري على النهر",
    "model": "sora-2",
    "seconds": 8,
    "size": "1280x720"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

الكود المقابل بلغة جافا سكريبت:

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: 'قط يجري على النهر',
    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": "شخص يمشي في حديقة جميلة",
    "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
`version`	1.0 (افتراضي)	2.0
`prompt`	✅	✅
`model`	✅ sora-2 / sora-2-pro	✅ sora-2 / sora-2-pro
`duration`	✅ 10/15/25 ثانية	✅ 4/8/12 ثانية
`orientation`	✅ أفقي/عمودي	❌
`size`	✅ صغير/كبير	✅ 720x1280/1280x720/1024x1792/1792x1024
`image_urls`	✅ صور مرجعية متعددة	✅ استخدام الصورة الأولى فقط
`character_url`	✅	❌
`callback_url`	✅	✅

ردود الفعل غير المتزامنة

نظرًا لأن واجهة برمجة تطبيقات Sora Videos Generation تستغرق وقتًا طويلاً نسبيًا للتوليد، حوالي 1-2 دقيقة، إذا لم تستجب واجهة برمجة التطبيقات لفترة طويلة، ستظل طلبات HTTP متصلة، مما يؤدي إلى استهلاك موارد النظام الإضافية، لذا توفر هذه الواجهة أيضًا دعمًا للردود غير المتزامنة. تتمثل العملية العامة في: عندما يقوم العميل بإرسال الطلب، يحدد حقل callback_url إضافي، بعد أن يقوم العميل بإرسال طلب واجهة برمجة التطبيقات، ستعيد الواجهة على الفور نتيجة تحتوي على معلومات حقل 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، كما هو موضح في الصورة:

المحتوى كما يلي:

{
    "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://platform.cdn.acedata.cloud/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": "فشل في الاسترجاع"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

الخاتمة

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

البداية

دردشة الذكاء الاصطناعي

صورة الذكاء الاصطناعي

فيديو الذكاء الاصطناعي

الصوت الذكي

الويب والبيانات

CAPTCHA

الهوية

وكيل

متقدم

Coding

واجهة برمجة تطبيقات توليد فيديوهات Sora - تعليمات الدمج

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

الاستخدام الأساسي (النسخة 1)

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

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

وضع الإصدار 2.0

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

مثال أساسي

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

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

ردود الفعل غير المتزامنة

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

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

الخاتمة

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

​الاستخدام الأساسي (النسخة 1)

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

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

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

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

​مثال أساسي

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

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

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

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

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

​الخاتمة

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

الاستخدام الأساسي (النسخة 1)

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

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

وضع الإصدار 2.0

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

مثال أساسي

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

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

ردود الفعل غير المتزامنة

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

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

الخاتمة