Documentação

Comparação via API

Endpoint REST POST /v1/compare — compare duas imagens sem o SDK React.

Use este endpoint quando o fluxo de câmera e liveness do SDK React não for necessário — por exemplo, comparar uma selfie já capturada com a foto de um documento. A autenticação é via Authorization: Bearer tf_live_… (veja Autenticação).

Requisição

POST /v1/compare

curl -X POST https://api.techfaceid.com/v1/compare \
  -H "Authorization: Bearer tf_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceImage": {
      "url": "https://cdn.exemplo.com/documento.jpg"
    },
    "compareImage": {
      "base64": "/9j/4AAQSkZJRg..."
    }
  }'

Campos

Campo	Descrição
`referenceImage`	Imagem de referência (documento, cadastro anterior). Informe `url` ou `base64` — não ambos.
`compareImage`	Imagem a ser comparada com a referência. Também aceita `url` ou `base64`.

URLs devem ser públicas (http:// ou https://), acessíveis em até 10 segundos. Base64 pode incluir ou omitir o prefixo data:image/jpeg;base64,. Tamanho máximo: 10 MB por imagem.

Resposta

200 OK

{
  "verificationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "matched": true,
  "similarity": 97.2,
  "timestamp": "2026-07-17T14:00:00.000Z"
}

matched é true quando similarity atinge o limiar configurado no servidor (padrão 90). A verificação é registrada no dashboard com tipo compare.

Erros

Respostas de erro seguem { "error": { "code", "message", "details"? } }. Exemplos comuns:

Código	Quando ocorre
`IMAGEM_REFERENCIA_INACESSIVEL`	URL da referência inacessível, timeout ou HTTP de erro.
`IMAGEM_COMPARACAO_INACESSIVEL`	URL da imagem de comparação inacessível.
`ROSTO_NAO_DETECTADO`	Nenhum rosto na imagem. `details.field` indica qual campo falhou.
`MULTIPLOS_ROSTOS_DETECTADOS`	Mais de um rosto — `details.faceCount` traz a quantidade.
`IMAGEM_FORMATO_INVALIDA`	Arquivo não é JPEG/PNG válido ou foi rejeitado pelo provedor.

Veja a lista completa em Erros da API e como gerar chaves em Autenticação.