चेहरा खोज 1:N रिपोर्ट: मिलान परिणाम JSON

अवलोकन

चेहरा खोज एक 1:N बायोमेट्रिक खोज है: Didit आपके user_image में सबसे बड़े पाए गए चेहरे को लेता है और उसे आपके एप्लिकेशन के चेहरा खोज इंडेक्स के विरुद्ध खोजता है — सत्यापन सत्रों से नामांकित चेहरे, सहेजे गए स्टैंडअलोन API कॉल, सीधे उपयोगकर्ता-प्रोफ़ाइल चेहरा अपलोड, और आपकी ब्लॉक/अनुमति सूचियाँ। यह चेहरा मिलान से अलग है, जो कि 1:1 है — चेहरा मिलान किसी विशिष्ट दस्तावेज़ पर मौजूद पोर्ट्रेट के साथ सेल्फ़ी की तुलना करता है, जबकि चेहरा खोज यह सवाल पूछता है कि “क्या हमने इस व्यक्ति को पहले कभी कहीं देखा है?”। रिपोर्ट पार्स करने से पहले दो व्यवहारों को समझना उपयोगी है:

केवल ब्लॉकलिस्ट मिलान ही अस्वीकृत करते हैं। face_search.status केवल तभी Declined होता है जब FACE_IN_BLOCKLIST या POSSIBLE_FACE_IN_BLOCKLIST चेतावनी ट्रिगर होती है। केवल डुप्लिकेट मिलान Approved लौटाते हैं — सिर्फ़ status ही नहीं, बल्कि matches और warnings की भी जाँच करें।
वैकल्पिक संग्रहण और नामांकन। जब save_api_request=true (डिफ़ॉल्ट) होता है, तो कॉल को API-प्रकार के सत्र के रूप में सहेजा जाता है और खोजे गए चेहरे को आपके चेहरा खोज इंडेक्स में नामांकित किया जाता है। चेहरा खोज कॉल द्वारा नामांकित चेहरों को भविष्य के चेहरा खोज परिणामों से बाहर रखा जाता है, ताकि बार-बार की जाने वाली खोजें कभी एक-दूसरे से मेल न खाएं। वन-शॉट क्वेरी के लिए save_api_request=false पास करें: कुछ भी संग्रहीत नहीं किया जाता है और चेहरा नामांकित नहीं होता है।

परिणाम कहाँ दिखाई देते हैं

चेहरा खोज एक स्टैंडअलोन API है। खोज परिणाम शीर्ष स्तर पर एक एकल face_search ऑब्जेक्ट के रूप में, केवल POST /v3/face-search/ रिस्पॉन्स में सिंक्रोनस रूप से लौटाए जाते हैं:

POST /v3/face-search/  ──▶  { "request_id": …, "face_search": { … }, "vendor_data": …, "metadata": …, "created_at": … }

कहीं भी कोई बहुवचन face_searches[] ऐरे नहीं है — सत्र निर्णय endpoint पर id_verifications[], aml_screenings[], और liveness_checks[] द्वारा उपयोग किया जाने वाला बहुवचन-ऐरे कन्वेंशन यहाँ लागू नहीं होता है। जब save_api_request=true (डिफ़ॉल्ट) होता है, तो कॉल को API-प्रकार के सत्र के रूप में भी सहेजा जाता है:

Business Console — सत्र आपकी सत्र सूची में खोज छवि, मिलान और चेतावनियों के साथ दिखाई देता है।
GET /v3/session/{sessionId}/decision/ — इसे लौटाए गए request_id को सत्र ID के रूप में उपयोग करके पुनः प्राप्त किया जा सकता है। सहेजा गया डेटा features[] में एक FACE_SEARCH प्रविष्टि के रूप में और संग्रहीत matches (ताज़ा हस्ताक्षरित match_image_url मानों के साथ) और warnings ले जाने वाले liveness_checks[] आइटम के रूप में दिखाई देता है — एक face_search ऑब्जेक्ट के रूप में नहीं।

जब save_api_request=false होता है, तो request_id एक अस्थायी सहसंबंध UUID होता है: सत्र कभी संग्रहीत नहीं होता है, इसलिए इसे कंसोल या निर्णय endpoint से प्राप्त नहीं किया जा सकता है।

स्कीमा

प्रामाणिक फ़ील्ड तालिकाओं के लिए डेटा मॉडल संदर्भ में चेहरा खोज देखें। नीचे दिया गया स्वरूप दर्शाता है कि रनटाइम पर endpoint वास्तव में क्या लौटाता है।

interface FaceSearchResponse {
  request_id: string;            // UUID — the persisted session id when save_api_request=true
  face_search: {
    status: 'Approved' | 'Declined';
    total_matches: number;       // 0-5, length of matches[]
    matches: FaceSearchMatch[];  // capped at 5, ordered by similarity
    user_image: {                // always present
      entities: {
        bbox: [number, number, number, number];
        confidence: number;      // 0-1, one entry per detected face
      }[];
      best_angle: 0 | 90 | 180 | 270;
    };
    warnings: Warning[];
  };
  vendor_data: string | null;    // echoed from the request
  metadata: object | null;       // echoed from the request
  created_at: string;            // ISO 8601, e.g. "2026-06-12T01:04:42.763237+00:00"
}

