> ## 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.
# Rilevamento della vitalità: API e prevenzione deepfake
> Rileva deepfake e attacchi di presentazione con Didit. Vitalità passiva e attiva, precisione 99.9%, testata iBeta, da $0.10 per chiamata.
Il Rilevamento della vitalità di Didit conferma che davanti alla fotocamera è presente una persona reale e viva, non una foto stampata, una riproduzione su schermo, una maschera o un deepfake, utilizzando il rilevamento passivo, con azione 3D o con flash. Raggiunge un'**accuratezza del 99.9%** con un tasso di falsa accettazione (FAR) inferiore allo **0.1%**.
Prompt di integrazione del rilevamento della vitalità
Copia il prompt negli appunti
\
\````# 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````
\
Incolla in
La lezione di Academy sul flusso utente ospitato arriva al selfie di rilevamento della vitalità al minuto 8:49, seguita al minuto 9:16 dal metodo passivo, dal 3D Flash e dal 3D Action.[Il selfie di rilevamento della vitalità — Didit Academy](https://www.youtube.com/embed/LzGe-dMWjUw?start=529\&rel=0\&playsinline=1)## Metodi di rilevamento della vitalitàLa nostra piattaforma implementa tre distinte tecnologie anti-spoofing, ciascuna adattata a diverse esigenze di sicurezza ed esperienze utente:
| Metodo |
Descrizione |
Livello di sicurezza |
Ideale per |
| **`3D Action & Flash`** |
• Combina la verifica biometrica a più fattori con una **sequenza casuale di azioni** e l'**analisi di pattern luminosi dinamici**.\
• All'inizio, all'utente viene richiesto di eseguire una semplice azione, come **sbattere le palpebre** o **annuire**, garantendo un'interazione in tempo reale.\
• Contemporaneamente, il sistema proietta una sequenza di pattern luminosi sul viso, analizzando i **riflessi** per confermare la struttura tridimensionale del volto.\
• Gli **algoritmi di deep learning** esaminano le microespressioni e le risposte ai riflessi di luce per verificare la presenza di una persona dal vivo.\
• Offre il **massimo livello di sicurezza** integrando elementi comportamentali (azione) e fisici (profondità basata sulla luce), rendendo quasi impossibile lo spoofing tramite immagini statiche, video o maschere avanzate.
|
Massimo |
Settore bancario, sanitario e applicazioni governative |
| **`3D Flash`** |
• Utilizza l'**analisi di pattern luminosi dinamici** per convalidare la topologia facciale senza richiedere interazioni da parte dell'utente.\
• Proietta una serie di pattern luminosi sul viso a oltre **30 fotogrammi al secondo**, analizzando i riflessi per creare una **mappa di profondità**.\
• Questa mappa di profondità conferma la struttura tridimensionale del volto, distinguendolo da immagini piatte o tentativi di spoofing 2D.\
• Offre un'**esperienza fluida** mantenendo al contempo un'**elevata sicurezza** contro attacchi di presentazione come foto o schermi.\
|
Alto |
Servizi finanziari, accesso all'account, verifica dell'identità |
| **`Passive Liveness`** |
• Si basa sull'**analisi di deep learning a singolo fotogramma** per rilevare i segni di vitalità.\
• Esamina l'immagine alla ricerca di **artefatti**, **pattern di texture** e altri indicatori impercettibili che differenziano un viso reale da un tentativo di spoofing.\
• Una **rete neurale convoluzionale (CNN)** convalida i tratti somatici e identifica anomalie, come quelle derivanti da foto stampate o schermi digitali.\
• Offre una verifica **rapida e comoda**, ma fornisce una **sicurezza standard**, adatta per casi d'uso a basso rischio.\
|
Standard |
Scenari a basso attrito, applicazioni consumer |
> [!NOTE]
>
> **Sicurezza avanzata di 3D Flash e Azione 3D e Flash:**
>
> > * Questi metodi sono progettati per contrastare **attacchi di spoofing sofisticati**, come **maschere di alta qualità**, **deepfake** e **riproduzioni video**.
> > * Proiettando pattern luminosi dinamici e analizzandone i riflessi, rilevano l'interazione della luce con un **vero viso 3D** rispetto a una superficie piatta o artificiale.
> > * Il metodo **Azione 3D e Flash** aggiunge un ulteriore livello di sicurezza con un'azione casuale (ad es. sbattere le palpebre o annuire), richiedendo **risposte comportamentali in tempo reale** che i supporti preregistrati o le identità sintetiche non possono replicare.
> > * Con una comprovata **elevata accuratezza** e **bassi tassi di falsa accettazione**, questi metodi sono ideali per ambienti ad alto rischio.Ogni metodo genera un **punteggio di vitalità normalizzato (0-100%)** basato sul nostro algoritmo proprietario, che valuta molteplici fattori di sicurezza in tempo reale.### Soglie configurabiliPuoi personalizzare i livelli di sicurezza impostando soglie diverse per i punteggi di vitalità. Ad esempio:> [!NOTE]
>
> Queste soglie possono essere regolate in base alla tua **tolleranza al rischio** e ai tuoi **requisiti di sicurezza**, offrendo flessibilità per diversi casi d'uso.## Nuovi tentativi e feedback praticoIn una sessione di Didit, un'acquisizione per il rilevamento della vitalità che non va a buon fine per un **motivo risolvibile** (scarsa illuminazione, viso non centrato, occlusione, un punteggio al limite) non viene immediatamente rifiutata. All'utente viene chiesto di **riprovare seguendo indicazioni specifiche**, fino a un numero configurabile di tentativi.* **Budget di tentativi** — `face_liveness_max_attempts` controlla il numero totale di invii per il rilevamento della vitalità per sessione. Il valore predefinito è **3** (un tentativo iniziale più due nuovi tentativi), configurabile per ciascun nodo del workflow (intervallo 1–3).
* **Feedback per i nuovi tentativi** — finché rimangono tentativi disponibili, un errore recuperabile mantiene l'utente nel passaggio del rilevamento della vitalità e restituisce un corpo contenente `feedback_codes` pratici (gli SDK Web e Mobile li mostrano automaticamente sotto forma di messaggi guida):
```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
}
```
* **Codici con nuovo tentativo consentito** — `LOW_FACE_LUMINANCE` (troppo scuro), `HIGH_FACE_LUMINANCE` (troppo luminoso), `NO_FACE_DETECTED`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, `LOW_LIVENESS_SCORE`, `MULTIPLE_FACES_DETECTED`, `AGE_NOT_DETECTED`.
* **Nuovo tentativo garantito per le condizioni di acquisizione** — `LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION` e `NO_FACE_DETECTED` descrivono l'ambiente in cui si trova l'utente, non la persona. Quando un tentativo fallisce solo per questi codici, l'utente riceve sempre un secondo tentativo con il messaggio guida indicato sopra, anche in un workflow configurato con `face_liveness_max_attempts: 1`. Tutti gli altri codici seguono rigorosamente il budget configurato.
* **Esaurimento e frode** — una volta esaurito il budget, viene applicato lo stato calcolato (`Declined` o `In Review`). Gli attacchi di presentazione confermati (`LIVENESS_FACE_ATTACK`), le corrispondenze nella blocklist e i volti duplicati vengono **rifiutati immediatamente** e non consentono mai nuovi tentativi.> [!NOTE]
>
> I nuovi tentativi si applicano solo al **flusso della sessione**. L'endpoint autonomo `POST /v3/passive-liveness/` è senza stato e con una sola esecuzione: restituisce il risultato direttamente senza alcun budget di nuovi tentativi.## Come funziona**1. Acquisizione del video selfie**L'utente viene guidato attraverso un'**interfaccia semplice e intuitiva**, su misura per il metodo di rilevamento della vitalità selezionato.| Controllo | Descrizione |
| - | - |
| **Feedback in tempo reale** | Garantisce illuminazione, posizionamento e inquadratura corretti |
| **Controlli di qualità** | Monitora sfocature, riflessi e visibilità ottimale del viso |
| **Acquisizione adattiva** | Si adatta alle capacità dei vari dispositivi e alle condizioni di rete |
| **Guida specifica per il metodo** | Mostra istruzioni dedicate al metodo (ad es. "Batti le palpebre ora" per 3D Action) |**2. Analisi di rilevamento della vitalità**Algoritmi avanzati elaborano i contenuti acquisiti in **tempo reale** per rilevare tentativi di spoofing. L'analisi varia in base al metodo:> [accordion] 3D Action & Flash
>
> * Verifica l'azione dell'utente (ad es. **sbattere le palpebre** o **annuire**) per confermare che sia eseguita correttamente e dal vivo
> * Analizza i **riflessi dei pattern luminosi** per convalidare la struttura tridimensionale del viso
> * Utilizza il deep learning per valutare le **microespressioni** e altri segnali comportamentali
> * Combina segnali comportamentali e fisici per offrire la **massima resistenza allo spoofing**> [accordion] 3D Flash
>
> * Elabora una sequenza di **riflessi dei pattern luminosi** a 30+ FPS per costruire una **mappa di profondità** dettagliata
> * Conferma le proprietà 3D del viso, distinguendolo da tentativi di spoofing piatti o 2D
> * Nessuna interazione richiesta all'utente: completamente **passivo dal punto di vista dell'utente**> [accordion] Passive Liveness
>
> * Applica il **deep learning** a un singolo fotogramma per rilevare **pattern di texture** e **artefatti**
> * Una rete neurale convoluzionale (CNN) convalida i tratti somatici e identifica eventuali anomalie
> * Metodo più rapido: funziona con l'**acquisizione di una singola foto**Il rilevamento multistrato identifica gli **attacchi di presentazione**, tra cui foto, schermi, maschere e deepfake.**3. Elaborazione dei risultati e verifica**Il sistema confronta il punteggio di vitalità con le tue **soglie configurate** e fornisce i risultati all'istante.| Risultato | Descrizione |
| - | - |
| **Punteggio di vitalità** | Punteggio di affidabilità normalizzato da 0 a 100% |
| **Decisione** | Approvata, Rifiutata o In revisione in base alle tue soglie |
| **Metodo** | Quale metodo di rilevamento della vitalità è stato utilizzato (`passive`, `flash`, `action_flash`) |
| **Immagine di riferimento** | Fotogramma acquisito utilizzato per il controllo della vitalità |
| **Avvisi** | Eventuali anomalie rilevate (ad es. bassa qualità, potenziali indicatori di spoofing) |I risultati vengono inviati tramite **risposta API**, **webhook** o sono visualizzabili nella **Console Aziendale** con registri di audit dettagliati per la compliance.> [!TIP]
>
> Puoi configurare quale metodo di rilevamento della vitalità utilizzare per ciascun workflow nella [Console Aziendale](https://docs.didit.me/it/console/workflows.md). Workflow diversi possono utilizzare metodi diversi a seconda delle tue esigenze di rischio.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.