> ## 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.
# API de prova de vida: prevenció de deepfakes
> Detecta deepfakes i atacs de presentació amb la prova de vida passiva i activa de Didit. 99.9% de precisió, testada per iBeta, des de $0.10.
La Prova de vida de Didit confirma que hi ha una persona viva i real davant de la càmera, i no pas una foto impresa, una reproducció en pantalla, una màscara o un deepfake, mitjançant prova de vida passiva, acció 3D o flash. Assoleix una **precisió del 99.9%** amb una taxa de falsa acceptació (FAR) per sota del **0.1%**.
Prompt d'integració de prova de vida
Copia el prompt al porta-retalls
\
\````# 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````
\
Enganxa a
La lliçó d'Academy sobre el flux d'usuari allotjat arriba a la selfie de la prova de vida al minut 8:49, seguida al minut 9:16 pels mètodes de prova de vida passiva, 3D Flash i acció 3D.[The liveness selfie — Didit Academy](https://www.youtube.com/embed/LzGe-dMWjUw?start=529\&rel=0\&playsinline=1)## Mètodes de prova de vidaLa nostra plataforma implementa tres tecnologies antisuplantació diferenciades, cadascuna adaptada a necessitats de seguretat i experiències d'usuari diferents:
| Mètode |
Descripció |
Nivell de seguretat |
Ideal per a |
| **`3D Action & Flash`** |
• Combina la verificació biomètrica multifactor amb una **seqüència d'accions aleatòria** i l'**anàlisi dinàmica de patrons de llum**.\
• A l'inici, es demana a l'usuari que faci una acció senzilla—com ara **parpellejar** o **assentir amb el cap**—, cosa que garanteix una interacció en temps real.\
• Simultàniament, el sistema projecta una seqüència de patrons de llum sobre la cara i n'analitza els **reflexos** per confirmar l'estructura tridimensional del rostre.\
• Els **algorismes d'aprenentatge profund** examinen les microexpressions i les respostes de reflexió de la llum per verificar la presència d'una persona viva.\
• Ofereix el **nivell màxim de seguretat** en integrar senyals conductuals (acció) i físics (profunditat basada en la llum), cosa que fa gairebé impossible suplantar-la amb imatges estàtiques, vídeos o fins i tot màscares avançades.
|
Màxim |
Banca, sanitat, aplicacions governamentals |
| **`3D Flash`** |
• Utilitza l'**anàlisi dinàmica de patrons de llum** per validar la topologia facial sense requerir la interacció de l'usuari.\
• Projecta una sèrie de patrons de llum sobre la cara a més de **30 fotogrames per segon**, analitzant els reflexos per crear un **mapa de profunditat**.\
• Aquest mapa de profunditat confirma l'estructura tridimensional de la cara i la distingeix d'imatges planes o suplantacions en 2D.\
• Proporciona una **experiència fluida** alhora que manté una **alta seguretat** contra atacs de presentació com ara fotos o pantalles.\
|
Alt |
Serveis financers, accés a comptes, verificació d'identitat |
| **`Passive Liveness`** |
• Es basa en l'**anàlisi d'aprenentatge profund d'un sol fotograma** per detectar indicis de vida.\
• Examina la imatge per detectar **artefactes**, **patrons de textura** i altres indicadors subtils que diferencien una cara real d'una suplantació.\
• Una **xarxa neuronal convolucional (CNN)** valida els trets facials i identifica anomalies, com ara les procedents de fotos impreses o pantalles digitals.\
• Ofereix una verificació **ràpida i còmoda**, però proporciona una **seguretat estàndard**, adequada per a casos d'ús de baix risc.\
|
Estàndard |
Escenaris de baixa fricció, aplicacions de consum |
> [!NOTE]
>
> **Seguretat avançada de 3D Flash i Acció 3D i Flash:**
>
> > * Aquests mètodes estan dissenyats per neutralitzar **atacs de suplantació sofisticats**, com ara **màscares d'alta qualitat**, **deepfakes** i **reproduccions de vídeo**.
> > * En projectar patrons de llum dinàmics i analitzar-ne els reflexos, detecten com interactua la llum amb una **cara 3D real** en comparació amb una superfície plana o artificial.
> > * El mètode **Acció 3D i Flash** afegeix una capa addicional de seguretat amb una acció aleatòria (p. ex., parpellejar o assentir amb el cap), exigint **respostes conductuals en temps real** que el contingut multimèdia pregravat o les identitats sintètiques no poden replicar.
> > * Aquests mètodes han demostrat oferir una **alta precisió** i **taxes de falsa acceptació baixes**, per la qual cosa són ideals per a entorns d'alta exigència.Cada mètode genera una **puntuació de prova de vida normalitzada (0-100%)** basada en el nostre algorisme propietari, que avalua múltiples factors de seguretat en temps real.### Llindars configurablesPots personalitzar els nivells de seguretat establint diferents llindars per a les puntuacions de prova de vida. Per exemple:> [!NOTE]
>
> Aquests llindars es poden ajustar en funció de la teva **tolerància al risc** i dels teus **requisits de seguretat**, oferint flexibilitat per a diferents casos d'ús.## Reintents i indicacions útilsEn una sessió de Didit, una captura de prova de vida que falla per un **motiu solucionable** (il·luminació deficient, rostre no centrat, oclusió, una puntuació límit) no es rebutja immediatament. Es demana a l'usuari que **reintenti amb indicacions específiques**, fins a un nombre configurable d'intents.* **Límit d'intents** — `face_liveness_max_attempts` controla el nombre total d'enviaments de prova de vida per sessió. Per defecte **3** (un intent inicial més dos reintents), configurable per node del flux de treball (interval 1–3).
* **Indicacions de reintent** — mentre quedin intents, una fallada reintentable manté l'usuari en el pas de prova de vida i retorna un cos que conté `feedback_codes` útils (els SDK web i mòbils els mostren automàticament com a missatges d'orientació):
```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
}
```
* **Codis reintentables** — `LOW_FACE_LUMINANCE` (massa fosc), `HIGH_FACE_LUMINANCE` (massa clar), `NO_FACE_DETECTED`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, `LOW_LIVENESS_SCORE`, `MULTIPLE_FACES_DETECTED`, `AGE_NOT_DETECTED`.
* **Reintent garantit per condicions de captura** — `LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION` i `NO_FACE_DETECTED` descriuen l'espai on es troba l'usuari, no pas la persona. Quan un intent falla només per aquests codis, l'usuari sempre obté un segon intent amb el missatge d'orientació anterior, fins i tot en un flux de treball configurat amb `face_liveness_max_attempts: 1`. Qualsevol altre codi segueix exactament el límit configurat.
* **Esgotament i frau** — un cop exhaurit el límit, s'aplica l'estat calculat (`Declined` o `In Review`). Els atacs de presentació confirmats (`LIVENESS_FACE_ATTACK`), les coincidències amb llistes de bloqueig i els rostres duplicats **es rebutgen immediatament** i mai es reintenten.> [!NOTE]
>
> Els reintents només s'apliquen al **flux de la sessió**. L'endpoint independent `POST /v3/passive-liveness/` és sense estat i funciona amb una sola execució: retorna el resultat directament sense cap límit de reintents.## Com funciona**1. Captura de vídeo selfie**Es guia l'usuari a través d'una **interfície senzilla i intuïtiva** adaptada al mètode de prova de vida seleccionat.| Comprovació | Descripció |
| - | - |
| **Informació en temps real** | Garanteix una il·luminació, un posicionament i un enquadrament correctes |
| **Comprovacions de qualitat** | Monitora el desenfocament, els reflexos i la visibilitat facial òptima |
| **Captura adaptativa** | S'adapta a les capacitats de diversos dispositius i a les condicions de la xarxa |
| **Guia del mètode** | Mostra instruccions específiques del mètode (per exemple, "Parpelleja ara" per a 3D Action) |**2. Anàlisi de la prova de vida**Algoritmes avançats processen el material multimèdia capturat en **temps real** per detectar intents de suplantació. L'anàlisi varia segons el mètode:> [accordion] 3D Action & Flash
>
> * Verifica l'acció de l'usuari (per exemple, **parpellejar** o **assentir amb el cap**) per confirmar que es realitza correctament i en directe
> * Analitza els **reflexos de patrons de llum** per validar l'estructura tridimensional del rostre
> * Utilitza aprenentatge profund per avaluar **microexpressions** i altres senyals conductuals
> * Combina senyals conductuals i físics per oferir la **màxima resistència contra la suplantació**> [accordion] 3D Flash
>
> * Processa una seqüència de **reflexos de patrons de llum** a 30+ FPS per construir un **mapa de profunditat** detallat
> * Confirma les propietats 3D del rostre, distingint-lo de suplantacions de superfícies planes o en 2D
> * No requereix cap interacció per part de l'usuari: completament **passiu des de la perspectiva de l'usuari**> [accordion] Passive Liveness
>
> * Aplica **aprenentatge profund** a un únic fotograma per detectar **patrons de textura** i **artefactes**
> * Una xarxa neuronal convolucional (CNN) valida els trets facials i identifica anomalies
> * El mètode més ràpid: funciona amb la **captura d'una sola foto**La detecció multicapa identifica **atacs de presentació**, incloent-hi fotos, pantalles, màscares i deepfakes.**3. Processament i verificació dels resultats**El sistema compara la puntuació de prova de vida amb els teus **llindars configurats** i lliura els resultats a l'instant.| Sortida | Descripció |
| - | - |
| **Puntuació de prova de vida** | Puntuació de confiança normalitzada del 0–100% |
| **Decisió** | Aprovada, Rebutjada o En revisió segons els teus llindars |
| **Mètode** | Quin mètode de prova de vida s'ha utilitzat (`passive`, `flash`, `action_flash`) |
| **Imatge de referència** | Fotograma capturat utilitzat per a la comprovació de la prova de vida |
| **Advertiments** | Qualsevol anomalia detectada (per exemple, baixa qualitat, indicadors potencials de suplantació) |Els resultats es lliuren mitjançant una **resposta de l'API**, un **webhook** o es poden consultar a la **Business Console** amb registres d'auditoria detallats per al compliment.> [!TIP]
>
> Pots configurar quin mètode de prova de vida s'utilitza per a cada flux de treball a la [Business Console](https://docs.didit.me/ca/console/workflows.md). Diferents fluxos de treball poden utilitzar mètodes diferents segons els teus requisits de risc.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.