Skip to main content
ستقدم هذه الوثيقة تعليمات دمج واجهة برمجة تطبيقات توليد مقاطع فيديو SeeDance، والتي يمكن من خلالها إدخال معلمات مخصصة لتوليد مقاطع الفيديو الرسمية من SeeDance.

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

لاستخدام واجهة برمجة تطبيقات توليد مقاطع فيديو SeeDance، يجب أولاً الذهاب إلى وحدة التحكم في Ace Data Cloud للحصول على رمز API الخاص بك، احتفظ به للاستخدام لاحقًا. إذا لم تكن قد قمت بتسجيل الدخول أو التسجيل بعد، فسيتم تحويلك تلقائيًا إلى صفحة تسجيل الدخول لدعوتك للتسجيل وتسجيل الدخول، وبعد الانتهاء، سيتم إرجاعك تلقائيًا إلى الصفحة الحالية. يمكن استخدام رمز API واحد لاستدعاء جميع خدمات المنصة، دون الحاجة لتقديم طلب منفصل لكل خدمة. عند التقديم لأول مرة، ستحصل على رصيد مجاني لتجربته؛ وعند نفاد الرصيد، يمكنك إعادة شحن الرصيد العام في وحدة التحكم.
📘 الوثائق الكاملة: واجهة برمجة تطبيقات توليد مقاطع فيديو SeeDance →

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

أولاً، يجب أن نفهم طريقة الاستخدام الأساسية، وهي إدخال كلمة التلميح content.text، النوع content.type=text، والنموذج model، للحصول على النتيجة المعالجة، المحتوى المحدد كما يلي:

يمكننا أن نرى هنا أننا قمنا بتعيين رؤوس الطلب، بما في ذلك:
  • accept: نوع الاستجابة التي ترغب في تلقيها، هنا يتم ملؤها بـ application/json، أي بتنسيق JSON.
  • authorization: مفتاح استدعاء API، يمكن اختياره مباشرة بعد التقديم.
بالإضافة إلى ذلك، تم تعيين جسم الطلب، بما في ذلك:
  • model: نموذج توليد الفيديو.
    • سلسلة Seedance 1.x: doubao-seedance-1-0-pro-250528، doubao-seedance-1-0-pro-fast-251015، doubao-seedance-1-5-pro-251215، doubao-seedance-1-0-lite-t2v-250428، doubao-seedance-1-0-lite-i2v-250428.
    • سلسلة Seedance 2.0 (تدعم المدخلات متعددة الوسائط مثل الوجه / مرجع الشخصية): doubao-seedance-2-0-260128 (قياسي)، doubao-seedance-2-0-fast-260128 (سريع)، doubao-seedance-2-0-mini-260615 (خفيف). انظر القسم أدناه “الوجه ومرجع الشخصية (Seedance 2.0)”.
  • content: مصفوفة المحتوى المدخل، يمكن أن يكون type إما text (كلمة التلميح)، image_url (صورة مرجعية)، audio_url (صوت مرجعي، 2.0)، video_url (فيديو مرجعي، 2.0). يمكن تحديد استخدام الصورة من خلال role: first_frame (الإطار الأول) / last_frame (الإطار الأخير) / reference_image (وجه / شخصية / مرجع رئيسي).
  • resolution: دقة الإخراج، يمكن اختيار 480p / 720p / 1080p (نموذج 2.0 القياسي يدعم أيضًا 4k؛ 2.0 من fast / mini يدعم حتى 720p).
  • ratio: نسبة العرض إلى الارتفاع، يمكن اختيار 16:9 / 4:3 / 1:1 / 3:4 / 9:16 / 21:9 / adaptive.
  • duration: مدة الفيديو (بالثواني، عدد صحيح). تختلف النطاقات بين السلاسل: سلسلة 1.0 من 2–12؛ 1.5 Pro من 4–12؛ سلسلة 2.0 من 4–15. تدعم 1.5 Pro وسلسلة 2.0 أيضًا -1 (يتم اختيار المدة تلقائيًا بواسطة النموذج).
  • seed: البذور العشوائية، عدد صحيح، من -1 إلى 4294967295.
  • camerafixed: هل يتم تثبيت الكاميرا، true / false.
  • watermark: هل يتم إضافة علامة مائية، true / false.
  • generate_audio: هل يتم توليد فيديو صوتي، true / false، يدعم فقط doubao-seedance-1-5-pro-251215.
  • return_last_frame: هل يتم إرجاع عنوان URL لصورة الإطار الأخير من الفيديو في النتيجة.
  • execution_expires_after: وقت انتهاء المهمة (بالثواني)، النطاق من 3600 إلى 259200.
  • callback_url: عنوان رد الاتصال غير المتزامن، بعد تعيينه، ستعيد واجهة برمجة التطبيقات على الفور task_id، وعند الانتهاء من المهمة، سيتم إرسال النتيجة عبر POST إلى هذا العنوان.
  • async: اختياري، عند تعيينه إلى true، ستعيد الواجهة على الفور task_id، دون الحاجة لتقديم callback_url، ثم يمكن الاستعلام عن النتائج من خلال واجهة استعلام المهام المقابلة.
