> ## 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. # Passive Liveness-Erkennung API: Deepfake-Erkennung > Didit erkennt Masken, Drucke, Replays und Deepfakes per Einzelbild. Passiv, unter 2s, Abrechnung pro Verifizierung, ohne Monatsminimum. ## OpenAPI ````yaml de/openapi-25.json POST /v3/passive-liveness/ 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/passive-liveness/: post: tags: - Standalone APIs summary: Passive Liveness-Erkennung description: >- Erkennen Sie Präsentationsangriffe — gedruckte Fotos, Bildschirmwiedergaben, Masken, Deepfakes — anhand eines einzelnen Gesichtsbildes. Kein Video, keine Bewegung oder Benutzerinteraktion erforderlich. **Funktionsweise.** Das Bild wird von einem biometrischen Modell analysiert; das größte erkannte Gesicht wird ausgewertet und ein Liveness-`score` (0–100) berechnet. `status` ist `Declined`, wenn eine Warnung mit dem Schweregrad `error` ausgelöst wird: - `NO_FACE_DETECTED` — das Liveness-Modell hat kein Gesicht gefunden, - `LOW_LIVENESS_SCORE` — Score liegt bei oder unter `face_liveness_score_decline_threshold` (Standardwert `30`), - `LIVENESS_FACE_ATTACK` — das Modell hat einen Präsentationsangriff erkannt, - `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST` — das Gesicht stimmt mit einem Eintrag auf Ihrer Gesichtssperrliste überein. `MULTIPLE_FACES_DETECTED` ist ein Signal mit dem Schweregrad `warning` (führt nicht zur Ablehnung), und `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` sind Signale mit dem Schweregrad `information`, dass dasselbe Gesicht bereits in einer anderen genehmigten Sitzung aufgetreten ist (sie führen niemals zur Ablehnung). `face_quality` und `face_luminance` (0–100, nullfähig) beschreiben die Aufnahmequalität. **Sperrlisten- und Duplikatsprüfung.** Wird bei **jedem** Aufruf ausgeführt — mit oder ohne `save_api_request` —, indem das erkannte Gesicht mit dem Gesichtssuchindex Ihrer Anwendung abgeglichen wird. Frühere Gesichter mit denselben `vendor_data` werden von der gesamten Indexsuche ausgeschlossen — eine erneute Ausführung der Liveness-Erkennung für denselben Benutzer löst also kein `DUPLICATED_FACE` aus, und ein auf der Sperrliste stehendes Gesicht, das aus einer Sitzung mit den eigenen `vendor_data` des Aufrufers stammt, wird ebenfalls NICHT markiert (die `FACE_IN_BLOCKLIST`-Prüfung wird für Gesichter mit denselben `vendor_data` umgangen). **Abrechnung.** Jede `200`-Antwort verbraucht einen Passive Liveness API-Credit (bezahlt aus Ihrem Tarif-Guthaben oder Aufladeguthaben). Bei unzureichendem Guthaben wird vor jeglicher Bildverarbeitung `403` zurückgegeben. **Sitzungspersistenz und Gesichtsregistrierung (`save_api_request`, Standardwert `true`).** Wenn `true`, wird der Aufruf als Sitzung vom Typ API persistiert (Business Console, `GET /v3/session/{sessionId}/decision/` über die zurückgegebene `request_id`, `status.updated`-Webhook), das Referenzbild und der Gesichtsausschnitt werden gespeichert und das erkannte Gesicht wird **in Ihren Gesichtssuchindex registriert**, sodass spätere Gesichtssuche-Aufrufe und Duplikatsprüfungen darauf abgleichen können. Wenn `false`, ist der Aufruf einmalig: Es wird nichts gespeichert und das Gesicht wird nicht registriert (die Sperrlisten-/Duplikatsprüfung wird weiterhin ausgeführt). **Sandbox.** Sandbox-API-Schlüssel überspringen jegliche Verarbeitung und Abrechnung: Nach der Anfragevalidierung (fehlerhafte Eingaben geben weiterhin `400` zurück) gibt der Endpoint eine statische `Approved`-Mock-Payload zurück, es wird keine Sitzung persistiert und es werden keine Credits verbraucht. **Authentifizierung.** Senden Sie den API-Schlüssel Ihrer Anwendung im Header `x-api-key`. Bei fehlenden oder ungültigen Anmeldedaten wird `403` zurückgegeben (`{"detail": "You do not have permission to perform this action."}`) — 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; bei Überschreitung wird `429` zurückgegeben. operationId: post_v3passive-liveness parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image properties: user_image: type: string format: binary description: >- Frontales Gesichtsbild (z. B. ein Selfie). 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 sollte eine einzelne Person enthalten – sind mehrere Gesichter vorhanden, wird das größte ausgewertet und eine Warnung `MULTIPLE_FACES_DETECTED` hinzugefügt. face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Schwellenwert für den Liveness-Score (0–100). Ein berechneter Score **bei oder unter** diesem Wert gibt eine `LOW_LIVENESS_SCORE`-Warnung aus und setzt `status` auf `Declined`. Standardwert ist `30`; erhöhen Sie ihn für eine strengere Spoofing-Abwehr. Werte außerhalb von 0–100 geben `400` zurück. example: 30 rotate_image: type: boolean default: false description: >- 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. example: false save_api_request: type: boolean default: true description: >- Wenn `true` (Standard), wird der Aufruf als Sitzung vom Typ API persistent gespeichert, die Gesichtsbilder gespeichert, ein Webhook `status.updated` ausgegeben und das erkannte Gesicht in Ihrem Gesichtssuchindex registriert. Wenn `false`, erfolgt der Aufruf einmalig – es wird nichts gespeichert und das Gesicht wird nicht registriert. Das Screening auf Sperrlisten und Duplikate wird in beiden Fällen ausgeführt. example: true vendor_data: type: string description: >- Optionaler opaker Bezeichner (Ihre Benutzer-ID, E-Mail, UUID…), der in der gespeicherten Sitzung hinterlegt und zurückgegeben wird. Wird auch verwendet, um vorherige Sitzungen mit denselben `vendor_data` von der Prüfung auf doppelte Gesichter auszuschließen, sodass eine erneute Verifizierung desselben Benutzers kein `DUPLICATED_FACE` auslöst. example: user-123 metadata: type: object additionalProperties: true description: >- 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. example: flow: withdrawal example: user_image: (binary JPEG/PNG selfie) face_liveness_score_decline_threshold: 30 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: withdrawal responses: '200': description: >- Passive Liveness-Erkennung abgeschlossen. `liveness.score` ist der Konfidenzwert des Modells von 0–100, dass das Bild eine lebende Person zeigt; `status` ist `Approved`, sofern keine Warnung mit der Schwere `error` ausgelöst wurde. Ein gefälschtes oder auf der Sperrliste stehendes Gesicht gibt dennoch `200` zurück – prüfen Sie `liveness.status` und `liveness.warnings`, nicht nur den HTTP-Code. Wenn `save_api_request=true`, ist `request_id` die persistierte Sitzungs-ID. content: application/json: examples: Approved: summary: Live-Gesicht – keine Warnungen value: request_id: a1b2c3d4-e5f6-7890-1234-567890abcdef liveness: status: Approved method: PASSIVE score: 95 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 warnings: [] face_quality: 84.21 face_luminance: 50.33 vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' Declined - presentation attack: summary: Das Modell hat ein Spoofing erkannt (Druck, Replay, Maske…) value: request_id: f1c8c9b2-d3e4-4f5a-9b8c-7d6e5f4a3b2c liveness: status: Declined method: PASSIVE score: 12.5 user_image: entities: - bbox: - 100 - 120 - 420 - 540 confidence: 0.81 age: 30.1 gender: female race: null best_angle: 0 warnings: - risk: LOW_LIVENESS_SCORE feature: LIVENESS additional_data: null log_type: error short_description: Low liveness score long_description: >- The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data. - risk: LIVENESS_FACE_ATTACK feature: LIVENESS additional_data: null log_type: error short_description: Liveness Face Attack long_description: >- The system detected a potential attempt to bypass the liveness check. face_quality: 72.4 face_luminance: 48.2 vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' Declined - face on blocklist: summary: >- Live-Gesicht, stimmt jedoch mit einem Sperrlisteneintrag überein value: request_id: 0b54a1de-22aa-4e0f-9c84-5a2b1f3c4d5e liveness: status: Declined method: PASSIVE score: 93.75 user_image: entities: - bbox: - 40 - 40 - 100 - 100 confidence: 0.722082 age: 27 gender: male race: null best_angle: 0 warnings: - risk: FACE_IN_BLOCKLIST feature: LIVENESS additional_data: blocklisted_session_id: 882c42d5-8a4d-4d20-8080-a22f57822c86 blocklisted_session_number: 3242 api_service: null 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. face_quality: null face_luminance: null vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+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. liveness: type: object properties: status: type: string enum: - Approved - Declined description: >- `Declined`, wenn mindestens eine Warnung mit dem Schweregrad `error` ausgelöst wurde (kein Gesicht, niedriger Score, Präsentationsangriff oder ein Sperrlistentreffer); andernfalls `Approved`. `warning`- oder `information`-Einträge (mehrere Gesichter, Duplikate) führen für sich allein nie zu einer Ablehnung. method: type: string enum: - PASSIVE description: Für diesen Endpoint immer `PASSIVE`. score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Liveness-Konfidenz (0–100, zwei Nachkommastellen), dass das Bild eine lebende Person und keinen Spoof darstellt. `null`, wenn das Modell keine Konfidenz zurückgegeben hat. example: 95 user_image: type: object description: >- Gesichtserkennungsergebnisse für das übermittelte Bild. 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 Liveness-Entscheidung. 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. Das größte Gesicht ist dasjenige, das ausgewertet wird. best_angle: type: integer nullable: true description: >- Drehung (Grad), die die beste Gesichtserkennung lieferte; nur ungleich null, wenn `rotate_image=true` die Ausrichtung korrigiert hat. example: 0 warnings: type: array description: >- Risikosignale. Schweregrad `error` (führt zur Ablehnung): `NO_FACE_DETECTED`, `LOW_LIVENESS_SCORE` (Score liegt am oder unter dem Schwellenwert), `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, `POSSIBLE_FACE_IN_BLOCKLIST`. Schweregrad `warning` (Prüfung, keine Ablehnung): `MULTIPLE_FACES_DETECTED`. Schweregrad `information` (keine Ablehnung): `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` – dasselbe Gesicht erschien bereits in einer anderen genehmigten Sitzung. items: type: object properties: risk: type: string enum: - NO_FACE_DETECTED - LOW_LIVENESS_SCORE - LIVENESS_FACE_ATTACK - MULTIPLE_FACES_DETECTED - FACE_IN_BLOCKLIST - POSSIBLE_FACE_IN_BLOCKLIST - DUPLICATED_FACE - POSSIBLE_DUPLICATED_FACE description: Maschinenlesbarer Risiko-Code. feature: type: string enum: - LIVENESS description: >- Funktion, die die Warnung ausgelöst hat. An diesem Endpoint immer `LIVENESS`. additional_data: type: object nullable: true additionalProperties: true description: >- `null` für die meisten Warnungen. Treffer auf Sperrlisten enthalten `{blocklisted_session_id, blocklisted_session_number, api_service}`; Duplikate enthalten `{duplicated_session_id, duplicated_session_number, api_service}`, die auf die übereinstimmende Sitzung verweisen. 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. face_quality: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Erfassungsqualitätswert des erkannten Gesichts, normalisiert auf 0–100. `null`, wenn das Modell keinen verlässlichen Wert ermitteln konnte. example: 84.21 face_luminance: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Helligkeit des erkannten Gesichts, normiert auf 0–100. `null`, wenn nicht verfügbar. example: 50.33 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 `user_image` fehlt, 5 MB überschreitet, eine nicht unterstützte Dateiendung hat, die serverseitige Bilddecodierung fehlschlägt oder eine Option außerhalb des zulässigen Bereichs liegt. Feldfehler verwenden die DRF-Envelope `{field: [messages]}`; Fehler bei der Bilddecodierung verwenden `{"error": ...}`. content: application/json: examples: Missing image: summary: '`user_image` ist nicht in den Formulardaten enthalten' value: user_image: - No file was submitted. Invalid image format: summary: Zulässige Dateiendung, aber nicht dekodierbarer Bildinhalt value: error: Invalid user image format. code: invalid_image 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 '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/passive-liveness/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'face_liveness_score_decline_threshold=30' \ -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.passive_liveness.check( user_image=open("user_image.jpg", "rb"), face_liveness_score_decline_threshold=30.0, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "withdrawal"}, ) 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.passiveLiveness.check({ user_image: await fileFromPath("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "withdrawal" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.PassiveLiveness.Check(ctx, didit.PassiveLivenessCheckParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.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\": \"withdrawal\"}),\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.PassiveLivenessCheckParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.passiveLiveness().check(PassiveLivenessCheckParams.builder() .userImage(Path.of("user_image.jpg")) .faceLivenessScoreDeclineThreshold(30.0) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "withdrawal")) .build()); System.out.println(result); - lang: php label: PHP source: |- passiveLiveness->check([ 'user_image' => File::fromPath('user_image.jpg'), 'face_liveness_score_decline_threshold' => 30.0, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'withdrawal'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.passive_liveness.check( user_image: Pathname("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "withdrawal" } ) 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.PassiveLiveness.CheckAsync(new PassiveLivenessCheckParams { UserImage = FileUpload.FromPath("user_image.jpg"), FaceLivenessScoreDeclineThreshold = 30.0, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "withdrawal" }, }); 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.