Face

Este endpoint recebe uma imagem e devolve a lista das faces encontradas nela. Para cada face, você recebe onde ela está na imagem (boundingBox), o recorte dela em base64 e os atributos estimados pelo detector — idade aparente e gênero.

É um endpoint de análise de uma imagem isolada. Ele não confronta a face com nada.

🚧 Face e Face Match não fazem a mesma coisa

Esta é a confusão mais comum entre os dois endpoints vizinhos:

• Face (esta página) — recebe uma imagem e descreve as faces que existem nela. Não há comparação.
• Face Match — recebe duas imagens e responde se a face de uma é a mesma pessoa da outra.

Se o que você quer é comparar uma selfie com a foto de um documento, o endpoint é o Face Match, não este.

Este endpoint também não faz liveness (use o Liveness) e não identifica a pessoa nem consulta bases oficiais.

Request

POST /face/v1

Headers

Authorization: ApiKey <sua-chave-de-api>

Este endpoint também aceita o token JWT, no formato Authorization: Bearer <accessToken>. Veja Token JWT.

Parâmetros

Todos são opcionais, na query string.

Parâmetro	Descrição	Obrigatório
shouldRotateFace	Quando true, o recorte da face é rotacionado antes de ser devolvido. Padrão: false.	Não
shouldReturnConfidence	Quando true, cada item de data passa a trazer também o campo confidence da detecção. Padrão: false.	Não
faceCropProportion	Proporção usada no recorte da face. Número decimal, padrão 1.	Não

TIP

shouldRotateFace e shouldReturnConfidence são ligados apenas pelo valor exato true. Qualquer outro valor — inclusive 1 ou TRUE — é tratado como false.

Arquivos aceitos

Item	Valor
Formatos	image/png, image/jpeg
Quantidade por chamada	1 arquivo
Tamanho máximo (multipart)	15 MB

O nome do campo do formulário é livre — use o que fizer sentido na sua integração. Se mais de um arquivo for enviado, a requisição é recusada com 422.

🚧 Este endpoint não aceita PDF

Diferente do Face Match, aqui só entram imagens PNG e JPEG. Enviar um PDF resulta em 422.

Além do multipart/form-data, o arquivo pode ser enviado em JSON, no campo base64, como descrito em Envio de arquivos.

Exemplo Request

curl -i -X POST 'https://api-homolog.nxcd.app/face/v1' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI' \
  --form 'foto=@./foto.jpg'

Com os parâmetros opcionais:

curl -i -X POST 'https://api-homolog.nxcd.app/face/v1?shouldReturnConfidence=true&faceCropProportion=1.5' \
  --header 'Authorization: ApiKey SUA_CHAVE_AQUI' \
  --form 'foto=@./foto.jpg'

Response

Campo	Descrição	Tipo
id	Identificador único da requisição	String
version	Versão da API que atendeu a chamada	String
data	Lista com uma entrada por face encontrada na imagem. Vem vazia quando nenhuma face é encontrada.	Object[]
data[].confidence	Confiança da detecção da face. Só aparece quando shouldReturnConfidence=true.	Number
data[].age	Idade aparente estimada para a face	Number
data[].gender	Objeto com o gênero aparente estimado para a face	Object
data[].gender.value	Gênero aparente: Male ou Female	String
data[].gender.confidence	Confiança da estimativa de gênero, de 0 a 100	Number
data[].boundingBox	Posição da face na imagem original. Os quatro valores são proporções da imagem, entre 0 e 1.	Object
data[].boundingBox.top	Início da face no eixo Y	Number
data[].boundingBox.left	Início da face no eixo X	Number
data[].boundingBox.width	Largura da face	Number
data[].boundingBox.height	Altura da face	Number
data[].croppedBase64	Recorte da face em base64, pronto para uso em HTML	String
metadata	Objeto com os metadados da requisição	Object
metadata.filesInfo	Lista com as informações do arquivo enviado	Object[]
metadata.filesInfo[].fieldname	Nome do campo usado no envio	String
metadata.filesInfo[].name	Nome do arquivo enviado	String
metadata.filesInfo[].size	Tamanho do arquivo, em bytes	Number
metadata.filesInfo[].mimetype	Tipo do arquivo enviado	String
metadata.filesInfo[].encoding	Codificação do arquivo no envio	String
metadata.filesInfo[].sha256	Hash SHA-256 do arquivo enviado	String
metadata.timeSpent	Tempo de processamento da requisição, em milissegundos	Number