بعد الاختيار، يمكننا أن نرى أن الجانب الأيمن قد أنشأ أيضًا الكود المقابل، كما هو موضح في الصورة:

يمكنك الضغط على زر “Try” لإجراء اختبار، كما هو موضح في الصورة أعلاه، هنا حصلنا على النتيجة التالية:
تتضمن النتيجة العائدة عدة حقول، كما يلي:
  • success، حالة مهمة توليد الفيديو في ذلك الوقت.
  • task_id، معرف مهمة توليد الفيديو في ذلك الوقت.
  • trace_id، معرف تتبع توليد الفيديو في ذلك الوقت.
  • data، قائمة نتائج مهمة توليد الفيديو في ذلك الوقت.
    • task_id، معرف مهمة توليد الفيديو على الخادم.
    • video_url، رابط الفيديو لمهمة توليد الفيديو في ذلك الوقت.
    • status، حالة مهمة توليد الفيديو في ذلك الوقت.
      • model، النموذج المستخدم لتوليد الفيديو.
يمكننا أن نرى أننا حصلنا على معلومات الفيديو المرضية، كل ما علينا هو الحصول على الفيديو الناتج من SeeDance بناءً على عنوان URL للفيديو في data. بالإضافة إلى ذلك، إذا كنت ترغب في توليد الكود المقابل، يمكنك نسخه مباشرة، مثل كود CURL كما يلي:

شرح المعلمات المضمنة

في نهاية كلمة التلميح content[].text، يمكن تمرير معلمات التوليد من خلال إضافة --parameter value (طريقة قديمة، تحقق ضعيف، عند إدخال خطأ، يتم استخدام القيم الافتراضية تلقائيًا). قائمة المعلمات الكاملة كما يلي:
الممارسة الموصى بها: استخدم الحقول العليا المقابلة مباشرة في جسم الطلب (مثل resolution، ratio، إلخ)، لنمط التحقق القوي، عند إدخال معلمات خاطئة ستعود رسالة خطأ واضحة، مما يسهل استكشاف الأخطاء.

إنشاء فيديو صوتي

doubao-seedance-1-5-pro-251215 يدعم إنشاء فيديو مع صوت من خلال معامل generate_audio:
النماذج الأخرى لا تدعم هذا المعامل، وسيتم تجاهله عند إدخاله.

الصورة لإنشاء الفيديو الإطار الأول

إذا كنت ترغب في إنشاء فيديو من صورة، يجب أن يحتوي معامل content أولاً على عنصر من النوع image_url، يجب أن يكون حقل image_url بتنسيق كائن: {"url": "https://..."} أو بتنسيق Base64 {"url": "data:image/png;base64,..."}.
ملاحظة: لا يدعم image_url إدخال بتنسيق سلسلة مباشرة (مثل "image_url": "https://...")، يجب استخدام تنسيق الكائن "image_url": {"url": "https://..."}، وإلا ستعود رسالة خطأ 400.
الكود المقابل:
عند النقر على التشغيل، يمكنك أن ترى أنك ستحصل على نتيجة على الفور، كما يلي:
يمكنك أن ترى أن التأثير الناتج هو فيديو تم إنشاؤه من صورة، والنتيجة مشابهة لما سبق.

الصورة لإنشاء الفيديو الإطار الأول والأخير

إذا كنت ترغب في إنشاء فيديو من الإطار الأول والأخير، يجب أن يتم تمرير معامل content بنوع image_url، ويجب تعيين role إلى first_frame و last_frame، يمكنك تحديد المحتوى كما يلي:
  • role: تحديد الإطار الأول أو الأخير.
  • image_url
    • url رابط الصورة في نفس الوقت، يجب أن يتضمن content أيضًا نوع text ككلمات تحفيزية.
الكود المقابل:
عند النقر على التشغيل، يمكنك أن ترى أنك ستحصل على نتيجة على الفور، كما يلي:
يمكنك أن ترى أن التأثير الناتج هو فيديو تم إنشاؤه من الشخصيات، والنتيجة مشابهة لما سبق.

مرجع الوجه والشخصيات (Seedance 2.0)

