Comparação facial

A comparação facial permite comparar duas imagens e identificar se elas representam a mesma pessoa com base em similaridade, confiança e limite mínimo definido na requisição. Essa validação pode ser usada em fluxos de cadastro, onboarding, revisão manual, prevenção de fraude e confirmação de identidade.

Endpoint

POST /v1/validation/face-comparison

Corpo da requisição

{
  "source_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
  "target_image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
  "threshold": 80
}

Campos da requisição

Campo	Tipo	Obrigatório	Descrição
`source_image`	`string`	Sim	Imagem base em formato base64.
`target_image`	`string`	Sim	Imagem que será comparada com a imagem base.
`threshold`	`number`	Não	Similaridade mínima para considerar as faces compatíveis. Aceita valores de `0` a `100`. O padrão é `80`.

Formato das imagens

As imagens devem ser enviadas em base64. Exemplo com prefixo MIME:

data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...

Exemplo sem prefixo MIME:

/9j/4AAQSkZJRgABAQ...

Limite de similaridade

O campo threshold define a similaridade mínima exigida para considerar a comparação como compatível. Exemplo:

{
  "threshold": 80
}

Se a similaridade retornada for maior ou igual ao limite informado, o campo matched será true. Se for menor, o campo matched será false.

Exemplo de resposta compatível

{
  "code": 200,
  "message": "Validação facial concluída com sucesso.",
  "result": {
    "id": "3c7b7f4a-2e3f-43f1-8fd6-2cc5efb8a111",
    "status": "completed",
    "test": false,
    "cost": {
      "total": 0.04,
      "charged": 0.04,
      "refunded": 0.0
    },
    "timing": {
      "total": 2.74
    },
    "comparison": {
      "matched": true,
      "similarity": 97.42,
      "confidence": 99.12,
      "threshold": 80.0,
      "source_face": {
        "confidence": 99.31,
        "bounding_box": {
          "width": 0.2184,
          "height": 0.3125,
          "left": 0.3941,
          "top": 0.1782
        }
      },
      "target_face": {
        "confidence": 99.12,
        "bounding_box": {
          "width": 0.2218,
          "height": 0.3189,
          "left": 0.3887,
          "top": 0.1814
        }
      },
      "unmatched_faces": 0
    }
  }
}

Exemplo de resposta não compatível

{
  "code": 200,
  "message": "Validação facial concluída com sucesso.",
  "result": {
    "id": "c1f6fa2d-1c0c-4f75-a71a-51733c4f4111",
    "status": "completed",
    "test": false,
    "cost": {
      "total": 0.04,
      "charged": 0.04,
      "refunded": 0.0
    },
    "timing": {
      "total": 2.91
    },
    "comparison": {
      "matched": false,
      "similarity": 42.18,
      "confidence": 98.76,
      "threshold": 80.0,
      "source_face": {
        "confidence": 99.04,
        "bounding_box": {
          "width": 0.2142,
          "height": 0.3098,
          "left": 0.4015,
          "top": 0.1741
        }
      },
      "target_face": {
        "confidence": 98.76,
        "bounding_box": {
          "width": 0.2291,
          "height": 0.3262,
          "left": 0.3768,
          "top": 0.1903
        }
      },
      "unmatched_faces": 1
    }
  }
}

Campos da resposta

Campo	Tipo	Descrição
`result.id`	`string`	Identificador da validação.
`result.status`	`string`	Status da validação.
`result.test`	`boolean`	Indica se a validação foi executada em ambiente de teste.
`result.cost.total`	`number`	Valor total da validação.
`result.cost.charged`	`number`	Valor debitado.
`result.cost.refunded`	`number`	Valor estornado, quando aplicável.
`result.timing.total`	`number`	Tempo total da validação em segundos.
`result.comparison.matched`	`boolean`	Indica se as faces foram consideradas compatíveis.
`result.comparison.similarity`	`number`	Percentual de similaridade entre as faces.
`result.comparison.confidence`	`number`	Menor confiança detectada entre as faces comparadas.
`result.comparison.threshold`	`number`	Similaridade mínima usada na validação.
`result.comparison.source_face`	`object`	Dados da face detectada na imagem base.
`result.comparison.target_face`	`object`	Dados da face detectada na imagem comparada.
`result.comparison.unmatched_faces`	`number`	Quantidade de faces detectadas que não foram compatíveis.

Chamada de teste

A comparação facial pode ser executada em ambiente de teste sem consumir saldo. Consulte a página de ambiente de teste:

Ambiente de teste

Veja como habilitar chamadas de teste usando o header correto.

Erros comuns

Imagem inválida

{
  "code": 43002,
  "message": "Imagem inválida."
}

Face não detectada

{
  "code": 43007,
  "message": "Não foi possível detectar uma face válida nas imagens enviadas."
}

Similaridade mínima inválida

{
  "code": 400,
  "message": "Similaridade mínima deve ser um valor entre 0 e 100."
}

Falha no provedor

{
  "code": 502,
  "message": "Não foi possível consultar o provedor da validação."
}

Observações

A comparação facial indica similaridade entre duas imagens. Ela não substitui validações documentais, análise humana ou regras internas de aprovação quando o fluxo exigir maior rigor. Para melhores resultados, utilize imagens nítidas, com rosto visível, boa iluminação e sem cortes relevantes.

​Endpoint

​Corpo da requisição

​Campos da requisição

​Formato das imagens

​Limite de similaridade

​Exemplo de resposta compatível

​Exemplo de resposta não compatível

​Campos da resposta

​Chamada de teste