أدلة الوسائط

مواد Seedance والتحقق من الشخص الحقيقي

إعادة استخدام الصور أو الفيديو أو الصوت أو شخص تم التحقق منه في Seedance

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

اختيار نوع المادة

ما تريد إعادة استخدامهما يجب فعله
صورة واحدة تُستخدم مرة واحدةأرسل رابط URL الخاص بها في حقل صورة مدعوم؛ هذا لا ينشئ معرف مادة قابل لإعادة الاستخدام
إعادة استخدام شخص افتراضي أو منتج أو نمطأنشئ مجموعة aigc_avatar، وأنشئ أصلاً (asset)، وانتظر حتى تصبح الحالة ACTIVE، ثم استخدم معرف الأصل
إعادة استخدام شخص حقيقيأكمل التحقق المرئي، واحصل على GroupId الخاص به، وأنشئ أصلاً في تلك المجموعة، وانتظر حتى تصبح الحالة ACTIVE، ثم استخدم معرف الأصل
ترحيل عميل مواد Volcengine موجوداحتفظ بشكل طلب الإجراء (Action) واستخدم مرجع المواد المتوافق مع Volc

المجموعات والمواد

العنصرحقل RESTحقل Actionالمعنى
مجموعة الموادgroup_idGroupIdتجمع المواد ذات الصلة معاً
المادةidIdملف صورة أو فيديو أو صوت مستورد واحد؛ استخدم هذا المعرف بعد أن يصبح نشطاً
مجموعة الصور الرمزية الافتراضيةlibrary_type: "aigc_avatar"GroupType: "AIGC"لا تتطلب تحققاً من شخص حقيقي
مجموعة الشخص الحقيقيlibrary_type: "liveness_face"GroupType: "LivenessFace"يتم إنشاؤها فقط من خلال عملية تحقق مرئي ناجحة
اسم المشروعproject_nameProjectNameيفصل المواد الخاصة بالمشاريع المختلفة؛ القيمة الافتراضية هي default

احتفظ بمعرفات المجموعات ومعرفات الأصول منفصلة. تقوم المجموعة بتنظيم عمليات الرفع؛ بينما معرف الأصل هو المرجع المستخدم في توليد الفيديو. تبدو المعرفات العامة مثل group-20260720123456-vrt01 و asset-20260720123457-def45.

الاحتفاظ بالمواد

تحتفظ TokenLab بكل أصل مادي حتى تقوم بحذف الأصل أو مجموعته. لا يتم تنظيف المواد بسبب عدم النشاط.

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

روابط الصور والمواد القابلة لإعادة الاستخدام

أرسل روابط HTTP(S) عامة أو روابط بيانات مدعومة في حقول الصور التي يقبلها النموذج الذي اخترته. تتبع هذه المدخلات مسار الوسائط العادي ولا تنشئ معرفات مواد قابلة لإعادة الاستخدام تلقائياً.

بالنسبة للمواد القابلة لإعادة الاستخدام، أنشئ أصلاً من خلال API المواد، وانتظر حتى تصبح الحالة ACTIVE، ثم استخدم material_asset_id أو material_asset_ids أو asset://<id> في حقل وسائط مدعوم. حافظ على دور الإطار الأول أو الإطار الأخير أو الصورة المرجعية المقصود.

عندما تكون المادة الصريحة لا تزال قيد الإعداد، سيعيد POST /v1/videos/generations الخطأ 409 seedance_material_preparing مع inactive_asset_ids. قم بعمل استطلاع (poll) لتلك الأصول حتى تصبح ACTIVE، ثم أعد المحاولة بنفس معرفات المواد. إذا كان الأصل في حالة FAILED، افحص error_message وقم بتصحيحه أو إعادة استيراده قبل إعادة المحاولة. طلب التوليد الذي يستخدم أصلاً فاشلاً سيعيد 422 seedance_material_failed مع failed_asset_ids.

مواد الصور الرمزية الافتراضية (Virtual-Avatar)

استخدم إنشاء مجموعة أصول المواد لإنشاء مجموعة aigc_avatar. بالنسبة لإنشاء أصول REST، يكون group_id اختيارياً فقط عندما يكون project_name هو default؛ حيث تستخدم TokenLab حينها مجموعة الصور الرمزية الافتراضية للمؤسسة أو تنشئ واحدة. يتطلب أي project_name غير افتراضي، وكذلك كل أصل لشخص حقيقي، وجود group_id.

بعد وجود مجموعة، يمكنك إدارتها باستخدام:

حذف مجموعة يؤدي أيضاً إلى حذف مواد TokenLab التي تحتوي عليها ولا يمكن التراجع عن ذلك.

التحقق من الشخص الحقيقي

استخدم هذا المسار عندما يجب على منتجك جمع الموافقة والتحقق من الوجه قبل إعادة استخدام شخص حقيقي كمرجع لـ Seedance.

  1. اتصل بـ إنشاء جلسة تحقق مرئي باستخدام CallbackURL؛ احفظ Result.BytedToken وافتح Result.H5Link للشخص الذي يتم التحقق منه.
  2. بعد إعادة توجيه مسار H5 إلى رابط الاستدعاء (callback)، قم بعمل استطلاع لـ الحصول على نتيجة التحقق المرئي باستخدام نفس BytedToken و ProjectName.
  3. احفظ Result.GroupId الذي تم إرجاعه. تنشئ TokenLab وتربط مجموعة LivenessFace خلال هذه الخطوة.
  4. أنشئ أصلاً باستخدام معرف المجموعة ذلك، ثم قم بعمل استطلاع للأصل حتى يصبح ACTIVE.

