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.

Method

POST

URL

http://23.21.173.192/v2/detect

Response

json

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)

(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.

Method

POST

URL

http://23.21.173.192/v2/detect_features

Response

json

Request Parameters

api_key

topLeftX

X-Coordinate for top left corner of face. May be modified from basic Detect output.

topLeftY

Y-Coordinate for top left corner of face. May be modified from basic Detect output.

width

Width of face. May be modified from basic Detect output.

height

Height 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")

url

image 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

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.

Method

GET

URL

http://23.21.173.192/v2/enroll

Response

json

Request Parameters

api_key

subject_id

a unique ID describing this person

gallery_id

a unique ID indicating the collection to which the person should be enrolled

image_id

an image ID that was returned from a detect operation

topLeftX

X-Coordinate for top left corner of face. May be modified from Detect output.

topLeftY

Y-Coordinate for top left corner of face. May be modified from Detect output.

width

Width of face. May be modified from Detect output.

height

Height 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.

Method

GET

URL

http://23.21.173.192/v2/recognize

Response

json

Request Parameters

api_key

gallery_id

a unique ID indicating the collection which this unknown person should be compared against

image_id OR face_id

an image ID that was returned from a detect operation OR a face ID from the response of a previous enrollment

max_num_results

the maximum number of matches returned by this search (default 10)

topLeftX

X-Coordinate for top left corner of face. May be modified from Detect output.

topLeftY

Y-Coordinate for top left corner of face. May be modified from Detect output.

width

Width of face. May be modified from Detect output.

height

Height 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.

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.

Method

GET

URL

http://23.21.173.192/v2/add_to_gallery

Response

json

Request Parameters

api_key

subject_id

The ID used to previously enroll some person ("subject")

gallery_id

A 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.

Method

GET

URL

http://23.21.173.192/v2/remove_from_gallery

Response

json

Request Parameters

api_key

subject_id

The ID used to previously enroll some person ("subject")

gallery_id

A 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.

Method

GET

URL

http://23.21.173.192/v2/delete_face

Response

json

Request Parameters

api_key

face_id

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

Method

GET

URL

http://23.21.173.192/v2/assign_face_to_subject

Response

json

Request Parameters

api_key

face_id

face ID from the response of a previous enrollment

subject_id

unique 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.