مواد Seedance من TokenLab: مراجع فيديو قابلة لإعادة الاستخدام لسير عمل الإنتاج

تعد مراجع الفيديو القابلة لإعادة الاستخدام أسهل في الإدارة عندما تكون أصولاً ذات حالة دورة حياة (lifecycle status)، بدلاً من كونها روابط URL تُستخدم لمرة واحدة وتُنسخ في كل طلب توليد. إذا سبق لك الاحتفاظ بجدول بيانات لروابط صور، أو أعدت رفع نفس فيديو المرجع خمس مرات، أو أعدت كتابة رابط تبديل الوجوه (face-swap) في ثلاثة استدعاءات API مختلفة، فأنت تدرك بالفعل المشكلة التي صُممت مواد Seedance لحلها.

تمنح مكتبة مواد Seedance من TokenLab فرق الفيديو طريقة منظمة على مستوى المؤسسة لتخزين المراجع والتحقق منها وإعادة استخدامها عبر استدعاءات التوليد. يشرح هذا المقال ماهية أصل المادة (material asset) فعلياً، وكيف ترتبط مجموعات المواد بالأصول الفردية، وكيف يعمل الإعداد التلقائي، وأين يتناسب التحقق من الشخص الحقيقي ضمن سير العمل.

أبرز النقاط

• أصل المادة (material asset) هو كائن المرجع الجاهز للتوليد؛ أما مجموعة المواد (material group) فهي الحاوية التي تنظم الأصول ذات الصلة، خاصة لسير عمل الأشخاص الحقيقيين.
• استخدم فقط id الخاص بأصل المادة كـ material_asset_id (أو داخل material_asset_ids) بعد أن تصل حالته إلى ACTIVE.
• يوجد نوعان من المكتبات: aigc_avatar للصور الرمزية الافتراضية والمراجع الأخرى غير المتعلقة بأشخاص حقيقيين، و liveness_face لمجموعات مواد الأشخاص الحقيقيين التي تتطلب تحققاً.
• يمكن لـ TokenLab إعداد مدخلات الصور المتوافقة تلقائياً (image, image_url, image_urls, reference_images, start_image, end_image) وتحويلها إلى أصول مواد دون الحاجة إلى خطوة رفع منفصلة.
• إذا استغرق الإعداد أكثر من 60 ثانية، تُرجع الـ API الخطأ 409 seedance_material_preparing مع auto_material_asset_ids التي يمكنك الاستعلام عنها وإعادة المحاولة.
• Seedance 2.0 و Seedance 2.0 Fast و Seedance 2.0 Mini هي النماذج العامة الحالية التي يدعمها نظام المواد هذا. تحقق من تفاصيل القدرات الدقيقة لكل نموذج في الوثائق قبل بناء اعتمادية على فئة محددة.

ما هي مادة Seedance؟

مادة Seedance هي مرجع قابل لإعادة الاستخدام — صورة أو فيديو أو صوت — تخزنه TokenLab كأصل على مستوى المؤسسة بدلاً من كونه رابط URL على مستوى الطلب. بدلاً من تمرير رابط ملف خام في كل استدعاء create-video، يمكنك رفع المرجع أو استيراده مرة واحدة، وانتظار أن يصبح جاهزاً للتوليد، ثم الإشارة إليه بالمعرف (ID) في أي عدد تريده من الاستدعاءات اللاحقة.

هذا الأمر مهم لثلاثة أسباب عملية.

أولاً، عمليات الرفع المتكررة تهدر النطاق الترددي وتضيف زمن انتقال (latency) لكل طلب، خاصة بالنسبة لفيديوهات المراجع الكبيرة.

ثانياً، روابط URL الخام تنتهي صلاحيتها، أو يتم تغييرها، أو إلغاؤها بواسطة أي نظام تخزين استضافها في الأصل. أصل المادة الذي تديره TokenLab لا يعاني من هذه الهشاشة.

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

أصول المواد مقابل مجموعات المواد

الكائنان الأساسيان في هذا النظام هما أصل المادة ومجموعة أصول المادة، ومن السهل الخلط بينهما إذا لم تقرأ مرجع الـ API بعناية.

أصل المادة (material asset) هو كائن مرجع واحد — صورة رمزية واحدة، وجه تم التحقق من حيويته، مقطع فيديو مرجعي واحد. عند إنشائه، تُرجع الـ API معرفاً id. هذا المعرف هو ما تمرره في النهاية إلى استدعاءات توليد الفيديو بمجرد وصول الأصل إلى حالة ACTIVE.

