चेहरा मिलान रिपोर्ट: समानता स्कोर JSON

अवलोकन

चेहरा मिलान रिपोर्ट लाइवनेस के दौरान कैप्चर की गई लाइव सेल्फ़ी और एक संदर्भ छवि (आमतौर पर पहचान दस्तावेज़ से निकाली गई पोर्ट्रेट) के बीच 1:1 बायोमेट्रिक तुलना को कैप्चर करती है। यह एकल 0–100 समानता स्कोर, दोनों तुलना की गई छवियों के लिए हस्ताक्षरित URLs, संदर्भ छवि के लिए स्रोत सत्र, और मिलान द्वारा उठाई गई कोई भी चेतावनी लौटाती है। यह रिपोर्ट तब तैयार होती है जब उपयोगकर्ता किसी वर्कफ़्लो में लाइवनेस चरण और दस्तावेज़ चरण दोनों को पूरा कर लेता है (या बायोमेट्रिक प्रमाणीकरण जैसे पोर्ट्रेट-आधारित वर्कफ़्लो के लिए, केवल लाइवनेस के बाद), या सीधे स्टैंडअलोन Face Match API के माध्यम से जब आप स्वयं चेहरे की दो मनमानी छवियाँ प्रदान करते हैं। प्रत्येक रिपोर्ट का अपना status होता है — जो समग्र सत्र स्थिति से स्वतंत्र होता है — जो यह दर्शाता है कि केवल चेहरा मिलान चरण का परिणाम क्या रहा:

स्वीकृत — score समीक्षा थ्रेशोल्ड से ऊपर है और कोई ऑटो-अस्वीकार चेतावनी ट्रिगर नहीं हुई है।
समीक्षा में — score अस्वीकार और समीक्षा थ्रेशोल्ड के बीच है, या किसी स्कोर की गणना नहीं की जा सकी और face_match_not_computed_action का मान REVIEW है।
अस्वीकृत — score अस्वीकार थ्रेशोल्ड पर या उससे नीचे है, NO_REFERENCE_IMAGE ट्रिगर हुई है, या किसी स्कोर की गणना नहीं की जा सकी और face_match_not_computed_action का मान DECLINE है।
पुनः सबमिट करने का अनुरोध — किसी समीक्षक ने कंसोल से अनुरोध किया कि उपयोगकर्ता इस चरण को पुनः सबमिट करे।
पूरा नहीं हुआ — चेहरा मिलान चरण ने अभी तक कोई परिणाम नहीं दिया है (जिसमें वह समय भी शामिल है जब उपयोगकर्ता विफल कैप्चर का पुनः प्रयास कर रहा हो)।

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

चेहरा मिलान रिपोर्ट face_matches[] ऐरे के अंदर आती है — हमेशा एक JSON ऐरे, कभी भी एकल face_match ऑब्जेक्ट नहीं। यह तब तक null रहती है जब तक कि कम से कम एक चेहरा मिलान चरण ने डेटा प्रस्तुत न किया हो, और जब कोई वर्कफ़्लो एक से अधिक बार चेहरा मिलान चलाता है तो एकाधिक प्रविष्टियाँ दिखाई देती हैं। एक Adaptive Age Verification वर्कफ़्लो भी इसे तब भरता है जब पहचान सत्यापन फ़ॉलबैक चलता है: वह प्रविष्टि आयु अनुमान नोड को अपने node_id के रूप में रिपोर्ट करती है, क्योंकि वर्कफ़्लो का अपना कोई चेहरा मिलान नोड नहीं होता है।

Session decision API — GET /v3/session/{sessionId}/decision/ शीर्ष स्तर पर face_matches[] लौटाता है। सत्र निर्णय प्राप्त करें देखें।
Webhooks — चरण द्वारा डेटा प्रस्तुत करने के बाद session.status.updated payload में वही face_matches[] ऐरे शामिल होता है। Webhooks देखें।
Standalone Face Match API — सीधे 1:1 तुलनाओं के लिए, Face Match स्टैंडअलोन API देखें।

response.face_matches[0] पढ़ें और ऐरे को इटरेट करें — कुछ पुराने ट्यूटोरियल में संदर्भित एकल face_match आकार v3 निर्णय endpoint पर मौजूद नहीं है।

स्कीमा

प्रामाणिक फ़ील्ड-दर-फ़ील्ड स्कीमा डेटा मॉडल संदर्भ पृष्ठ पर उपलब्ध है। नीचे दिए गए फ़ील्ड उस प्रामाणिक स्कीमा को दर्शाते हैं।

