Liveness

O liveness (prova de vida) responde a uma única pergunta: a imagem enviada é de uma pessoa viva, presente no momento da captura? Ele existe para barrar tentativas de fraude por apresentação — foto de foto, print de tela, vídeo reproduzido em um monitor, máscara.

A imagem normalmente vem de um dos nossos SDKs de captura, que rodam no aplicativo ou no navegador do usuário final e conversam com a API usando um token JWT de curta duração.

🚧 O liveness não compara com documento

Este endpoint não compara a face enviada com a foto de um documento e não identifica a pessoa. Ele só diz se há uma pessoa viva na captura. Para comparar a face capturada aqui com outra imagem, use o Face Match for Liveness, encadeando o id desta resposta.

Request

POST /liveness/v2

Parâmetros

Parâmetro	Descrição	Obrigatório
version	Versão da API no caminho da URL. Use v2. Veja Versões.	Sim

Headers

Authorization: ApiKey <sua-chave-de-api>

Este endpoint também aceita o token JWT, no formato Authorization: Bearer <accessToken> — é assim que os SDKs se autenticam. Veja Token JWT.

Arquivos aceitos

Item	Valor
Formatos	image/png, image/jpeg
Quantidade por chamada	1 arquivo
Tamanho máximo (multipart)	15 MB

O nome do campo do formulário é livre — use o que fizer sentido na sua integração. Se mais de um arquivo for enviado, a requisição é recusada com 422.

Além do multipart/form-data, o arquivo pode ser enviado em JSON, no campo base64, como descrito em Envio de arquivos.

Exemplo Request

curl -i -X POST 'https://api-homolog.nxcd.app/liveness/v2' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI' \
  --form 'selfie=@./selfie.jpg'

Response

O envelope é o padrão da API:

Campo	Descrição	Tipo
id	Identificador único da requisição. É ele que se usa no Face Match for Liveness.	String
version	Versão da API que atendeu a chamada	String
data	Objeto com o resultado da análise	Object
data.isAlive	true quando a imagem é de uma pessoa viva presente na captura	Boolean
metadata	Objeto com os metadados da requisição	Object
metadata.filesInfo	Lista com as informações do arquivo enviado	Object[]
metadata.filesInfo[].fieldname	Nome do campo usado no envio	String
metadata.filesInfo[].name	Nome do arquivo enviado	String
metadata.filesInfo[].size	Tamanho do arquivo, em bytes	Number
metadata.filesInfo[].mimetype	Tipo do arquivo enviado	String
metadata.filesInfo[].encoding	Codificação do arquivo no envio	String
metadata.filesInfo[].sha256	Hash SHA-256 do arquivo enviado	String
metadata.timeSpent	Tempo de processamento da requisição, em milissegundos	Number

🚧 Atenção!

isAlive: false não significa necessariamente uma tentativa de fraude. Uma captura ruim — pouca luz, foco errado, rosto parcialmente fora do quadro — também leva a false. A decisão sobre o que fazer nesse caso é sua.

Exemplos JSON

1. Liveness aprovado

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v2",
  "data": {
    "isAlive": true
  },
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "selfie",
        "name": "selfie.jpg",
        "size": 184320,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
      }
    ],
    "timeSpent": 850
  }
}

2. Liveness recusado

Status Code: 200

{
  "id": "6a1d1e8c-4a7d-4a5e-9f2c-1b0f2a9c7e11",
  "version": "v2",
  "data": {
    "isAlive": false
  },
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "selfie",
        "name": "selfie.jpg",
        "size": 152064,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
      }
    ],
    "timeSpent": 790
  }
}

Headers de resposta

Header	Quando aparece
Nextid-ReqId	Em todas as respostas. Traz o identificador da requisição, o mesmo do campo id do corpo.

Erros

Código	Quando ocorre
401 Unauthorized	Chave de API ou token JWT ausente, inválido, ou sem permissão para o liveness.
404 Not Found	A versão informada na URL não existe.
406 Not Acceptable	O corpo foi enviado como JSON, mas sem o campo base64.
413 Payload Too Large	O arquivo enviado em multipart/form-data passa de 15 MB.
415 Unsupported Media Type	O header Content-Type está ausente ou não é suportado.
422 Unprocessable Entity	O formato do arquivo não é aceito, ou foi enviado mais de um arquivo na mesma chamada.
500 Internal Server Error	Falha inesperada durante o processamento.

O formato das respostas de erro está descrito em Códigos HTTP das respostas.

Versões

Versão	Situação	O que muda
v2	Recomendada	Envelope padrão da API, com data.isAlive.

A v2 é a versão suportada deste endpoint. Informe sempre a versão no caminho da chamada.

Próximo passo

Guarde o id da resposta: é ele que identifica a sessão de liveness no Face Match for Liveness.