Zum Hauptinhalt springen
POST
cURL

Autorisierungen

x-api-key
string
header
erforderlich

Der API-Schlüssel Ihrer Anwendung, aus Entwickler -> API-Schlüssel in der Business Console. Der Primärschlüssel hat Vollzugriff. Ein benannter Schlüssel kann im Geltungsbereich eingeschränkt werden: keine, Lese- oder Schreibberechtigung pro Ressource, beschränkt auf bestimmte Workflows oder genehmigte Sitzungen, auf eine Liste von IP-Adressen und auf ein Ablaufdatum. 401 bedeutet, dass der Schlüssel falsch, widerrufen oder abgelaufen ist; 403 bedeutet, dass kein Schlüssel gesendet wurde, der Schlüssel keinen Zugriff auf diese Ressource oder Aktion hat oder die Anfrage von einer Adresse außerhalb seiner IP-Liste stammte; 404 bei einer Sitzungsroute bedeutet, dass die Sitzung außerhalb der Workflows oder Status des Schlüssels liegt. Ein Schlüssel ohne Medienzugriff erhält Bild-, Video- und PDF-URLs als null, und ein Schlüssel ohne Schreibberechtigung für Sitzungen erhält Sitzungslinks und Token als null. Siehe https://docs.didit.me/console/api-keys.

Body

multipart/form-data
user_image
file
erforderlich

Frontales Gesichtsbild für die Suche. Zulässige Dateiendungen: tiff, jpg, jpeg, png, webp. Maximale Upload-Größe: 5 MB (größere Dateien werden mit 400 abgelehnt). Bilder werden vor der Verarbeitung automatisch auf ca. 0,5 MB komprimiert, sodass sehr hohe Auflösungen die Genauigkeit nicht verbessern. Das Bild muss mindestens ein erkennbares Gesicht enthalten – andernfalls gibt der Endpoint 400 zurück. Sind mehrere Gesichter vorhanden, wird nach dem größten gesucht und eine Warnung MULTIPLE_FACES_DETECTED hinzugefügt.

search_type
enum<string>
Standard:most_similar

Suchrichtlinie. most_similar (Standard) sortiert jedes in Ihrer Anwendung registrierte Gesicht nach Ähnlichkeit. blocklisted_or_approved beschränkt die Kandidaten auf Gesichter auf der Sperrliste, Gesichter auf der Zulassungsliste, Gesichter aus genehmigten Sitzungen und importierte Benutzerprofil-Gesichter — wobei Einträge auf der Sperrliste an erster Stelle stehen.

Verfügbare Optionen:
most_similar,
blocklisted_or_approved
Beispiel:

"most_similar"

rotate_image
boolean
Standard:false

Wenn true, versucht der Dienst 90-Grad-Drehungen der Eingabe und verwendet die Ausrichtung, die die beste Gesichtserkennung liefert. Nützlich, wenn die EXIF-Ausrichtung fehlt. Erhöht die Latenz.

Beispiel:

false

save_api_request
boolean
Standard:true

Wenn true (Standard), wird der Aufruf als Sitzung vom Typ API persistent gespeichert, ein Webhook status.updated ausgegeben, match_image_url-Werte vorsigniert und das gesuchte Gesicht in Ihrem Gesichtssuchindex registriert (Gesichtssuch-Registrierungen sind von zukünftigen Suchen ausgeschlossen). Wenn false, erfolgt die Suche einmalig – es wird keine Sitzung gespeichert und das Gesicht wird nicht registriert.

Beispiel:

true

vendor_data
string

Optionaler opaker Bezeichner (Ihre Benutzer-ID, E-Mail, UUID…), der in der gespeicherten Sitzung hinterlegt und zurückgegeben wird. Schließt Gesichter desselben Benutzers nicht aus den Suchergebnissen aus.

Beispiel:

"user-123"

metadata
object

Optionales JSON-Objekt, das mit der Sitzung gespeichert (wenn save_api_request=true) und zurückgegeben wird. Senden Sie es bei Multipart-Anfragen als JSON-codiertes String-Feld – es wird in ein Objekt geparst.

Beispiel:

Antwort

Gesichtssuche abgeschlossen. face_search.matches enthält bis zu 5 ähnliche Gesichter, sortiert nach Ähnlichkeit; ein leeres Array bedeutet, dass kein registriertes Gesicht den Mindestähnlichkeitswert überschritten hat. status ist nur bei Treffern auf der Sperrliste Declined – reine Duplikattreffer geben Approved zurück, prüfen Sie daher matches und warnings, nicht nur status. Wenn save_api_request=true, ist request_id die persistierte Sitzungs-ID. Jeder Treffer enthält source (session, imported, list_entry oder retained_template), vendor_user_id und biometric_template_id; ein Treffer mit retained_template stammt von einem bildfreien biometrischen Template, das nach dem Löschen der Quellsitzung aufbewahrt wurde, und weist null für Sitzungsfelder, match_image_url und user_details auf.

request_id
string<uuid>

Beibehaltene Sitzungs-ID, wenn save_api_request=true (verwendbar mit GET /v3/session/{sessionId}/decision/); andernfalls eine vorübergehende Korrelations-UUID.

vendor_data
string | null

Rückgabe der von Ihnen gesendeten vendor_data oder null.

metadata
object | null

Rückgabe des von Ihnen gesendeten metadata-Objekts oder null.

created_at
string<date-time>

ISO 8601-Zeitstempel (UTC), wann die Antwort generiert wurde, z. B. 2026-06-12T01:04:42.763237+00:00.

Zuletzt geändert am 7. November 2026