Gesichtssuche 1:N: Alle Konten einer Person finden (DE)

Ein Betreiber, der vierzig Konten auf Ihrer Plattform führt, hat vierzig E-Mail-Adressen, wahrscheinlich vierzig Zahlungsinstrumente und möglicherweise vierzig Geräte. Was er nicht hat, sind vierzig Gesichter.

Wenn ein Teil Ihres Zugangsprozesses ein Selfie erfasst, halten Sie bereits den einen Identifikator in der Hand, dessen Vervielfältigung wirklich teuer ist. Die Gesichtssuche 1:N ist der Aufruf, der ihn nutzt – eine Anfrage, ein Gesicht, und zurück kommt jedes Konto in Ihrem eigenen System, das dieselbe Person verifiziert hat.

Es ist kostenlos mit der Didit Identitätsverifizierung, liefert Ergebnisse in unter zwei Sekunden und läuft automatisch während der Liveness-Prüfung innerhalb einer Verifizierungssitzung ab.

Wichtigste Erkenntnisse

• POST /v3/face-search/ durchsucht ein Gesicht anhand der Gesichter, die Ihre eigene Anwendung registriert hat – Sitzungen, die mit save_api_request=true ausgeführt werden – und nicht eines gemeinsamen globalen Index.
• Übereinstimmungen werden mit Ihren eigenen vendor_data für jede zurückgegeben, sodass die Ergebnisse direkt Ihren Konto-IDs zugeordnet werden.
• Zwei Modi: most_similar für Deduplizierung und wiederkehrende Benutzer, blocklisted_or_approved für Blocklist-Screening.
• status ist "Declined" nur bei einer Blocklist-Übereinstimmung. Duplikate geben "Approved" mit einer DUPLICATED_FACE-Warnung zurück – absichtlich informativ, da die Deduplizierungsrichtlinie Ihre ist.
• Die Antwort ist ein einziges face_search-Objekt, kein Array. Das verwirrt die Leute.
• Kostenlos mit Didit-Verifizierung. Antwortzeit unter zwei Sekunden. Läuft automatisch während der Liveness-Prüfung.

Was 1:N bedeutet und warum es das richtige Werkzeug ist

Eine 1:1-Gesichtsübereinstimmung beantwortet die Frage: „Ist das die Person in diesem Dokument?“ Das ist eine Verifizierungsfrage und wird während des Onboardings ausgeführt.

Eine 1:N-Suche beantwortet eine andere Frage: „Ist dies eine der Personen, die ich bereits verifiziert habe?“ Ein Bild wird eingegeben, und jede Übereinstimmung in Ihrem Index wird ausgegeben.

Für koordinierten Kontomissbrauch ist die zweite Frage die relevante. Anthropic's Bericht über Distillationskampagnen beschrieb die Attribution, die auf relationalen Signalen – gemeinsamen Zahlungsmethoden, koordinierter Zeitplanung, gemeinsamer Infrastruktur – basiert. Eine biometrische 1:N-Suche ist dieselbe Art von Signal, das aus dem teuersten Identifikator stammt, den ein Betreiber vervielfältigen muss.

Der Index ist Ihr eigener. Die Gesichtssuche wird anhand von Gesichtern durchgeführt, die Ihre eigene Anwendung durch frühere Verifizierungen registriert hat – Sitzungen mit save_api_request=true oder Passive Liveness mit save_api_request=true. Es handelt sich nicht um eine Suche über Benutzer anderer Didit-Kunden hinweg. Wenn Sie keine Gesichter registriert haben, gibt es nichts zu suchen.

Die API

Anfrage

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, authentifiziert mit x-api-key.

Erforderlich: user_image – jpg, jpeg, png, tiff oder webp, maximal 5 MB. PDFs werden nicht akzeptiert. Das Bild muss mindestens ein erkennbares Gesicht enthalten; wenn mehrere vorhanden sind, gewinnt das größte Bounding Box.

Optional:

• search_type – most_similar (Standard) für Deduplizierung und Erkennung wiederkehrender Benutzer, oder blocklisted_or_approved für Blocklist-Screening.
• save_api_request – dieses Bild in Ihren Index aufnehmen.
• vendor_data – Ihre eigene Kennung für das Subjekt.

Antwort

Die Antwort enthält ein einziges face_search-Objekt. Die meisten Didit-Funktionen geben pluralistische Arrays zurück, daher ist dies die eine Form, die man sorgfältig lesen sollte, bevor man den Parser schreibt.

{
  "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": []
  }
}

Die Felder, die die Untersuchung tragen:

• total_matches – wie viele Konten dieses Gesicht teilen.
• vendor_data bei jeder Übereinstimmung – Ihre Kennung, sodass eine Übereinstimmungsliste sofort eine Kontenliste ist.
• similarity_percentage – die Stärke jeder einzelnen Übereinstimmung.
• verification_date – die Zeitachse. Zwölf Konten, die über elf Monate verifiziert wurden, lesen sich anders als zwölf, die an einem Nachmittag verifiziert wurden.
• is_blocklisted – ob diese Übereinstimmung bereits auf Ihrer Blocklist steht.
• session_id – der Dreh- und Angelpunkt für alles andere, was diese Sitzung erfasst hat, einschließlich ihrer Geräte- und Netzwerk-Warnungen.

