> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# API كشف الحيوية: منع التزييف العميق
> اكشف التزييف العميق والأقنعة وهجمات العرض مع كشف الحيوية من Didit بدقة 99.9%، واختبار iBeta، والدفع لكل استدعاء من $0.10.
يؤكد كشف الحيوية من Didit وجود شخص حقيقي وحي أمام الكاميرا، وليس صورة مطبوعة أو إعادة تشغيل عبر شاشة أو قناعاً أو تزييفاً عميقاً، وذلك باستخدام كشف الحيوية السلبي أو الإجراء ثلاثي الأبعاد أو الفلاش. وتصل دقته إلى **99.9%** مع معدل قبول خاطئ (FAR) يقل عن **0.1%**.
تعليمات دمج كشف الحيوية
نسخ الموجّه إلى الحافظة
\
\````# Goal
Integrate Didit Liveness Detection (passive / 3D-action / flashing) into your app. Pick ONE mode.
\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow (SDK or session.url). The workflow's LIVENESS feature controls which method runs.
1\. Configure the workflow's liveness method — `face_liveness_method`: "PASSIVE" | "ACTIVE_3D" | "FLASHING" (Business Console or POST /v3/workflows/).
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user (or mount the Web/Mobile SDK).
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.
Decision surface: `liveness_checks[]` array on the decision payload (one entry per liveness node).
\# Mode B — Standalone API (server-to-server, passive only)
Use when you already have a captured selfie and want a one-shot passive-liveness check.
POST https://verification.didit.me/v3/passive-liveness/
multipart/form-data — x-api-key: YOUR_API_KEY
Required: user_image (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted).
curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/passive-liveness/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```
Returns: { request_id, liveness: { status, method: "PASSIVE", score, user_image: { entities, best_angle }, warnings, face_quality, face_luminance } }.
When `save_api_request=true` the submitted face is also screened against your blocklist and face index for duplicates — set to `false` to skip enrolment.
\# Status enum (per liveness_checks[].status or liveness.status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"
\# Warnings (LogWarningChoices.LIVENESS)
warnings[] risk codes include:
LOW_LIVENESS_SCORE, NO_FACE_DETECTED, LIVENESS_FACE_ATTACK, MULTIPLE_FACES_DETECTED, FACE_IN_BLOCKLIST, POSSIBLE_FACE_IN_BLOCKLIST, DUPLICATED_FACE, POSSIBLE_DUPLICATED_FACE.
Full catalogue: /core-technology/liveness/warnings-liveness.
\# Failure modes to handle
\- HTTP 403 — out of credits.
\- HTTP 400 — missing user_image, file too large, unsupported extension.
\- status="Declined" with LIVENESS_FACE_ATTACK or LOW_LIVENESS_SCORE — presentation attack suspected; do not approve.
\- FACE_IN_BLOCKLIST / DUPLICATED_FACE — block or route to manual review per your policy.
\- NO_FACE_DETECTED / MULTIPLE_FACES_DETECTED — ask the user to retry with a single, well-framed face.
\# See also
\- Canonical schema: /reference/data-models#liveness-check
\- Per-feature report: /core-technology/liveness/report-liveness
\- Risk catalogue: /core-technology/liveness/warnings-liveness
\- Full integration playbook: /integration/integration-prompt````
\
الصق في
يصل درس Didit Academy حول مسار المستخدم المستضاف إلى صورة سيلفي كشف الحيوية عند الدقيقة 8:49، وتليه عند الدقيقة 9:16 طرق كشف الحيوية السلبية، والفلاش ثلاثي الأبعاد، والإجراء ثلاثي الأبعاد.[صورة سيلفي كشف الحيوية — Didit Academy](https://www.youtube.com/embed/LzGe-dMWjUw?start=529\&rel=0\&playsinline=1)## طرق كشف الحيويةتطبق منصتنا ثلاث تقنيات متميزة لمكافحة الانتحال، كل منها مصممة لتلبية احتياجات أمنية وتجارب مستخدم مختلفة:
| الطريقة |
الوصف |
مستوى الأمان |
الأفضل لـ |
| **`3D Action & Flash`** |
• يجمع بين التحقق البيومتري متعدد العوامل و**تسلسل إجراءات عشوائي** و**تحليل ديناميكي لأنماط الإضاءة**.\
• في البداية، يُطلب من المستخدم تنفيذ إجراء بسيط—مثل **الرمش بالعينين** أو **إيماءة الرأس**—لضمان التفاعل في الوقت الفعلي.\
• بالتزامن مع ذلك، يُسقط النظام تسلسلاً من أنماط الإضاءة على الوجه، ويحلل **الانعكاسات** لتأكيد البنية ثلاثية الأبعاد للوجه.\
• تفحص **خوارزميات التعلم العميق** التعبيرات الدقيقة واستجابات انعكاس الضوء للتحقق من وجود شخص حي.\
• يوفر **أعلى درجات الأمان** عبر دمج الدلائل السلوكية (الإجراء) والفيزيائية (العمق المعتمد على الضوء)، مما يجعل الانتحال باستخدام الصور الثابتة أو مقاطع الفيديو أو حتى الأقنعة المتقدمة شبه مستحيل.
|
الأعلى |
التطبيقات المصرفية، والرعاية الصحية، والتطبيقات الحكومية |
| **`3D Flash`** |
• يستخدم **تحليل أنماط الإضاءة الديناميكية** للتحقق من تضاريس الوجه دون اشتراط تفاعل من المستخدم.\
• يُسقط سلسلة من أنماط الإضاءة على الوجه بمعدل يزيد عن **30 إطاراً في الثانية**، ويحلل الانعكاسات لإنشاء **خريطة عمق**.\
• تؤكد خريطة العمق هذه البنية ثلاثية الأبعاد للوجه، وتميزه عن الصور المسطحة أو محاولات الانتحال ثنائية الأبعاد.\
• يوفر **تجربة سلسة** مع الحفاظ على **مستوى أمان عالٍ** ضد هجمات العرض مثل الصور أو الشاشات.\
|
عالي |
الخدمات المالية، والوصول إلى الحسابات، والتحقق من الهوية |
| **`Passive Liveness`** |
• يعتمد على **تحليل إطار واحد بالتعلم العميق** لكشف علامات الحيوية.\
• يفحص الصورة بحثاً عن **الشوائب والعيوب التصويرية** و**أنماط الملمس** وغيرها من المؤشرات الدقيقة التي تميز الوجه الحقيقي عن محاولة انتحاله.\
• تتحقق **شبكة عصبية التفافية (CNN)** من ملامح الوجه وتحدد الحالات الشاذة، مثل تلك الناتجة عن الصور المطبوعة أو الشاشات الرقمية.\
• يوفر تحققاً **سريعاً ومريحاً** ولكنه يقدم **مستوى أمان قياسياً**، وهو مناسب لحالات الاستخدام منخفضة المخاطر.\
|
قياسي |
سيناريوهات الاحتكاك المنخفض، وتطبيقات المستهلكين |
> [!NOTE]
>
> **الأمان المتقدم لطريقتَي 3D Flash و3D Action & Flash:**
>
> > * صُممت هاتان الطريقتان لإحباط **هجمات الانتحال المتطورة**، مثل **الأقنعة عالية الجودة** و**التزييف العميق** و**إعادة تشغيل الفيديو**.
> > * عبر إسقاط أنماط إضاءة ديناميكية وتحليل انعكاساتها، تكتشفان كيفية تفاعل الضوء مع **وجه ثلاثي الأبعاد حقيقي** مقارنة بسطح مسطح أو اصطناعي.
> > * تضيف طريقة **3D Action & Flash** طبقة أمان إضافية بإجراء عشوائي (مثل الرمش أو إيماءة الرأس)، مما يتطلب **استجابات سلوكية في الوقت الفعلي** لا يمكن للوسائط المسجلة مسبقاً أو الهويات الاصطناعية محاكاتها.
> > * أثبتت هاتان الطريقتان قدرتهما على تقديم **دقة عالية** و**معدلات قبول خاطئ منخفضة**، وهما مثاليتان للبيئات الحساسة وعالية المخاطر.تولد كل طريقة **درجة حيوية معيارية (0-100%)** بناءً على خوارزميتنا المملوكة، والتي تقيم عوامل أمان متعددة في الوقت الفعلي.### الحدود القابلة للضبطيمكنك تخصيص مستويات الأمان عبر تعيين حدود مختلفة لدرجات الحيوية. على سبيل المثال:> [!NOTE]
>
> يمكن تعديل هذه الحدود بناءً على **قدرتك على تحمل المخاطر** و**متطلبات الأمان** الخاصة بك، مما يوفر مرونة عبر مختلف حالات الاستخدام.## عمليات إعادة المحاولة والملاحظات التوجيهيةفي جلسة Didit، لا يؤدي التقاط الحيوية الذي يفشل لـ **سبب قابل للإصلاح** (إضاءة ضعيفة، أو عدم توسيط الوجه، أو الحجب، أو درجة حدية) إلى الرفض المباشر. بل يُطلب من المستخدم **إعادة المحاولة مع إرشادات محددة**، وذلك حتى عدد محاولات قابل للتهيئة.* **ميزانية المحاولات** — يتحكم المعامل `face_liveness_max_attempts` في إجمالي عدد عمليات إرسال الحيوية لكل جلسة. القيمة الافتراضية هي **3** (محاولة أولية واحدة بالإضافة إلى عمليتي إعادة محاولة)، وهي قابلة للتهيئة لكل عقدة في سير العمل (النطاق 1–3).
* **ملاحظات إعادة المحاولة** — طالما بقيت محاولات متاحة، فإن الفشل القابل لإعادة المحاولة يُبقي المستخدم في خطوة كشف الحيوية ويعيد payload يتضمن `feedback_codes` قابلة للتنفيذ (تعرضها حزم SDK للويب والهاتف المحمول كرسائل إرشادية تلقائياً):
```json theme={null}
{
"detail": "Move to a brighter, evenly lit place and try again.",
"error": "LOW_FACE_LUMINANCE",
"feedback_codes": ["LOW_FACE_LUMINANCE"],
"attempts_used": 1,
"max_attempts": 3
}
```
* **الرموز القابلة لإعادة المحاولة** — `LOW_FACE_LUMINANCE` (مظلم للغاية)، و`HIGH_FACE_LUMINANCE` (شديد السطوع)، و`NO_FACE_DETECTED`، و`LOW_FACE_QUALITY`، و`HIGH_FACE_OCCLUSION`، و`LOW_LIVENESS_SCORE`، و`MULTIPLE_FACES_DETECTED`، و`AGE_NOT_DETECTED`.
* **إعادة محاولة مضمونة لظروف الالتقاط** — تصف الرموز `LOW_FACE_LUMINANCE` و`HIGH_FACE_LUMINANCE` و`LOW_FACE_QUALITY` و`HIGH_FACE_OCCLUSION` و`NO_FACE_DETECTED` الغرفة التي يتواجد فيها المستخدم، وليس الشخص نفسه. عندما تفشل محاولة بسبب هذه الرموز وحدها، يحصل المستخدم دائماً على محاولة ثانية مع الرسالة الإرشادية المذكورة أعلاه، حتى في سير عمل تمت تهيئته بالقيمة `face_liveness_max_attempts: 1`. وتتبع جميع الرموز الأخرى الميزانية المحددة بدقة.
* **استنفاد المحاولات والاحتيال** — بمجرد استنفاد الميزانية، يتم تطبيق الحالة المحسوبة (`Declined` أو `In Review`). أما هجمات العرض المؤكدة (`LIVENESS_FACE_ATTACK`)، وتطابقات قائمة الحظر، والوجوه المكررة، فيتم **رفضها فوراً** ولا يُعاد المحاولة فيها أبداً.> [!NOTE]
>
> تنطبق عمليات إعادة المحاولة على **سير الجلسة** فقط. أما endpoint المستقل `POST /v3/passive-liveness/` فهو عديم الحالة ويُنفَّذ مرة واحدة فقط — حيث يُعيد النتيجة مباشرة دون ميزانية لإعادة المحاولة.## آلية العمل**1. التقاط فيديو سيلفي**يتم توجيه المستخدم من خلال **واجهة بسيطة وبديهية** مصممة خصيصاً لطريقة كشف الحيوية المحددة.| الفحص | الوصف |
| - | - |
| **ملاحظات فورية** | تضمن الإضاءة المناسبة، وتحديد الموضع، وتأطير الوجه |
| **فحوصات الجودة** | تراقب الضبابية، والوهج، والوضوح الأمثل للوجه |
| **التقاط تكيفي** | يتكيف مع إمكانات الأجهزة المختلفة وظروف الشبكة |
| **إرشادات الطريقة** | تعرض تعليمات خاصة بالطريقة (مثل "ارمِش الآن" لطريقة 3D Action) |**2. تحليل كشف الحيوية**تعالج خوارزميات متقدمة الوسائط الملتقطة في **الوقت الفعلي** لاكتشاف محاولات الانتحال. ويختلف التحليل باختلاف الطريقة:> [accordion] 3D Action & Flash
>
> * يتحقق من حركة المستخدم (مثل **الرمش** أو **إيماءة الرأس**) للتأكد من تنفيذها بشكل صحيح وأنها حية
> * يحلل **انعكاسات أنماط الضوء** للتحقق من البنية ثلاثية الأبعاد للوجه
> * يستخدم التعلم العميق لتقييم **التعبيرات الدقيقة** وغيرها من الإشارات السلوكية
> * يجمع بين الإشارات السلوكية والفيزيائية لتحقيق **أقوى مقاومة للانتحال**> [accordion] 3D Flash
>
> * يعالج تسلسلاً من **انعكاسات أنماط الضوء** بمعدل 30+ إطاراً في الثانية لإنشاء **خريطة عمق** مفصلة
> * يؤكد الخصائص ثلاثية الأبعاد للوجه، مما يميزه عن محاولات الانتحال المسطحة أو ثنائية الأبعاد
> * لا يتطلب أي تفاعل من المستخدم — فهو **سلبي بالكامل من منظور المستخدم**> [accordion] Passive Liveness
>
> * يطبق **التعلم العميق** على إطار واحد لاكتشاف **أنماط النسيج** و**التشوّهات**
> * تتحقق شبكة عصبية تلافيفية (CNN) من ملامح الوجه وتحدد الحالات الشاذة
> * أسرع طريقة — تعمل من خلال **التقاط صورة واحدة**يكتشف النظام متعدد الطبقات **هجمات العرض** بما في ذلك الصور والشاشات والأقنعة والتزييف العميق.**3. معالجة النتائج والتحقق منها**يقارن النظام درجة الحيوية بالـ **حدود التي قمت بتهيئتها** ويقدم النتائج فوراً.| المخرج | الوصف |
| - | - |
| **درجة الحيوية** | درجة ثقة مُطبّعة تتراوح بين 0 و100% |
| **القرار** | مقبولة، أو مرفوضة، أو قيد المراجعة بناءً على الحدود التي حددتها |
| **الطريقة** | طريقة كشف الحيوية المستخدمة (`passive`، أو `flash`، أو `action_flash`) |
| **الصورة المرجعية** | الإطار الملتقط المستخدم لفحص الحيوية |
| **التحذيرات** | أي حالات شاذة تم اكتشافها (مثل الجودة المنخفضة، أو مؤشرات الانتحال المحتملة) |يتم تسليم النتائج عبر **استجابة API**، أو **webhook**، أو يمكن عرضها في **Business Console** مع سجلات التدقيق المفصلة للامتثال.> [!TIP]
>
> يمكنك تهيئة طريقة كشف الحيوية المراد استخدامها لكل سير عمل في [Business Console](https://docs.didit.me/ar/console/workflows.md). يمكن أن تستخدم سير العمل المختلفة طرقاً مختلفة بناءً على متطلبات المخاطر لديك.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.