TIP

data é uma lista, não um objeto: uma foto com três pessoas devolve três entradas. Nenhuma face detectada devolve 200 com "data": [] — não é um erro.

Exemplos JSON

1. Uma face encontrada

Status Code: 200

{
  "id": "13cfec7c-b238-4820-a4d1-5173e4c1418e",
  "version": "v1",
  "data": [
    {
      "age": 34,
      "gender": {
        "value": "Male",
        "confidence": 99.72
      },
      "boundingBox": {
        "top": 0.11424895375967026,
        "left": 0.26937249302864075,
        "width": 0.42325547337532043,
        "height": 0.6968063116073608
      },
      "croppedBase64": "iVBORw0KGgoAAAANSUhEUgAAAlgAAAJYCAMAAA...K5CYII="
    }
  ],
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "foto",
        "name": "foto.jpg",
        "size": 196965,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
      }
    ],
    "timeSpent": 1230
  }
}

2. Nenhuma face encontrada

Status Code: 200

{
  "id": "6a1d1e8c-4a7d-4a5e-9f2c-1b0f2a9c7e11",
  "version": "v1",
  "data": [],
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "foto",
        "name": "paisagem.jpg",
        "size": 152064,
        "mimetype": "image/jpeg",
        "encoding": "7bit",
        "sha256": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
      }
    ],
    "timeSpent": 640
  }
}

3. Com shouldReturnConfidence=true

Status Code: 200

{
  "id": "a7f0c3d2-9e51-4b8a-8f31-2d4c6b9e0a77",
  "version": "v1",
  "data": [
    {
      "confidence": 0.97,
      "age": 29,
      "gender": {
        "value": "Female",
        "confidence": 98.4
      },
      "boundingBox": {
        "top": 0.2237228155136108,
        "left": 0.2856607735157013,
        "width": 0.1555942893028259,
        "height": 0.1687679588794708
      },
      "croppedBase64": "iVBORw0KGgoAAAANSUhEUgAAAlgAAAJYCAMAAA...SuQmCC"
    }
  ],
  "metadata": {
    "filesInfo": [
      {
        "fieldname": "foto",
        "name": "foto.png",
        "size": 210433,
        "mimetype": "image/png",
        "encoding": "7bit",
        "sha256": "fcde2b2edba56bf408601fb721fe9b5c338d10ee429ea04fae5511b68fbf8fb9"
      }
    ],
    "timeSpent": 1410
  }
}

Headers de resposta

Header	Quando aparece
Nextid-ReqId	Em todas as respostas. Traz o identificador da requisição, o mesmo do campo id do corpo.

Erros

Código	Quando ocorre
401 Unauthorized	Chave de API ou token JWT ausente, inválido, ou sem permissão para este endpoint.
404 Not Found	A versão informada na URL não existe. Só a v1 é aceita.
406 Not Acceptable	O corpo foi enviado como JSON, mas sem o campo base64.
413 Payload Too Large	O arquivo enviado em multipart/form-data passa de 15 MB.
415 Unsupported Media Type	O header Content-Type está ausente ou não é suportado.
422 Unprocessable Entity	O formato do arquivo não é aceito, ou foi enviado mais de um arquivo na mesma chamada.
500 Internal Server Error	Falha inesperada durante o processamento.

O formato das respostas de erro está descrito em Códigos HTTP das respostas.

Versões

Este endpoint tem uma única versão, a v1. Ela é o padrão quando a versão é omitida na URL.

Versão	Situação	O que muda
v1	Recomendada	Única versão. Atende tanto /face quanto /face/v1.

Qualquer outro valor na URL — /face/v2, por exemplo — devolve 404.