interface FaceSearchMatch {
  session_id: string | null;     // UUID of the matched session; null for non-session matches
  session_number: number | null; // Console-friendly number; null for non-session matches
  similarity_percentage: number; // 0-100
  source: 'session' | 'imported' | 'list_entry' | 'retained_template';
  vendor_data: string | null;    // the matched session's, imported profile's, or retained template's User vendor_data
  vendor_user_id: string | null; // UUID of the linked User; null for list_entry matches and sessions without a User
  biometric_template_id: string | null; // set only for retained_template matches
  verification_date: string | null;  // "YYYY-MM-DDThh:mm:ssZ"; null for list_entry matches; the retention date for retained_template matches
  user_details: {
    full_name: string | null;
    document_type: string | null;
    document_number: string | null;
  } | null;                      // null when the matched session has no document data
  match_image_url: string | null; // signed URL when save_api_request=true; raw storage path otherwise; null for retained_template matches
  status: 'Approved' | 'Declined' | 'In Review' | null;  // the matched session's status
  is_blocklisted: boolean;
  is_allowlisted: boolean;
  api_service: 'ID_VERIFICATION' | 'FACE_MATCH' | 'AGE_ESTIMATION' | 'POA' | 'AML'
             | 'PASSIVE_LIVENESS' | 'DATABASE_VALIDATION' | 'PHONE_VERIFICATION'
             | 'EMAIL_VERIFICATION' | null;  // null when the match comes from a workflow session
}

interface Warning {
  risk: string;
  feature: 'LIVENESS';           // always LIVENESS on this endpoint
  additional_data: object | null;
  log_type: 'error' | 'warning' | 'information';
  short_description: string;
  long_description: string;
}

फ़ील्ड नोट्स:

matches[] समानता की न्यूनतम सीमा से ऊपर 5 प्रविष्टियों तक सीमित है, जो घटती हुई समानता के क्रम में व्यवस्थित होती हैं (search_type=blocklisted_or_approved ब्लॉकलिस्ट की गई प्रविष्टियों को पहले, फिर अनुमति सूची वाली, फिर समानता को रैंक करता है)।
source आपको बताता है कि मिलान किया गया चेहरा कहाँ से नामांकित किया गया था: session — एक सत्यापन सत्र या एक सहेजी गई स्टैंडअलोन API कॉल; imported — सीधे उपयोगकर्ता प्रोफ़ाइल पर अपलोड किया गया चेहरा; list_entry — आपकी किसी सूची से जुड़ा चेहरा; retained_template — एक छवि-मुक्त बायोमेट्रिक टेम्पलेट जिसे एप्लिकेशन ने स्रोत सत्र को हटाने के बाद बनाए रखा था। imported, list_entry, और retained_template मिलानों के लिए session_id, session_number, status, और api_service का मान null होता है।
retained_template मिलान vendor_user_id, vendor_data, और biometric_template_id ले जाते हैं, और match_image_url, user_details, तथा सत्र से संबंधित हर चीज़ के लिए हमेशा null होते हैं: जिस सत्र ने चेहरा बनाया था वह अब मौजूद नहीं है और टेम्पलेट में कोई छवि या पहचान डेटा नहीं होता है। बनाए रखे गए टेम्पलेट के लिए is_blocklisted हमेशा false होता है; एक ब्लॉकलिस्ट किए गए चेहरे की रिपोर्ट list_entry मिलान के रूप में अलग से दी जाती है। DELETE /v3/biometric-templates/{biometric_template_id}/ के साथ टेम्पलेट को पर्ज करें।
api_service मिलान किए गए सत्र का स्टैंडअलोन API प्रकार है (अपरकेस, उदा. PASSIVE_LIVENESS) और जब मिलान किया गया चेहरा किसी सामान्य वर्कफ़्लो सत्यापन सत्र से आया हो तो यह null होता है।
user_details मिलान किए गए सत्र के दस्तावेज़ सत्यापन से आता है। source: imported मिलानों के लिए इसे इसके बजाय उपयोगकर्ता प्रोफ़ाइल से पॉप्युलेट किया जाता है (full_name सेट, document_type/document_number null); जब कोई पहचान डेटा मौजूद नहीं होता है (उदाहरण के लिए केवल-लाइवनेस सत्र) तो यह null होता है।
चेतावनियों का स्वरूप वर्कफ़्लो चेतावनियों की तुलना में संक्षिप्त होता है: कोई node_id नहीं होता है। प्रलेखित रिस्पॉन्स अनुबंध (FaceSearchResponseSerializer) पाँच फ़ील्ड risk, additional_data, log_type, short_description, long_description घोषित करता है; रनटाइम payload अतिरिक्त रूप से feature ले जाता है, जो यहाँ हमेशा "LIVENESS" होता है। चेहरा खोज चेतावनियाँ देखें।
एक ही उपयोगकर्ता के मिलानों को बाहर नहीं रखा जाता है — वर्कफ़्लो डुप्लिकेट डिटेक्शन के विपरीत, स्टैंडअलोन endpoint समान vendor_data वाले पिछले सत्रों को फ़िल्टर नहीं करता है, इसलिए लौटने वाला वैध उपयोगकर्ता अपने स्वयं के पुराने सत्रों से मेल खाता है।

