> ## 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.

# लाइवनेस रिपोर्ट: स्कोर, विधि और मिलान

> Didit की लाइवनेस रिपोर्ट: स्थिति, विश्वास स्कोर, डिटेक्शन विधि, आयु अनुमान, क्रॉस-सत्र चेहरा मिलान और रिस्पॉन्स विवरण समझें।

## अवलोकन

**लाइवनेस रिपोर्ट** Didit द्वारा यह सत्यापित करते समय देखी गई हर चीज़ को कैप्चर करती है कि कैमरे के सामने एक वास्तविक, जीवित व्यक्ति मौजूद था — कोई प्रिंट किया हुआ फ़ोटो, स्क्रीन रीप्ले, या डीपफ़ेक नहीं। इसमें लाइवनेस विधि, 0–100 विश्वास स्कोर, संदर्भ सेल्फ़ी और कैप्चर वीडियो, एक वैकल्पिक आयु अनुमान, पैसिव-लाइवनेस गुणवत्ता मेट्रिक्स, और आपके एप्लिकेशन के इतिहास और ब्लॉकलिस्ट के विरुद्ध क्रॉस-सत्र चेहरा मिलान शामिल हैं।

यह रिपोर्ट तब तैयार की जाती है जब उपयोगकर्ता वर्कफ़्लो में लाइवनेस चरण पूरा कर लेता है (या स्टैंडअलोन फ़ेस endpoint पर कॉल करता है)। Didit तीन लाइवनेस विधियों (सक्रिय 3D, फ़्लैशिंग, या पैसिव) में से एक चलाता है, कैप्चर को स्कोर करता है, ज्ञात स्पूफिंग पैटर्न की जाँच करता है, और आपके एप्लिकेशन में देखे गए प्रत्येक अन्य चेहरे के साथ चेहरे की बायोमेट्रिक तुलना करता है।

प्रत्येक रिपोर्ट का अपना `status` होता है — जो समग्र सत्र स्थिति से स्वतंत्र होता है — और यह दर्शाता है कि केवल लाइवनेस चरण का समाधान कैसे हुआ:

* **स्वीकृत** — चेहरा डिटेक्ट हुआ, लाइवनेस स्कोर समीक्षा थ्रेशोल्ड से ऊपर है, कोई ऑटो-डिक्लाइन चेतावनी ट्रिगर नहीं हुई।
* **समीक्षाधीन** — समीक्षा के लिए रूट की गई एक या अधिक चेतावनियाँ ट्रिगर हुईं, या स्कोर समीक्षा थ्रेशोल्ड पर या उससे कम है लेकिन अस्वीकार थ्रेशोल्ड से ऊपर है।
* **अस्वीकृत** — एक ऑटो-डिक्लाइन स्थिति ट्रिगर हुई (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, या आयु-अनुमान प्रवाह पर आयु जोखिम), एक कॉन्फ़िगर करने योग्य चेतावनी को अस्वीकृति के लिए रूट किया गया था, या स्कोर अस्वीकार थ्रेशोल्ड पर या उससे नीचे है।
* **पूरा नहीं हुआ** — उपयोगकर्ता ने लाइवनेस चरण कभी पूरा नहीं किया।

## API रिस्पॉन्स में यह कहाँ दिखाई देता है

लाइवनेस रिपोर्ट `GET /v3/session/{sessionId}/decision/` में `liveness_checks[]` के रूप में दिखाई देती है — **हमेशा एक JSON ऐरे**, कभी भी एकवचन `liveness` ऑब्जेक्ट नहीं। एकाधिक प्रविष्टियाँ तब दिखाई देती हैं जब कोई वर्कफ़्लो लाइवनेस को एक से अधिक बार चलाता है (उदाहरण के लिए प्राथमिक जाँच के साथ एक पुनः कैप्चर)।

