> ## 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 Passiva: Detecção de Deepfake > A Didit detecta máscaras, impressões, replays e deepfakes em uma única imagem. Passiva, inferência sub-2s, pague por uso, sem mínimo mensal. ## OpenAPI ````yaml pt-br/openapi-25.json POST /v3/passive-liveness/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificação de identidade. Autentique-se com o cabeçalho x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/passive-liveness/: post: tags: - Standalone APIs summary: Prova de vida passiva description: >- Detecte ataques de apresentação, como fotos impressas, reproduções em tela, máscaras e deepfakes, a partir de uma única imagem facial. Não exige vídeo, movimento nem interação do usuário. **Como funciona.** Um modelo biométrico analisa a imagem, avalia o maior rosto detectado e calcula uma pontuação de prova de vida `score` (0–100). O `status` é `Declined` quando qualquer aviso de severidade `error` é disparado: - `NO_FACE_DETECTED`: o modelo de prova de vida não encontrou nenhum rosto, - `LOW_LIVENESS_SCORE`: pontuação igual ou inferior a `face_liveness_score_decline_threshold` (padrão `30`), - `LIVENESS_FACE_ATTACK`: o modelo detectou um ataque de apresentação, - `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST`: o rosto corresponde a uma entrada da sua lista de bloqueio facial. `MULTIPLE_FACES_DETECTED` é um sinal de severidade `warning` (não recusa a sessão). `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` são sinais de severidade `information` de que o mesmo rosto já apareceu em outra sessão aprovada (nunca recusam a sessão). `face_quality` e `face_luminance` (0–100, anuláveis) descrevem a qualidade da captura. **Triagem de lista de bloqueio e de duplicados.** É executada em **todas** as chamadas, com ou sem `save_api_request`, comparando o rosto detectado com o índice de busca facial da sua aplicação. Rostos anteriores com o mesmo `vendor_data` são excluídos de toda a busca no índice. Por isso, executar novamente a prova de vida para o mesmo usuário não dispara `DUPLICATED_FACE`. Da mesma forma, um rosto da lista de bloqueio originado de uma sessão com o próprio `vendor_data` de quem faz a chamada NÃO é sinalizado (a triagem `FACE_IN_BLOCKLIST` é ignorada para rostos com o mesmo `vendor_data`). **Faturamento.** Cada resposta `200` consome um crédito da API de Prova de vida passiva, pago com o crédito do seu plano ou com o saldo recarregado. Saldo insuficiente retorna `403` antes de qualquer processamento da imagem. **Persistência da sessão e cadastro facial (`save_api_request`, padrão `true`).** Quando o valor é `true`, a chamada é persistida como uma sessão do tipo API (no Business Console, em `GET /v3/session/{sessionId}/decision/` por meio do `request_id` retornado e no webhook `status.updated`). A imagem de referência e o recorte do rosto são armazenados, e o rosto detectado é **cadastrado no seu índice de busca facial** para que chamadas posteriores de Busca facial e verificações de duplicidade possam encontrá-lo. Quando o valor é `false`, a chamada é única: nada é armazenado e o rosto não é cadastrado (a triagem de lista de bloqueio e de duplicados continua sendo executada). **Sandbox.** Chaves de API de sandbox ignoram todo o processamento e o faturamento. Após a validação da requisição (entradas malformadas continuam retornando `400`), o endpoint retorna um payload simulado estático `Approved`, nenhuma sessão é persistida e nenhum crédito é consumido. **Autenticação.** Envie a chave de API da sua aplicação no cabeçalho `x-api-key`. Credenciais ausentes ou inválidas retornam `403` (`{"detail": "You do not have permission to perform this action."}`). Esta API nunca retorna `401`. **Limite de requisições.** Há uma cota de escrita compartilhada de 300 requisições/min por chave de API em todos os endpoints POST/PATCH/DELETE. Ultrapassá-la retorna `429`. operationId: post_v3passive-liveness parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image properties: user_image: type: string format: binary description: >- Imagem frontal do rosto (por exemplo, uma selfie). Extensões permitidas: `tiff`, `jpg`, `jpeg`, `png`, `webp`. Tamanho máximo de upload: **5 MB** (arquivos maiores são rejeitados com `400`). As imagens são comprimidas automaticamente para ~0,5 MB antes do processamento, portanto resoluções muito altas não melhoram a precisão. A imagem deve conter uma única pessoa: quando há vários rostos, o maior é avaliado e um aviso `MULTIPLE_FACES_DETECTED` é adicionado. face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Limiar da pontuação de prova de vida (0–100). Uma pontuação calculada **igual ou inferior** a este valor emite um aviso `LOW_LIVENESS_SCORE` e define `status` como `Declined`. O padrão é `30`. Aumente esse valor para uma proteção antispoofing mais rigorosa. Valores fora do intervalo 0–100 retornam `400`. example: 30 rotate_image: type: boolean default: false description: >- Quando `true`, o serviço testa rotações de 90 graus da entrada e usa a orientação que produz a melhor detecção de rosto. Útil quando a orientação EXIF está ausente. Aumenta a latência. example: false save_api_request: type: boolean default: true description: >- Quando `true` (padrão), persiste a chamada como uma sessão do tipo API, armazena as imagens do rosto, emite um webhook `status.updated` e cadastra o rosto detectado no seu índice de busca facial. Quando `false`, a chamada é avulsa: nada é armazenado e o rosto não é cadastrado. A triagem de lista de bloqueio e de duplicados é executada em ambos os casos. example: true vendor_data: type: string description: >- Identificador opaco opcional (seu ID de usuário, e-mail, UUID…) armazenado na sessão persistida e devolvido. Também é usado para excluir sessões anteriores com o mesmo `vendor_data` da verificação de rosto duplicado, de modo que reverificar o mesmo usuário não gere `DUPLICATED_FACE`. example: user-123 metadata: type: object additionalProperties: true description: >- Objeto JSON opcional armazenado com a sessão (quando `save_api_request=true`) e devolvido. Em requisições multipart, envie-o como um campo de string codificada em JSON, que é convertido em um objeto. example: flow: withdrawal example: user_image: (binary JPEG/PNG selfie) face_liveness_score_decline_threshold: 30 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: withdrawal responses: '200': description: >- Prova de vida passiva concluída. `liveness.score` é a confiança do modelo, de 0 a 100, de que a imagem mostra uma pessoa real; `status` é `Approved`, a menos que um aviso de severidade `error` tenha sido disparado. Um rosto falsificado ou presente na lista de bloqueio ainda retorna `200`: verifique `liveness.status` e `liveness.warnings`, não apenas o código HTTP. Quando `save_api_request=true`, `request_id` é o id da sessão persistida. content: application/json: examples: Approved: summary: Rosto real — sem avisos value: request_id: a1b2c3d4-e5f6-7890-1234-567890abcdef liveness: status: Approved method: PASSIVE score: 95 user_image: entities: - bbox: - 661 - 728 - 1688 - 2188 confidence: 0.732973 age: 26.91 gender: male race: null best_angle: 0 warnings: [] face_quality: 84.21 face_luminance: 50.33 vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' Declined - presentation attack: summary: >- O modelo sinalizou um spoofing (impressão, reprodução, máscara…) value: request_id: f1c8c9b2-d3e4-4f5a-9b8c-7d6e5f4a3b2c liveness: status: Declined method: PASSIVE score: 12.5 user_image: entities: - bbox: - 100 - 120 - 420 - 540 confidence: 0.81 age: 30.1 gender: female race: null best_angle: 0 warnings: - risk: LOW_LIVENESS_SCORE feature: LIVENESS additional_data: null log_type: error short_description: Low liveness score long_description: >- The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data. - risk: LIVENESS_FACE_ATTACK feature: LIVENESS additional_data: null log_type: error short_description: Liveness Face Attack long_description: >- The system detected a potential attempt to bypass the liveness check. face_quality: 72.4 face_luminance: 48.2 vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' Declined - face on blocklist: summary: >- Rosto real, mas corresponde a uma entrada da lista de bloqueio value: request_id: 0b54a1de-22aa-4e0f-9c84-5a2b1f3c4d5e liveness: status: Declined method: PASSIVE score: 93.75 user_image: entities: - bbox: - 40 - 40 - 100 - 100 confidence: 0.722082 age: 27 gender: male race: null best_angle: 0 warnings: - risk: FACE_IN_BLOCKLIST feature: LIVENESS additional_data: blocklisted_session_id: 882c42d5-8a4d-4d20-8080-a22f57822c86 blocklisted_session_number: 3242 api_service: null log_type: error short_description: Face in blocklist long_description: >- The system identified a face in the blocklist, which means the face is not allowed to be verified. face_quality: null face_luminance: null vendor_data: user-123 metadata: null created_at: '2026-06-12T01:04:42.763237+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- ID da sessão persistida quando `save_api_request=true` (utilizável com `GET /v3/session/{sessionId}/decision/`); caso contrário, um UUID de correlação transitório. liveness: type: object properties: status: type: string enum: - Approved - Declined description: >- `Declined` quando pelo menos um aviso com severidade `error` foi disparado (nenhum rosto, pontuação baixa, ataque de apresentação ou ocorrência na lista de bloqueio); `Approved` caso contrário. Entradas `warning`/`information` (múltiplos rostos, duplicatas) nunca causam recusa por si só. method: type: string enum: - PASSIVE description: Sempre `PASSIVE` neste endpoint. score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Confiança da prova de vida (0–100, com duas casas decimais) de que a imagem mostra uma pessoa real, e não um spoofing. `null` quando o modelo não retornou nenhuma confiança. example: 95 user_image: type: object description: Resultados da detecção facial para a imagem enviada. properties: entities: type: array items: type: object properties: bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Caixa delimitadora do rosto detectado, como coordenadas em pixels `[x_min, y_min, x_max, y_max]` na imagem processada. example: - 661 - 728 - 1688 - 2188 confidence: type: number format: float minimum: 0 maximum: 1 description: Confiança da detecção facial (0–1). example: 0.732973 age: type: number format: float description: >- Idade do rosto detectado estimada pelo modelo, em anos. Apenas informativa: não afeta a decisão de prova de vida. example: 26.91 gender: type: string description: >- Gênero do rosto detectado previsto pelo modelo (`male` ou `female`). Apenas informativo. example: male race: type: string nullable: true description: >- Campo reservado: sempre `null` nas respostas deste endpoint. example: null description: >- Uma entrada por rosto detectado. O maior rosto é o avaliado. best_angle: type: integer nullable: true description: >- Rotação (em graus) que produziu a melhor detecção de rosto; diferente de zero apenas quando `rotate_image=true` corrigiu a orientação. example: 0 warnings: type: array description: >- Sinais de risco. Gravidade `error` (recusam): `NO_FACE_DETECTED`, `LOW_LIVENESS_SCORE` (pontuação igual ou abaixo do limiar), `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, `POSSIBLE_FACE_IN_BLOCKLIST`. Gravidade `warning` (revisão, sem recusa): `MULTIPLE_FACES_DETECTED`. Gravidade `information` (sem recusa): `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE`, quando o mesmo rosto já apareceu em outra sessão aprovada. items: type: object properties: risk: type: string enum: - NO_FACE_DETECTED - LOW_LIVENESS_SCORE - LIVENESS_FACE_ATTACK - MULTIPLE_FACES_DETECTED - FACE_IN_BLOCKLIST - POSSIBLE_FACE_IN_BLOCKLIST - DUPLICATED_FACE - POSSIBLE_DUPLICATED_FACE description: Código de risco legível por máquina. feature: type: string enum: - LIVENESS description: >- Recurso que emitiu o aviso. Sempre `LIVENESS` neste endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- `null` para a maioria dos avisos. Ocorrências na lista de bloqueio trazem `{blocklisted_session_id, blocklisted_session_number, api_service}`; ocorrências de duplicidade trazem `{duplicated_session_id, duplicated_session_number, api_service}`, que apontam para a sessão correspondente. log_type: type: string enum: - error - warning - information description: >- Severidade. Avisos `error` levam o `status` para `Declined`; entradas `warning` e `information` são apenas informativas e nunca recusam a sessão por conta própria. short_description: type: string description: Resumo legível do risco em uma linha. long_description: type: string description: Explicação legível do risco. face_quality: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Pontuação da qualidade de captura do rosto detectado, normalizada de 0 a 100. `null` quando o modelo não conseguiu gerar um valor confiável. example: 84.21 face_luminance: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Brilho do rosto detectado, normalizado de 0 a 100. `null` quando indisponível. example: 50.33 vendor_data: type: string nullable: true description: Eco do `vendor_data` que você enviou, ou `null`. metadata: type: object nullable: true additionalProperties: true description: Eco do objeto `metadata` que você enviou, ou `null`. created_at: type: string format: date-time description: >- Timestamp ISO 8601 (UTC) do momento em que a resposta foi gerada, por exemplo `2026-06-12T01:04:42.763237+00:00`. '400': description: >- Erro de validação. Retornado quando `user_image` está ausente, excede 5 MB, tem uma extensão não suportada ou falha na decodificação da imagem no servidor, ou quando uma opção está fora do intervalo permitido. Erros de campo usam o envelope `{field: [messages]}` do DRF; falhas de decodificação de imagem usam `{"error": ...}`. content: application/json: examples: Missing image: summary: '`user_image` não incluído nos dados do formulário' value: user_image: - No file was submitted. Invalid image format: summary: >- Extensão permitida, mas conteúdo de imagem que não pode ser decodificado value: error: Invalid user image format. code: invalid_image Unsupported file extension: summary: Extensão de arquivo fora de tiff/jpg/jpeg/png/webp value: user_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp. File too large: summary: O upload excede o limite de 5 MB value: user_image: - File size should not exceed 5 MB '403': description: >- Permissão negada. Retornado quando o cabeçalho `x-api-key` está ausente e também quando o saldo da organização que faz a chamada não cobre a chamada; uma chave incorreta, revogada ou expirada retorna `401`. Uma chave ausente retorna `403` com `{"detail": ...}`; uma chave incorreta, revogada ou expirada retorna `401`. Créditos insuficientes retornam `403` com `{"error": ...}` antes de qualquer processamento da imagem. content: application/json: examples: Missing or invalid API key: summary: Nenhum cabeçalho `x-api-key`, ou a chave é inválida/revogada value: detail: You do not have permission to perform this action. Not enough credits: summary: O saldo da organização não cobre a chamada value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Limite de requisições excedido. Todos os endpoints POST/PATCH/DELETE compartilham uma cota de 300 requisições de escrita por minuto por chave de API. A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Mais de 300 requisições de escrita no minuto atual value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/passive-liveness/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'face_liveness_score_decline_threshold=30' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.passive_liveness.check( user_image=open("user_image.jpg", "rb"), face_liveness_score_decline_threshold=30.0, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "withdrawal"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.passiveLiveness.check({ user_image: await fileFromPath("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "withdrawal" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.PassiveLiveness.Check(ctx, didit.PassiveLivenessCheckParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"withdrawal\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.PassiveLivenessCheckParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.passiveLiveness().check(PassiveLivenessCheckParams.builder() .userImage(Path.of("user_image.jpg")) .faceLivenessScoreDeclineThreshold(30.0) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "withdrawal")) .build()); System.out.println(result); - lang: php label: PHP source: |- passiveLiveness->check([ 'user_image' => File::fromPath('user_image.jpg'), 'face_liveness_score_decline_threshold' => 30.0, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'withdrawal'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.passive_liveness.check( user_image: Pathname("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "withdrawal" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.PassiveLiveness.CheckAsync(new PassiveLivenessCheckParams { UserImage = FileUpload.FromPath("user_image.jpg"), FaceLivenessScoreDeclineThreshold = 30.0, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "withdrawal" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está errada, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.