> ## 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 Didit deteta deepfakes, máscaras e ataques de apresentação com prova de vida passiva e ativa. 99.9% de precisão, testado pela iBeta, desde $0.10.
A Prova de vida da Didit confirma que uma pessoa real e viva está em frente à câmara, e não uma fotografia impressa, uma reprodução em ecrã, uma máscara ou um deepfake, utilizando prova de vida passiva, ação 3D ou flash. Atinge **99.9% de precisão** com uma taxa de falsa aceitação (FAR) inferior a **0.1%**.
Prompt de integração de prova de vida
Copiar o prompt para a área de transferência
\
\````# 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````
\
Colar em
A lição da Academy sobre o fluxo de utilizador alojado chega à selfie de prova de vida às 8:49, seguida, às 9:16, pelos métodos passivo, 3D Flash e 3D Action.[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 vidaA nossa plataforma implementa três tecnologias de anti-spoofing distintas, cada uma adaptada a diferentes necessidades de segurança e experiências de utilizador:
| Método |
Descrição |
Nível de segurança |
Mais indicado 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 utilizador é convidado a realizar uma ação simples — como **piscar os olhos** ou **acenar com a cabeça** —, garantindo uma interação em tempo real.\
• Simultaneamente, o sistema projeta uma sequência de padrões de luz no rosto, analisando os **reflexos** para confirmar a estrutura tridimensional do rosto.\
• **Algoritmos de aprendizagem profunda** examinam microexpressões e as respostas à reflexão da luz para verificar a presença de uma pessoa viva.\
• Oferece a **segurança mais elevada** ao integrar sinais comportamentais (ação) e físicos (profundidade baseada em luz), tornando quase impossível o spoofing com imagens estáticas, vídeos ou até máscaras avançadas.
|
Mais elevado |
Banca, saúde, aplicações governamentais |
| **`3D Flash`** |
• Utiliza **análise dinâmica de padrões de luz** para validar a topologia facial sem exigir a interação do utilizador.\
• Projeta uma série de padrões de luz no rosto a mais de **30 fotogramas por segundo**, analisando os reflexos para criar um **mapa de profundidade**.\
• Este mapa de profundidade confirma a estrutura tridimensional do rosto, distinguindo-o de imagens planas ou ataques de spoofing em 2D.\
• Proporciona uma **experiência fluida** enquanto mantém uma **segurança elevada** contra ataques de apresentação como fotos ou ecrãs.\
|
Elevado |
Serviços financeiros, acesso a contas, verificação de identidade |
| **`Passive Liveness`** |
• Baseia-se na **análise de deep learning de fotograma único** para detetar sinais de prova de vida.\
• Examina a imagem em busca de **artefactos**, **padrões de textura** e outros indicadores subtis que diferenciam um rosto real de um spoof.\
• Uma **rede neuronal convolucional (CNN)** valida traços faciais e identifica anomalias, como as resultantes de fotografias impressas ou ecrãs digitais.\
• Oferece uma verificação **rápida e conveniente**, mas proporciona uma **segurança padrão**, adequada para casos de uso de baixo risco.\
|
Padrão |
Cenários de baixo atrito, aplicações de consumo |
> [!NOTE]
>
> **Segurança avançada de 3D Flash e Ação 3D e Flash:**
>
> > * Estes métodos foram concebidos para combater **ataques de spoofing sofisticados**, como **máscaras de alta qualidade**, **deepfakes** e **reproduções de vídeo**.
> > * Ao projetar padrões dinâmicos de luz e analisar os seus reflexos, detetam a forma como a luz interage com um **rosto 3D real** em comparação com uma superfície plana ou artificial.
> > * O método **Ação 3D e Flash** adiciona uma camada adicional de segurança com uma ação aleatória (por exemplo, piscar os olhos ou acenar com a cabeça), exigindo **respostas comportamentais em tempo real** que meios pré-gravados ou identidades sintéticas não conseguem replicar.
> > * Comprovados para proporcionar uma **alta precisão** e **baixas taxas de falsa aceitação**, estes métodos são ideais para ambientes de alto risco.Cada método gera uma **pontuação de prova de vida normalizada (0-100%)** com base no nosso algoritmo proprietário, que avalia múltiplos fatores de segurança em tempo real.### Limiares configuráveisPode personalizar os níveis de segurança definindo diferentes limiares para as pontuações de prova de vida. Por exemplo:> [!NOTE]
>
> Estes limiares podem ser ajustados com base na sua **tolerância ao risco** e nos seus **requisitos de segurança**, oferecendo flexibilidade em diversos casos de uso.## Novas tentativas e feedback acionávelNuma sessão Didit, uma captura de prova de vida que falhe por um **motivo corrigível** (iluminação fraca, rosto não centrado, oclusão, uma pontuação no limiar) não é imediatamente recusada. É pedido ao utilizador que **tente 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. Predefinição **3** (uma tentativa inicial mais duas novas tentativas), configurável por nó de fluxo (intervalo de 1 a 3).
* **Feedback de nova tentativa** — enquanto restarem tentativas, uma falha passível de repetição mantém o utilizador no passo de prova de vida e devolve um corpo que contém `feedback_codes` acionáveis (os SDKs Web e Mobile apresentam-nos 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 passíveis de repetição** — `LOW_FACE_LUMINANCE` (demasiado escuro), `HIGH_FACE_LUMINANCE` (demasiado claro), `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 a divisão onde o utilizador se encontra, não a pessoa. Quando uma tentativa falha apenas por esses códigos, o utilizador recebe sempre uma segunda tentativa com a mensagem de orientação acima, mesmo num fluxo configurado com `face_liveness_max_attempts: 1`. Todos os outros códigos continuam a seguir rigorosamente o limite configurado.
* **Esgotamento e fraude** — assim que o limite for esgotado, o estado calculado é aplicado (`Declined` ou `In Review`). Ataques de apresentação confirmados (`LIVENESS_FACE_ATTACK`), ocorrências em listas de bloqueio e rostos duplicados são **recusados imediatamente** e nunca recebem nova tentativa.> [!NOTE]
>
> As novas tentativas aplicam-se apenas ao **fluxo da sessão**. O endpoint autónomo `POST /v3/passive-liveness/` é sem estado e funciona com uma única tentativa — devolve o resultado diretamente, sem limite de novas tentativas.## Como funciona**1. Captura de vídeo selfie**O utilizador é guiado através de uma **interface simples e intuitiva**, adaptada ao método de prova de vida selecionado.| Verificação | Descrição |
| - | - |
| **Feedback em tempo real** | Assegura uma iluminação, posicionamento e enquadramento adequados |
| **Verificações de qualidade** | Monitoriza a existência de desfoque, reflexos e a visibilidade facial ideal |
| **Captura adaptativa** | Ajusta-se às várias capacidades dos dispositivos e às condições de rede |
| **Orientação do método** | Mostra instruções específicas do método (por exemplo, "Pisque agora" para 3D Action) |**2. Análise da deteção de prova de vida**Algoritmos avançados processam os ficheiros multimédia capturados em **tempo real** para detetar tentativas de spoofing. A análise varia consoante o método:> [accordion] 3D Action & Flash
>
> * Verifica a ação do utilizador (por exemplo, **piscar os olhos** ou **acenar com a cabeça**) para confirmar que é realizada corretamente e em direto
> * Analisa os **reflexos de padrões de luz** para validar a estrutura tridimensional do rosto
> * Utiliza aprendizagem profunda para avaliar **microexpressões** e outros sinais comportamentais
> * Combina sinais comportamentais e físicos para obter a **maior resistência a spoofing**> [accordion] 3D Flash
>
> * Processa uma sequência de **reflexos de padrões de luz** a 30+ FPS para criar um **mapa de profundidade** detalhado
> * Confirma as propriedades 3D do rosto, distinguindo-o de tentativas de spoofing planas ou em 2D
> * Não requer interação do utilizador — totalmente **passivo do ponto de vista do utilizador**> [accordion] Prova de vida passiva
>
> * Aplica **aprendizagem profunda** a um único fotograma para detetar **padrões de textura** e **artefactos**
> * Uma rede neuronal convolucional (CNN) valida características faciais e identifica anomalias
> * O método mais rápido — funciona com a **captura de uma única fotografia**A deteção multicamada identifica **ataques de apresentação**, incluindo fotografias, ecrãs, máscaras e deepfakes.**3. Processamento e verificação de resultados**O sistema compara a pontuação de prova de vida com os seus **limiares configurados** e disponibiliza os resultados instantaneamente.| Resultado | Descrição |
| - | - |
| **Pontuação de prova de vida** | Pontuação de confiança normalizada de 0 a 100% |
| **Decisão** | Aprovada, Recusada ou Em análise com base nos seus limiares |
| **Método** | Qual o método de prova de vida utilizado (`passive`, `flash`, `action_flash`) |
| **Imagem de referência** | Fotograma capturado utilizado para a verificação de prova de vida |
| **Avisos** | Quaisquer anomalias detetadas (por exemplo, baixa qualidade, potenciais indicadores de spoofing) |Os resultados são entregues via **resposta da API**, **webhook**, ou podem ser visualizados na **Consola Empresarial** com registos de auditoria detalhados para efeitos de conformidade.> [!TIP]
>
> Pode configurar qual o método de prova de vida a utilizar por fluxo na [Consola Empresarial](https://docs.didit.me/pt/console/workflows.md). Fluxos diferentes podem utilizar métodos distintos consoante os seus requisitos de risco.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.