FaceRTMAPI


 
Function Reference

Detect

Finds either face information (a bounding box around faces), face + eye information including eye centers and possibly eye corners (eye corners should not be relied on to be present in every response), or full feature information including eyebrows, eye corners, nose, chin, lips, and ears for each face. If selecting eyes, full or setpose, the gender and confidence level will be returned for all faces found in the image. Intended for faster detection and pre-processing of images. The output face or eye coordinates of this function may be modified and sent to Detect Features. Coordinates all begin at the top left of the image. The image_id returned by this function is a reference to a temporarily cached image that can be passed to Detect Features, Enroll, or Find operations.

All binary images supplied to this function are stored for later use by Enroll and Find operations. Images are deleted after 5 hours.

MethodPOST
URLhttp://23.21.173.192/v2/detect
Responsejson
Request Parameters
api_key
selector[ FACE | EYES | FULL | SETPOSE ] - return information on all faces in the image (default "FACE"), all faces + eyes ("EYES"), all faces + eyes + features ("FULL"), or all faces + eyes + features + setpose ("SETPOSE") for all faces (see sample response below), attributes such as gender will also be returned for all requests except for the FACE selector
minHeadScale(optional) ratio of smallest considered head size to the shortest image dimension. Value must be a float > 0.015 (1:64) and <= 0.5 (1:2), default 0.125 (1:8)
urlimage url containing possible face or faces for detection
image(optional, required if url omitted) jpg or png multipart image stream containing at least one face
symmetricFill(optional if selector == SETPOSE) fills occluded facets, (true | false, default false)
setPitch(optional if selector == SETPOSE) set the pitch (up/down) output for the SetPose rendering, (range -90 to 90, default 0)
setYaw(optional if selector == SETPOSE) set the yaw (left/right) output for the SetPose rendering, (range -90 to 90, default 0)
setRoll(optional if selector == SETPOSE) set the roll (tilt) output for the SetPose rendering, (range -90 to 90, default 0)

Detect Features

Finds either eye information, full feature information, or full features + "Setpose" for one face in a picture. Face bounding box or eye center coordinates must be supplied, and may be taken from the output of basic Detect. "Setpose" is a returned image which contains a frontal view of a face which has been zero-corrected for pitch, yaw, and roll (like a mug shot). Intended for more detailed detection than basic Detect. Since this function takes the face bounding box or eye coordinates, corrections may be made on the values output from Detect. The image_id returned by this function is a reference to a temporarily cached image that can be passed back to other Detect Features calls, or Enroll or Find calls.

Setpose images are returned as URLs which are made private through obfuscation. Setpose image urls expire after 20 minutes.

All binary images supplied to this function are stored for later use by Enroll and Find operations. Images are deleted after 5 hours.

MethodPOST
URLhttp://23.21.173.192/v2/detect_features
Responsejson
Request Parameters
api_key
topLeftXX-Coordinate for top left corner of face. May be modified from basic Detect output.
topLeftYY-Coordinate for top left corner of face. May be modified from basic Detect output.
widthWidth of face. May be modified from basic Detect output.
heightHeight of face. May be modified from basic Detect output.
leftEyeCenterX(required if face coordinates/dimensions omitted) X-Coordinate for the left eye center. May be modified from basic Detect output.
leftEyeCenterY(required if face coordinates/dimensions omitted) Y-Coordinate for the left eye center. May be modified from basic Detect output.
rightEyeCenterX(required if face coordinates/dimensions omitted) X-Coordinate for the right eye center. May be modified from basic Detect output.
rightEyeCenterY(required if face coordinates/dimensions omitted) Y-Coordinate for the right eye center. May be modified from basic Detect output.
selector[ EYES | FULL | SETPOSE ] - return information on one face + eyes in the image (default "EYES"), full features ("FULL") for one face, or full features + set pose ("SETPOSE")
urlimage url containing possible face or faces for detection
image(optional, required if url and image_id omitted) jpg or png multipart image stream containing one face of this person
image_id(optional, required if url and image omitted) an image ID that was returned from a basic detect operation
symmetricFill(optional if selector == SETPOSE) fills occluded facets, (true | false, default false)
setPitch(optional if selector == SETPOSE) set the pitch (up/down) output for the SetPose rendering, (range -90 to 90, default 0)
setYaw(optional if selector == SETPOSE) set the yaw (left/right) output for the SetPose rendering, (range -90 to 90, default 0)
setRoll(optional if selector == SETPOSE) set the roll (tilt) output for the SetPose rendering, (range -90 to 90, default 0)