مجموعة أصول المادة (material asset group) هي حاوية يتم تحديدها بواسطة group_id. تنظم المجموعات الأصول ذات الصلة معاً، وهي مطلوبة هيكلياً لسير عمل الأشخاص الحقيقيين (liveness_face)، حيث يتم التحقق على مستوى المجموعة قبل إمكانية رفع الأصول الفردية إليها.

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

الحقل	ما يحدده	أين تستخدمه
group_id	مجموعة أصول المادة (حاوية)	إنشاء أو الإشارة إلى مجموعة، خاصة لتدفقات التحقق من الشخص الحقيقي
id (في أصل المادة)	مرجع واحد قابل لإعادة الاستخدام	يصبح material_asset_id بمجرد أن يصبح ACTIVE
material_asset_id	مرجع أصل واحد، مفرد	يُمرر إلى create-video لفتحة مرجع واحدة
material_asset_ids	مصفوفة من مراجع الأصول	يُمرر إلى create-video عند الحاجة إلى مراجع متعددة قابلة لإعادة الاستخدام

تم توثيق تعريفات الحقول الكاملة والمعلمات المطلوبة في مراجع الـ API الخاصة بـ إنشاء أصل مادة و إنشاء مجموعة أصول مادة. اقرأ تلك الوثائق قبل ربط هذا في كود الإنتاج — هذا المقال يغطي شكل سير العمل، وليس كل معلمة طلب.

سير عمل الصور الرمزية الافتراضية والأشخاص الحقيقيين

تدعم مواد Seedance نوعين من المكتبات، والتمييز ليس تجميلياً — بل يعكس وضعين مختلفين للسلامة والموافقة.

aigc_avatar: الصور الرمزية الافتراضية والمراجع غير المتعلقة بأشخاص حقيقيين

يغطي نوع aigc_avatar المراجع القابلة لإعادة الاستخدام التي لا ترتبط بشخص حقيقي تم التحقق منه: الشخصيات المصورة، الصور الرمزية الاصطناعية، الشخصيات المنمقة، تمائم العلامات التجارية، والأصول المماثلة. يمكن إنشاؤها مباشرة من خلال تدفق إنشاء أصل المادة دون خطوة تحقق.

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

liveness_face: مجموعات مواد الأشخاص الحقيقيين

نوع liveness_face مخصص لمجموعات المواد المبنية حول ملامح شخص حقيقي — وهو نوع المرجع المستخدم لتوليد فيديو متسق الوجه يضم فرداً فعلياً. نظراً لأن هذا يمس الهوية والموافقة، تتطلب TokenLab تدفق تحقق قبل إمكانية رفع الأصول إلى المجموعة.

يحتوي تسلسل التحقق على عدة خطوات متميزة:

1. إنشاء الجلسة — يطلب نظامك الخلفي جلسة تحقق للمجموعة.
2. تدفق H5 — يكمل الشخص الذي يتم التحقق منه فحص الحيوية من خلال تدفق ويب مستضاف (هذا ما تشير إليه "H5": واجهة تحقق عبر ويب الهاتف المحمول).
3. رد الاتصال (Callback) — تُخطر TokenLab نظامك عند انتهاء جلسة التحقق.
4. ربط النتيجة — يتم ربط الهوية التي تم التحقق منها بمجموعة المواد.
5. الرفع على مستوى المجموعة — فقط بعد نجاح الربط يمكن رفع أصول المواد إلى تلك المجموعة المحددة.

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

قائمة مرجعية: اختيار نوع المكتبة الصحيح

• هل المرجع هو وجه أو ملامح شخص حقيقي يمكن التعرف عليه؟ ← استخدم liveness_face وخطط لتدفق التحقق.
• هل المرجع اصطناعي، أو مصور، أو صورة رمزية غير حقيقية؟ ← استخدم aigc_avatar وتخطَّ التحقق.
• هل يحتاج منتجك إلى هوية متسقة عبر عمليات توليد متعددة لنفس الشخص الحقيقي؟ ← ابنِ المجموعة مرة واحدة، وتحقق مرة واحدة، وأعد استخدام المجموعة للأصول المستقبلية.
• هل أنت غير متأكد من النوع الذي يندرج تحته مرجع مقدم من عميل؟ ← تعامل معه كـ liveness_face حتى يتم تأكيد خلاف ذلك؛ تحقق من الوثائق، لا تفترض.

لا تفترض أن كل نموذج توليد أو كل نوع طلب يدعم كلا نوعي المكتبات بشكل متطابق — تحقق من الدعم الحالي في دليل نماذج فيديو Seedance 2.0 قبل الالتزام ببنية معينة.