फ़ील्ड	प्रकार	विवरण
`status`	`"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"`	चेहरा मिलान चरण की स्थिति (`FeatureStatusChoices`)।
`node_id`	string \| null	वर्कफ़्लो ग्राफ़ नोड जिसने यह रिपोर्ट तैयार की।
`score`	number 0–100 \| null	बायोमेट्रिक समानता स्कोर, 2 दशमलव स्थानों तक राउंड किया गया। जब कोई तुलना संभव न हो तो `null`।
`source_image_session_id`	string \| null	उस सत्र का UUID जिसके संग्रहीत पोर्ट्रेट ने संदर्भ (स्रोत) छवि प्रदान की — पोर्ट्रेट-आधारित प्रवाहों (बायोमेट्रिक प्रमाणीकरण, या सत्र निर्माण के समय प्रदान किए गए पोर्ट्रेट) में सेट किया जाता है। जब संदर्भ छवि उसी सत्र में कैप्चर किया गया दस्तावेज़ पोर्ट्रेट हो तो `null`।
`source_image`	string (signed URL)	संदर्भ छवि (आमतौर पर दस्तावेज़ पोर्ट्रेट)। अल्पकालिक हस्ताक्षरित URL — तुरंत डाउनलोड करें, URL को कभी भी सुरक्षित न रखें।
`target_image`	string (signed URL)	लक्षित छवि (आमतौर पर लाइवनेस सेल्फ़ी)। अल्पकालिक हस्ताक्षरित URL — तुरंत डाउनलोड करें, URL को कभी भी सुरक्षित न रखें।
`warnings[]`	array	मॉड्यूल-स्तरीय चेतावनियाँ। प्रत्येक प्रविष्टि में `feature` (हमेशा `"FACEMATCH"`), `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, और `node_id` शामिल होते हैं — चेहरा मिलान चेतावनियाँ देखें।

स्टेटस मान

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

स्थिति तय होने से पहले कम-समानता वाली विफलताओं का पुनः प्रयास किया जाता है: उपयोगकर्ता को अधिकतम face_match_max_attempts कैप्चर प्रयास मिलते हैं (डिफ़ॉल्ट रूप से 3), और केवल अंतिम प्रयास का स्कोर लागू होता है। वर्कफ़्लो नोड पर कॉन्फ़िगर किए गए कस्टम स्टेटस नियम परिणामी स्थिति को और समायोजित कर सकते हैं, जो Declined > In Review > Approved प्राथमिकता के तहत स्कोर-व्युत्पन्न स्थिति के साथ संयोजित होते हैं।

उदाहरण

स्वीकृत — स्पष्ट मिलान

{
  "face_matches": [
    {
      "status": "Approved",
      "node_id": "feature_face_match_1",
      "score": 96.42,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": []
    }
  ]
}

समीक्षा में — बॉर्डरलाइन समानता

{
  "face_matches": [
    {
      "status": "In Review",
      "node_id": "feature_face_match_1",
      "score": 65.43,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}

अस्वीकृत — तुलना करने के लिए कोई संदर्भ छवि नहीं

{
  "face_matches": [
    {
      "status": "Declined",
      "node_id": "feature_face_match_1",
      "score": null,
      "source_image_session_id": null,
      "source_image": null,
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "NO_REFERENCE_IMAGE",
          "additional_data": null,
          "log_type": "error",
          "short_description": "No source image found for performing face match",
          "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}

सुरक्षा संबंधी नोट

source_image और target_image के लिए हस्ताक्षरित URLs बायोमेट्रिक डेटा हैं और एक छोटी वैधता अवधि के बाद समाप्त हो जाते हैं। इन्हें अल्पकालिक मानें: इन्हें कैश न करें या सार्वजनिक रूप से प्रदर्शित न करें। आमतौर पर आपके एप्लिकेशन को केवल status और score की आवश्यकता होती है — अपने सर्वर पर बायोमेट्रिक डेटा को कम से कम रखने के लिए जितना संभव हो उतना कम डेटा संग्रहीत करें।

चेहरा मिलान चेतावनियाँ — चेतावनियों का पूरा enum, कारण और समाधान।
लाइवनेस रिपोर्ट — अपस्ट्रीम चरण जो लक्ष्य छवि को कैप्चर करता है।
webhook — रिपोर्ट प्राप्त करने के लिए session.status.updated सुनें।
डेटा मॉडल — चेहरा मिलान — प्रत्येक फ़ील्ड के साथ कैनोनिकल स्कीमा।

प्रमाणीकरण

सत्यापन

निगरानी

प्लेटफ़ॉर्म

चेहरा मिलान रिपोर्ट: समानता स्कोर JSON

अवलोकन

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

स्कीमा

स्टेटस मान

उदाहरण

स्वीकृत — स्पष्ट मिलान

समीक्षा में — बॉर्डरलाइन समानता

अस्वीकृत — तुलना करने के लिए कोई संदर्भ छवि नहीं

सुरक्षा संबंधी नोट

​अवलोकन

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

​स्कीमा

​स्टेटस मान

​उदाहरण

​स्वीकृत — स्पष्ट मिलान

​समीक्षा में — बॉर्डरलाइन समानता

​अस्वीकृत — तुलना करने के लिए कोई संदर्भ छवि नहीं

​सुरक्षा संबंधी नोट

​Related

अवलोकन

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

स्कीमा

स्टेटस मान

उदाहरण

स्वीकृत — स्पष्ट मिलान

समीक्षा में — बॉर्डरलाइन समानता

अस्वीकृत — तुलना करने के लिए कोई संदर्भ छवि नहीं

सुरक्षा संबंधी नोट

Related