Detect - Sample Code

Detect - Sample Response

Enroll

Computes a biometric signature for a known face ("subject") in a picture and adds it to a collection ("gallery") for later searching. The subject id and gallery id must be supplied in addition to an image id reference from a previous Detect or Detect Features call. A subject id must be a globally unique identifier for each known individual identity for each API key. Subjects may exist in more than one gallery and can be added to or removed from a gallery with the Add To Gallery and Remove From Gallery functions. Adding multiple pictures of the same subject will help improve matching accuracy. Similarly, adding pictures of different people with the same subject id will negatively affect the accuracy of the matching algorithm.

Enroll operations also require a face hint describing which face in a picture is to be enrolled. This may be in the form of face bounds (topLeftX, topLeftY, width, height) or eye coordinates (leftEyeCenterX, leftEyeCenterY, rightEyeCenterX, rightEyeCenterY). These landmarks may all be taken from the output of Detect or Detect Features calls.

MethodGET
URLhttp://23.21.173.192/v2/enroll
Responsejson
Request Parameters
api_key
subject_ida unique ID describing this person
gallery_ida unique ID indicating the collection to which the person should be enrolled
image_idan image ID that was returned from a detect operation
topLeftXX-Coordinate for top left corner of face. May be modified from Detect output.
topLeftYY-Coordinate for top left corner of face. May be modified from Detect output.
widthWidth of face. May be modified from Detect output.
heightHeight of face. May be modified from Detect output.
leftEyeCenterX(required if face coordinates/dimensions omitted) X-Coordinate for the left eye center. May be modified from Detect output.
leftEyeCenterY(required if face coordinates/dimensions omitted) Y-Coordinate for the left eye center. May be modified from Detect output.
rightEyeCenterX(required if face coordinates/dimensions omitted) X-Coordinate for the right eye center. May be modified from Detect output.
rightEyeCenterY(required if face coordinates/dimensions omitted) Y-Coordinate for the right eye center. May be modified from Detect output.

Enroll - Sample Code

Enroll - Sample Response

Recognize

Matches an unknown face against a collection ("gallery") of known faces. Galleries are built using the Enroll function. Response includes a similarity score between 0 and 1 for all closely matching subjects in the gallery.

A gallery id must be supplied in addition to an image id reference from a previous Detect or Detect Features call. Recognize operations require a face hint describing which face in a picture is to be enrolled. This may be in the form of face bounds (topLeftX, topLeftY, width, height) or eye coordinates (leftEyeCenterX, leftEyeCenterY, rightEyeCenterX, rightEyeCenterY). These landmarks may all be taken from the output of Detect or Detect Features calls.

MethodGET
URLhttp://23.21.173.192/v2/recognize
Responsejson
Request Parameters
api_key
gallery_ida unique ID indicating the collection which this unknown person should be compared against
image_id OR face_idan image ID that was returned from a detect operation OR a face ID from the response of a previous enrollment
max_num_resultsthe maximum number of matches returned by this search (default 10)
topLeftXX-Coordinate for top left corner of face. May be modified from Detect output.
topLeftYY-Coordinate for top left corner of face. May be modified from Detect output.
widthWidth of face. May be modified from Detect output.
heightHeight of face. May be modified from Detect output.
leftEyeCenterX(required if face coordinates/dimensions omitted) X-Coordinate for the left eye center. May be modified from Detect output.
leftEyeCenterY(required if face coordinates/dimensions omitted) Y-Coordinate for the left eye center. May be modified from Detect output.
rightEyeCenterX(required if face coordinates/dimensions omitted) X-Coordinate for the right eye center. May be modified from Detect output.
rightEyeCenterY(required if face coordinates/dimensions omitted) Y-Coordinate for the right eye center. May be modified from Detect output.

