Cerca Facial 1:N: Trobant Tots els Comptes Controlats per una Persona (CA)

Un operador que gestiona quaranta comptes a la vostra plataforma té quaranta adreces de correu electrònic, probablement quaranta instruments de pagament i possiblement quaranta dispositius. El que no tenen són quaranta cares.

Si alguna part del vostre flux d'accés captura un selfie, ja teniu l'únic identificador que és genuïnament car de multiplicar. La cerca facial 1:N és la trucada que l'utilitza: una sol·licitud, una cara, i torna cada compte del vostre propi sistema que la mateixa persona ha verificat.

És gratuït amb la verificació d'identitat de Didit, retorna en menys de dos segons i s'executa automàticament durant la prova de vida dins d'una sessió de verificació.

Punts clau

• POST /v3/face-search/ cerca una cara enfront de les cares que la vostra pròpia aplicació ha registrat (sessions executades amb save_api_request=true), no un índex global compartit.
• Les coincidències tornen amb les vostres pròpies vendor_data a cadascuna, de manera que els resultats es mapen directament als vostres ID de compte.
• Dos modes: most_similar per a la deduplicació i usuaris recurrents, blocklisted_or_approved per al cribratge de llistes negres.
• status és "Declined" només en cas de coincidència amb una llista negra. Els duplicats retornen "Approved" amb un avís DUPLICATED_FACE: informatiu per disseny, perquè la política de deduplicació és vostra.
• La resposta és un objecte face_search singular, no una matriu. Això confon la gent.
• Gratuït amb la verificació de Didit. Resposta en menys de dos segons. S'executa automàticament durant la prova de vida.

Què significa 1:N i per què és l'eina adequada

Una coincidència facial 1:1 respon a la pregunta "és aquesta la persona del document?". Aquesta és una pregunta de verificació, i és el que s'executa durant l'incorporació.

Una cerca 1:N respon a una pregunta diferent: "de totes les persones que ja he verificat, és aquesta una d'elles?". Entra una imatge i surten totes les coincidències del vostre índex.

Per a l'abús coordinat de comptes, la segona pregunta és la que importa. L'informe d'Anthropic sobre campanyes de destil·lació descrivia l'atribució basada en senyals relacionals: mètodes de pagament compartits, sincronització coordinada, infraestructura compartida. Una cerca biomètrica 1:N és la mateixa classe de senyal, obtinguda de l'identificador més car que un operador ha de multiplicar.

L'índex és vostre. La cerca facial s'executa contra les cares que la vostra pròpia aplicació va registrar mitjançant verificacions prèvies (sessions amb save_api_request=true, o prova de vida passiva amb save_api_request=true). No és una cerca entre els usuaris d'altres clients de Didit. Si no heu registrat cares, no hi ha res a cercar.

L'API

Sol·licitud

curl -X POST 'https://verification.didit.me/v3/face-search/' \
  -H 'x-api-key: YOUR_API_KEY' \
  -F 'user_image=@./selfie.jpg' \
  -F 'search_type=most_similar' \
  -F 'save_api_request=true' \
  -F 'vendor_data=acct_8842'

multipart/form-data, autenticat amb x-api-key.

Obligatori: user_image — jpg, jpeg, png, tiff o webp, màxim 5 MB. No s'accepten PDF. La imatge ha de contenir almenys una cara detectable; quan hi ha diverses, la caixa delimitadora més gran és la que guanya.

Opcional:

• search_type — most_similar (per defecte) per a la deduplicació i detecció d'usuaris recurrents, o blocklisted_or_approved per al cribratge de llistes negres.
• save_api_request — inscriure aquesta imatge al vostre índex.
• vendor_data — el vostre propi identificador per al subjecte.

Resposta

La resposta conté un objecte face_search singular. La majoria de les funcions de Didit retornen matrius plurals, així que aquesta és l'única forma que val la pena llegir amb atenció abans d'escriure l'analitzador.

{
  "request_id": "...",
  "face_search": {
    "status": "Approved",
    "total_matches": 12,
    "matches": [
      {
        "session_id": "...",
        "session_number": 4471,
        "similarity_percentage": 97.4,
        "vendor_data": "acct_3310",
        "verification_date": "2026-06-02T09:14:00Z",
        "user_details": { },
        "match_image_url": "...",
        "status": "Approved",
        "is_blocklisted": false
      }
    ],
    "user_image": { "entities": [] },
    "warnings": []
  }
}

