Age Verification

Endpoint

POST https://hml.certiface.com.br/age-verification/api/v1/age-verify

Autenticação

Envie a chave de API no header da requisição:

X-Api-Key: <api-key>

A chave será disponibilizada pela CertiFace.

Request

Headers

Nome	Tipo	Obrigatório	Descrição
`X-Api-Key`	String	Sim	Chave de autenticação da API fornecida pela CertiFace.

Body

{
  "transactionId": "<string>",
  "image": "<imagem da face em base64>"
}

Campo	Tipo	Obrigatório	Descrição
transactionId	String	Não	Identificador da transação definido pelo cliente. Caso não seja informado, uma UUID será gerada automaticamente pela Certiface.
image	String	Sim	Imagem facial codificada em Base64.

Response

Sucesso

{
    "transactionId": "0bd43fa1-5812-4daa-a424-2ee2ae39d085",
    "isUnderAge": false,
    "age": 61.3,
    "ic80": "55-67",
    "ic90": "53-69",
    "timestamp": "2026-06-09T11:27:32.946455189-03:00"
}

Campo	Tipo	Descrição
transactionId	String	Identificador da transação enviado pelo cliente ou gerado pela Certiface.
isUnderAge	Boolean	Indica se a pessoa foi identificada como menor de idade.
age	Float	Idade estimada da pessoa na imagem.
ic80	String	Intervalo de confiança de 80% para a idade estimada.
ic90	String	Intervalo de confiança de 90% para a idade estimada.
timestamp	String	Data e hora em que a estimativa foi realizada.

Tratamento de Erros

Em caso de erro, a API retorna uma resposta no seguinte formato:

{
  "timestamp": "2026-06-02T12:03:46.055618806",
  "status": 400,
  "error": "invalid_image",
  "message": "unable to decode base64 image"
}

Campo	Tipo	Descrição
timestamp	String	Data e hora do erro.
status	Integer	Código HTTP retornado pela API.
error	String	Identificador resumido do erro.
message	String	Descrição detalhada do erro ocorrido.

Exemplo - Imagem inválida

Este erro é retornado quando:

O campo image não contém um Base64 válido.
O conteúdo enviado não pode ser identificado como uma imagem JPEG.
O payload da requisição está vazio.

Erros de Validação

Quando a imagem enviada não atende aos requisitos de processamento, a API retorna HTTP Status 400 com uma ou mais mensagens de erro no campo message.

As mensagens são separadas pelo caractere /.

Exemplo 1 - Múltiplas validações

{
  "timestamp": "2026-06-02T12:06:07.304422778",
  "status": 400,
  "error": "Bad Request",
  "message": "Encontrado 2 faces na imagem / Distância entre olhos de 49.0444. Deve ser maior que 70.0000 / Fake image detectada: cartoon_faces"
}

Exemplo 2 - Foto de foto

{
    "timestamp": "2026-06-09T12:14:01.161216277",
    "status": 400,
    "error": "Bad Request",
    "message": "Fake image detectada: foto_da_foto"
}

As mensagens retornadas no campo message podem variar conforme as validações realizadas na imagem enviada.

Requisitos da Imagem

Para que a estimativa de idade seja realizada com sucesso, a imagem deve atender aos seguintes requisitos:

Conter apenas uma face.
Ser uma fotografia real da pessoa.
Não ser uma foto de outra foto, impressão, tela ou imagem reproduzida.
Possuir qualidade suficiente para a detecção facial.

Alguns critérios de validação podem variar de acordo com as configurações do ambiente.