REST API :: faces.detect

Returns tags for detected faces in one or more photos, with geometric information of the tag, eyes, nose and mouth, as well as various attributes such as gender, is wearing glasses, and is smiling.

Photos can also be uploaded directly in the API request. A requests that uploads a photo must be formed as a MIME multi-part message sent using POST data. Each argument, including the raw image data, should be specified as a separate chunk of form data. (See example below)

Try it now on the API Sandbox

usage notes:

• All coordinates are provided in % values to support any photo scale. Photo height and width (vs. tag height/width) are provided in pixels. Yaw, roll, and pitch, are provided on the -90° to 90° scale.
• The Maximum width or height of a photo is 900 pixels. You may POST or send links to higher-size photos, but those will be resized internally to improve  performance.
• Every tag we return contains a set of attributes. The most important of them is the face attribute. It contains the confidence level of that tag being a face. As shown in the developer tools demo, we recommend using tags with confidence greater than 50%. Tags with lower confidence may also be face, but have higher probability to be false-positive detection.
• Face detection is a prerequisite step in adding training-set data for a user to the recognition index: when calling tags.save you need to pass the temporary tag IDs returned by detection, along with the relevant user IDs. To learn more about recognition, check out Recognition How-To and tags.save.
• If you've previously called a tags.save on the specified photo, the returned tag(s) will include the relevant uid. Otherwise the uid field remains empty.
• Check out the tagging and poster sample apps, for Face Detection use-cases and usage.

rate limiting (info):

This API is rate limited. Each passed photo or photo URL is added to your usage.

url:

http://api.face.com/faces/detect.format

parameters:

example:

http://api.face.com/faces/detect.json?api_key=4b4b4c6d54c37&api_secret= &urls= http://farm3.static.flickr.com/2566/3896283279_0209be7a67.jpg

post example: (post to http://api.face.com/faces/detect.json)

Content-Type: multipart/form-data; boundary=nonRelevantString
Content-Length: 104687
-----------------------------nonRelevantString
Content-Disposition: form-data; name="api_key"
4b4b4c6d54c37
-----------------------------nonRelevantString
Content-Disposition: form-data; name="api_secret"
sfhs8fj948fj29
-----------------------------nonRelevantString
Content-Disposition: form-data; filename="image.jpg"
Content-Type: image/jpeg
<<Raw Image Data Here>>

response sample (json, truncated):

View complete list of response fields

{
    photos: [
        {
            url: "http://farm3.static.flickr.com/2566/3896283279_0209be7a67.jpg",
            pid: "F@53f98f0f3ffeef58413190e657e297ff_4b4b4c6d54c37",
            width: 333,
            height: 500,
            tags: [
                {
                    tid: "TEMP_F@53f98f0f3ffeef58413190e657e297ff_4b4b4c6d54c37_51.05_60.40_0",
                    threshold: null,
                    uids: [ ],
                    label: "",
                    confirmed: false,
                    manual: false,
                    width: 11.71,
                    height: 7.8,
                    center: {
                        x: 51.05,
                        y: 60.4
                    },
                    eye_left: {
                        x: 49.18,
                        y: 59.7
                    },
                    eye_right: {
                        x: 52.5,
                        y: 59.46
                    },
                    mouth_left: {
                        x: 50.16,
                        y: 62.03
                    },
                    mouth_center: {
                        x: 51.61,
                        y: 61.86
                    },
                    mouth_right: {
                        x: 52.65,
                        y: 61.86
                    },
                    nose: {
                        x: 51.55,
                        y: 60.53
                    },
                    yaw: 26.44,
                    roll: -6.19,
                    pitch: 19.47,
                    attributes: {
                        gender: {
                            value: "male",
                            confidence: 95
                        },
                        glasses: {
                            value: "true",
                            confidence: 95
                        },
                        smiling: {
                            value: "false",
                            confidence: 95
                        }
                    }
                },
                {
                    tid: "TEMP_F@53f98f0f3ffeef58413190e657e297ff_4b4b4c6d54c37_54.35_34.40_0",
                    threshold: null,
                    uids: [ ],
                    label: "",
                    confirmed: false,
                    manual: false,
                    width: 37.24,
                    height: 24.8,
                    center: {
                        x: 54.35,
                        y: 34.4
                    },
                    eye_left: {
                        x: 48.18,
                        y: 32.16
                    },
                    eye_right: {
                        x: 58.85,
                        y: 31.65
                    },
                    mouth_left: {
                        x: 51.46,
                        y: 40.07
                    },
                    mouth_center: {
                        x: 55.55,
                        y: 39.56
                    },
                    mouth_right: {
                        x: 58.65,
                        y: 39.64
                    },
                    nose: {
                        x: 55.92,
                        y: 34.96
                    },
                    yaw: 30.97,
                    roll: -4.1,
                    pitch: 21.04,
                    attributes: {
                        gender: {
                            value: "male",
                            confidence: 95
                        },
                        glasses: {
                            value: "true",
                            confidence: 95
                        },
                        smiling: {
                            value: "false",
                            confidence: 95
                        }
                    }
                }
            ]
        }
    ],
    status: "success",
    usage: {
        used: 1,
        remaining: 199,
        limit: 200,
        reset_time_text: "Wed, 03 Mar 2010 13:46:40 +0000",
        reset_time: "1267624000"
    }
}