كيف يعمل الإعداد التلقائي للمواد

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

الحقول التي تتعرف عليها للإعداد التلقائي هي:

• image
• image_url
• image_urls
• reference_images
• start_image
• end_image

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

ماذا يحدث عندما يستغرق الإعداد أكثر من 60 ثانية

عادة ما يكون الإعداد سريعاً، ولكن صور المراجع الأكبر أو الأكثر تعقيداً قد تستغرق وقتاً أطول للمعالجة لتصبح أصلاً جاهزاً للتوليد. إذا تجاوز الإعداد 60 ثانية، تستجيب الـ API بـ:

409 seedance_material_preparing

جنباً إلى جنب مع حقل auto_material_asset_ids الذي يحتوي على معرفات الأصول التي لا تزال قيد الإعداد.

هذا ليس خطأ بالمعنى التقليدي — بل هو إشارة لإعادة المحاولة. يجب أن يتعامل تكاملك مع 409 seedance_material_preparing كاستجابة "تحقق مرة أخرى قريباً"، وليس كفشل يجب إظهاره للمستخدم النهائي. استعلم عن معرفات الأصول المرجعة، وانتظر حالة ACTIVE، ثم تابع التوليد باستخدام تلك المعرفات.

عملياً، هذا يعني أن خط إنتاج التوليد الخاص بك يحتاج إلى حلقة إعادة محاولة صغيرة، وليس مجرد محاولة/التقاط (try/catch) واحدة. يجب على الفرق التي تبني خطوط إنتاج فيديو مؤتمتة التعامل مع هذه الحالة بنفس الطريقة التي تتعامل بها مع تقييد المعدل (rate-limit backoff) — متوقع، ومؤقت، ويتم التعامل معه في الكود بدلاً من الإبلاغ عنه كخطأ يواجه المستخدم.

كيفية استخدام المواد في التوليد

بمجرد وصول أصل المادة — سواء تم رفعه يدوياً أو إعداده تلقائياً — إلى حالة ACTIVE، يصبح معرفه id قابلاً للاستخدام كـ material_asset_id (أو كعنصر في material_asset_ids) في استدعاء إنشاء فيديو.

سير العمل الأساسي يبدو كالتالي:

1. قرر ما إذا كان المرجع لشخص حقيقي أم لا. اختر liveness_face (مع التحقق) أو aigc_avatar وفقاً لذلك.
2. إذا كان شخصاً حقيقياً: أنشئ مجموعة المواد، وقم بتشغيل جلسة التحقق وتدفق H5، واستقبل رد الاتصال، واربط النتيجة.
3. أنشئ أو استورد أصل المادة — إما من خلال استدعاء رفع مباشر، أو بالسماح للإعداد التلقائي بمعالجة حقل صورة متوافق داخل طلب توليد.
4. تحقق من الحالة. لا تمرر معرف الأصل إلى التوليد حتى يبلغ عن حالة ACTIVE.
5. إذا حصلت على 409 seedance_material_preparing، استعلم عن auto_material_asset_ids المرجعة وأعد المحاولة بمجرد أن تصبح ACTIVE.
6. استخدم id كـ material_asset_id أو ضمن material_asset_ids في استدعاء create-video الخاص بك، مستهدفاً نموذج Seedance حالي مثل seedance-2.0 أو seedance-2.0-fast أو seedance-2.0-mini اعتماداً على احتياجات زمن الانتقال والجودة لديك.
7. أعد استخدام نفس معرف الأصل عبر استدعاءات التوليد المستقبلية بدلاً من إعادة رفع المرجع.

هذا هو المكان الذي تهم فيه إدارة المهام أيضاً. إذا كان استدعاء التوليد المبني على مادة معاد استخدامها يحتاج إلى التوقف في منتصف التشغيل — للتحكم في التكلفة، أو تغيير موجز إبداعي، أو مطالبة (prompt) سيئة — راجع مقالتنا المصاحبة حول إلغاء مهام Seedance لمعرفة كيفية تفاعل الإلغاء مع وظائف الفيديو قيد التشغيل.

للحصول على مقارنة أوسع لما هو متاح حالياً عبر نماذج توليد الفيديو على TokenLab، تسرد صفحة فئة نماذج الفيديو الخيارات الحالية جنباً إلى جنب.

خطوات عملية تالية