Status-Semantik

Dies ist das wichtigste Verhalten im gesamten Endpunkt:

status ist "Declined" nur, wenn mindestens eine Blocklist-Übereinstimmung gefunden wird. Reine Duplikats-Übereinstimmungen geben "Approved" zurück.

Ein Duplikat ist keine Ablehnung. Es ist Information. Didit weigert sich bewusst, die Deduplizierungsentscheidung für Sie zu treffen, da Duplikate legitime Erklärungen haben und nur Sie die Regeln Ihres Produkts kennen.

Warnungen

Warnung	Bedeutung
FACE_IN_BLOCKLIST	Eindeutige Blocklist-Übereinstimmung – ablehnen
POSSIBLE_FACE_IN_BLOCKLIST	Grenzfall unterhalb des harten Schwellenwerts – zur manuellen Überprüfung weiterleiten
DUPLICATED_FACE	Dieses Gesicht ist bereits unter anderen vendor_data verifiziert
POSSIBLE_DUPLICATED_FACE	Mögliches Duplikat im Grenzbereich
MULTIPLE_FACES_DETECTED	Mehr als ein Gesicht im übermittelten Bild erkannt

Fehlermodi

• HTTP 400 – kein Gesicht in user_image erkannt. Fordern Sie eine Neuaufnahme an.
• HTTP 403 – keine Credits mehr.
• status: "Declined" mit FACE_IN_BLOCKLIST – eindeutiger Treffer. Ablehnen.
• POSSIBLE_FACE_IN_BLOCKLIST – unterhalb des harten Schwellenwerts. Manuelle Überprüfung.
• DUPLICATED_FACE – bereits unter anderen vendor_data verifiziert. Zusammenführen, blockieren oder zulassen gemäß Ihrer Richtlinie.

Der automatische Pfad

Oft müssen Sie den Endpunkt überhaupt nicht aufrufen. Die Gesichtssuche läuft automatisch während der Liveness-Prüfung innerhalb einer Verifizierungssitzung ab:

• Gesichtsbiometrie wird mit allen zuvor verifizierten Benutzern verglichen.
• Potenzielle doppelte Konten werden durch Gesichtsähnlichkeit identifiziert.
• Übereinstimmungen werden gemäß Ihrer konfigurierten Ähnlichkeitsschwellenwerte gekennzeichnet.
• Gesichter werden mit Ihrer Blocklist abgeglichen, und eine Blocklist-Übereinstimmung lehnt die Verifizierung automatisch ab.

Für jede Stufe, bei der Sie bereits eine vollständige Verifizierung durchführen, ist die Duplikaterkennung ohne zusätzliche Kosten und ohne zusätzlichen Aufruf enthalten. Der eigenständige Endpunkt ist für Fälle gedacht, die der Sitzungsablauf nicht abdeckt – die Untersuchung eines Kontos im Nachhinein, das Screening eines Bildes, das Sie auf andere Weise erhalten haben, oder das Umschalten von search_type, um eine blocklist-fokussierte Suche über ein bereits vorhandenes Bild durchzuführen.

Übereinstimmungen in eine Akteurkarte umwandeln

Der praktische Workflow, beginnend mit einem verdächtigen Konto:

1. Suchen Sie das Gesicht. total_matches: 12 – zwölf Konten, eine Person.
2. Lesen Sie die vendor_data. Zwölf Ihrer eigenen Konto-IDs, kein Join erforderlich.
3. Lesen Sie die Zeitachse. Gruppieren Sie die verification_date-Werte. Konten, die in Schüben erstellt wurden, unterscheiden sich operativ von Konten, die über Jahre hinweg erstellt wurden.
4. Pivot auf session_id. Ziehen Sie die Geräte- und Netzwerk-Warnungen jeder Sitzung. Gesichter, die DUPLICATED_DEVICE_FINGERPRINT teilen, straffen das Cluster; Konten auf nicht verwandten Geräten können eine andere Anordnung darstellen.
5. Erweitern. Geräte und IP-Bereiche, die in Schritt 4 aufgedeckt wurden, ziehen Konten an, die die Gesichtssuche verpasst hat – weil eine andere Person diese Prüfungen durchgeführt hat.
6. Einmal entscheiden, über alle Identifikatoren hinweg durchsetzen. Wenn der Cluster als Missbrauch bestätigt wird, posten Sie die bestätigte reference_session_id in jede Art von Blocklist, die Sie interessieren – Gesicht, Gerät, IP, E-Mail, Telefon, Dokument. Es ist ein Aufruf pro Liste, und jeder Aufruf extrahiert automatisch den richtigen Wert aus dieser Sitzung, sodass nichts manuell neu eingegeben werden muss.