BytedToken صالح لمدة 30 دقيقة. لا يمكن للعميل إنشاء مجموعة LivenessFace باستخدام CreateAssetGroup؛ هذا يمنع تقديم مجموعة غير محققة على أنها محققة.

افتح H5Link الذي تم إرجاعه فور إنشائه. صلاحية الرمز لا تعني أنه يمكن فتح صفحة التحقق لأول مرة في أي وقت خلال تلك النافذة.

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

إنشاء وإعداد أصل

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

النوعالمدخلات المدعومة
صورةjpeg, png, webp, bmp, tiff, gif, heic, heif؛ ≤ 30 ميجابايت؛ العرض والارتفاع [300, 6000] بكسل؛ نسبة العرض إلى الارتفاع [0.4, 2.5]
فيديوmp4, mov؛ ≤ 200 ميجابايت
صوتaac, wav, mp3؛ ≤ 15 ميجابايت

هذه هي حدود استيراد الملفات. طلب الاستيراد الناجح لا يضمن نجاح التحقق من الوسائط أو الشخص الحقيقي. انتظر حتى تصبح الحالة ACTIVE؛ إذا أصبح الأصل FAILED، استخدم error_message لتصحيح المصدر قبل الاستيراد مرة أخرى.

استيعاب المواد عملية غير متزامنة. قم بعمل استطلاع لـ الحصول على أصل مادي حتى تصبح status هي ACTIVE. نجاح HTTP يعني قبول الاستيراد، وليس أن الأصل جاهز. إذا أصبح الأصل FAILED، افحص error_message وقم بتصحيح المصدر وإنشاء أصل جديد.

يُستخدم رابط المصدر للاستيراد فقط. تُرجع TokenLab معرف الأصل الخاص بها وتحتفظ بالأصل في مكتبة مواد مؤسستك حتى تقوم بحذف الأصل أو مجموعته.

استخدام أصل في توليد الفيديو

بعد أن يصبح الأصل ACTIVE، اختر أحد هذه النماذج عند استدعاء إنشاء فيديو:

  • material_asset_id لمرجع مادة عام واحد
  • material_asset_ids لمراجع عامة متعددة
  • asset://<asset-id> في image_url أو start_image أو end_image أو reference_images عندما يجب أن يكون دور الوسائط صريحاً

تحتسب مراجع المواد ضمن حدود مراجع Seedance الخاصة بالنموذج المختار. إذا أعاد الـ API الخطأ Seedance material asset not found or not accessible، فتأكد من أن القيمة هي معرف أصل وليس معرف مجموعة، وأنها تنتمي لنفس المؤسسة والمشروع، ولم يتم حذفها، وأن حالتها ACTIVE.

REST أو Volcengine Action

يمكن لعمليات التكامل الأصلية مع TokenLab الاستمرار في استخدام نقاط نهاية REST ذات التنسيق snake_case مثل /v1/videos/assets*. يمكن لعملاء Volcengine الحاليين الاحتفاظ بهياكل PascalCase مع إجراءات المواد (متوافقة مع Volc). تعمل كلتا الواجهتين على نفس بيانات المواد المحددة للمؤسسة والمشروع.

مثال REST: أصل صورة رمزية افتراضية

curl https://api.tokenlab.sh/v1/videos/assets/groups \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"library_type":"aigc_avatar","group_name":"Product references","project_name":"default"}'

curl https://api.tokenlab.sh/v1/videos/assets \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_id":"group-20260720123456-abc12","asset_url":"https://example.com/reference.png","asset_name":"Front view","asset_type":"Image","project_name":"default"}'

curl https://api.tokenlab.sh/v1/videos/assets/asset-20260720123457-def45?project_name=default \
  -H "Authorization: Bearer $TOKENLAB_API_KEY"

مثال Action: أصل شخص حقيقي تم التحقق منه

أولاً، قم بإنشاء وإكمال التحقق المرئي:

curl 'https://api.tokenlab.sh/?Action=CreateVisualValidateSession&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"CallbackURL":"https://yourapp.example.com/seedance/callback","ProjectName":"default"}'

curl 'https://api.tokenlab.sh/?Action=GetVisualValidateResult&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"BytedToken":"<BYTED_TOKEN>","ProjectName":"default"}'

ثم مرر GroupId الذي تم إرجاعه إلى CreateAsset:

curl 'https://api.tokenlab.sh/?Action=CreateAsset&Version=2024-01-01' \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "GroupId":"group-20260720123456-real1",
    "URL":"https://example.com/person-front.png",
    "Name":"Verified front view",
    "AssetType":"Image",
    "ProjectName":"default"
  }'

قم بعمل استطلاع باستخدام GetAsset حتى تصبح حالته Active، ثم مرر معرف الأصل الذي تم إرجاعه إلى عملية توليد الفيديو. للحصول على جميع عمليات Action العشر، والفلاتر، والترقيم، وأشكال الاستجابة، والأخطاء، راجع إجراءات المواد (متوافقة مع Volc).

في هذه الصفحة