स्थिति मान

शीर्ष-स्तरीय face_search.status को warnings[] से प्राप्त किया जाता है। मिलान-स्तरीय status मिलान किए गए सत्र के सत्यापन परिणाम को दर्शाता है और स्वतंत्र होता है।

मान	यह कब दिखाई देता है
`Approved`	कोई ब्लॉकलिस्ट चेतावनी ट्रिगर नहीं हुई। इसमें वह मामला भी शामिल है जहाँ डुप्लिकेट मिलान पाए गए थे — डुप्लिकेट केवल सूचनात्मक संकेत हैं, अस्वीकृति नहीं।
`Declined`	एक `FACE_IN_BLOCKLIST` या `POSSIBLE_FACE_IN_BLOCKLIST` चेतावनी ट्रिगर हुई — खोज छवि आपकी चेहरे की ब्लॉकलिस्ट में मौजूद किसी चेहरे से मेल खाती है।

नोट: जब खोज छवि में कोई पता लगाने योग्य चेहरा नहीं होता है, तो API face_search ऑब्जेक्ट बनने से पहले {"error": "No face detected in the image"} के साथ HTTP 400 लौटाता है — उस मामले के लिए कोई Declined स्थिति नहीं होती है। अपर्याप्त क्रेडिट किसी भी छवि प्रसंस्करण से पहले HTTP 403 लौटाते हैं।

उदाहरण

Approved — डुप्लिकेट मिलान, कोई ब्लॉकलिस्ट नहीं

{
  "request_id": "5e0c3a1f-7b2d-4c8e-9f10-2a3b4c5d6e7f",
  "face_search": {
    "status": "Approved",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
        "session_number": 1024,
        "similarity_percentage": 87.42,
        "source": "session",
        "vendor_data": "user-9",
        "verification_date": "2025-11-20T09:15:00Z",
        "user_details": {
          "full_name": "Jane Marie Doe",
          "document_type": "Passport",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/9c8b7a6d/reference.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": false,
        "is_allowlisted": false,
        "api_service": null
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "DUPLICATED_FACE",
        "feature": "LIVENESS",
        "additional_data": {
          "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
          "duplicated_session_number": 1024,
          "api_service": null
        },
        "log_type": "information",
        "short_description": "Duplicated face from other approved session",
        "long_description": "The system identified a duplicated face from another approved session, requiring further investigation."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}

Declined — ब्लॉकलिस्ट मिलान

{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "face_search": {
    "status": "Declined",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "session_number": 323442,
        "similarity_percentage": 99.99,
        "source": "session",
        "vendor_data": "user-1",
        "verification_date": "2025-01-01T00:00:00Z",
        "user_details": {
          "full_name": "Jane Marie Doe",
          "document_type": "ID",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/3f6a1c2e/reference.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": true,
        "is_allowlisted": false,
        "api_service": "PASSIVE_LIVENESS"
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "FACE_IN_BLOCKLIST",
        "feature": "LIVENESS",
        "additional_data": {
          "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
          "blocklisted_session_number": 323442,
          "api_service": "PASSIVE_LIVENESS"
        },
        "log_type": "error",
        "short_description": "Face in blocklist",
        "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}

प्रमाणीकरण

सत्यापन

निगरानी

प्लेटफ़ॉर्म

चेहरा खोज 1:N रिपोर्ट: मिलान परिणाम JSON

अवलोकन

परिणाम कहाँ दिखाई देते हैं

स्कीमा

स्थिति मान

उदाहरण

Approved — डुप्लिकेट मिलान, कोई ब्लॉकलिस्ट नहीं

Declined — ब्लॉकलिस्ट मिलान

संबंधित

​अवलोकन

​परिणाम कहाँ दिखाई देते हैं

​स्कीमा

​स्थिति मान

​उदाहरण

​Approved — डुप्लिकेट मिलान, कोई ब्लॉकलिस्ट नहीं

​Declined — ब्लॉकलिस्ट मिलान

​संबंधित

अवलोकन

परिणाम कहाँ दिखाई देते हैं

स्कीमा

स्थिति मान

उदाहरण

Approved — डुप्लिकेट मिलान, कोई ब्लॉकलिस्ट नहीं

Declined — ब्लॉकलिस्ट मिलान

संबंधित