Image Analysis API

Main URL

http://api.facereader-online.com/analyze

Example Request

http://api.facereader-online.com/analyze?CustomerKey=Test&ImageUrl=http://api.facereader-online.com/Images/example.jpg&GetSimpleLandmarks=true&GetFacialStates=true&GetCharacteristics=true

All variables can be supplied as postdata aswell.

Example Page

VicarVision FaceReader Demo

Get Access

Send an email to: info@humaninsightservices.com

Input

Authentication Variable

CustomerKey
Description
Authentication key provided by Human Insight Services (VicarVision / Noldus)

Required Variables When Using Image From URL

ImageUrl
Description
Url to publicly available image (jpg, png, gif, bmp)

Required Variables When Using Uploaded Image

Image
Description
Attached image file in Post Data

Optional Variables

ResponseType
Description
Selects which response type to use (xml or json)
Default Values
json
Possible Values
xml, json
TimeOut
Description
Duration before each request surely timeouts
Default Values
30000 (30000 milliseconds)
GetCharacteristics
Description
Adds the Characteristics Gender, Age, Glasses, Beard, Moustache and Ethnicity to the output
Possible Values
true
GetFullLandmarks
Description
Adds the full set of projected 2D Landmarks to the output
Possible Values
true
GetSimpleLandmarks
Description
Adds a small subset of the projected 2D Landmarks to the output
Possible Values
true
GetFacialStates
Description
Add the facial states, Eyes (Open, Closed), EyeBows (Lowered, Neutral, Raised), Mouth (Open, Closed) to the output
Possible Values
true

Output

Successful Output

When an image is successfully analyzed, the response contains of an array of FaceResults. Where each FaceResult contains the following results:

ValidModel
Description
Boolean denoting if the algorithm was able to create a model for the detected face. When false, only face detection results are available
Possible Values
true, false
ModelQuality
Description
Float denoting the quality of the created face model. 1 meaning very good, 0 meaning very bad.
Expressions
Description
Float array of expressions intensities in the following order: (Neutral, Happy, Sad, Angry, Surprised, Scared, Disgusted)
Possible Values
true, false
DominantExpression
Description
String with the label of the most dominant facial expression
Possible Values
Neutral, Happy, Sad, Angry, Surprised, Scared, Disgusted
Valence
Description
Float denoting the valence of the expressions. 1 meaning a positive expression and -1 meaning a negative expression.
Possible Values
(-1, 1)
Arousal
Description
Float denoting the arousal of the person. 1 meaning active and 0 meaning inactive.
Possible Values
(0, 1)
HeadPose
Description
Array of floats denoting the HeadPose of the modeled face in radians.
DetectionQuality
Description
Float denoting quality of the face detection. 1 meaning very good, 0 meaning very bad.
Possible Values
(0, 1)
FaceBox
Description
Rectangle denoting the position of the detected face.
FaceCorners
Description
Array of 4 simple points, denoting the corners of the rotated facebox (contains the in plane rotation of the face).
LeftEyeBrowLandmarks
Description
Array of simple points, denoting the landmarks of the left eye brow. Only supplied when variable GetSimpleLandmarks was set to true.
RightEyeBrowLandmarks
Description
Array of simple points, denoting the landmarks of the right eye brow. Only supplied when variable GetSimpleLandmarks was set to true.
LeftEyeLandmarks
Description
Array of simple points, denoting the landmarks of the left eye. Only supplied when variable GetSimpleLandmarks was set to true.
RightEyeLandmarks
Description
Array of simple points, denoting the landmarks of the right eye. Only supplied when variable GetSimpleLandmarks was set to true.
MouthLandmarks
Description
Array of simple points, denoting the landmarks of the mouth. Only supplied when variable GetSimpleLandmarks was set to true.
NoseLandmarks
Description
Array of simple points, denoting the landmarks of the nose. Only supplied when variable GetSimpleLandmarks was set to true.
Gender
Description
Gender of the person.
Possible Values
Male, Female
Age
Description
Age range of the person. range of 10 years, rounded to the nearest 5 year.
Ethnicity
Description
Ethnicity of the person
Possible Values
Caucasian, African, Eastern Asian, South Asian, Other, Unknown
Beard
Description
Presence of a beard
Possible Values
None, Some, Heavy
Moustache
Description
Presence of a moustache
Possible Values
None, Some, Heavy
Glasses
Description
Presence of glasses
Possible Values
Yes, No
FacialStates
Description
Array of FacialStates, containing a name and a state.
Possible Values
LeftEyeBrowState - (Lowered, Neutral, Raised)
RightEyeBrowState - (Lowered, Neutral, Raised)
LeftEyeState - (Open, Closed)
RightEyeState - (Open, Closed)
Mouth - (Open, Closed)

Failed Output

When an error occurs for some reason the api returns the ResponseError object, containing:
IsError
Description
Boolean for easy checking if the returned object was an error, always true
ErrorCode
Description
Integer denoting the ErrorCode
Possible Values
0 = UNKNOWN_ERROR
1 = WRONG_API_KEY
2 = INSUFFICIENT_CREDITS
3 = FAILED_TO_OPEN_UPLOADED_IMAGE
4 = FAILED_TO_OPEN_IMAGE
5 = NO_IMAGE_SUPPLIED
6 = FAILED_TO_ANALYZE_IMAGE
7 = TIMEOUT_OCCURED
ErrorMessage
Description
Description of the Error

Example Output JSON

Example Output XML