Els camps que contenen la investigació:

• total_matches — quants comptes comparteixen aquesta cara.
• vendor_data a cada coincidència — el vostre identificador, de manera que una llista de coincidències és immediatament una llista de comptes.
• similarity_percentage — la força de cada coincidència individual.
• verification_date — la línia de temps. Dotze comptes verificats en onze mesos es llegeixen de manera diferent de dotze verificats en una tarda.
• is_blocklisted — si aquesta coincidència ja es troba a la vostra llista negra.
• session_id — el pivot cap a tot el que la sessió va capturar, inclosos els seus avisos de dispositiu i de xarxa.

Semàntica d'estat

Aquest és el comportament més important de tot l'endpoint:

status és "Declined" només quan es troba almenys una coincidència amb la llista negra. Les coincidències duplicades pures retornen "Approved".

Un duplicat no és un rebuig. És informació. Didit es nega deliberadament a prendre la decisió de deduplicació per vosaltres, perquè els duplicats tenen explicacions legítimes i només vosaltres coneixeu les regles del vostre producte.

Advertiments

Advertiment	Significat
FACE_IN_BLOCKLIST	Coincidència definitiva amb la llista negra — rebutjar
POSSIBLE_FACE_IN_BLOCKLIST	Coincidència límit per sota del llindar dur — enviar a revisió manual
DUPLICATED_FACE	Aquesta cara ja està verificada amb una vendor_data diferent
POSSIBLE_DUPLICATED_FACE	Duplicat límit
MULTIPLE_FACES_DETECTED	Més d'una cara a la imatge enviada

Modes de fallada

• HTTP 400 — no s'ha detectat cap cara a user_image. Demaneu una nova presa.
• HTTP 403 — sense crèdits.
• status: "Declined" amb FACE_IN_BLOCKLIST — coincidència definitiva. Rebutjar.
• POSSIBLE_FACE_IN_BLOCKLIST — per sota del llindar dur. Revisió manual.
• DUPLICATED_FACE — ja verificat amb una vendor_data diferent. Fusionar, bloquejar o permetre segons la vostra política.

El camí automàtic

Sovint no cal trucar a l'endpoint. La cerca facial s'executa automàticament durant la prova de vida dins d'una sessió de verificació:

• La biometria facial es compara amb tots els usuaris verificats prèviament.
• Els possibles comptes duplicats s'identifiquen per similitud facial.
• Les coincidències s'assenyalen segons els vostres llindars de similitud configurats.
• Les cares es comproven amb la vostra llista negra, i una coincidència amb la llista negra rebutja automàticament la verificació.

Així, per a qualsevol nivell on ja executeu la verificació completa, la detecció de duplicats s'inclou sense cost addicional i sense trucades addicionals. L'endpoint autònom és per als casos que el flux de la sessió no cobreix: investigar un compte després dels fets, cribrar una imatge que heu obtingut d'una altra manera o canviar search_type per executar una cerca centrada en la llista negra sobre una imatge que ja teniu.

Convertir coincidències en un mapa d'actors

El flux de treball pràctic, començant per un compte sospitós:

1. Cerca la cara. total_matches: 12 — dotze comptes, una persona.
2. Llegeix les vendor_data. Dotze dels teus propis ID de compte, sense necessitat d'unió.
3. Llegeix la línia de temps. Agrupa els valors de verification_date. Els comptes creats en ràfegues són operacionalment diferents dels comptes creats al llarg dels anys.
4. Pivota sobre session_id. Extreu els avisos de dispositiu i de xarxa de cada sessió. Les cares que comparteixen DUPLICATED_DEVICE_FINGERPRINT estressen el grup; els comptes en dispositius no relacionats poden ser un arranjament diferent.
5. Expandeix. Els dispositius i els rangs d'IP que apareixen al pas 4 arrossegaran comptes que la cerca facial va passar per alt, perquè una persona diferent va completar aquestes comprovacions.
6. Decideix una vegada, aplica'l a tots els identificadors. Si el grup es confirma com a abús, publica el reference_session_id confirmat a cada llista negra de tipus d'entrada que t'interessi: cara, dispositiu, IP, correu electrònic, telèfon, document. És una trucada per llista, i cada trucada extreu automàticament el valor correcte d'aquesta sessió, de manera que no es torna a escriure res a mà.

