عملية التقديم
لاستخدام واجهة برمجة تطبيقات توليد مقاطع فيديو 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)”.
- سلسلة Seedance 1.x:
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، ثم يمكن الاستعلام عن النتائج من خلال واجهة استعلام المهام المقابلة.

success، حالة مهمة توليد الفيديو في ذلك الوقت.task_id، معرف مهمة توليد الفيديو في ذلك الوقت.trace_id، معرف تتبع توليد الفيديو في ذلك الوقت.data، قائمة نتائج مهمة توليد الفيديو في ذلك الوقت.task_id، معرف مهمة توليد الفيديو على الخادم.video_url، رابط الفيديو لمهمة توليد الفيديو في ذلك الوقت.status، حالة مهمة توليد الفيديو في ذلك الوقت.model، النموذج المستخدم لتوليد الفيديو.
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ككلمات تحفيزية.
- url رابط الصورة
في نفس الوقت، يجب أن يتضمن
مرجع الوجه والشخصيات (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.0audio_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: خطأ في الخادم الداخلي، حدث خطأ ما على الخادم.

