API Reference - Face shape


This document presents the guideline for the VTO face shape detection.

Face shape detection

The VTO is capable of detecting the user's face shape.

The workflow consists of switching to face shape mode, then requesting the face shape. A screenshot will be taken and face analysis will be run on it.

Once you get a result, you can reset the feature to either take a new screenshot for analysis or go back to live mode.

setMode (‘faceshape’)

Once a VTO instance is created, you must switch to face shape mode


The 'onModeFaceshape' callback will be called.
The VTO is now showing the camera stream to let the user position themselves


It is now possible to take a screenshot and determine the user's face shape by calling 



The result will be sent via the onGetFaceshape callback

var params = {
 apiKey: ...
 onGetFaceshape: function(data) {
if(data.errorCode) {
console.log('faceshape : ' + data.errorCode + ' ' + data.errorDetail);
} else {
console.log('faceshape : ' + data.faceshape);
console.log('points list:' + data.facePoints);

Face shape is now available in data.faceshape.
List of available face shapes : 'oval', 'square', 'round', 'heart', 'long', 'rectangle', 'triangle'

It is possible to display the detected points with the coordinates of said points in data.facePoints.

errorCode details

If a face shape cannot be detected, the errorCode property will be defined with errorDetail:

# Error details
10  Detection error
11  No face detected
12  Detection server connection error
20  Faceshape server connection error
21  Empty faceshape
30  Not in faceshape mode
31  FBxLive version not compatible
102  Face not aligned to the left / right
103  Face not aligned up / down
104  Face not aligned up / down and left / right
105  Face edge not detected
106  Face shape cannot be classifie

Integration samples

Here is a basic sample to call faceshape and get a result :

Here is a more advanced sample with basic UI demonstrating how to use facePoints :https://codepen.io/Fittingbox/pen/0bbfab282db4c71b2cc77aa6dd38ac70?editors=1010