Microsoft Cognitive Face API

Ref : https://www.microsoft.com/cognitive-services/en-us/face-api

Face Detection

ry this now by uploading a local image, or providing an image URL. We don’t keep your images for this demo unless you give us permission.

result : 

Response 200

A successful call returns an array of face entries ranked by face rectangle size in descending order. An empty response indicates no faces detected. A face entry may contain the following values depending on input parameters:

Fields	Type	Description
faceId	String	Unique faceId of the detected face, created by detection API and it will expire in 24 hours after detection call. To return this, it requires "returnFaceId" parameter to be true.
faceRectangle	Object	A rectangle area for the face location on image.
faceLandmarks	Object	An array of 27-point face landmarks pointing to the important positions of face components. To return this, it requires "returnFaceLandmarks" parameter to be true.
faceAttributes	Object	Face Attributes: age: an age number in years. gender: male or female. smile: smile intensity, a number between [0,1] facialHair: consists of lengths of three facial hair areas: moustache, beard and sideburns. headPose: 3-D roll/yew/pitch angles for face direction. Pitch value is a reserved field and will always return 0. glasses: glasses type. Possible values are 'noGlasses', 'readingGlasses', 'sunglasses', 'swimmingGoggles'.

[
    {
        "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
        "faceRectangle": {
            "width": 78,
            "height": 78,
            "left": 394,
            "top": 54
        },
        "faceLandmarks": {
            "pupilLeft": {
                "x": 412.7,
                "y": 78.4 
            },
            "pupilRight": {
                "x": 446.8,
                "y": 74.2 
            },
            "noseTip": {
                "x": 437.7,
                "y": 92.4 
            },
            "mouthLeft": {
                "x": 417.8,
                "y": 114.4 
            },
            "mouthRight": {
                "x": 451.3,
                "y": 109.3 
            },
            "eyebrowLeftOuter": {
                "x": 397.9,
                "y": 78.5 
            },
            "eyebrowLeftInner": {
                "x": 425.4,
                "y": 70.5 
            },
            "eyeLeftOuter": {
                "x": 406.7,
                "y": 80.6 
            },
            "eyeLeftTop": {
                "x": 412.2,
                "y": 76.2 
            },
            "eyeLeftBottom": {
                "x": 413.0,
                "y": 80.1 
            },
            "eyeLeftInner": {
                "x": 418.9,
                "y": 78.0 
            },
            "eyebrowRightInner": {
                "x": 4.8,
                "y": 69.7 
            },
            "eyebrowRightOuter": {
                "x": 5.5,
                "y": 68.5 
            },
            "eyeRightInner": {
                "x": 441.5,
                "y": 75.0 
            },
            "eyeRightTop": {
                "x": 446.4,
                "y": 71.7 
            },
            "eyeRightBottom": {
                "x": 447.0,
                "y": 75.3 
            },
            "eyeRightOuter": {
                "x": 451.7,
                "y": 73.4 
            },
            "noseRootLeft": {
                "x": 428.0,
                "y": 77.1 
            },
            "noseRootRight": {
                "x": 435.8,
                "y": 75.6 
            },
            "noseLeftAlarTop": {
                "x": 428.3,
                "y": 89.7 
            },
            "noseRightAlarTop": {
                "x": 442.2,
                "y": 87.0 
            },
            "noseLeftAlarOutTip": {
                "x": 424.3,
                "y": 96.4 
            },
            "noseRightAlarOutTip": {
                "x": 446.6,
                "y": 92.5 
            },
            "upperLipTop": {
                "x": 437.6,
                "y": 105.9 
            },
            "upperLipBottom": {
                "x": 437.6,
                "y": 108.2 
            },
            "underLipTop": {
                "x": 436.8,
                "y": 111.4 
            },
            "underLipBottom": {
                "x": 437.3,
                "y": 114.5 
            }
        },
        "faceAttributes": {
            "age": 71.0,
            "gender": "male",
            "smile": 0.88,
            "facialHair": {
                "mustache": 0.8,
                "beard": 0.1,
                "sideburns": 0.02
                }
            },
            "glasses": "sunglasses",
            "headPose": {
                "roll": 2.1,
                "yaw": 3,
                "pitch": 0
            }
        }
    }
]

Response 400

Error code and message returned in JSON:

Error Code	Error Message Description
BadArgument	JSON parsing error. Bad or unrecognizable request JSON body.
BadArgument	Invalid returnFaceAttributes. Supported values are: age, gender, headPose, smile, facialHair, glasses in a comma-separated format.
InvalidURL	Invalid image format or URL. Supported formats include JPEG, PNG, GIF(the first frame) and BMP.
InvalidURL	Failed to download image from the specified URL. Remote server error returned.
InvalidImage	Decoding error, image format unsupported.
InvalidImageSize	Image size is too small or too big. The valid image file size should be larger than or equal to 1KB but no larger than 4MB.

• application/json

{
    "error":{
        "code":"BadArgument",
        "message":"Request body is invalid." 
    }
}

Response 401

Error code and message returned in JSON:

Error Code	Error Message Description
Unspecified	Invalid subscription Key or user/plan is blocked.

• application/json

{
    "error":{
        "code": "Unspecified",
        "message": "Access denied due to invalid subscription key. Make sure you are subscribed to an API you are trying to call and provide the right key." 
    }
}

Response 403

• application/json

{
    "error":{
        "statusCode": 403,
        "message": "Out of call volume quota. Quota will be replenished in 2.12 days." 
    }
}

Response 408

Operation exceeds maximum execution time.

• application/json

{
    "error":{
        "code":"OperationTimeOut",
        "message":"Request Timeout." 
    }
}

Response 415

Unsupported media type error. Content-Type is not in the allowed types:

1. For an image URL, Content-Type should be application/json
2. For a local image, Content-Type should be application/octet-stream

• application/json

{
    "error":{
        "code":"BadArgument",
        "message":"Invalid Media Type" 
    }
}

Response 429

• application/json

{
    "error":{
       "statusCode": 429,
        "message": "Rate limit is exceeded. Try again in 26 seconds." 
    }
}

php sample:

<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://westus.api.cognitive.microsoft.com/face/v1.0/detect');
$url = $request->getUrl();

$headers = array(
    // Request headers
    'Content-Type' => 'application/json',
    'Ocp-Apim-Subscription-Key' => '{subscription key}',
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
    'returnFaceId' => 'true',
    'returnFaceLandmarks' => 'false',
    'returnFaceAttributes' => '{string}',
);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_POST);

// Request body
$request->setBody("{body}");

/*

{
    "url":"http://example.com/1.jpg"
}

*/

try
{
    $response = $request->send();
    echo $response->getBody();
}
catch (HttpException $ex)
{
    echo $ex;
}

?>