> ## 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: prevenção de deepfakes
> A prova de vida da Didit detecta deepfakes, máscaras e ataques de apresentação, em modo passivo e ativo. 99.9% de precisão, testada pela iBeta, desde $0.10.
A prova de vida da Didit confirma que há uma pessoa real e viva diante da câmera, e não uma foto impressa, uma reprodução em tela, uma máscara ou um deepfake, usando prova de vida passiva, com ação 3D ou com flash. Ela alcança **99.9% de precisão**, com taxa de falsa aceitação (FAR) abaixo de **0.1%**.
Prompt de integração da prova 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
A lição da Academy sobre o fluxo hospedado do usuário chega à selfie de prova de vida aos 8:49 e, aos 9:16, aos métodos passivo, 3D com flash e 3D com ação.[A selfie de prova de vida — Didit Academy](https://www.youtube.com/embed/LzGe-dMWjUw?start=529\&rel=0\&playsinline=1)## Métodos de prova de vidaNossa plataforma implementa três tecnologias antispoofing distintas, cada uma adaptada a diferentes necessidades de segurança e experiências do usuário:
| Método |
Descrição |
Nível de segurança |
Ideal para |
| **`3D Action & Flash`** |
• Combina verificação biométrica multifator com uma **sequência de ações aleatória** e **análise dinâmica de padrões de luz**.\
• No início, o usuário é solicitado a executar uma ação simples - como **piscar** ou **acenar com a cabeça** - garantindo interação em tempo real.\
• Ao mesmo tempo, o sistema projeta uma sequência de padrões de luz sobre o rosto e analisa os **reflexos** para confirmar a estrutura tridimensional do rosto.\
• **Algoritmos de deep learning** examinam microexpressões e as respostas aos reflexos de luz para verificar a presença de uma pessoa viva.\
• Oferece a **máxima segurança** ao integrar sinais comportamentais (ação) e físicos (profundidade por luz), o que torna quase impossível falsificá-la com imagens estáticas, vídeos ou até máscaras avançadas.
|
Máximo |
Bancos, saúde, aplicações governamentais |
| **`3D Flash`** |
• Usa **análise dinâmica de padrões de luz** para validar a topologia facial sem exigir interação do usuário.\
• Projeta uma série de padrões de luz sobre o rosto a mais de **30 quadros por segundo** e analisa os reflexos para criar um **mapa de profundidade**.\
• Esse mapa de profundidade confirma a estrutura tridimensional do rosto e o distingue de imagens planas ou falsificações 2D.\
• Oferece uma **experiência fluida**, mantendo **alta segurança** contra ataques de apresentação como fotos ou telas.\
|
Alto |
Serviços financeiros, acesso a contas, verificação de identidade |
| **`Passive Liveness`** |
• Baseia-se em **análise de deep learning de um único quadro** para detectar sinais de vida.\
• Examina a imagem em busca de **artefatos**, **padrões de textura** e outros indícios sutis que diferenciam um rosto real de uma falsificação.\
• Uma **rede neural convolucional (CNN)** valida as características faciais e identifica anomalias, como as de fotos impressas ou telas digitais.\
• Oferece uma verificação **rápida e conveniente**, mas com **segurança padrão**, adequada a casos de uso de baixo risco.\
|
Padrão |
Cenários de baixo atrito, aplicações para o consumidor |
> [!NOTE]
>
> **Segurança avançada do 3D Flash e do 3D Action & Flash:**
>
> > * Esses métodos foram projetados para derrotar **ataques de falsificação sofisticados**, como **máscaras de alta qualidade**, **deepfakes** e **reproduções de vídeo**.
> > * Ao projetar padrões de luz dinâmicos e analisar seus reflexos, detectam como a luz interage com um **rosto 3D real** em comparação com uma superfície plana ou artificial.
> > * O método **3D Action & Flash** acrescenta uma camada extra de segurança com uma ação aleatória (por exemplo, piscar ou acenar com a cabeça), exigindo **respostas comportamentais em tempo real** que mídias pré-gravadas ou identidades sintéticas não conseguem reproduzir.
> > * Comprovadamente de **alta precisão** e com **baixas taxas de falsa aceitação**, esses métodos são ideais para ambientes de alto risco.Cada método gera uma **pontuação de prova de vida normalizada (0-100%)**, baseada em nosso algoritmo proprietário, que avalia vários fatores de segurança em tempo real.### Limites configuráveisVocê pode personalizar os níveis de segurança definindo limites diferentes para as pontuações de prova de vida. Por exemplo:> [!NOTE]
>
> Esses limites podem ser ajustados conforme a sua **tolerância a risco** e os seus **requisitos de segurança**, o que dá flexibilidade entre os casos de uso.## Novas tentativas e feedback acionávelEm uma sessão da Didit, uma captura de prova de vida que falha por um **motivo corrigível** (pouca luz, rosto fora do centro, obstrução, pontuação no limite) não é recusada de imediato. O usuário é convidado a **tentar novamente com orientações específicas**, até um número configurável de tentativas.* **Limite de tentativas** - `face_liveness_max_attempts` controla o número total de envios de prova de vida por sessão. O padrão é **3** (uma tentativa inicial mais duas novas tentativas), configurável por nó do fluxo (intervalo de 1 a 3).
* **Feedback de nova tentativa** - enquanto ainda houver tentativas, uma falha que permite nova tentativa mantém o usuário na etapa de prova de vida e devolve um corpo com `feedback_codes` acionáveis (os SDKs Web e Mobile os exibem automaticamente como mensagens de orientação):
```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 que permitem nova tentativa** - `LOW_FACE_LUMINANCE` (escuro demais), `HIGH_FACE_LUMINANCE` (claro demais), `NO_FACE_DETECTED`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, `LOW_LIVENESS_SCORE`, `MULTIPLE_FACES_DETECTED`, `AGE_NOT_DETECTED`.
* **Nova tentativa garantida para condições de captura** - `LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION` e `NO_FACE_DETECTED` descrevem o ambiente em que o usuário está, não a pessoa. Quando uma tentativa falha apenas por esses códigos, o usuário sempre tem uma segunda tentativa com a mensagem de orientação acima, mesmo em um fluxo configurado com `face_liveness_max_attempts: 1`. Todos os demais códigos continuam seguindo exatamente o limite configurado.
* **Esgotamento e fraude** - quando o limite se esgota, aplica-se o status calculado (`Declined` ou `In Review`). Ataques de apresentação confirmados (`LIVENESS_FACE_ATTACK`), ocorrências na lista de bloqueio e rostos duplicados **são recusados de imediato** e nunca têm nova tentativa.> [!NOTE]
>
> As novas tentativas se aplicam apenas ao **fluxo de sessão**. O endpoint independente `POST /v3/passive-liveness/` não mantém estado e executa uma única vez - devolve o resultado diretamente, sem limite de tentativas.## Como funciona**1. Captura da selfie em vídeo**O usuário é conduzido por uma **interface simples e intuitiva**, adaptada ao método de prova de vida selecionado.| Verificação | Descrição |
| - | - |
| **Feedback em tempo real** | Garante iluminação, posicionamento e enquadramento adequados |
| **Verificações de qualidade** | Monitora desfoque, reflexo e a visibilidade ideal do rosto |
| **Captura adaptativa** | Ajusta-se a diferentes capacidades de dispositivo e condições de rede |
| **Orientação do método** | Mostra instruções específicas do método (por exemplo, "Pisque agora" para o 3D Action) |**2. Análise de detecção de prova de vida**Algoritmos avançados processam a mídia capturada em **tempo real** para detectar tentativas de falsificação. A análise varia conforme o método:> **3D Action & Flash**
>
> * Verifica a ação do usuário (por exemplo, **piscar** ou **acenar com a cabeça**) para confirmar que foi executada corretamente e ao vivo
> * Analisa os **reflexos dos padrões de luz** para validar a estrutura tridimensional do rosto
> * Usa deep learning para avaliar **microexpressões** e outros sinais comportamentais
> * Combina sinais comportamentais e físicos para a **maior resistência a falsificações**> **3D Flash**
>
> * Processa uma sequência de **reflexos de padrões de luz** a 30+ FPS para construir um **mapa de profundidade** detalhado
> * Confirma as propriedades 3D do rosto e o distingue de falsificações planas ou 2D
> * Sem interação do usuário - totalmente **passivo do ponto de vista do usuário**> **Passive Liveness**
>
> * Aplica **deep learning** a um único quadro para detectar **padrões de textura** e **artefatos**
> * Uma rede neural convolucional (CNN) valida as características faciais e identifica anomalias
> * Método mais rápido - funciona com **uma única foto**A detecção em várias camadas identifica **ataques de apresentação**, incluindo fotos, telas, máscaras e deepfakes.**3. Processamento do resultado e verificação**O sistema compara a pontuação de prova de vida com os seus **limites configurados** e entrega os resultados instantaneamente.| Saída | Descrição |
| - | - |
| **Pontuação de prova de vida** | Pontuação de confiança normalizada de 0 a 100% |
| **Decisão** | Aprovado, Recusado ou Em revisão, conforme os seus limites |
| **Método** | Qual método de prova de vida foi usado (`passive`, `flash`, `action_flash`) |
| **Imagem de referência** | Quadro capturado usado na verificação de prova de vida |
| **Avisos** | Quaisquer anomalias detectadas (por exemplo, baixa qualidade, indícios de falsificação) |Os resultados são entregues por **resposta da API**, **webhook** ou podem ser consultados no **Business Console**, com logs de auditoria detalhados para conformidade.> [!TIP]
>
> Você pode configurar qual método de prova de vida usar em cada fluxo no [Business Console](https://docs.didit.me/console/workflows.md). Fluxos diferentes podem usar métodos diferentes, conforme os seus requisitos de risco.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.