* **सत्र निर्णय API** — `GET /v3/session/{sessionId}/decision/` शीर्ष स्तर पर `liveness_checks[]` लौटाता है। देखें [सत्र निर्णय पुनः प्राप्त करें](https://docs.didit.me/hi/sessions-api/retrieve-session.md)।
* **वेबहुक्स** — चरण द्वारा डेटा तैयार करने के बाद `session.status.updated` payloads में समान `liveness_checks[]` ऐरे शामिल होता है। देखें [वेबहुक्स](https://docs.didit.me/hi/integration/webhooks.md)।
* **स्टैंडअलोन लाइवनेस API** — देखें [स्टैंडअलोन लाइवनेस API](https://docs.didit.me/hi/standalone-apis/passive-liveness.md)।

> [!NOTE]
>
> `response.liveness_checks[0]` पढ़ें और ऐरे की प्रत्येक प्रविष्टि पर काम करें — एकवचन `liveness` संरचना जिसका उल्लेख कुछ पुराने ट्यूटोरियल में किया गया था, v3 निर्णय endpoint पर मौजूद नहीं है।

## Schema

कैनोनिकल फ़ील्ड-दर-फ़ील्ड स्कीमा [Data models](https://docs.didit.me/hi/reference/data-models.md#लाइवनेस-जाँच) संदर्भ पृष्ठ पर उपलब्ध है। नीचे दिए गए फ़ील्ड उस कैनोनिकल स्कीमा को दर्शाते हैं।

| फ़ील्ड | प्रकार | विवरण |
| - | - | - |
| `status` | `"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"` | लाइवनेस-चरण स्थिति (नीचे देखें)। |
| `node_id` | string \| null | वर्कफ़्लो ग्राफ़ नोड जिसने यह रिपोर्ट जनरेट की। |
| `method` | `"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"` | लाइवनेस विधि जिसके द्वारा यह कैप्चर तैयार किया गया। |
| `score` | number 0–100 \| null | लाइवनेस विश्वास स्कोर, 2 दशमलव स्थानों तक राउंड किया गया। |
| `reference_image` | string (हस्ताक्षरित URL) \| null | कैप्चर से निकाली गई संदर्भ सेल्फ़ी। सीमित वैधता विंडो वाला हस्ताक्षरित URL। |
| `video_url` | string (हस्ताक्षरित URL) \| null | पूरा लाइवनेस कैप्चर वीडियो (सक्रिय विधियाँ)। सीमित वैधता विंडो वाला हस्ताक्षरित URL। |
| `age_estimation` | number \| null | संदर्भ छवि में सबसे बड़े चेहरे की वर्षों में अनुमानित आयु। |
| `face_quality` | number 0–100 \| null | पैसिव-लाइवनेस चेहरे की गुणवत्ता, प्रतिशत में सामान्यीकृत। केवल तभी भरा जाता है जब `method = "PASSIVE"` हो। |
| `face_luminance` | number 0–100 \| null | पैसिव-लाइवनेस चेहरे का प्रकाश स्तर, 0–255 से प्रतिशत में सामान्यीकृत। केवल तभी भरा जाता है जब `method = "PASSIVE"` हो। |
| `matches[]` | array | क्रॉस-सत्र चेहरा मिलान (नीचे देखें)। |
| `warnings[]` | array | मॉड्यूल-स्तरीय चेतावनियाँ — [Liveness warnings](https://docs.didit.me/hi/core-technology/liveness/warnings-liveness.md) देखें। प्रत्येक प्रविष्टि [Warning object](https://docs.didit.me/hi/reference/data-models.md#चेतावनी-ऑब्जेक्ट) संरचना (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`) का पालन करती है। |

### क्रॉस-सत्र चेहरा मिलान

`matches[]` आपके एप्लिकेशन के इतिहास में उन चेहरों को सूचीबद्ध करता है जो इस सेल्फ़ी के विरुद्ध बायोमेट्रिक समानता थ्रेशोल्ड को पार कर गए — अधिकतम 5 प्रविष्टियाँ, पहले ब्लॉकलिस्ट और अनुमति-सूची वाले चेहरे, फिर अवरोही समानता क्रम में। पात्र उम्मीदवार ब्लॉकलिस्ट किए गए चेहरे, अनुमति-सूची वाले चेहरे, `Approved` सत्रों के चेहरे, और आपके वेंडर उपयोगकर्ताओं के विरुद्ध इंपोर्ट किए गए चेहरे हैं। एक ही उपयोगकर्ता से संबंधित चेहरे (समान `vendor_data`, या उपलब्ध होने पर समान वेंडर-उपयोगकर्ता) को **पूरी** खोज से बाहर रखा जाता है — डुप्लिकेट डिटेक्शन और ब्लॉकलिस्ट स्क्रीनिंग दोनों से।

प्रत्येक प्रविष्टि में शामिल हैं:

| फ़ील्ड | प्रकार | विवरण |
| - | - | - |
| `session_id` | string (UUID) \| null | मेल खाने वाला सत्र। जब `source` का मान `imported` या `list_entry` हो, तो यह `null` होता है। |
| `session_number` | number \| null | मेल खाने वाले सत्र के लिए अनुक्रमिक सत्र संख्या। गैर-सत्र स्रोतों के लिए `null`। |
| `similarity_percentage` | number 0–100 | बायोमेट्रिक समानता स्कोर, 0–100 तक सीमित। |
| `vendor_data` | string \| null | मेल खाने वाले सत्र (या इंपोर्ट किए गए चेहरों के लिए वेंडर उपयोगकर्ता) से आपका संदर्भ डेटा। |
| `verification_date` | string (ISO 8601) \| null | मेल खाने वाला सत्र (या इंपोर्ट किया गया चेहरा) कब बनाया गया था। |
| `user_details` | object \| null | मेल खाने वाले सत्र के KYC से `{ full_name, document_type, document_number }`। इंपोर्ट किए गए चेहरे केवल `full_name` भरते हैं (दोनों दस्तावेज़ फ़ील्ड `null` होते हैं); जब कोई विवरण रिकॉर्ड में नहीं होता है तो `null` होता है। |
| `match_image_url` | string (हस्ताक्षरित URL) \| null | मेल खाने वाले सत्र, इंपोर्ट किए गए चेहरे, या सूची प्रविष्टि से संदर्भ चेहरा। |
| `status` | string \| null | मेल खाने वाले सत्र की स्थिति (उदा. `"Approved"`)। गैर-सत्र स्रोतों के लिए `null`। |
| `is_blocklisted` | boolean | यदि मेल खाने वाला चेहरा आपकी चेहरे की ब्लॉकलिस्ट में है तो `true`। |
| `is_allowlisted` | boolean | यदि मेल खाने वाला चेहरा आपकी चेहरे की अनुमति-सूची में है तो `true` (डुप्लिकेट-चेहरा कार्रवाइयों को छोड़ दिया जाता है)। |
| `api_service` | string \| null | तब सेट होता है जब मेल खाने वाला चेहरा किसी स्टैंडअलोन API कॉल (उदा. `"PASSIVE_LIVENESS"`) से आया हो; वर्कफ़्लो सत्रों और गैर-सत्र स्रोतों के लिए `null`। |
| `source` | `"session" \| "imported" \| "list_entry"` | मेल खाने वाला चेहरा कहाँ से आया: दूसरा सत्यापन सत्र, किसी वेंडर उपयोगकर्ता के विरुद्ध अपलोड किया गया चेहरा, या संगठन द्वारा प्रबंधित अनुमति/ब्लॉक सूची का चेहरा। |

## स्थिति मान

स्थितियाँ साझा सुविधा-स्थिति enum (`FeatureStatusChoices`) से आती हैं।

| स्थिति | अर्थ | डाउनस्ट्रीम प्रभाव |
| - | - | - |
| `Approved` | चेहरे का पता चला, लाइवनेस स्कोर समीक्षा थ्रेशोल्ड से ऊपर है, कोई ऑटो-अस्वीकृति चेतावनी ट्रिगर नहीं हुई। | एक सफल लाइवनेस जाँच के रूप में गिना जाता है। |
| `In Review` | स्कोर समीक्षा थ्रेशोल्ड पर या उससे नीचे लेकिन अस्वीकृति थ्रेशोल्ड से ऊपर है, या समीक्षा के लिए रूट की गई कोई चेतावनी ट्रिगर हुई। | समीक्षक द्वारा कार्रवाई किए जाने तक सत्र भी `In Review` में चला जाता है। |
| `Declined` | एक ऑटो-अस्वीकृति जोखिम ट्रिगर हुआ (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, या आयु-अनुमान प्रवाहों पर आयु जोखिम), एक कॉन्फ़िगर करने योग्य चेतावनी को अस्वीकृति के लिए रूट किया गया था, या स्कोर अस्वीकृति थ्रेशोल्ड पर या उससे नीचे है। | सत्र अस्वीकृत कर दिया जाता है जब तक कि कोई अन्य स्वीकृत शाखा वर्कफ़्लो को संतुष्ट न करे। |
| `Not Finished` | उपयोगकर्ता ने लाइवनेस चरण छोड़ दिया (या पुनः प्रयास करने योग्य कैप्चर विफलता किसी अन्य प्रयास की प्रतीक्षा कर रही है)। | लाइवनेस शाखा ने कोई परिणाम नहीं दिया। |
| `Resub Requested` | एक समीक्षक ने कंसोल से इस चरण को फिर से सबमिट करने का अनुरोध किया। | अस्थायी — उपयोगकर्ता द्वारा दोबारा कैप्चर करने के बाद बदल दिया जाता है। |

## उदाहरण

### Approved — स्वच्छ सक्रिय-3D कैप्चर

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "Approved",
      "node_id": "liveness_primary",
      "method": "ACTIVE_3D",
      "score": 92.4,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": "https://<media-host>/.../liveness.mp4?signature=...",
      "age_estimation": 24.3,
      "face_quality": null,
      "face_luminance": null,
      "matches": [],
      "warnings": []
    }
  ]
}
```

### In Review — पैसिव लाइवनेस, कम गुणवत्ता वाला कैप्चर और संभावित डुप्लिकेट

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "In Review",
      "node_id": "liveness_primary",
      "method": "PASSIVE",
      "score": 76.1,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": 31.0,
      "face_quality": 12.4,
      "face_luminance": 18.7,
      "matches": [
        {
          "session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
          "session_number": 123,
          "similarity_percentage": 96.8,
          "vendor_data": "user-555",
          "verification_date": "2024-07-15T10:23:45Z",
          "user_details": {
            "full_name": "John Smith",
            "document_type": "Passport",
            "document_number": "SAMPLE-DOC-12345"
          },
          "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
          "status": "Approved",
          "is_blocklisted": false,
          "is_allowlisted": false,
          "api_service": null,
          "source": "session"
        }
      ],
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_QUALITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face quality",
          "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_LUMINANCE",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face luminance",
          "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "POSSIBLE_DUPLICATED_FACE",
          "additional_data": {
            "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
            "duplicated_session_number": 123,
            "api_service": null
          },
          "log_type": "warning",
          "short_description": "Possible duplicated face from other approved session",
          "long_description": "The system identified a possible duplicate face from another approved session, requiring further investigation.",
          "node_id": "liveness_primary"
        }
      ]
    }
  ]
}
```

यहाँ चेहरे की गुणवत्ता (12.4) डिफ़ॉल्ट समीक्षा थ्रेशोल्ड (15) से नीचे है, ल्यूमिनेन्स (18.7) डिफ़ॉल्ट न्यूनतम (20) से नीचे है, और वर्कफ़्लो की डुप्लिकेट-चेहरा कार्रवाई समीक्षा पर सेट है — इसलिए तीनों चेतावनियों में `log_type: "warning"` है और रिपोर्ट की स्थिति `In Review` हो जाती है।

## सुरक्षा नोट

लाइवनेस वीडियो और सेल्फ़ी बायोमेट्रिक डेटा हैं — हस्ताक्षरित URL अस्थायी होते हैं और समाप्त हो जाते हैं (डिफ़ॉल्ट रूप से 4 घंटे बाद)। इन्हें अल्पकालिक समझें: इन्हें कैश न करें या सार्वजनिक रूप से प्रदर्शित न करें। आमतौर पर आपके एप्लिकेशन को केवल `status`, `score`, और चेतावनियों की आवश्यकता होती है — अपने सर्वर पर बायोमेट्रिक डेटा को न्यूनतम रखने के लिए यथासंभव कम जानकारी स्टोर करें।

## संबंधित

* [लाइवनेस चेतावनियाँ](https://docs.didit.me/hi/core-technology/liveness/warnings-liveness.md) — चेतावनियों का पूरा enum, कारण और समाधान।
* [Webhooks](https://docs.didit.me/hi/integration/webhooks.md) — रिपोर्ट प्राप्त करने के लिए `session.status.updated` सुनें।
* [डेटा मॉडल — लाइवनेस चेक](https://docs.didit.me/hi/reference/data-models.md#लाइवनेस-जाँच) — प्रत्येक फ़ील्ड के साथ कैनोनिकल स्कीमा।
* [चेहरा मिलान रिपोर्ट](https://docs.didit.me/hi/core-technology/face-match/report-face-match.md) — दस्तावेज़ के पोर्ट्रेट के विरुद्ध सहायक 1:1 चेहरा मिलान।


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.