Face

This endpoint takes one image and returns the list of the faces found in it. For each face you get where it is in the image (boundingBox), its crop in base64, and the attributes estimated by the detector — apparent age and gender.

It is an endpoint for analyzing a single image in isolation. It does not check the face against anything.

🚧 Face and Face Match do not do the same thing

This is the most common confusion between the two neighboring endpoints:

• Face (this page) — takes one image and describes the faces that exist in it. There is no comparison.
• Face Match — takes two images and answers whether the face in one is the same person as the other.

If what you want is to compare a selfie with the photo on a document, the endpoint is Face Match, not this one.

This endpoint also does not perform liveness (use Liveness) and does not identify the person or query official databases.

Request

POST /face/v1

Headers

Authorization: ApiKey <your-api-key>

This endpoint also accepts the JWT token, in the format Authorization: Bearer <accessToken>. See JWT Token.

Parameters

All are optional, in the query string.

Parameter	Description	Required
shouldRotateFace	When true, the face crop is rotated before being returned. Default: false.	No
shouldReturnConfidence	When true, each item of data also carries the confidence field of the detection. Default: false.	No
faceCropProportion	Proportion used in the face crop. Decimal number, default 1.	No

TIP

shouldRotateFace and shouldReturnConfidence are turned on only by the exact value true. Any other value — including 1 or TRUE — is treated as false.

Accepted files

Item	Value
Formats	image/png, image/jpeg
Files per call	1 file
Maximum size (multipart)	15 MB

The form field name is up to you — use whatever makes sense in your integration. If more than one file is sent, the request is rejected with 422.

🚧 This endpoint does not accept PDF

Unlike Face Match, only PNG and JPEG images go in here. Sending a PDF results in 422.

Besides multipart/form-data, the file can be sent as JSON, in the base64 field, as described in Sending files.

Example request

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

With the optional parameters:

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

Response

Field	Description	Type
id	Unique identifier of the request	String
version	API version that served the call	String
data	List with one entry per face found in the image. Comes back empty when no face is found.	Object[]
data[].confidence	Confidence of the face detection. Only appears when shouldReturnConfidence=true.	Number
data[].age	Apparent age estimated for the face	Number
data[].gender	Object with the apparent gender estimated for the face	Object
data[].gender.value	Apparent gender: Male or Female	String
data[].gender.confidence	Confidence of the gender estimate, from 0 to 100	Number
data[].boundingBox	Position of the face in the original image. The four values are proportions of the image, between 0 and 1.	Object
data[].boundingBox.top	Start of the face on the Y axis	Number
data[].boundingBox.left	Start of the face on the X axis	Number
data[].boundingBox.width	Width of the face	Number
data[].boundingBox.height	Height of the face	Number
data[].croppedBase64	Crop of the face in base64, ready to use in HTML	String
metadata	Object with the metadata of the request	Object
metadata.filesInfo	List with the information of the file sent	Object[]
metadata.filesInfo[].fieldname	Name of the field used to send the file	String
metadata.filesInfo[].name	Name of the file sent	String
metadata.filesInfo[].size	Size of the file, in bytes	Number
metadata.filesInfo[].mimetype	Type of the file sent	String
metadata.filesInfo[].encoding	Encoding of the file as sent	String
metadata.filesInfo[].sha256	SHA-256 hash of the file sent	String
metadata.timeSpent	Processing time of the request, in milliseconds	Number

TIP

data is a list, not an object: a photo with three people returns three entries. No face detected returns 200 with "data": [] — that is not an error.

JSON examples

1. One face found

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. No face found

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. With 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
  }
}

Response headers

Header	When it appears
Nextid-ReqId	On every response. Carries the request identifier, the same one as the id field in the body.

Errors

Code	When it happens
401 Unauthorized	API key or JWT token missing, invalid, or without permission for this endpoint.
404 Not Found	The version given in the URL does not exist. Only v1 is accepted.
406 Not Acceptable	The body was sent as JSON, but without the base64 field.
413 Payload Too Large	The file sent as multipart/form-data is larger than 15 MB.
415 Unsupported Media Type	The Content-Type header is missing or is not supported.
422 Unprocessable Entity	The file format is not accepted, or more than one file was sent in the same call.
500 Internal Server Error	Unexpected failure during processing.

The error response format is described in HTTP response codes.

Versions

This endpoint has a single version, v1. It is the default when the version is omitted from the URL.

Version	Status	What changes
v1	Recommended	The only version. Serves both /face and /face/v1.

Any other value in the URL — /face/v2, for example — returns 404.