Sis passos, un punt de partida i cap inspecció ràpida enlloc. La capa de trànsit et diu alguna cosa no va bé amb aquest compte. Això et diu quants comptes són realment.

Val la pena afirmar-ho clarament: una cerca facial 1:N no impedeix l'extracció de models i no la detecta. La cerca facial no té visibilitat del vostre trànsit API. Resol comptes a persones, que és el que us permet actuar sobre una alerta en tot un clúster en lloc d'una fila. Els controls de sortida a nivell de model i la detecció semàntica del trànsit són capes separades i segueixen sent responsabilitat del proveïdor del model.

Casos d'ús

Plataformes d'API d'IA que resolen una alerta de comportament en el conjunt complet de comptes que controla un operador.

Abús de nivell gratuït i de crèdit — una persona, molts comptes de prova, és el mateix problema de detecció amb menys riscos.

Mercats i plataformes de serveis que detecten venedors, conductors o missatgers prohibits que es tornen a registrar.

iGaming que aplica les regles de compte únic i autoexclusió, on un jugador exclòs que torna és una fallada regulatòria, no només un cas d'abús.

Serveis financers que identifiquen xarxes d'identitat sintètica on una cara real es distribueix entre moltes identitats fabricades.

Preguntes freqüents

El meu índex facial es comparteix amb altres clients de Didit?

No. La cerca facial s'executa contra l'índex que la vostra pròpia aplicació va construir mitjançant les vostres pròpies verificacions. No és una cerca entre clients.

Què controla que una cara entri a l'índex?

save_api_request=true en una sessió de verificació o una trucada de prova de vida passiva. Vosaltres decidiu què s'inscriu i controleu la retenció, d'acord amb el vostre propi avís de privadesa i base legal per al processament de dades biomètriques.

Quin llindar de similitud hauria d'utilitzar?

Tingueu en compte on s'aplica l'ajust. A l'endpoint autònom, les bandes de similitud que separen les coincidències confirmades (FACE_IN_BLOCKLIST, DUPLICATED_FACE) de les possibles coincidències (POSSIBLE_FACE_IN_BLOCKLIST, POSSIBLE_DUPLICATED_FACE) estan fixades internament — l'ajust del llindar per aplicació s'aplica a la comprovació de vida del flux de treball, no a POST /v3/face-search/. Per tant, en el camí autònom, llegiu similarity_percentage per coincidència i apliqueu la vostra pròpia barra a la lògica de l'aplicació, i tracteu els avisos POSSIBLE_* com la vostra cua de revisió en lloc de la vostra cua de rebuig.

Què tan ràpid és a escala?

Resposta en menys de dos segons.

Puc cercar una cara que mai no va passar per la verificació de Didit?

Sí. Qualsevol user_image en un format acceptat funciona. Si no es detecta cap cara, la trucada retorna HTTP 400.

Realment és gratuït?

Sí — la cerca facial 1:N és gratuïta amb la verificació d'identitat de Didit. No hi ha cap càrrec per cerca. Esteu pagant per les verificacions que construeixen l'índex, a 0,33 $ pel paquet complet, amb les primeres 500 gratuïtes cada mes.

Què passa si la mateixa persona té legítimament dos comptes?

Llavors DUPLICATED_FACE és exactament el senyal informatiu que ha estat dissenyat per ser, i per això no declina. Fusioneu-los, permeteu-los o pregunteu a l'usuari, segons les regles del vostre producte.

A punt per començar?

La cerca facial està disponible a tots els comptes de Didit, sense necessitat de comprar un producte separat.

• Llegeix la documentació — Visió general de la cerca facial 1:N i l'API de llistes per a llistes negres facials.
• Consulta el producte — Verificació d'usuari.
• Consulta els preus — La cerca facial 1:N és gratuïta; el paquet de verificació que construeix l'índex costa 0,33 $.
• Comença gratis — business.didit.me, 500 verificacions KYC al mes sense cost.