Recognize - Sample Code

Recognize - Sample Response

Verify

Verify if an unknown face (or collection of faces of an unknown individual) has the same identity as a claimed target. A similarity score is returned, and is optimized for discriminating the target subject from other individuals. Note that there must be at least two faces of the target subject enrolled.

MethodGET
URLhttp://23.21.173.192/v2/verify
Responsejson
Request Parameters
api_key
subject_id_of_targeta unique subject ID of the known person
subject_id_of_unknowna unique subject ID of the person who's identity is to be verified

Verify - Sample Code

Verify - Sample Response

List Galleries

Lists the galleries that have been created by your personal API key.

MethodGET
URLhttp://23.21.173.192/v2/list_galleries
Responsejson
Request Parameters
api_key

List Galleries - Sample Response

View Gallery

View the subject ids that have been enrolled in a specific gallery.

MethodGET
URLhttp://23.21.173.192/v2/view_gallery
Responsejson
Request Parameters
api_key
gallery_idA unique ID indicating the gallery to query.

View Gallery - Sample Response

View Subject

View the face ids that have been enrolled in a specific subject.

MethodGET
URLhttp://23.21.173.192/v2/view_subject
Responsejson
Request Parameters
api_key
subject_idunique subject ID that matches one or more previous enrollments

View Subject - Sample Response

Add To Gallery

Adds an already enrolled Subject into an existing or uncreated Gallery. Galleries that don't exist will automatically be created.

MethodGET
URLhttp://23.21.173.192/v2/add_to_gallery
Responsejson
Request Parameters
api_key
subject_idThe ID used to previously enroll some person ("subject")
gallery_idA unique ID indicating the collection to which the subject should be added. If this gallery doesn't exist, it will be created.

Add To Gallery - Sample Response

Remove From Gallery

Removes an already enrolled Subject from an existing Gallery. If this is the only subject in that Gallery, the Gallery will be deleted. If the Subject exists in no other Galleries, he will be deleted from the Face Recognition System.

MethodGET
URLhttp://23.21.173.192/v2/remove_from_gallery
Responsejson
Request Parameters
api_key
subject_idThe ID used to previously enroll some person ("subject")
gallery_idA unique ID indicating the collection from which the subject should be removed. If the subject exists in no other galleries, his biometric template will be removed from the Facial Recognition System and subsequent Add To Gallery operations for this subject will fail.

Remove From Gallery - Sample Response

Delete Face

Delete a Face from a known Subject. This operation will only delete the individual Face that is associated with an enrollment transaction for a Subject. The Face ID that is required should be taken from the response of a previous enrollment. Deleteing a Face from a Subject who belongs to more than one gallery will affect that Subject's identity in each gallery.

This operation might be used if several pictures of an individual are enrolled and then later it is found out that one of these pictures was in fact someone else who's identity is unknown.

MethodGET
URLhttp://23.21.173.192/v2/delete_face
Responsejson
Request Parameters
api_key
face_idface ID from the response of a previous enrollment

Delete Face - Sample Response

Assign Face to Subject

Assign Face ID to a Subject ID. This operation will change the Subject ID associated with an individual Face ID. The Face ID that is required should be taken from the response of a previous enrollment. Assigning a Face ID to a new Subject ID who belongs to more than one gallery will affect that Subject's identity in each gallery.

This operation might be used if several pictures of an individual are enrolled and then later it is found out that one of these pictures was in fact someone else.

MethodGET
URLhttp://23.21.173.192/v2/assign_face_to_subject
Responsejson
Request Parameters
api_key
face_idface ID from the response of a previous enrollment
subject_idunique subject ID to replace that of a previous enrollment

Assign Face to Subject - Sample Response

Usage

Retrieve your current daily and monthly count of function calls made to the api. Total, billable, detect, enroll and recognize counts are displayed.

MethodGET
URLhttp://23.21.173.192/v2/usage
Responsejson
Request Parameters
api_key

Usage - Sample Response