Interpretação de respostas

Os campos de primeiro nível

Campo	O que é
`id`	O identificador da transação. Registre-o sempre: é a primeira coisa que o suporte pede.
`info`	A sua referência, devolvida tal como enviada.
`code` / `message`	O resultado global: `200` / `Operation end successfully`.
`biometric`	A matriz de similaridade 0–100. O campo sobre o qual se decide.
`confidences`	Uma cópia de `biometric` mantida por compatibilidade. Não o leia.
`faceLocation`	O retângulo do rosto detectado em cada imagem, em pixels. Informativo.
`faceFeatures`	Os 16 atributos 0–100, se pedidos.
`headPoseEstimation`	A pose em graus, se pedida.
`inferenceConfidence`	O veredito agregado de qualidade. Aparece sempre, com duas formas diferentes — veja abaixo.
`antiSpoofingFace`	A resposta do serviço de antispoofing, aninhada, se pedida.
`faceVector`	O vetor de 512 valores por rosto, se você enviou `returnFaceVector`.
`faceImage`	O recorte alinhado do rosto em base64, se você enviou `returnFaceImage`.
`benchmark`	Tempo interno de processamento. Não é uma pontuação: não decida sobre ele.

As chaves de resultado são strings

Cada bloco de resultado vem indexado pelo número da imagem como texto JSON: "0", "1"… A matriz biométrica é body.biometric["0"]["1"], não [0][1]. Em linguagens tipadas, desserialize como Map<String, …>.

{
  "biometric": {
    "0": { "0": 100, "1": 93 },
    "1": { "1": 100, "0": 93 }
  }
}

A diagonal ("0" vs "0") sempre vale 100: é cada rosto contra si mesmo. Se você também enviou faceVectors, os vetores continuam a numeração depois das imagens: 1 imagem + 1 vetor ⇒ chaves "0" (a imagem) e "1" (o vetor). Referências medidas com vu_v4 sobre as fotos de teste da equipe: mesma pessoa ≈ 93–95 · pessoas diferentes ≈ 19. Com as mesmas duas fotos, cosine dá 78 e euclidean_l2 dá 66: nunca compare pontuações de metodologias diferentes.

`inferenceConfidence` muda de forma

Aparece para cada imagem, sempre, mas com duas formas:

Forma	Quando
`{"message": "...", "code": 200 \| 202 \| 406, "confidence": "high" \| "medium" \| "low"}`	Você pediu `faceFeatures` e `headPoseEstimation` juntas, ou a imagem tem menos de 360 px.
`{"message": "headPoseEstimation and faceFeatures need to be enabled..."}` — sem `code` nem `confidence`	Qualquer outro caso.

Tipifique code e confidence como opcionais. O mapeamento é fixo: 200 = high, 202 = medium, 406 = low.

Não confunda níveis. O code: 406 aninhado dentro de inferenceConfidence não muda o código HTTP nem o code de primeiro nível, que continuam em 200. Uma imagem de baixa qualidade não é um erro da API: é um sinal para pedir outra captura ao usuário.

O que degrada o veredito: máscara, olhos fechados, desfoque, pose não frontal, maquiagem extrema e — automaticamente — qualquer imagem abaixo de 360 px de lado.

Os 16 atributos de `faceFeatures`

Cada atributo é uma pontuação 0–100 em que mais alto = mais presente: blurry, eyeglasses, sunglasses, faceMask, leftEyeClosed, rightEyeClosed, mouthOpen, beard, mustache, smiling, heavyMakeup, hat, earrings, necklace, necktie, lipstick. Use-os para guiar o usuário («tire os óculos de sol»), não como condições de identidade. headPoseEstimation traz a pose em graus: leftRight (guinada) e upDown (arfagem). Zero é frontal perfeito; um rosto útil para biometria costuma estar dentro de ±15°.

O antispoofing vem aninhado e com escala própria

antiSpoofingFace["0"] contém a resposta completa do serviço de Antispoofing Facial, aninhada tal como é:

{
  "antiSpoofingFace": {
    "0": {
      "code": 200,
      "spoofing": false,
      "confidence": 99.2
    }
  }
}

Decida pelo campo spoofing (booleano). Não decida pelo code nem pelo confidence internos: eles carregam a semântica do serviço de antispoofing, não a do Face Analysis.

Se o serviço de antispoofing não responder, antiSpoofingFace["0"] chega como null e o resto da resposta continua sendo 200. Trate null como «sem veredito» — nunca como aprovação.

Particularidades do desserializador

Os blocos de resultado são indexados por string ("0", "1"), não por inteiro.
inferenceConfidence tem duas formas: code e confidence são opcionais.
antiSpoofingFace[i] pode ser um objeto ou null.
confidences duplica biometric: ignore-o, mas não falhe quando aparecer.
Com faceVectors, a numeração dos resultados inclui os vetores depois das imagens.
Os 500 chegam com corpo em texto puro, não JSON — veja Erros.

Próximo: Erros

Códigos de erro, os 500 em texto puro, o aborto de lote com imageNumber e o que pode ser repetido.

Comece aqui

ID Analysis

Face Analysis

Antispoofing Facial

Connection Fingerprint

Interpretação de respostas

Os campos de primeiro nível

As chaves de resultado são strings

`inferenceConfidence` muda de forma

Os 16 atributos de `faceFeatures`

O antispoofing vem aninhado e com escala própria

Particularidades do desserializador

Próximo: Erros

​Os campos de primeiro nível

​As chaves de resultado são strings

​inferenceConfidence muda de forma

​Os 16 atributos de faceFeatures

​O antispoofing vem aninhado e com escala própria

​Particularidades do desserializador

Próximo: Erros

Os campos de primeiro nível

As chaves de resultado são strings

`inferenceConfidence` muda de forma

Os 16 atributos de `faceFeatures`

O antispoofing vem aninhado e com escala própria

Particularidades do desserializador