API: Face - age, expression and gender identification

Introduction
Age-detection call
Age-detection response
Gender-detection call
Gender-detection response
Face expression call
Face expression response

Introduction

This is a rather straightforward API, where our customers send over the image they wish to check for age, gender or facial-expression details and get a response with the results.

Age information from age calls is often used for quick automated age-verifications. Mind it that there should always be a certain margin of error predicted (in most cases - cca 5 years), and that this API is not meant to be used for definite age-verifications. Instead, you may choose to use it to get approximate age of your end user and then decide to use some other (more reliable, more requiring and possibly expensive) method to verify the age of your end user positively.
For example: If the face of your user indicates through this quick API call that user is probably 55, you may choose to skip for detailed verification of 18+, in order to spare user's time and your resources.

Expression and gender indications should be used only statistically, and possibly to improve your marketing/sales insights.

Otherwise - this API is often used in combination with other APIs, such as face-enrolment and face-verification, in order to provide additional information about the person in question.

Age-Detection Call

(Call from your server to our API.)

POST /faceapi/v1/face_age_detection

Parameters / body:

            {
                "image": "string",
                "api_key": "string"
              }

Parameters explained:

  • "image" = (mandatory) Image encoded as b64 (hence string).
  • "api_key" = (mandatory) Your developer key found in your Settings

Age-Detection Response

Code: 200

Default response:

            {
                "result": "Ok",
                "code": 0,
                "message": "string",
                "data": {
                  "age": 0
                }
              }

Response explained:

  • "result" = "Ok" or "Err" (error)
  • "code" = 0 or error code (int)
  • "message" = If result "Err" - textual description (string)
  • "data" = JSON object with data
    • "age" = Integer indicating approximate age (cca +/- 5 yr).

Gender-Detection Call

(Call from your server to our API.)

POST /faceapi/v1/face_gender_detection

Parameters / body:

            {
                "image": "string",
                "api_key": "string"
              }

Parameters explained:

  • "image" = (mandatory) Image encoded as b64 (hence string).
  • "api_key" = (mandatory) Your developer key found in your Settings

Gender-Detection Response

Code: 200

Default response:

            {
                "result": "Ok",
                "code": 0,
                "message": "string",
                "data": {
                  "gender": "string",
                  "genderProbability": 0
                }
            }

Response explained:

  • "result" = "Ok" or "Err" (error)
  • "code" = 0 or error code (int)
  • "message" = If result "Err" - textual description (string)
  • "data" = JSON object with data
    • "gender" = "M" or "F" (male or female)
    • "genderProbability = Integer, probability percentage.

Face Expression Call

(Call from your server to our API.)

POST /faceapi/v1/face_expression_detection

Parameters / body:

            {
                "image": "string",
                "api_key": "string"
              }

Parameters explained:

  • "image" = (mandatory) Image encoded as b64 (hence string).
  • "api_key" = (mandatory) Your developer key found in your Settings

Face Expression Response

Code: 200

Default response:

            {
                "result": "Ok",
                "code": 0,
                "message": "string",
                "data": {
                  "neutral": 0,
                  "happy": 0,
                  "sad": 0,
                  "angry": 0,
                  "fearful": 0,
                  "disgusted": 0,
                  "surprised": 0
                }
              }

Response explained:

  • "result" = "Ok" or "Err" (error)
  • "code" = 0 or error code (int)
  • "message" = If result "Err" - textual description (string)
  • "data" = JSON object with data. Each possible expression is represented with an integer value, displaying percentage of probability of named expression ("happy", "sad", etc.)

Top of the Page