Sechs Schritte, ein Ausgangspunkt und keine sofortige Überprüfung an irgendeiner Stelle. Die Verkehrsebene sagt Ihnen: Mit diesem Konto stimmt etwas nicht. Dies sagt Ihnen: Wie viele Konten das tatsächlich sind.

Es muss ausdrücklich gesagt werden: Eine 1:N-Gesichtssuche verhindert weder die Modellextraktion noch erkennt sie diese. Die Gesichtssuche hat keine Einsicht in Ihren API-Verkehr. Sie ordnet Konten Personen zu, was es Ihnen ermöglicht, bei einem Alarm über ein ganzes Cluster statt nur einer Zeile zu handeln. Modell-Level-Ausgabekontrollen und semantische Verkehrsdetektion sind separate Ebenen und bleiben in der Verantwortung des Modellanbieters.

Anwendungsfälle

KI-API-Plattformen, die eine Verhaltenswarnung in die vollständige Kontenmenge auflösen, die ein Betreiber kontrolliert.

Missbrauch von kostenlosen Stufen und Credits – eine Person, viele Testkonten, ist dasselbe Erkennungsproblem mit geringeren Einsätzen.

Marktplätze und Gig-Plattformen, die gesperrte Verkäufer, Fahrer oder Kuriere beim erneuten Registrieren erwischen.

iGaming, das Regeln für Einzelkonten und Selbstausschluss durchsetzt, wobei ein zurückkehrender ausgeschlossener Spieler ein regulatorischer Fehler ist, nicht nur ein Missbrauchsfall.

Finanzdienstleistungen, die Ringe synthetischer Identitäten identifizieren, bei denen ein echtes Gesicht auf viele gefälschte Identitäten verteilt ist.

Häufig gestellte Fragen

Wird mein Gesichtsindex mit anderen Didit-Kunden geteilt?

Nein. Die Gesichtssuche läuft gegen den Index, den Ihre eigene Anwendung durch Ihre eigenen Verifizierungen aufgebaut hat. Es handelt sich nicht um eine kundenübergreifende Suche.

Was steuert, ob ein Gesicht in den Index aufgenommen wird?

save_api_request=true bei einer Verifizierungssitzung oder einem Passive Liveness-Aufruf. Sie entscheiden, was registriert wird, und Sie kontrollieren die Aufbewahrung, im Einklang mit Ihrer eigenen Datenschutzerklärung und der rechtlichen Grundlage für die Verarbeitung biometrischer Daten.

Welchen Ähnlichkeitsschwellenwert sollte ich verwenden?

Beachten Sie, wo die Abstimmung anwendbar ist. Beim eigenständigen Endpunkt sind die Ähnlichkeitsbereiche, die bestätigte Treffer (FACE_IN_BLOCKLIST, DUPLICATED_FACE) von möglichen Treffern (POSSIBLE_FACE_IN_BLOCKLIST, POSSIBLE_DUPLICATED_FACE) trennen, intern festgelegt – die anwendungsspezifische Schwellenwertabstimmung gilt für die Liveness-Prüfung des Workflows, nicht für POST /v3/face-search/. Lesen Sie also beim eigenständigen Pfad die similarity_percentage pro Treffer und wenden Sie Ihre eigene Grenze in der Anwendungslogik an, und behandeln Sie die POSSIBLE_*-Warnungen als Ihre Überprüfungswarteschlange statt als Ihre Ablehnungswarteschlange.

Wie schnell ist es im großen Maßstab?

Antwortzeit unter zwei Sekunden.

Kann ich ein Gesicht suchen, das nie eine Didit-Verifizierung durchlaufen hat?

Ja. Jedes user_image in einem akzeptierten Format funktioniert. Wenn kein Gesicht erkannt wird, gibt der Aufruf HTTP 400 zurück.

Ist es wirklich kostenlos?

Ja – die Gesichtssuche 1:N ist kostenlos mit der Didit Identitätsverifizierung. Es gibt keine Gebühr pro Suche. Sie bezahlen für die Verifizierungen, die den Index aufbauen, zu 0,33 $ für das vollständige Paket, wobei die ersten 500 pro Monat kostenlos sind.

Was ist, wenn dieselbe Person legitim zwei Konten hat?

Dann ist DUPLICATED_FACE genau das informative Signal, das es sein soll – deshalb wird es nicht abgelehnt. Führen Sie sie zusammen, erlauben Sie sie oder fragen Sie den Benutzer, gemäß den Regeln Ihres Produkts.

Bereit zum Start?

Die Gesichtssuche ist auf jedem Didit-Konto verfügbar, ohne dass ein separates Produkt gekauft werden muss.

• Lesen Sie die Dokumentation – Gesichtssuche 1:N Übersicht und die Listen-API für Gesichts-Blocklists.
• Sehen Sie sich das Produkt an – Benutzerverifizierung.
• Überprüfen Sie die Preise – Gesichtssuche 1:N ist kostenlos; das Verifizierungspaket, das den Index aufbaut, kostet 0,33 $.
• Kostenlos starten – business.didit.me, 500 KYC-Verifizierungen pro Monat kostenlos.