> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vu-one.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Face Analysis
> API de Face Analysis da VU: compara dois rostos, avalia a qualidade de uma selfie e estima pose, atributos e prova de vida em uma única chamada HTTP.
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:
```js theme={null}
// 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:
1. **As chaves da matriz são strings**, não números: `biometric["0"]["1"]`. Em linguagens tipadas, desserialize como mapa de `string` para objeto.
2. **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».
3. **`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.
```bash theme={null}
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:
```bash theme={null}
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:
```json theme={null}
{
"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](/pt/vucs/antispoofing-facial/introducao), 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](/pt/vucs/face-analysis/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
Prepare as imagens, alinhe `operations`, monte a chamada e valide antes da produção.
A matriz biométrica, o veredito de qualidade aninhado e o antispoofing dentro da resposta.
Códigos, os `500` em texto puro e quais erros podem ser repetidos.
## Related topics
- [ID Analysis](/pt/vucs/id-analysis/introducao.md)
- [Interpretação de respostas](/pt/vucs/face-analysis/respostas.md)
- [Guia de integração](/pt/vucs/face-analysis/integracao.md)
- [Erros e diagnóstico](/pt/vucs/face-analysis/erros.md)
- [VU Cloud Services](/pt/vucs/introducao.md)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.