> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Gesichtsabgleich API: 1:1-Gesichtsvergleich > 1:1-Gesichtsvergleich mit Didit via POST /v3/face-match/ für Identitätsprüfung. Inferenz unter 2s, Preise pro Nutzung, keine monatlichen Mindestbeträge. ## OpenAPI ````yaml de/openapi-25.json POST /v3/face-match/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API für Ausweisverifizierung. Authentifizierung über den x-api-key-Header. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/face-match/: post: tags: - Standalone APIs summary: Gesichtsabgleich description: >- Vergleichen Sie zwei Gesichtsbilder (1:1) und erhalten Sie einen Ähnlichkeits-`score` (0–100) sowie einen `status` von `Approved`/`Declined` zurück. **Funktionsweise.** Beide Bilder werden dekodiert und von einem biometrischen Modell analysiert (setzen Sie `rotate_image=true`, falls Aufnahmen seitlich oder auf dem Kopf stehen könnten), anschließend wird ein Ähnlichkeitswert zwischen den beiden Gesichtern berechnet. Ein Wert **strikt über** `face_match_score_decline_threshold` (Standardwert `30`) gibt `status: "Approved"` zurück; ein Wert gleich oder darunter gibt `Declined` mit einer `LOW_FACE_MATCH_SIMILARITY`-Warnung zurück. Wenn überhaupt kein Gesichtspaar bewertet werden kann, gibt der Aufruf dennoch `200` mit `status: "Declined"` und einer `NO_REFERENCE_IMAGE`-Warnung zurück – `score` ist auf dem standardmäßigen Speicherpfad `null` oder `0` bei `save_api_request=false`. Reichen Sie für beste Ergebnisse ein deutliches, nach vorne gerichtetes Gesicht pro Bild ein. **Abrechnung.** Jede `200`-Antwort verbraucht einen Gesichtsabgleich-API-Credit (bezahlt über Ihre Tarif-Credits oder Ihr aufgeladenes Guthaben). Reicht das Guthaben der Organisation für den Aufruf nicht aus, gibt der Endpoint vor jeder Bildverarbeitung `403` mit dem Fehler für unzureichendes Guthaben zurück. **Sitzungspersistenz (`save_api_request`, Standardwert `true`).** Wenn `true`, wird der Aufruf als Sitzung vom Typ API beibehalten: Er erscheint in der Business Console, die zurückgegebene `request_id` ist eine echte Sitzungs-ID, die Sie an `GET /v3/session/{sessionId}/decision/` übergeben können, beide Bilder werden als Quell-/Zielbilder für den Gesichtsabgleich der Sitzung gespeichert und ein `status.updated`-Webhook wird an Ihre konfigurierten Webhook-Endpoints gesendet. Wenn `false`, wird nichts gespeichert und `request_id` ist eine einmalige Korrelations-UUID, die später nicht nachgeschlagen werden kann. **Gesichtssuch-Index.** Dieser Endpoint nimmt niemals Gesichter in Ihren Gesichtssuch-Index auf und führt niemals Sperrlisten- oder Duplikatsprüfungen durch – verwenden Sie dafür `POST /v3/passive-liveness/` oder `POST /v3/face-search/`. **Sandbox.** Sandbox-API-Schlüssel überspringen die gesamte Verarbeitung und Abrechnung: Nach der Validierung der Anfrage (fehlerhafte Eingaben geben weiterhin `400` zurück) gibt der Endpoint eine statische `Approved`-Mock-Payload zurück, es wird keine Sitzung gespeichert und es werden keine Credits verbraucht. **Authentifizierung.** Senden Sie den API-Schlüssel Ihrer Anwendung im Header `x-api-key`. Fehlende oder ungültige Anmeldedaten geben `403` (`{"detail": "You do not have permission to perform this action."}`) zurück – diese API gibt niemals `401` zurück. **Rate-Limit.** Geteiltes Schreibkontingent von 300 Anfragen/Min. pro API-Schlüssel über alle POST/PATCH/DELETE-Endpoints hinweg; bei Überschreitung wird `429` zurückgegeben. operationId: post_v3face-match parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image - ref_image properties: user_image: type: string format: binary description: >- Zu verifizierendes Live- oder Kandidaten-Gesichtsbild (z. B. ein Selfie). Reichen Sie ein einzelnes frontales Foto ein, auf dem das Gesicht der Person deutlich sichtbar und gut ausgeleuchtet ist. 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, daher verbessern sehr hohe Auflösungen die Genauigkeit nicht. ref_image: type: string format: binary description: >- Referenz-Gesichtsbild für den Abgleich (z. B. ein Ausweisdokument-Porträt oder ein zuvor registriertes Foto). Gleiche Format- und Größenbeschränkungen wie bei `user_image`. face_match_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Ähnlichkeitsschwellenwert (0–100), der den `status` der Antwort steuert. Ein berechneter Wert **an oder unter** diesem Wert setzt `status` auf `Declined` und fügt eine `LOW_FACE_MATCH_SIMILARITY`-Warnung hinzu; ein Wert strikt darüber gibt `Approved` zurück. Der Standardwert `30` ist permissiv – erhöhen Sie ihn (z. B. auf `50`–`60`) für eine strengere Verifizierung. Werte außerhalb von 0–100 geben `400` zurück. example: 50 rotate_image: type: boolean default: false description: >- Wenn `true`, testet der Dienst die Eingabebilder in 90-Grad-Schritten (0, 90, 180, 270) und verwendet die Ausrichtung, die die beste Gesichtserkennung liefert – nützlich für mobile Aufnahmen mit fehlender EXIF-Ausrichtung. Erhöht die Latenz, aktivieren Sie dies also nur, wenn Sie aufrechte Bilder nicht garantieren können. example: false save_api_request: type: boolean default: true description: >- Wenn `true` (Standard), wird der Aufruf als Sitzung vom Typ API persistent gespeichert — sichtbar in der Business Console, abrufbar über `GET /v3/session/{sessionId}/decision/` unter Verwendung der zurückgegebenen `request_id` und angekündigt über einen `status.updated`-Webhook. Wenn `false`, wird nichts gespeichert und `request_id` ist eine flüchtige UUID, die nur der Antwortkorrelation dient. example: true vendor_data: type: string description: >- Optionale opake Zeichenfolge (Ihre interne Benutzer-ID, E-Mail, UUID…), die in der gespeicherten Sitzung hinterlegt und in der Antwort zurückgegeben wird. Verwenden Sie sie, um API-Aufrufe mit Ihren eigenen Datensätzen abzugleichen und Sitzungen später zu filtern. example: user-123 metadata: type: object additionalProperties: true description: >- Optionales JSON-Objekt, das mit der Sitzung gespeichert (wenn `save_api_request=true`) und in der Antwort zurückgegeben wird. Senden Sie es bei Multipart-Anfragen als JSON-codiertes String-Feld (z. B. `metadata={"flow":"login"}`) – es wird in ein Objekt geparst. example: flow: login device_id: abc123 example: user_image: (binary JPEG/PNG of the live selfie) ref_image: (binary JPEG/PNG of the reference photo) face_match_score_decline_threshold: 50 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: login responses: '200': description: >- Gesichtsabgleich wurde berechnet. `face_match.score` ist eine Gleitkommazahl von 0–100 (zwei Nachkommastellen); `status` ist `Approved`, wenn der Wert strikt über `face_match_score_decline_threshold` liegt, andernfalls `Declined` mit einer erläuternden Warnung. Ein Paar mit geringer Ähnlichkeit oder ohne Bewertungsmöglichkeit gibt dennoch `200` zurück – prüfen Sie `face_match.status` und `face_match.warnings`, nicht nur den HTTP-Code. Wenn `save_api_request=true`, ist `request_id` die persistierte Sitzungs-ID. content: application/json: examples: Approved: summary: Gleiche Person — Score über dem Schwellenwert value: request_id: f9f5a777-8002-44c6-baaf-128bcfd6e226 face_match: status: Approved score: 99.41 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 ref_image: entities: - bbox: - 653 - 745 - 1691 - 2185 confidence: 0.722082 age: 27 gender: male race: null best_angle: 0 warnings: [] vendor_data: user-123 metadata: flow: login created_at: '2026-06-12T01:04:42.763237+00:00' Declined - low similarity: summary: Score auf oder unter dem Schwellenwert für Ablehnung value: request_id: 7cdda24e-311a-46d3-a3bb-e5d9b564ce73 face_match: status: Declined score: 24.87 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 ref_image: entities: - bbox: - 156 - 234 - 679 - 898 confidence: 0.717775 age: 41.2 gender: male race: null best_angle: 0 warnings: - risk: LOW_FACE_MATCH_SIMILARITY feature: FACEMATCH additional_data: null log_type: error 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. vendor_data: user-123 metadata: null created_at: '2026-06-12T01:08:19.859116+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- Beibehaltene Sitzungs-ID, wenn `save_api_request=true` (verwendbar mit `GET /v3/session/{sessionId}/decision/`); andernfalls eine vorübergehende Korrelations-UUID. face_match: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved`, wenn der Ähnlichkeitswert strikt über `face_match_score_decline_threshold` liegt und ein Wert berechnet werden konnte; andernfalls `Declined` (eine Warnung erklärt den Grund). score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Ähnlichkeitswert von 0 bis 100 – die Konfidenz des Modells, dass beide Bilder dieselbe Person darstellen. Wird nur auf zwei Dezimalstellen gerundet, wenn `save_api_request` true ist; bei `save_api_request=false` wird der unverarbeitete Float-Wert zurückgegeben. `null`, wenn kein Gesichtspaar bewertet werden konnte (bei der Standardeinstellung `save_api_request=true`); bei `save_api_request=false` kann dieselbe Bedingung als `score: 0` erscheinen. In beiden Fällen ist eine `NO_REFERENCE_IMAGE`-Warnung vorhanden und `status` ist `Declined`. example: 99.41 user_image: type: object description: >- Gesichtserkennungsergebnisse für die analysierten Bilder. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Bounding-Box des erkannten Gesichts als Pixelkoordinaten `[x_min, y_min, x_max, y_max]` im verarbeiteten Bild. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: Konfidenz der Gesichtserkennung (0–1). example: 0.732973 age: type: number format: float description: >- Vom Modell geschätztes Alter des erkannten Gesichts in Jahren. Dient nur zur Information — hat keinen Einfluss auf die Entscheidung des Gesichtsabgleichs. example: 26.91 gender: type: string description: >- Vom Modell vorhergesagtes Geschlecht des erkannten Gesichts (`male` oder `female`). Dient nur zur Information. example: male race: type: string nullable: true description: >- Reserviertes Feld — in Antworten dieses Endpoints immer `null`. example: null description: Ein Eintrag pro erkanntem Gesicht. best_angle: type: integer description: >- Drehung (Grad: 0, 90, 180 oder 270), die die beste Gesichtserkennung lieferte. Nur ungleich null, wenn `rotate_image=true` die Ausrichtung korrigiert hat. example: 0 ref_image: type: object description: >- Gesichtserkennungsergebnisse für das Referenzbild, gleiche Struktur wie `user_image`. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Bounding-Box des erkannten Gesichts als Pixelkoordinaten `[x_min, y_min, x_max, y_max]` im verarbeiteten Bild. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: Konfidenz der Gesichtserkennung (0–1). example: 0.732973 age: type: number format: float description: >- Vom Modell geschätztes Alter des erkannten Gesichts in Jahren. Dient nur zur Information — hat keinen Einfluss auf die Entscheidung des Gesichtsabgleichs. example: 26.91 gender: type: string description: >- Vom Modell vorhergesagtes Geschlecht des erkannten Gesichts (`male` oder `female`). Dient nur zur Information. example: male race: type: string nullable: true description: >- Reserviertes Feld — in Antworten dieses Endpoints immer `null`. example: null description: Ein Eintrag pro erkanntem Gesicht. best_angle: type: integer example: 0 warnings: type: array description: >- Leer bei einer fehlerfreien Genehmigung. `NO_REFERENCE_IMAGE` (`error`) — es konnte kein Gesichtspaar bewertet werden; `LOW_FACE_MATCH_SIMILARITY` (`error`) — Wert liegt bei oder unter dem Ablehnungsschwellenwert. Jeder dieser Fälle setzt `status` auf `Declined`. items: type: object properties: risk: type: string enum: - NO_REFERENCE_IMAGE - LOW_FACE_MATCH_SIMILARITY description: Maschinenlesbarer Risiko-Code. feature: type: string enum: - FACEMATCH description: >- Funktion, die die Warnung ausgelöst hat. An diesem Endpoint immer `FACEMATCH`. additional_data: type: object nullable: true additionalProperties: true description: Für Gesichtsabgleich-Warnungen immer `null`. log_type: type: string enum: - error - warning - information description: >- Schweregrad. `error`-Warnungen setzen `status` auf `Declined`; `warning`- und `information`-Einträge sind hinweisend und führen für sich allein nie zu einer Ablehnung. short_description: type: string description: >- Für Menschen lesbare einzeilige Zusammenfassung des Risikos. long_description: type: string description: Lesbare Erklärung des Risikos. vendor_data: type: string nullable: true description: >- Rückgabe der von Ihnen gesendeten `vendor_data` oder `null`. metadata: type: object nullable: true additionalProperties: true description: >- Rückgabe des von Ihnen gesendeten `metadata`-Objekts oder `null`. created_at: type: string format: date-time description: >- ISO 8601-Zeitstempel (UTC), wann die Antwort generiert wurde, z. B. `2026-06-12T01:04:42.763237+00:00`. '400': description: >- Validierungsfehler. Wird zurückgegeben, wenn ein erforderliches Bild fehlt, 5 MB überschreitet, eine nicht unterstützte Dateiendung hat oder eine Option außerhalb des zulässigen Bereichs liegt. Der Body ist die standardmäßige Feld-Fehler-Envelope von DRF: ein Array von Meldungen pro betroffenem Feld. content: application/json: examples: Missing required image: summary: >- `ref_image` (oder `user_image`) nicht in den Formulardaten enthalten value: ref_image: - No file was submitted. Unsupported file extension: summary: Dateiendung außerhalb von tiff/jpg/jpeg/png/webp value: user_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp. File too large: summary: Der Upload überschreitet das Limit von 5 MB value: user_image: - File size should not exceed 5 MB Threshold out of range: summary: >- `face_match_score_decline_threshold` liegt außerhalb von 0–100 value: face_match_score_decline_threshold: - Ensure this value is less than or equal to 100. '403': description: >- Zugriff verweigert. Wird zurückgegeben, wenn der Header `x-api-key` fehlt sowie wenn das Guthaben der aufrufenden Organisation den Aufruf nicht decken kann; ein falscher, widerrufener oder abgelaufener Schlüssel gibt `401` zurück. Ein fehlender Schlüssel gibt `403` mit `{"detail": ...}` zurück; ein falscher, widerrufener oder abgelaufener Schlüssel gibt `401` zurück. Unzureichende Credits geben `403` mit `{"error": ...}` zurück, bevor eine Bildverarbeitung stattfindet. content: application/json: examples: Missing or invalid API key: summary: >- Kein `x-api-key`-Header, oder der Schlüssel ist ungültig/widerrufen value: detail: You do not have permission to perform this action. Not enough credits: summary: >- Das Guthaben der Organisation reicht für den Aufruf nicht aus value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Rate-Limit überschritten. POST/PATCH/DELETE-Endpoints teilen sich ein Budget von 300 Schreibanfragen pro Minute pro API-Schlüssel (Transaktionserstellungen und Ereignis-Ingestion haben ein separates Budget von 600). Die Antwort enthält die Header `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` und `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Mehr als 300 Schreibanfragen in der aktuellen Minute value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/face-match/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'ref_image=@./id_portrait.jpg' \ -F 'face_match_score_decline_threshold=50' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.face_match.compare( user_image=open("user_image.jpg", "rb"), ref_image=open("ref_image.jpg", "rb"), face_match_score_decline_threshold=50.0, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "login"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.faceMatch.compare({ user_image: await fileFromPath("user_image.jpg"), ref_image: await fileFromPath("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceMatch.Compare(ctx, didit.FaceMatchCompareParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tRefImage: didit.FileFromPath(\"ref_image.jpg\"),\n\tFaceMatchScoreDeclineThreshold: didit.Float(50.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"login\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.FaceMatchCompareParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.faceMatch().compare(FaceMatchCompareParams.builder() .userImage(Path.of("user_image.jpg")) .refImage(Path.of("ref_image.jpg")) .faceMatchScoreDeclineThreshold(50.0) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "login")) .build()); System.out.println(result); - lang: php label: PHP source: |- faceMatch->compare([ 'user_image' => File::fromPath('user_image.jpg'), 'ref_image' => File::fromPath('ref_image.jpg'), 'face_match_score_decline_threshold' => 50.0, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'login'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.face_match.compare( user_image: Pathname("user_image.jpg"), ref_image: Pathname("ref_image.jpg"), face_match_score_decline_threshold: 50.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "login" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.FaceMatch.CompareAsync(new FaceMatchCompareParams { UserImage = FileUpload.FromPath("user_image.jpg"), RefImage = FileUpload.FromPath("ref_image.jpg"), FaceMatchScoreDeclineThreshold = 50.0, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "login" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.