• إذا كنت تقوم بالنماذج الأولية، ابدأ بمواد aigc_avatar — مسار الإنشاء أبسط ولا توجد اعتمادية تحقق للبناء حولها أولاً.
• إذا كان منتجك يتطلب اتساق الشخص الحقيقي، ابنِ تدفق التحقق (جلسة ← H5 ← رد اتصال ← ربط) كجزء أساسي من عملية الإعداد، وليس كإضافة لاحقة.
• أضف حلقة إعادة محاولة لـ 409 seedance_material_preparing قبل شحن أي شيء إلى الإنتاج — تعامل معه كسلوك متوقع، وليس كحالة استثنائية.
• خزّن معرفات أصول المواد بجانب سجلاتك المرجعية الداخلية حتى لا تضطر إلى إعادة استنتاج أي أصل يرتبط بأي شخصية أو منتج.
• راجع مراجع الـ API الخاصة بـ أصل المادة و مجموعة أصول المادة مباشرة — يصف هذا المقال شكل سير العمل، ويجب تأكيد حقول الطلب/الاستجابة الدقيقة مقابل الوثائق الحالية قبل كتابة كود التكامل.

يمكنك تصفح مكتبة المواد مباشرة في لوحة تحكم أصول Seedance لرؤية الحالة، ونوع المكتبة، وعلاقات المجموعة للأصول التي أنشأتها بالفعل.

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

الأسئلة الشائعة

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

ما الفرق بين group_id و material_asset_id؟ يحدد group_id مجموعة أصول المادة، وهي حاوية تُستخدم بشكل أساسي لتنظيم أصول الأشخاص الحقيقيين (liveness_face) وإدارة التحقق على مستوى المجموعة. يحدد material_asset_id مرجعاً واحداً قابلاً لإعادة الاستخدام — المعرف id الذي يتم إرجاعه عند إنشاء أصل مادة — وهو ما تمرره في استدعاءات توليد الفيديو.

متى يجب أن أستخدم التحقق من الشخص الحقيقي؟ استخدم نوع liveness_face وتدفق التحقق الخاص به كلما تضمنت المادة المرجعية وجه أو ملامح شخص حقيقي يمكن التعرف عليه. يتطلب التدفق إنشاء جلسة، وفحص حيوية H5، ورد اتصال، وخطوة ربط قبل إمكانية رفع أي أصول إلى تلك المجموعة. المراجع غير المتعلقة بأشخاص حقيقيين، مثل الصور الرمزية المصورة أو الاصطناعية، تستخدم aigc_avatar ولا تتطلب مسار التحقق هذا.

ماذا يعني seedance_material_preparing؟ هي استجابة 409 يتم إرجاعها عندما يستغرق الإعداد التلقائي للمواد — الذي يتم تشغيله بواسطة حقول صور متوافقة مثل image_url أو start_image في طلب توليد — أكثر من 60 ثانية ليكتمل. تتضمن الاستجابة auto_material_asset_ids حتى تتمكن من الاستعلام عن تلك المعرفات وإعادة محاولة التوليد بمجرد أن تصبح ACTIVE. إنها تشير إلى حالة مؤقتة قيد التقدم، وليست فشلاً.

المصادر والحداثة

• دليل نماذج فيديو Seedance 2.0 — https://docs.tokenlab.sh/guides/seedance-2-video — تمت ملاحظته في 2026-07-09
• إنشاء أصل مادة Seedance (مرجع API) — https://docs.tokenlab.sh/api-reference/video/create-material-asset — تمت ملاحظته في 2026-07-09
• إنشاء مجموعة أصول مادة Seedance (مرجع API) — https://docs.tokenlab.sh/api-reference/video/create-material-asset-group — تمت ملاحظته في 2026-07-09
• إنشاء فيديو (مرجع API) — https://docs.tokenlab.sh/api-reference/video/create-video — تمت ملاحظته في 2026-07-09
• لوحة تحكم أصول Seedance من TokenLab — https://tokenlab.sh/en/dashboard/seedance-assets — تمت ملاحظته في 2026-07-09

يعكس سلوك الـ API، وأسماء الحقول، ودلالات الحالة الموصوفة هنا الوثائق العامة ونسخ لوحة التحكم اعتباراً من تاريخ الملاحظة. نظام مواد Seedance من TokenLab قيد التطوير النشط — تأكد من أسماء المعلمات الحالية، وقيم الحالة، والدعم الخاص بالنموذج في الوثائق المرتبطة قبل الانتهاء من كود تكامل الإنتاج.

إذا كنت تبني خط إنتاج فيديو يعتمد على مراجع ثابتة وقابلة لإعادة الاستخدام، ابدأ بـ دليل نماذج فيديو Seedance 2.0 — فهو أسرع طريقة لرؤية أسماء المعلمات الحالية وتأكيد ما تدعمه فئة النموذج المستهدف فعلياً.