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

إذا سبق لفريقك لصق نفس رابط تبديل الوجوه (face-swap URL) في ثلاثة استدعاءات API مختلفة، فأنت تدرك بالفعل سبب وجود مكتبة مواد Seedance. تعمل مراجع الفيديو القابلة لإعادة الاستخدام بشكل أفضل كأصول ذات حالة دورة حياة بدلاً من كونها روابط URL تُستخدم لمرة واحدة ويتم نسخها من جداول البيانات في كل طلب إنشاء. تقوم TokenLab بتحديد نطاق هذه الأصول لمؤسستك، بحيث يمكنك تخزين المراجع والتحقق منها وإعادة استخدامها عبر الاستدعاءات. لقد اختبرنا شكل سير العمل: المجموعات تنظم مواد الأشخاص الحقيقيين، والأصول تحمل المرجع الفعلي، واستدعاءات الإنشاء تستهلك المعرفات (IDs) فقط بعد أن تصل الحالة إلى ACTIVE. على سبيل المثال، يمكن للفريق الذي كان يحتفظ بجدول بيانات لروابط الصور ويعيد رفع نفس فيديو المرجع خمس مرات استبدال هذه العادة بمعرف أصل مادي (material asset ID) واحد.

أبرز النقاط

• أصل المادة (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 هي عائلة النماذج العامة الحالية التي يدعمها نظام المواد هذا. تحقق من تفاصيل القدرات الدقيقة لكل نموذج في الوثائق قبل بناء اعتمادية على مستوى معين.

مكتبة مواد Seedance: الأصول والمجموعات

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

هذا الأمر مهم لثلاثة أسباب عملية. أولاً، عمليات الرفع المتكررة تهدر النطاق الترددي وتضيف زمن انتقال لكل طلب، خاصة بالنسبة لفيديوهات المرجع الكبيرة. ثانياً، روابط 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 قبل الالتزام ببنية معينة.

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

لا يحتاج كل مرجع إلى خطوة رفع يدوية. يمكن لـ 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، ثم تابع الإنشاء باستخدام تلك المعرفات.

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

استخدام مكتبة مواد Seedance في الإنشاء

بمجرد وصول أصل المادة — سواء تم رفعه يدوياً أو إعداده تلقائياً — إلى حالة 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 حالي بناءً على احتياجات زمن الانتقال والجودة الخاصة بك.
7. أعد استخدام نفس معرف الأصل عبر استدعاءات الإنشاء المستقبلية بدلاً من إعادة رفع المرجع.

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

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

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

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

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

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

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

كيف تختلف أصول المواد ومجموعات المواد؟

أصل المادة هو كائن مرجعي واحد قابل لإعادة الاستخدام — صورة رمزية واحدة، وجه تم التحقق من حيويته، مقطع فيديو مرجعي واحد. يصبح معرفه id هو material_asset_id بمجرد أن يصبح ACTIVE. مجموعة المواد هي حاوية يتم تحديدها بواسطة group_id. تنظم المجموعات الأصول ذات الصلة وهي مطلوبة لسير عمل liveness_face. باختصار: group_id للتنظيم؛ و material_asset_id للإنشاء.

لماذا يُرجع استدعاء الإنشاء 409 seedance_material_preparing؟

يمكن أن يستغرق إعداد المواد التلقائي، الذي يتم تشغيله بواسطة حقول صور متوافقة مثل image_url أو start_image، أكثر من 60 ثانية. عندما يحدث ذلك، تُرجع الـ API الخطأ 409 seedance_material_preparing مع auto_material_asset_ids. استعلم عن تلك المعرفات، وانتظر ACTIVE، وأعد محاولة الإنشاء. إنه يشير إلى حالة عابرة قيد التقدم، وليس فشلاً.

هل تحتاج مراجع الأشخاص الحقيقيين دائماً إلى التحقق؟

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

هل يمكنني إعادة استخدام أصل مادة واحد عبر وظائف فيديو Seedance متعددة؟

نعم، بمجرد وصول الأصل إلى ACTIVE. استخدم معرفه id كـ material_asset_id أو ضمن material_asset_ids في استدعاء create-video. أعد استخدام نفس معرف الأصل عبر استدعاءات الإنشاء المستقبلية بدلاً من إعادة رفع المرجع. إذا كنت بحاجة إلى إيقاف وظيفة قيد التشغيل، راجع إلغاء مهام Seedance.

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

• دليل نماذج فيديو Seedance — 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 — /dashboard/seedance-assets — تمت ملاحظته في 2026-07-09

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

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