Face Analysis

O serviço de Face Analysis é uma caixa de ferramentas de análise facial atrás de um único endpoint. Você envia uma ou mais imagens e declara, imagem por imagem, quais operações rodar: comparação biométrica 1:1, avaliação de qualidade da captura, estimativa de pose, atributos faciais, prova de vida passiva, idade e gênero. O caso de uso central é a verificação de identidade: comparar a selfie de uma pessoa com a foto do seu documento — ou com um vetor biométrico guardado — e obter uma pontuação de similaridade de 0 a 100. As demais operações acompanham esse fluxo: a qualidade da captura decide se vale a pena pedir outra foto, e o antispoofing decide se a selfie veio de uma pessoa presente.

A regra de decisão

Esta é a parte mais importante da integração. Escreva-a na forma positiva:

// Confirmar exige as duas condições e o limiar. Qualquer outra coisa NÃO confirma.
if (status === 200 && body.biometric?.["0"]?.["1"] >= 70) {
  mesmaPessoa();      // 70: limiar para a metodologia padrão (vu_v4)
} else {
  naoConfirmada();
}

Nunca confirme por exclusão. Não existe um código que signifique «não é a mesma pessoa»: o no-match chega com 200 e uma pontuação baixa. Se a sua condição aprova por exclusão, qualquer resposta inesperada — um 500 em texto puro, um bloco ausente — vira uma aprovação.

Três detalhes do contrato que quebram integrações:

As chaves da matriz são strings, não números: biometric["0"]["1"]. Em linguagens tipadas, desserialize como mapa de string para objeto.
O limiar 70 vale só para vu_v4, a metodologia padrão. As mesmas duas fotos da mesma pessoa pontuam 95 com vu_v4, 78 com cosine e 66 com euclidean_l2 — um 66 que, lido com o limiar de vu_v4, significaria «pessoa diferente».
confidences é uma cópia de biometric mantida por compatibilidade com integrações antigas. Não o leia; decida sobre biometric.

Endpoints

Método	Caminho	Para que serve
`GET`	`/version`	Verificar conectividade. Avalie o código de status, não o corpo. Não exige api-key.
`POST`	`/inference`	Rodar as operações pedidas sobre as imagens enviadas.

A URL base depende do ambiente e é fornecida pela VU junto com a sua api-key. Nos exemplos ela aparece como BASE_URL.

Autenticação

Toda chamada leva o cabeçalho Api-Key com a chave do seu ambiente.

curl -X GET "$BASE_URL/version" \
  -H "Api-Key: $VU_FACE_ANALYSIS_API_KEY"

A api-key vive no seu backend. Nunca a embuta em um app móvel nem no front-end: qualquer pessoa consegue extraí-la do binário ou do bundle.

Um exemplo completo

Comparação de dois rostos — a selfie contra a foto do documento:

curl -X POST "$BASE_URL/inference" \
  -H "Api-Key: $VU_FACE_ANALYSIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "info": "onboarding-12345",
    "images": ["/9j/4AAQSkZJRgABAQ...", "/9j/4AAQSkZJRgABAQ..."],
    "operations": [["biometric"], ["biometric"]]
  }'

Uma confirmação se parece com isto, reduzida aos campos que importam:

{
  "id": "e0e9c259-ab66-4455-a330-c9a0d3b40567",
  "info": "onboarding-12345",
  "code": 200,
  "message": "Operation end successfully",
  "biometric": { "0": { "0": 100, "1": 93 }, "1": { "1": 100, "0": 93 } },
  "benchmark": 200
}

biometric["0"]["1"] = 93 ≥ 70 ⇒ mesma pessoa. A diagonal ("0" contra "0") sempre vale 100; ignore-a. id é o identificador da transação: registre-o sempre — é a primeira coisa que o suporte vai pedir.

As operações disponíveis

Operação	O que devolve
`biometric`	A matriz de similaridade 0–100 entre todos os rostos da chamada. Roda por padrão se você omitir `operations`.
`faceFeatures`	16 atributos 0–100: nitidez, óculos, máscara, olhos fechados, iluminação…
`headPoseEstimation`	A pose em graus: guinada (`leftRight`) e arfagem (`upDown`).
`antiSpoofing`	A resposta completa do serviço de Antispoofing Facial, aninhada.
`gazeTrackingEstimation`	Coordenadas de ambas as írises em pixels.
`facialAgeGender`	Idade estimada e probabilidade de gênero. Sinais de consistência, não dados de registro.
`steganography`	Verificação da assinatura esteganográfica de imagens geradas por componentes VU.

Quando você pede faceFeatures e headPoseEstimation juntas, o serviço adiciona o veredito agregado de qualidade em inferenceConfidence: high, medium ou low. Os detalhes estão em Respostas.

Ambientes

O ambiente de homologação pode estar à frente da produção. Ele também valida versões pré-produtivas, então pode diferir em tempo de resposta e nas pontuações. Use-o para certificar a sua integração — o contrato, os códigos, o tratamento de erros —, não como referência de performance nem para comparar pontuações imagem a imagem entre ambientes.

Continuar

Integração

Prepare as imagens, alinhe operations, monte a chamada e valide antes da produção.

Respostas

A matriz biométrica, o veredito de qualidade aninhado e o antispoofing dentro da resposta.

Erros

Códigos, os 500 em texto puro e quais erros podem ser repetidos.

Comece aqui

ID Analysis

Antispoofing Facial

Connection Fingerprint

Face Analysis

A regra de decisão

Endpoints

Autenticação

Um exemplo completo

As operações disponíveis

Ambientes

Continuar

Integração

Respostas

Erros

​A regra de decisão

​Endpoints

​Autenticação

​Um exemplo completo

​As operações disponíveis

​Ambientes

​Continuar

Integração

Respostas

Erros

A regra de decisão

Endpoints

Autenticação

Um exemplo completo

As operações disponíveis

Ambientes

Continuar