> ## 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.
# Liveness-Erkennung API: Deepfake-Schutz
> Deepfakes und Präsentationsangriffe mit Didit erkennen: passive und aktive Liveness-Erkennung, 99.9% Genauigkeit, iBeta-geprüft, ab $0.10.
Die Liveness-Erkennung von Didit bestätigt mithilfe von passiver Liveness, 3D-Aktion oder Flash-Liveness, dass sich eine echte, lebende Person vor der Kamera befindet und kein gedrucktes Foto, keine Bildschirmwiedergabe, keine Maske und kein Deepfake. Sie erreicht eine **Genauigkeit von 99.9%** bei einer Falschakzeptanzrate (FAR) von unter **0.1%**.
Prompt zur Liveness-Integration
Prompt in die Zwischenablage kopieren
\
\````# Goal
Integrate Didit Liveness Detection (passive / 3D-action / flashing) into your app. Pick ONE mode.
\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow (SDK or session.url). The workflow's LIVENESS feature controls which method runs.
1\. Configure the workflow's liveness method — `face_liveness_method`: "PASSIVE" | "ACTIVE_3D" | "FLASHING" (Business Console or POST /v3/workflows/).
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user (or mount the Web/Mobile SDK).
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.
Decision surface: `liveness_checks[]` array on the decision payload (one entry per liveness node).
\# Mode B — Standalone API (server-to-server, passive only)
Use when you already have a captured selfie and want a one-shot passive-liveness check.
POST https://verification.didit.me/v3/passive-liveness/
multipart/form-data — x-api-key: YOUR_API_KEY
Required: user_image (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted).
curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/passive-liveness/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```
Returns: { request_id, liveness: { status, method: "PASSIVE", score, user_image: { entities, best_angle }, warnings, face_quality, face_luminance } }.
When `save_api_request=true` the submitted face is also screened against your blocklist and face index for duplicates — set to `false` to skip enrolment.
\# Status enum (per liveness_checks[].status or liveness.status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"
\# Warnings (LogWarningChoices.LIVENESS)
warnings[] risk codes include:
LOW_LIVENESS_SCORE, NO_FACE_DETECTED, LIVENESS_FACE_ATTACK, MULTIPLE_FACES_DETECTED, FACE_IN_BLOCKLIST, POSSIBLE_FACE_IN_BLOCKLIST, DUPLICATED_FACE, POSSIBLE_DUPLICATED_FACE.
Full catalogue: /core-technology/liveness/warnings-liveness.
\# Failure modes to handle
\- HTTP 403 — out of credits.
\- HTTP 400 — missing user_image, file too large, unsupported extension.
\- status="Declined" with LIVENESS_FACE_ATTACK or LOW_LIVENESS_SCORE — presentation attack suspected; do not approve.
\- FACE_IN_BLOCKLIST / DUPLICATED_FACE — block or route to manual review per your policy.
\- NO_FACE_DETECTED / MULTIPLE_FACES_DETECTED — ask the user to retry with a single, well-framed face.
\# See also
\- Canonical schema: /reference/data-models#liveness-check
\- Per-feature report: /core-technology/liveness/report-liveness
\- Risk catalogue: /core-technology/liveness/warnings-liveness
\- Full integration playbook: /integration/integration-prompt````
\
Einfügen in
Die Academy-Lektion zum gehosteten Benutzerablauf erreicht das Liveness-Selfie bei Minute 8:49, gefolgt um 9:16 von den Methoden Passive Liveness, 3D Flash und 3D Action.[Das Liveness-Selfie — Didit Academy](https://www.youtube.com/embed/LzGe-dMWjUw?start=529\&rel=0\&playsinline=1)## Methoden zur Liveness-ErkennungUnsere Plattform implementiert drei verschiedene Anti-Spoofing-Technologien, die jeweils auf unterschiedliche Sicherheitsanforderungen und Benutzererlebnisse zugeschnitten sind:
| Methode |
Beschreibung |
Sicherheitsstufe |
Ideal für |
| **`3D Action & Flash`** |
• Kombiniert Multi-Faktor-Biometrieverifizierung mit einer **randomisierten Aktionssequenz** und **dynamischer Lichtmusteranalyse**.\
• Zu Beginn wird der Benutzer aufgefordert, eine einfache Aktion auszuführen – wie **Blinzeln** oder **Nicken** –, was eine Interaktion in Echtzeit gewährleistet.\
• Gleichzeitig projiziert das System eine Folge von Lichtmustern auf das Gesicht und analysiert die **Reflexionen**, um die dreidimensionale Struktur des Gesichts zu bestätigen.\
• **Deep-Learning-Algorithmen** untersuchen Mikroausdrücke und die Reaktionen auf Lichtreflexionen, um die Anwesenheit einer lebenden Person zu verifizieren.\
• Bietet die **höchste Sicherheit**, indem verhaltensbasierte (Aktion) und physische (lichtbasierte Tiefe) Merkmale integriert werden, wodurch Spoofing mit statischen Bildern, Videos oder sogar hochentwickelten Masken nahezu unmöglich wird.
|
Höchste |
Banking, Gesundheitswesen, Behördenanwendungen |
| **`3D Flash`** |
• Nutzt **dynamische Lichtmusteranalyse**, um die Gesichtstopologie zu validieren, ohne dass eine Benutzerinteraktion erforderlich ist.\
• Projiziert eine Serie von Lichtmustern mit über **30 Bildern pro Sekunde** auf das Gesicht und analysiert die Reflexionen, um eine **Tiefenkarte** zu erstellen.\
• Diese Tiefenkarte bestätigt die dreidimensionale Struktur des Gesichts und unterscheidet es von flachen Bildern oder 2D-Spoofs.\
• Bietet ein **nahtloses Erlebnis** bei gleichzeitig **hoher Sicherheit** gegen Präsentationsangriffe wie Fotos oder Bildschirme.\
|
Hoch |
Finanzdienstleistungen, Kontozugriff, Identitätsverifizierung |
| **`Passive Liveness`** |
• Basiert auf einer **Einzelbild-Deep-Learning-Analyse**, um Anzeichen von Lebendigkeit zu erkennen.\
• Untersucht das Bild auf **Artefakte**, **Texturmuster** und andere subtile Indikatoren, die ein echtes Gesicht von einem Spoof unterscheiden.\
• Ein **Faltungsneuronales Netz (CNN)** validiert Gesichtsmerkmale und identifiziert Anomalien, wie sie etwa bei gedruckten Fotos oder digitalen Bildschirmen vorkommen.\
• Bietet eine **schnelle und bequeme** Verifizierung bei **standardmäßiger Sicherheit**, geeignet für Anwendungsfälle mit geringem Risiko.\
|
Standard |
Reibungsarme Szenarien, Verbraucheranwendungen |
> [!NOTE]
>
> **Erweiterte Sicherheit von 3D Flash und 3D Action & Flash:**
>
> > * Diese Methoden wurden entwickelt, um **ausgeklügelte Spoofing-Angriffe** wie **hochwertige Masken**, **Deepfakes** und **Videowiedergaben** abzuwehren.
> > * Durch das Projizieren dynamischer Lichtmuster und das Analysieren ihrer Reflexionen erkennen sie, wie Licht mit einem **echten 3D-Gesicht** im Vergleich zu einer flachen oder künstlichen Oberfläche interagiert.
> > * Die Methode **3D Action & Flash** fügt durch eine randomisierte Aktion (z. B. Blinzeln oder Nicken) eine zusätzliche Sicherheitsebene hinzu, die **Echtzeit-Verhaltensreaktionen** erfordert, welche vorab aufgezeichnete Medien oder synthetische Identitäten nicht reproduzieren können.
> > * Diese Methoden liefern nachweislich **hohe Genauigkeit** und **niedrige Falschakzeptanzraten** und sind ideal für Umgebungen mit hohen Risiken bzw. weitreichenden Konsequenzen.Jede Methode generiert basierend auf unserem proprietären Algorithmus einen **normalisierten Liveness-Score (0-100%)**, der mehrere Sicherheitsfaktoren in Echtzeit auswertet.### Konfigurierbare SchwellenwerteSie können die Sicherheitsstufen anpassen, indem Sie unterschiedliche Schwellenwerte für Liveness-Scores festlegen. Zum Beispiel:> [!NOTE]
>
> Diese Schwellenwerte können basierend auf Ihrer **Risikotoleranz** und Ihren **Sicherheitsanforderungen** angepasst werden und bieten so Flexibilität über verschiedene Anwendungsfälle hinweg.## Wiederholungsversuche und konkretes FeedbackIn einer Didit-Sitzung führt eine Liveness-Erfassung, die aus einem **behebbaren Grund** fehlschlägt (schlechte Beleuchtung, nicht zentriertes Gesicht, Verdeckung, ein grenzwertiger Score), nicht sofort zu einer Ablehnung. Der Benutzer wird aufgefordert, **mit konkreten Anweisungen einen Wiederholungsversuch** zu unternehmen, bis zu einer konfigurierbaren Anzahl von Versuchen.* **Versuchskontingent** — `face_liveness_max_attempts` steuert die Gesamtzahl der Liveness-Einreichungen pro Sitzung. Standardmäßig **3** (ein erster Versuch plus zwei Wiederholungsversuche), konfigurierbar pro Workflow-Knoten (Bereich 1–3).
* **Feedback bei Wiederholungsversuchen** — Solange noch Versuche verbleiben, hält ein wiederholbarer Fehler den Benutzer im Liveness-Schritt und gibt einen Body mit umsetzbaren `feedback_codes` zurück (die Web- und Mobile-SDKs zeigen diese automatisch als Coaching-Hinweise an):
```json theme={null}
{
"detail": "Move to a brighter, evenly lit place and try again.",
"error": "LOW_FACE_LUMINANCE",
"feedback_codes": ["LOW_FACE_LUMINANCE"],
"attempts_used": 1,
"max_attempts": 3
}
```
* **Wiederholbare Codes** — `LOW_FACE_LUMINANCE` (zu dunkel), `HIGH_FACE_LUMINANCE` (zu hell), `NO_FACE_DETECTED`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, `LOW_LIVENESS_SCORE`, `MULTIPLE_FACES_DETECTED`, `AGE_NOT_DETECTED`.
* **Garantierter Wiederholungsversuch bei Aufnahmebedingungen** — `LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION` und `NO_FACE_DETECTED` beschreiben die Umgebung, in der sich der Benutzer befindet, nicht die Person selbst. Schlägt ein Versuch ausschließlich aufgrund dieser Codes fehl, erhält der Benutzer immer einen zweiten Versuch mit dem oben genannten Coaching-Hinweis, selbst in einem Workflow mit der Konfiguration `face_liveness_max_attempts: 1`. Jeder andere Code folgt weiterhin exakt dem konfigurierten Kontingent.
* **Erschöpfung des Kontingents und Betrug** — Sobald das Kontingent erschöpft ist, wird der berechnete Status angewendet (`Declined` oder `In Review`). Bestätigte Präsentationsangriffe (`LIVENESS_FACE_ATTACK`), Treffer auf Sperrlisten und doppelte Gesichter werden **sofort abgelehnt** und können niemals wiederholt werden.> [!NOTE]
>
> Wiederholungsversuche gelten ausschließlich für den **Sitzungsablauf**. Der eigenständige Endpoint `POST /v3/passive-liveness/` ist zustandslos und umfasst nur einen einzigen Aufruf — er liefert das Ergebnis direkt ohne Wiederholungskontingent zurück.## So funktioniert es**1. Video-Selfie-Erfassung**Der Benutzer wird durch eine **einfache, intuitive Benutzeroberfläche** geführt, die auf die ausgewählte Liveness-Methode abgestimmt ist.| Prüfung | Beschreibung |
| - | - |
| **Echtzeit-Feedback** | Gewährleistet angemessene Beleuchtung, Positionierung und Bildausschnitt |
| **Qualitätsprüfungen** | Prüft auf Unschärfe, Blendung und optimale Sichtbarkeit des Gesichts |
| **Adaptive Erfassung** | Passt sich an verschiedene Gerätefunktionen und Netzwerkbedingungen an |
| **Methodenspezifische Anleitung** | Zeigt spezifische Anweisungen für die Methode an (z. B. „Jetzt blinzeln“ bei 3D Action) |**2. Analyse der Liveness-Erkennung**Fortschrittliche Algorithmen verarbeiten die erfassten Medien in **Echtzeit**, um Spoofing-Versuche zu erkennen. Die Analyse unterscheidet sich je nach Methode:> [accordion] 3D Action & Flash
>
> * Verifiziert die Aktion des Benutzers (z. B. **Blinzeln** oder **Nicken**), um zu bestätigen, dass sie korrekt und live ausgeführt wird
> * Analysiert **Lichtmusterreflexionen**, um die dreidimensionale Struktur des Gesichts zu validieren
> * Nutzt Deep Learning zur Auswertung von **Mikroausdrücken** und weiteren Verhaltenssignalen
> * Kombiniert verhaltensbasierte und physische Signale für die **höchste Spoofing-Resistenz**> [accordion] 3D Flash
>
> * Verarbeitet eine Sequenz von **Lichtmusterreflexionen** bei 30+ FPS, um eine detaillierte **Tiefenkarte** zu erstellen
> * Bestätigt die 3D-Eigenschaften des Gesichts und unterscheidet es von flachen oder 2D-Spoofs
> * Keine Benutzerinteraktion erforderlich — aus Sicht des Benutzers **vollständig passiv**> [accordion] Passive Liveness
>
> * Wendet **Deep Learning** auf ein einzelnes Bild an, um **Texturmuster** und **Artefakte** zu erkennen
> * Ein Convolutional Neural Network (CNN) validiert Gesichtsmerkmale und identifiziert Anomalien
> * Schnellste Methode — funktioniert mit einer **einzelnen Fotoaufnahme**Die mehrschichtige Erkennung identifiziert **Präsentationsangriffe** einschließlich Fotos, Bildschirmen, Masken und Deepfakes.**3. Ergebnisverarbeitung und Verifizierung**Das System vergleicht den Liveness-Score mit Ihren **konfigurierten Schwellenwerten** und liefert die Ergebnisse sofort.| Ausgabe | Beschreibung |
| - | - |
| **Liveness-Score** | Normalisierter Konfidenzwert von 0–100% |
| **Entscheidung** | Genehmigt, Abgelehnt oder In Prüfung basierend auf Ihren Schwellenwerten |
| **Methode** | Welche Liveness-Methode verwendet wurde (`passive`, `flash`, `action_flash`) |
| **Referenzbild** | Erfasstes Einzelbild, das für die Liveness-Prüfung verwendet wurde |
| **Warnungen** | Alle erkannten Anomalien (z. B. geringe Qualität, potenzielle Spoofing-Indikatoren) |Die Ergebnisse werden über eine **API-Antwort** oder einen **Webhook** bereitgestellt oder können in der **Business Console** mit detaillierten Audit-Logs für Compliance-Zwecke eingesehen werden.> [!TIP]
>
> Sie können in der [Business Console](https://docs.didit.me/de/console/workflows.md) pro Workflow konfigurieren, welche Liveness-Methode verwendet werden soll. Unterschiedliche Workflows können je nach Ihren Risikoanforderungen unterschiedliche Methoden nutzen.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.