الفيديو والمواد

إنشاء جلسة تحقق مرئي

إنشاء جلسة تحقق مرئي من الهوية الشخصية متوافقة مع Volc.

POST
/api/v3

قم بإنشاء جلسة التحقق المرئي من الهوية الشخصية قبل تحميل مواد liveness_face القابلة لإعادة الاستخدام. يستخدم TokenLab هيكل Volc Action API ومصادقة TokenLab Bearer.

استخدم نفس المؤسسة والمستخدم و ProjectName (حساس لحالة الأحرف) التي تم استخدامها لإنشاء الجلسة.

افتح Result.H5Link فور إنشاء الجلسة. قد تنتهي صلاحية التشغيل الأولي للرابط قبل انتهاء صلاحية BytedToken البالغة 30 دقيقة؛ لذا لا تتأخر في فتحه.

نقطة النهاية والمصادقة

POST https://api.tokenlab.sh/api/v3?Action=CreateVisualValidateSession&Version=2024-01-01
Authorization: Bearer <TOKENLAB_API_KEY>
Content-Type: application/json

لا يتم قبول توقيع Volc AK/SK. حقل CallbackURL مطلوب ويجب أن يكون رابط HTTPS عاماً. حقل ProjectName اختياري وقيمته الافتراضية هي default.

سير العمل

  1. احفظ Result.BytedToken وافتح Result.H5Link للشخص المراد التحقق منه.
  2. لاختيار لغة H5، أضف lng إلى H5Link؛ على سبيل المثال &lng=en. اللغة ليست حقلاً في نص الطلب (request-body).
  3. بعد انتهاء سير عمل H5، سيقوم المتصفح بفتح Result.CallbackURL. يمكن أن يحتوي استعلام رد الاتصال (callback query) على bytedToken و resultCode و algorithmBaseRespCode و reqMeasureInfoValue و verify_type.
  4. قم بإجراء استعلام (Poll) على الحصول على نتيجة التحقق المرئي باستخدام BytedToken المحفوظ حتى يتم إرجاع Result.GroupId.

صلاحية BytedToken هي 30 دقيقة، وهي مرتبطة بالمؤسسة الموثقة و ProjectName. يدعم رابط H5 عملية مصادقة واحدة مكتملة ويصبح غير صالح بعد الاستخدام.

تعامل مع Result.H5Link كرابط متصفح مبهم (opaque): افتحه كصفحة في المستوى الأعلى، ولا تقم بتحليله أو فك ترميزه أو إعادة كتابته أو تضمينه. TokenLab هو المسؤول عن تسليم المتصفح وجسر رد الاتصال.

مثال على الطلب

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

مثال على الاستجابة

{
  "ResponseMetadata": {
    "RequestId": "req_abc123",
    "Action": "CreateVisualValidateSession",
    "Version": "2024-01-01",
    "Service": "ark",
    "Region": "cn-beijing"
  },
  "Result": {
    "BytedToken": "ZXhhbXBsZS10b2tlbg",
    "H5Link": "https://api.tokenlab.sh/api/v3/visual-validation/sessions/svv_example/h5?Version=2024-01-01",
    "CallbackURL": "https://yourapp.example.com/seedance/callback"
  }
}

إعادة المحاولة بأمان

أرسل ترويسة Idempotency-Key اختيارية (من 1 إلى 255 حرفاً) بحيث يمكن استعادة الاستجابة المفقودة. إعادة المحاولة بنفس المفتاح، ومفتاح API، و CallbackURL و ProjectName ستعيد نفس BytedToken و H5Link. استخدام نفس المفتاح مع طلب مختلف سيؤدي إلى إرجاع 409 IdempotencyConflict. بينما لا يزال الطلب الأول قيد الإنشاء، ستكون الاستجابة 409 RequestInProgress مع Retry-After: 2. المفتاح غير الصالح يؤدي إلى إرجاع 400 InvalidParameter.

الأخطاء

تستخدم الأخطاء نفس الغلاف (envelope) في المستوى الأعلى. اقرأ ResponseMetadata.Error.Code و ResponseMetadata.Error.Message بدلاً من توقع الحقول من واجهات برمجة تطبيقات TokenLab الأخرى /v1.

الحالةالرمزالسبب
400InvalidParameterCallbackURL مفقود أو غير صالح (يجب أن يكون رابط HTTPS عاماً بدون بيانات اعتماد)، أو Idempotency-Key غير صالح، أو حقل غير معروف
400InvalidVersionVersion ليست 2024-01-01
405MethodNotAllowedالإجراء يقبل فقط POST
409IdempotencyConflict, RequestInProgressراجع قسم إعادة المحاولة بأمان
503ServiceUnavailableالتحقق من الهوية الشخصية غير متاح لهذا الحساب أو فشل؛ حاول مرة أخرى لاحقاً
curl -X POST "https://example.com/api/v3" \  -H "Content-Type: application/json" \  -d '{    "CallbackURL": "http://example.com"  }'
{  "id": "string"}

التفويض

BearerAuth
AuthorizationBearer <token>

مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.

الموضع: header

معاملات الاستعلام

Action?string

القيم المتاحة

  • "CreateContentsGenerationsTasks"
  • "GetContentsGenerationsTask"
  • "ListContentsGenerationsTasks"
  • "DeleteContentsGenerationsTasks"
  • "CreateVisualValidateSession"
  • "GetVisualValidateResult"
  • "CreateAssetGroup"
  • "ListAssetGroups"
  • "GetAssetGroup"
  • "UpdateAssetGroup"
  • "DeleteAssetGroup"
  • "CreateAsset"
  • "ListAssets"
  • "GetAsset"
  • "UpdateAsset"
  • "DeleteAsset"
Version?string
الافتراضي"2024-01-01"

الترويسات

X-TokenLab-Delivery-Policy?string

سياسة التسليم لكل طلب. تتجاوز إعدادات API key و Workspace الافتراضية. يحاول النظام تلقائياً استخدام TokenLab Verified أولاً، وقد ينتقل مرة واحدة إلى Official فقط قبل المخرجات، أو قبول الطلب، أو إنشاء مورد دائم.

القيم المتاحة

  • "auto"
  • "verified"
  • "official"

جسم الطلب

application/json

الاستجابة

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json