> ## 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 prueba de vida: prevención de deepfakes
> Didit detecta deepfakes, máscaras y ataques de presentación con prueba de vida pasiva y activa. Precisión del 99.9%, probada por iBeta, desde $0.10 por llamada.
La prueba de vida de Didit confirma que hay una persona real y presente frente a la cámara, y no una foto impresa, una reproducción en pantalla, una máscara o un deepfake, mediante prueba de vida pasiva, con acción 3D o con destellos. Alcanza una **precisión del 99.9%** con una tasa de falsa aceptación (FAR) inferior al **0.1%**.
Prompt de integración de la prueba de vida
Copy prompt to clipboard
\
\````# 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````
\
Paste into
La lección de Academy sobre el flujo alojado del usuario llega al selfie de prueba de vida en el minuto 8:49 y, en el 9:16, a los métodos pasivo, de destello 3D y de acción 3D.[El selfie de prueba de vida — Didit Academy](https://www.youtube.com/embed/LzGe-dMWjUw?start=529\&rel=0\&playsinline=1)## Métodos de prueba de vidaNuestra plataforma implementa tres tecnologías antisuplantación distintas, cada una pensada para diferentes necesidades de seguridad y experiencias de usuario:
| Método |
Descripción |
Nivel de seguridad |
Ideal para |
| **`3D Action & Flash`** |
• Combina una verificación biométrica multifactor con una **secuencia de acciones aleatoria** y un **análisis dinámico de patrones de luz**.\
• Al comenzar, se pide al usuario una acción sencilla, como **parpadear** o **asentir**, lo que asegura la interacción en tiempo real.\
• A la vez, el sistema proyecta una secuencia de patrones de luz sobre el rostro y analiza los **reflejos** para confirmar la estructura tridimensional de la cara.\
• Los **algoritmos de aprendizaje profundo** examinan las microexpresiones y las respuestas a los reflejos de luz para verificar la presencia de una persona real.\
• Ofrece la **máxima seguridad** al integrar señales de comportamiento (acción) y físicas (profundidad basada en luz), lo que hace casi imposible suplantarlo con imágenes estáticas, vídeos o incluso máscaras avanzadas.
|
Máximo |
Aplicaciones bancarias, sanitarias y gubernamentales |
| **`3D Flash`** |
• Usa un **análisis dinámico de patrones de luz** para validar la topología facial sin requerir interacción del usuario.\
• Proyecta una serie de patrones de luz sobre el rostro a más de **30 fotogramas por segundo** y analiza los reflejos para crear un **mapa de profundidad**.\
• Este mapa de profundidad confirma la estructura tridimensional del rostro y lo distingue de imágenes planas o suplantaciones 2D.\
• Ofrece una **experiencia fluida** y mantiene una **alta seguridad** frente a ataques de presentación como fotos o pantallas.\
|
Alto |
Servicios financieros, acceso a cuentas, verificación de identidad |
| **`Passive Liveness`** |
• Se basa en un **análisis de aprendizaje profundo de un solo fotograma** para detectar indicios de vida.\
• Examina la imagen en busca de **artefactos**, **patrones de textura** y otros indicadores sutiles que diferencian un rostro real de una suplantación.\
• Una **red neuronal convolucional (CNN)** valida los rasgos faciales e identifica anomalías, como las de fotos impresas o pantallas digitales.\
• Ofrece una verificación **rápida y cómoda**, pero con una seguridad **estándar**, adecuada para casos de uso de bajo riesgo.\
|
Estándar |
Escenarios de baja fricción, aplicaciones de consumo |
> [!NOTE]
>
> **Seguridad avanzada de 3D Flash y 3D Action & Flash:**
>
> > * Estos métodos están diseñados para frustrar **ataques de suplantación sofisticados**, como **máscaras de alta calidad**, **deepfakes** y **reproducciones de vídeo**.
> > * Al proyectar patrones de luz dinámicos y analizar sus reflejos, detectan cómo interactúa la luz con un **rostro 3D real** frente a una superficie plana o artificial.
> > * El método **3D Action & Flash** añade una capa extra de seguridad con una acción aleatoria (por ejemplo, parpadear o asentir) que exige **respuestas de comportamiento en tiempo real** que los medios pregrabados o las identidades sintéticas no pueden replicar.
> > * Está demostrado que ofrecen una **alta precisión** y **bajas tasas de falsa aceptación**, por lo que son ideales para entornos de alto riesgo.Cada método genera una **puntuación de prueba de vida normalizada (0-100%)** basada en nuestro algoritmo propietario, que evalúa varios factores de seguridad en tiempo real.### Umbrales configurablesPuedes personalizar los niveles de seguridad definiendo distintos umbrales para las puntuaciones de prueba de vida. Por ejemplo:> [!NOTE]
>
> Estos umbrales se pueden ajustar según tu **tolerancia al riesgo** y tus **requisitos de seguridad**, lo que da flexibilidad en distintos casos de uso.## Reintentos y feedback accionableEn una sesión de Didit, una captura de prueba de vida que falla por una **causa corregible** (poca luz, rostro descentrado, oclusión, una puntuación en el límite) no se rechaza de inmediato. Se pide al usuario que **reintente con indicaciones concretas**, hasta un número de intentos configurable.* **Número de intentos** - `face_liveness_max_attempts` controla el total de envíos de prueba de vida por sesión. Por defecto es **3** (un intento inicial más dos reintentos) y se puede configurar por nodo del flujo (rango 1-3).
* **Feedback de reintento** - mientras queden intentos, un fallo reintentable mantiene al usuario en el paso de prueba de vida y devuelve un cuerpo con `feedback_codes` accionables (los SDK web y móviles los muestran automáticamente como mensajes de ayuda):
```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
}
```
* **Códigos reintentables** - `LOW_FACE_LUMINANCE` (demasiado oscuro), `HIGH_FACE_LUMINANCE` (demasiado brillante), `NO_FACE_DETECTED`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, `LOW_LIVENESS_SCORE`, `MULTIPLE_FACES_DETECTED`, `AGE_NOT_DETECTED`.
* **Reintento garantizado por condiciones de captura** - `LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION` y `NO_FACE_DETECTED` describen el lugar donde está el usuario, no a la persona. Cuando un intento falla únicamente por esos códigos, el usuario siempre recibe un segundo intento con el mensaje de ayuda anterior, incluso en un flujo configurado con `face_liveness_max_attempts: 1`. Cualquier otro código sigue aplicando exactamente el número de intentos configurado.
* **Agotamiento y fraude** - cuando se agotan los intentos, se aplica el estado calculado (`Declined` o `In Review`). Los ataques de presentación confirmados (`LIVENESS_FACE_ATTACK`), las coincidencias con la lista de bloqueo y los rostros duplicados **se rechazan de inmediato** y nunca se reintentan.> [!NOTE]
>
> Los reintentos se aplican solo al **flujo de sesión**. El endpoint independiente `POST /v3/passive-liveness/` no guarda estado y es de un solo intento: devuelve el resultado directamente, sin número de reintentos.## Cómo funciona**1. Captura del selfie en vídeo**Se guía al usuario con una **interfaz sencilla e intuitiva** adaptada al método de prueba de vida seleccionado.| Comprobación | Descripción |
| - | - |
| **Feedback en tiempo real** | Asegura una iluminación, posición y encuadre adecuados |
| **Controles de calidad** | Vigila el desenfoque, los reflejos y la visibilidad óptima del rostro |
| **Captura adaptativa** | Se ajusta a las capacidades de cada dispositivo y a las condiciones de red |
| **Guía del método** | Muestra instrucciones específicas de cada método (por ejemplo, "Parpadea ahora" en 3D Action) |**2. Análisis de la prueba de vida**Algoritmos avanzados procesan el contenido capturado en **tiempo real** para detectar intentos de suplantación. El análisis varía según el método:> **3D Action & Flash**
>
> * Verifica la acción del usuario (por ejemplo, **parpadear** o **asentir**) para confirmar que se realiza correctamente y en directo
> * Analiza los **reflejos de los patrones de luz** para validar la estructura tridimensional del rostro
> * Usa aprendizaje profundo para evaluar las **microexpresiones** y otras señales de comportamiento
> * Combina señales de comportamiento y físicas para lograr la **mayor resistencia a la suplantación**> **3D Flash**
>
> * Procesa una secuencia de **reflejos de patrones de luz** a 30+ FPS para construir un **mapa de profundidad** detallado
> * Confirma las propiedades 3D del rostro y lo distingue de suplantaciones planas o 2D
> * No requiere interacción del usuario: es totalmente **pasivo desde su punto de vista**> **Passive Liveness**
>
> * Aplica **aprendizaje profundo** a un solo fotograma para detectar **patrones de textura** y **artefactos**
> * Una red neuronal convolucional (CNN) valida los rasgos faciales e identifica anomalías
> * Es el método más rápido: funciona con una **única captura fotográfica**La detección multicapa identifica **ataques de presentación** como fotos, pantallas, máscaras y deepfakes.**3. Procesamiento del resultado y verificación**El sistema compara la puntuación de prueba de vida con tus **umbrales configurados** y entrega los resultados al instante.| Resultado | Descripción |
| - | - |
| **Puntuación de prueba de vida** | Puntuación de confianza normalizada de 0 a 100% |
| **Decisión** | Aprobado, Rechazado o En revisión según tus umbrales |
| **Método** | Qué método de prueba de vida se usó (`passive`, `flash`, `action_flash`) |
| **Imagen de referencia** | Fotograma capturado usado para la comprobación de prueba de vida |
| **Advertencias** | Cualquier anomalía detectada (por ejemplo, baja calidad, posibles indicios de suplantación) |Los resultados se entregan mediante **respuesta de la API**, **webhook**, o se pueden consultar en la **Business Console** con registros de auditoría detallados para el cumplimiento normativo.> [!TIP]
>
> Puedes configurar qué método de prueba de vida usar en cada flujo desde la [Business Console](https://docs.didit.me/console/workflows.md). Distintos flujos pueden usar métodos diferentes según tus requisitos de riesgo.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.