سلسلة Seedance 2.0 (doubao-seedance-2-0-260128، doubao-seedance-2-0-fast-260128، doubao-seedance-2-0-mini-260615) تدعم إدخال مواد مرجعية لـ “أشخاص حقيقيين / شخصيات”: أضف عنصرًا من النوع image_url، و role كـ reference_image في content، وضع صورة الشخص كمرجع، سيحتفظ النموذج بخصائص مظهر هذا الشخص في الفيديو الناتج، مما يتيح “وضع نفس الشخص” في مشهد جديد، أو حركة، أو لقطة.
📌 سيتم تسجيل صور الأشخاص الحقيقيين تلقائيًا كمواد أساسية من قبل المنصة قبل استخدامها في الإنشاء، العملية بأكملها شفافة تمامًا للجهة المستدعية: تنسيق الطلب والاستجابة لا يتغير، ولا حاجة لأي معلمات إضافية، فقط ستستغرق عملية المعالجة بضع ثوانٍ إضافية عند الإنشاء الأول.
  • فقط نموذج Seedance 2.0 يدعم reference_image؛ يرجى استخدام first_frame / last_frame (الإطار الأول / الأخير للفيديو) للنماذج 1.x.
  • لا يمكن استخدام reference_image مع first_frame / last_frame معًا، يجب اختيار أحدهما فقط.
  • الحد الأقصى لعدد المراجع متعددة الوسائط: image_url بحد أقصى 9 صور؛ كما يدعم 2.0 audio_url (دور reference_audio، بحد أقصى 3 مقاطع) و video_url (دور reference_video، بحد أقصى 3 مقاطع).
  • متطلبات مادة الصوت المرجعي (audio_url): صيغة wav / mp3؛ مدة كل مقطع من 2 إلى 15 ثانية، بحد أقصى 3 مقاطع وإجمالي المدة لا يتجاوز 15 ثانية؛ لا يتجاوز كل مقطع 15 ميغابايت. أي تجاوز في المدة سيؤدي إلى فشل معالجة المادة في مرحلة المعالجة.
  • متطلبات مادة الفيديو المرجعي (video_url): صيغة mp4 / mov؛ مدة كل مقطع من 2 إلى 15 ثانية، بحد أقصى 3 مقاطع وإجمالي المدة لا يتجاوز 15 ثانية.
  • يُنصح باستخدام صور مرجعية لشخص واحد، من الأمام، واضحة، وغير محجوبة، كلما كانت ملامح الوجه أوضح، زادت درجة التشابه.

مثال 1: لقطة قريبة تحافظ على مظهر الشخص

قم بإدخال صورة وجه، ليبتسم الشخص أمام الكاميرا ويهز يده. الكود المقابل:
النتيجة كما يلي، الفيديو الناتج يظهر الشخص متوافقًا مع الصورة المرجعية:

مثال 2: وضع نفس الشخص في مشهد جديد تمامًا

تكمن قوة reference_image في: الاحتفاظ فقط بـ هوية الشخص، بينما يتم تحديد المشهد والملابس والحركات بالكامل بواسطة الكلمات الدالة. أدناه، باستخدام نفس صورة الوجه، نضع الشخص في معطف بيج وهو يمشي في حديقة خريفية:
النتيجة كما يلي، مظهر الشخص محفوظ، بينما تم تغيير المشهد إلى حديقة خريفية:
💡 إذا كنت ترغب في جعل الشخص يعيد تكوين التركيب الموجود في الصورة بدقة (بدلاً من “نفس الشخص في مشهد مختلف”)، يمكنك استخدام first_frame (الإطار الأول للفيديو) لبدء الفيديو من هذه الصورة.

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

نظرًا لأن واجهة برمجة تطبيقات SeeDance Videos Generation تستغرق وقتًا طويلاً للتوليد (حوالي 1-2 دقيقة)، يمكنك استخدام حقل callback_url في وضع غير متزامن، لتجنب احتلال اتصال HTTP لفترة طويلة. العملية الكاملة: عند بدء العميل الطلب، يتم تحديد callback_url، وتقوم واجهة برمجة التطبيقات بإرجاع استجابة تحتوي على task_id على الفور؛ بعد الانتهاء من المهمة، ستقوم المنصة بإرسال النتائج الناتجة إلى callback_url بصيغة POST JSON، وستحتوي النتائج أيضًا على task_id لربطها.
عند الانتهاء من المهمة، المحتوى الذي يتم دفعه إلى callback_url كما يلي:
حقل task_id في النتائج يتطابق مع ما تم إرجاعه عند الطلب، ويمكن من خلال هذا الحقل ربط المهمة.

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

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

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

الاستنتاج

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