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

مواد Seedance هي مراجع صور أو فيديو أو صوت قابلة لإعادة الاستخدام داخل المؤسسة. اختر مسار العمل أولًا؛ تختلف طريقة إنشاء مواد الصور الرمزية العادية عن مواد الأشخاص الموثقين.

اختر مسار الموادCopy Anchor Link

مفاهيم الموادCopy Anchor Link

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

حافظ على الفصل بين group_id و id الخاص بأصل المادة. يُستخدم group_id لتنظيم المرفوعات، بينما يُستخدم id الخاص بأصل المادة لتوليد الفيديو. إذا أرجع طلب الفيديو خطأ Seedance material asset not found or not accessible، فتأكد من أنك مررت id الخاص بأصل المادة وليس group_id، وأن الأصل ينتمي لنفس المؤسسة، ولم يتم حذفه، وأن حالته status: "ACTIVE".

الاحتفاظ بالموادCopy Anchor Link

تحتفظ TokenLab بكل مادة إلى أن تحذف المادة أو مجموعتها. ولا تُنظَّف المادة بسبب عدم النشاط من جانب TokenLab.

قد يزيل مزوّد Seedance في المصدر نسخة العمل الخاصة به من المادة بعد 30 يومًا دون استخدام. لا يؤدي ذلك إلى حذف مادتك ولا إلى تغيير معرّفها: في المرة التالية التي تستخدمها فيها في طلب توليد، تُعِدّ TokenLab تلقائيًا نسخة جديدة لدى المزوّد من الأصل المخزَّن.

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

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

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

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

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

التحقق من مواد الأشخاص الحقيقيينCopy Anchor Link

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

1. استدعِ إنشاء جلسة تحقق مرئي مع CallbackURL واحفظ Result.BytedToken المُعادة.
2. افتح Result.H5Link للشخص المراد التحقق منه. أضف lng إلى رابط H5 إذا احتجت إلى لغة محددة.
3. بعد اكتمال تدفق H5، يفتح المتصفح Result.CallbackURL مع أسماء الاستعلام الرسمية مثل bytedToken وresultCode.
4. استعلم دوريًا عن الحصول على نتيجة التحقق المرئي باستخدام BytedToken حتى تُعاد Result.GroupId.
5. احفظ GroupId واستخدمها بوصفها group_id عند إنشاء مواد liveness_face.

تظل BytedToken صالحة لمدة 30 دقيقة. استخدم ProjectName نفسها في طلبي Action. تستخدم المصادقة Authorization: Bearer <TOKENLAB_API_KEY>؛ ولا تُقبل توقيعات AK/SK من Volc.

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

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

إنشاء مجموعات الموادCopy Anchor Link

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

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

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

رفع الموادCopy Anchor Link

استخدم إنشاء أصل مادي (Material Asset) لاستيراد رابط مصدر واحد يمكن الوصول إليه علنياً في كل مرة.

بالنسبة لـ aigc_avatar، يعتبر group_id اختيارياً؛ حيث تستخدم TokenLab أو تنشئ مجموعة الصور الرمزية الافتراضية الافتراضية للمؤسسة. بالنسبة لـ liveness_face، يعتبر group_id مطلوباً ويجب أن يكون المجموعة المُرجعة من الحصول على نتيجة التحقق المرئي.

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

استيعاب المواد عملية غير متزامنة. قم باستطلاع الحصول على أصل مادي (Material Asset) حتى تصبح الحالة ACTIVE. استجابة HTTP الناجحة تعني فقط أنه تم قبول الطلب؛ اقرأ دائماً حالة العمل. إذا كانت الحالة FAILED، افحص error_message وقم بإصلاح المادة المصدر وأنشئ أصلاً جديداً.

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

تحتفظ TokenLab بأصول المواد في مكتبة مؤسستك إلى أن تحذف الأصل أو مجموعة المواد الخاصة به. وتُعاد نسخة المزوّد تلقائيًا إذا جرى تنظيفها؛ راجع قسم الاحتفاظ أعلاه.

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

استخدام المواد في توليد الفيديوCopy Anchor Link

بعد أن يصبح الأصل ACTIVE، مرر id الخاص بأصل TokenLab المُرجع كـ material_asset_id، أو قم بتضمينه في material_asset_ids عند استدعاء إنشاء فيديو. تُحتسب أصول المواد ضمن حدود مراجع Seedance.

REST أو Action من VolcengineCopy Anchor Link

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

أمثلة على APICopy Anchor Link

أنشئ مجموعة صور رمزية افتراضية، وارفع صورة، وقم بالاستطلاع حتى تصبح نشطة، ثم استخدم معرف أصل المادة في طلب فيديو.

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"}'

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

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

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

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

مسار Action الكامل لشخص حقيقيCopy Anchor Link

مرر 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، ثم استخدم معرف المادة في توليد الفيديو.