Method is used for recognizing trained users in one or more photos. For each detected face, method will return user ids that match specified face or empty result set if no matches found. Each tag also includes a threshold score, if matching score is below this threshold – matched user id can be treated as unlikely match.

Api call usage is limited. Each passed image (either URL or through POST) is added to your allowed usage.

Note: as a side effect, faces/recognize also does face detection and therefore returns similar results as faces/detect. This means that returned tags can be used to train new users (using tags/save), without the need of additional call to faces/detect).

Method entry point:

Supported HTTP methods
Required parameters
  • standard API parameters
  • uids – a comma separated list of user ids to search for.
  • urls – a comma separated list of images (accepted image formats: PNG, JPEG, BMP, JPEG2000).
Optional parameters
  • namespace – default data namespace to be used for all specified uids without data namespace specified.
  • detector – face detection quality attribute. Normal (default) – fast face and attribute detection, aggressive – more accurate and slower face and attribute detection.
  • attributes – specifies which attributes will be returned with the results. Accepted values: all, none or a comma separated list of supported attributes.
  • limit – specifies maximum number of matches that will be returned with the results. If not specified value of 100 will be used.
  • detect_all_feature_points – specifies that all possible feature points are detected if set to true.
  • matching_threshold – specifies threshold used for faces comparison (minimal confidence value).  This threshold separates identical from different templates. Matching threshold is linked to false acceptance rate (FAR, different templates erroneously accepted as of the same) of matching algorithm. The higher is threshold, the lower is FAR and higher FRR (false rejection rate, same templates erroneously accepted as different) and vice a versa. Any matching threshold from 0 to 100 can be set.

Note: in case where you want to POST images instead of specifying urls, request to the method must be formed as a MIME multi-part message sent using POST data. Each argument should be specified as a separate chunk of form data.

Note: if specified user ids include user ids which were not yet trained or do not have any training set assigned, they are returned in no_training_set array.

Note: in order to minimize query size and in cases you want to use all trained user ids in the database, you can use ‘all@namespace’ keyword as uidsparameter value.


"photos" : [
"url" : "",
"pid" : "F@053a763a06d9d578430b9f2d06c686bb_f0bf798c4c4e8",
"width" : 1024,
"height" : 767,
"tags" : [
"tid" : "c24ac564_f0bf798c4c4e8",
"recognizable" : true,
"uids" : [
"uid" : "mary@docs",
"confidence" : 98
"threshold" : 50,
"label" : "",
"confirmed" : true,
"manual" : false,
"width" :27.73,
"height" : 37.03,
"center" : { "x" : 64.75, "y" : 48.24 },
"eye_left" : { "x" : 66.5, "y" : 39.24 },
"eye_right" : { "x" : 53.12, "y" : 34.55 },
"yaw" : 45,
"roll" : 15,
"pitch" : 0,
"attributes" : {
"face" : { "value" : "true", "confidence" : 71 }
] }
"status" : "success",
"usage" : {
"used" : 1,
"remaining" : 99,
"limit" : 100,
"reset_time_text" : "Fri, 22 September 2012 12:57:19 +0000",
"reset_time" : 1348232239

Recent Posts