Detection

Face detection may be performed in two ways:

By the selected parameters when you add them manually to the request. In this case, the configuration is not saved and can not be automatically repeated.
By a processing scenario that already includes certain parameters. You can use the predefined scenarios or add a custom one.

For face detection, the following scenarios are available:

CropCentralFace returns the cropped portrait of the person whose face is the most central in the photo by the set type and size.
CropAllFaces returns the cropped portraits of all the people in the image by the set type and size.
Thumbnail returns the cropped portrait of the person whose face is the most central in the photo in the original size.

Request

The SDK uses the following parameters to detect faces, check face image quality, and evaluate attributes.

└── image
└── thumbnails
└── processParam
    └── scenario
    └── onlyCentralFace
    └── outputImageParams    
    |   └── backgroundColor
    |   └── crop
    |       └── type
    |       └── size
    |       └── padColor
    |       └── returnOriginalRect
    └── quality
    |   └── backgroundMatchColor
    |   └── config
    |       └── name
    |       └── range
    └── attributes
    |   └── config
    |       └── name

Parameter	Description
image	The Base64 image.
thumbnails	Deprecated, use crop instead.
processParam	The processing parameters.
scenario	The name of the scenario. If applied and the scenario is found, the settings are set automatically for the face image quality assessment and any other parameters mentioned in the request are ignored. If not set, left empty, or the name is not found, the processing is performed according to the set parameters.
onlyCentralFace	Whether to process only the central face on the image or all the faces. If set to true, the SDK detects and processes only one—the most central face in the image. If set to false, the SDK processess all faces in the image.
outputImageParams	If set, the uploaded image is processed according to the indicated settings.
background	If set, the background color is replaced. Defines the RGB value for the background color: the silhouette of a person is cut out and the background is filled with this color.
crop	If set, the Base64 of an aligned and cropped portrait is returned in the `crop` field. Alignment is performed according to `type`. If a head on the original image is tilted, for the returned portrait it is aligned in a straight vertical line. If there are more than one face in the photo, all the faces will be detected and processed, and separate portraits for each face will be returned. So, if there were five people in the photo, you'll get five processed portraits. Each portrait can be downloaded. `crop` includes `type`, `padColor`, and `size`.
type	The aspect ratio according to which alignment is performed. See the FaceImageQualityAlignType enum. To get a thumbnail with dimensions 3x4, set `0`.
size	The resize value in case `type` matches this value. If it doesn't match, no resize is performed.
padColor	When an image is aligned by `type`, its original size may be insufficient, and in this case it needs to be supplemented, "padded". `padColor` sets the RGB value for the color that will be used for such a supplement.
returnOriginalRect	If set, the coordinates of the rectangle with the face in the original image prepared for the face crop are returned in the `originalRect` field. Can be used only if the face on the original image is not tilted.
quality	If set, the portrait quality assessment is performed, find the detailed info on the Face Image Quality Assessment page.
attributes	If set, the selected attributes are checked, find the detailed info on the Attributes Detection page.

Response

The response returns the list of parameters with a processing status for the corresponding ones. The list of returned parameters is defined by the set configuration.

└── code
└── msg
└── results
    └── detections
    |   └── attributes
    |   |   └── details
    |   |   |   └── name
    |   |   |   └── value
    |   |   |   └── confidence
    |   └── crop
    |   └── landmarks
    |   └── originalRect
    |   └── quality
    |   |   └── details
    |   |   |   └── groupId
    |   |   |   └── name
    |   |   |   └── range
    |   |   |   └── status
    |   |   |   └── value
    |   |   └── detailsGroups
    |   |   |   └── compliantCount
    |   |   |   └── groupId
    |   |   |   └── name
    |   |   |   └── totalCount
    |   |   └── nonCompliant
    |   |   └── score
    |   |   └── timer
    |   └── roi
    └── detectorType
    └── landmarksType
    └── scenario
    └── timer

Parameter	Description
code	The code the SDK returns.
msg	The message result. If everything is OK, the result looks as follows: `code: 0,` `msg: FACER_OK,` See the list of error codes.
results	The returned results.
detections	The array of performed checks.
attributes	The array of the checked attributes, see details in the Attributes response section.
crop	Thumbnail: Base64 of the aligned and cropped portrait.
landmarks	Returns absolute coordinates (x,y) of five points of each detected face: left eye, right eye, nose, left point of lips, right point of lips.
originalRect	Returned if `returnOriginalRect` is set. Coordinates of the rectangle with the face on the original image prepared for the face crop: x, y, width, height. `x` - the coordinate of the top left corner of the rectangle; `y` - the coordinate of the top left corner of the rectangle; `width` - the width of the rectangle, pixels; `height` - the height of the rectangle, pixels.
quality	The array for the face image quality assessment, see the portrait quality assessment response.
roi	Сoordinates of the rectangular area that contains the face relative to the overall image: x, y, height, width.
detectorType	The type of detector, for internal use and can not be changed.
landmarksType	The type of landmarks identification, for internal use and can not be changed.
scenario	The used processing scenario if was set.
timer	The total time.

Errors

Error	Description
FR_FACE_NOT_DETECTED = 2	No faces are detected, most probably, the image does not contain faces.
FACER_NO_LICENSE = 200	There is no license.
FACER_IS_NOT_INITIALIZED = 201	The library is not initialized.
FACER_COMMAND_IS_NOT_SUPPORTED = 202	The command is not supported.
FACER_COMMAND_PARAMS_READ_ERROR = 203	The request is formed incorrectly.