Developing with Kairos

API Reference

 

Overview

 

We're building a Face Recognition platform that lets you quickly integrate human identity features into your products and services—it's speedy, safe, and secure.

Kairos is a simple concept—you submit images into our API, and our deep learning algorithms analyze the faces found, then the API returns a bunch of useful data about the faces we find. You can use this to search, match and compare faces, or measure characteristics such as age, and gender.

 

QUICK START API GUIDE

 

Note: We have provided sample APP_KEY, APP_ID, and image URLs in the sandbox. Please replace with your keys / images during development.

 

Help and Support

 

We'd love to hear feedback from you and we're also here to help if you have any challenges. We have lots of answers to popular questions in our FAQ. Failing that, feel free to This email address is being protected from spambots. You need JavaScript enabled to view it..

 

Get Started with Face Recognition

Overview

Detect human faces in photos and images. Kairos returns information on facial features as coordinates on the image.

Base URL

api.kairos.com

Authentication

Requests must be authenticated with your API key. This must be sent as an HTTP header:

app_id:  "YOUR APP_ID"
app_key: "YOUR APP_KEY"

You can create and manage your API Keys via your dashboard. It's free to sign-up and start testing.

Requests

Requests return a JSON object with the header:

Content-Type: application/json

Storage

Face metadata extracted from the detected faces are stored for face recognition. Images used for api transactions are stored in the cloud are used strictly for R&D purpose only. To avoid file storage, this must be sent as an HTTP header:

store_image:  "false"

Usage

It's free to sign-up and start testing.

POST /enroll

Takes a photo, finds the faces within it, and stores the faces into a gallery you create.

To enroll someone into a gallery, all you need to do is submit a JPG or PNG photo. You can submit the photo either as a publicly accessible URL, Base64 encoded photo or as a file upload.

Next you need to choose an identifier for the person being enrolled. The identifier could be their name ("Bob"), something unique to your app ("ABC123xyz"), or anything meaningful for you. We call that identifier "subject_id".

You also need to pick a name for the gallery we are storing your faces in. We`ve called this "gallery_name". If you had used that gallery name before, we will just add your new face to it, otherwise we will create a new gallery for you.

Introducting the "Liveness" feature:

Detects pixel-level patterns to predict spoof-attacks, enabling the best possible combination of user experience, speed and security robustness. To use this feature, simply include the "liveness" selector in your API request.
(see example below)

Note: This feature is only available for Business & Enterprise Cloud Plans, as well with On-Premises Solutions.

Finally, we have some advanced options available for your use. We have set these options to sensible defaults, but sometimes there is a need to override them and we have provided that facility for you.

Tip: You can enroll multiple pictures of the same person (aka subject_id) to improve the matching accuracy. We find that 6-8 pictures is optimal, but it works fine with just 1.

Required Parameters

image Publicly accessible URL, file upload or Base64 encoded photo.
subject_id Defined by you. Is used as an identifier for the face.
gallery_name Defined by you. Is used to identify the gallery.

Optional Parameters

minHeadScale Defined by you. Is used to set the ratio of the smallest face we should look for in the photo. Accepts a value between .015 (1:64 scale) and .5 (1:2 scale). By default it is set at .015 (1:64 scale) if not specified.
multiple_faces If set to true lets the API enroll every face found in your photo under the same subject_id.
selector LIVENESS used to predict spoof-attacks.

POST https://api.kairos.com/enroll

POST https://api.kairos.com/enroll

Try it in our API sandbox

Try it in our API sandbox

Request

POST /enroll HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e

{
    "image":" https://media.kairos.com/kairos-elizabeth.jpg ",
    "subject_id":"Elizabeth",
    "gallery_name":"MyGallery"
}
Response
200
Content-Type: application/json


{
  "face_id": "7e77c8deb5fc4b958c0",
  "images": [
    {
      "attributes": {
        "age": 17,
        "asian": 0.00031,
        "black": 0.00716,
        "gender": {
          "femaleConfidence": 1,
          "maleConfidence": 0,
          "type": "F"
        },
        "glasses": "None",
        "hispanic": 0.98536,
        "lips": "Together",
        "other": 0.00003,
        "white": 0.00714
      },
      "transaction": {
        "confidence": 0.99908,
        "eyeDistance": 377,
        "face_id": "7e77c8deb5fc4b958c0",
        "gallery_name": "MyGallery",
        "height": 1107,
        "image_id": 1,
        "pitch": 14,
        "quality": 0.97309,
        "roll": 1,
        "status": "success",
        "subject_id": "Elizabeth",
        "timestamp": "20210313075722",
        "topLeftX": 378,
        "topLeftY": 427,
        "version": 2,
        "width": 771,
        "yaw": 0
      }
    }
  ]
}
Response
200
Content-Type: application/json{
    "Errors": [
    {
        "Message": "no faces found in the image",
        "ErrCode": 5002
    }]
}
Response
200
Content-Type: application/json{
    "Errors": [
    {
        "Message": "too many faces in image",
        "ErrCode": 5010
    }]
}
Request (includes "liveness" selector)

POST /enroll HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e

{
    "image":" https://media.kairos.com/kairos-elizabeth.jpg ",
    "subject_id":"Elizabeth",
    "gallery_name":"MyGallery",
    "selector":"liveness"
}
Response (includes "liveness" attribute)
200
Content-Type: application/json


{
  "face_id": "5410001743ab64935982",
  "images": [
    {
      "attributes": {
        "lips": "Together",
        "asian": 0.25658,
        "gender": {
          "type": "F"
        },
        "age": 26,
        "hispanic": 0.41825,
        "other": 0.11144,
        "black": 0.16007,
        "white": 0.05365,
        "glasses": "None",
        "liveness": 0.99091
      },
      "transaction": {
        "status": "success",
        "topLeftX": 390,
        "topLeftY": 706,
        "gallery_name": "MyGallery",
        "timestamp": "1487012582681",
        "height": 780,
        "quality": 0.79333,
        "confidence": 0.99997,
        "subject_id": "Elizabeth",
        "width": 781,
        "face_id": 1
      }
    }
  ]
}



POST /verify

Takes a photo, finds the face within it, and tries to compare it against a face you have already enrolled into a gallery.

To verify a face that you have enrolled in your gallery, all you need to do is submit a JPG or PNG photo. You can submit the photo either as a publicly accessible URL, Base64 encoded photo or as a file upload.

Next, specify which gallery and subject ID we should search against to compare. These are the same names you used previously during the /enroll calls to create the gallery.

Introducting the "Liveness" feature:

Detects pixel-level patterns to predict spoof-attacks, enabling the best possible combination of user experience, speed and security robustness. To use this feature, simply include the "liveness" selector in your API request.
(see example below)

Note: This feature is only available for Business & Enterprise Cloud Plans, as well with On-Premises Solutions.

Note: As long as the request is able to perform a match then you will receive a status of "success". You should use the "confidence" value to determine whether the comparison is valid for your application. We find that confidence values in excess of 60% are almost always of the same person.

Required Parameters

image Publicly accessible URL, file upload or Base64 encoded photo.
subject_id Defined by you. Is used as an identifier for the face.
gallery_name Defined by you. Is used to identify the gallery.
selector LIVENESS used to predict spoof-attacks.

POST https://api.kairos.com/verify

POST https://api.kairos.com/verify

Try it in our API sandbox

Try it in our API sandbox

Request
POST /verify HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e{
    "image":" https://media.kairos.com/kairos-elizabeth2.jpg ",
    "gallery_name":"MyGallery",
    "subject_id":"Elizabeth"
}
Response
200
Content-Type: application/json{
  "images": [
    {
      "transaction": {
        "status": "success",
        "subject_id": "Elizabeth",
        "quality": 0.84705,
        "width": 170,
        "height": 287,
        "topLeftX": 108,
        "topLeftY": 55,
        "confidence": 0.88309,
        "gallery_name": "MyGallery"
      }
    }
  ]
}
Request (includes "liveness" selector)

POST /verify HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e


{
    "image":"  https://media.kairos.com/kairos-elizabeth2.jpg  ",
    "gallery_name":"MyGallery",
    "subject_id":"Elizabeth",
    "selector":"liveness"
}
Response (includes "liveness" attribute)
200
Content-Type: application/json


{
    "images": [
    {
        "transaction": {
            "status": "success",
            "subject_id": "Elizabeth",
            "quality": 0.84705,
            "width": 170,
            "height": 287,
            "topLeftX": 108,
            "topLeftY": 55,
            "confidence": 0.88309,
            "gallery_name": "MyGallery",
            "liveness": 0.99091
        }
    }
    ]
}
Response
200
Content-Type: application/json{
    "Errors": [
    {
        "Message": "gallery name not found",
        "ErrCode": 5004
    }]
}
Response
200
Content-Type: application/json{
    "Errors": [
    {
        "Message": "subject ID was not found",
        "ErrCode": 5003
    }]
}
Response
200
Content-Type: application/json{
    "Errors": [
    {
        "Message": "no faces found in the image",
        "ErrCode": 5002
    }]
}
Response
200
Content-Type: application/json{
    "Errors": [
    {
        "Message": "too many faces in image",
        "ErrCode": 5010
    }]
}
Response
200
Content-Type: application/json{
    "Errors": [
    {
        "Message": "no match found",
        "ErrCode": 5012
    }]
}



POST /recognize

Takes a photo, finds the faces within it, and tries to match them against the faces you have already enrolled into a gallery.

To match someone to a face enrolled in your gallery, all you need to do is submit a JPG or PNG photo. You can submit the photo either as a publicly accessible URL, Base64 encoded photo or as a file upload.

Next, specify which gallery we should search against for matches. This is the same name you used previously during the /enroll calls to create the gallery.

We have the concept of a 'matching threshold'— learn more about thresholds— which by default is set at .60 (60%). If the face you submit is .60 similar to one or more faces in your gallery we will return that as a list of potential candidates and how closely they match. If no one falls in that range we will return no matches.

Depending on your usage, you may want to adjust the threshold lower or higher to return more or less potential candidates respectively.

Introducting the "Liveness" feature:

Detects pixel-level patterns to predict spoof-attacks, enabling the best possible combination of user experience, speed and security robustness. To use this feature, simply include the "liveness" selector in your API request.
(see example below)

Note: This feature is only available for Business & Enterprise Cloud Plans, as well with On-Premises Solutions.

Finally, we have some advanced options available for your use. We have set these options to sensible defaults, but sometimes there is a need to override them and we have provided that facility for you.

Required Parameters

image Publicly accessible URL, file upload or Base64 encoded photo.
gallery_name Defined by you. Is used to identify the gallery.

Optional Parameters

minHeadScale Defined by you. Is used to set the ratio of the smallest face we should look for in the photo. Accepts a value between .015 (1:64 scale) and .5 (1:2 scale). By default it is set at .015 (1:64 scale) if not specified.
threshold Is used to determine a valid facial match.
max_num_results Is the maximum number of potential matches that are returned. By default it is set to 10 if not supplied.
selector LIVENESS used to predict spoof-attacks.

POST https://api.kairos.com/recognize

POST https://api.kairos.com/recognize

Try it in our API sandbox

Try it in our API sandbox

Request
POST /recognize HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e{
    "image":" https://media.kairos.com/kairos-elizabeth.jpg ",
    "gallery_name":"MyGallery"
}
Response
200
Content-Type: application/json{
  "images": [
    {
      "transaction": {
        "status": "success",
        "width": 175,
        "topLeftX": 103,
        "topLeftY": 157,
        "gallery_name": "MyGallery",
        "face_id": 1,
        "confidence": 0.86944,
        "subject_id": "Elizabeth",
        "height": 175,
        "quality": 0.84705
      },
      "candidates": [
        {
          "subject_id": "Elizabeth",
          "confidence": 0.86944,
          "enrollment_timestamp": "1486925605094"
        },
        {
          "subject_id" : "Rachel",
          "confidence" : 0.63782,
          "enrollment_timestamp": "1416431816"
        }
      ]
    }
  ]
}
+ Response 200 (application/json)
    + Body
{
    "Errors": [
    {
        "Message": "gallery name not found",
        "ErrCode": 5004
    }]
}
Response
200
Content-Type: application/json{
    "Errors": [
    {
        "Message": "no faces found in the image",
        "ErrCode": 5002
    }]
}
Request (includes "liveness" selector)

POST /recognize HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e


{
    "image":"  https://media.kairos.com/kairos-elizabeth.jpg  ",
    "gallery_name":"MyGallery",
    "selector":"liveness"
}
Response (includes "liveness" attribute)
200
Content-Type: application/json


{
    "images": [
      {
        "transaction": {
          "status": "success",
          "width": 175,
          "topLeftX": 103,
          "topLeftY": 157,
          "gallery_name": "MyGallery",
          "face_id": 1,
          "confidence": 0.86944,
          "subject_id": "Elizabeth",
          "height": 175,
          "quality": 0.84705,
          "liveness": 0.99091
        },
        "candidates": [
          {
            "subject_id": "Elizabeth",
            "confidence": 0.86944,
            "enrollment_timestamp": "1486925605094"
          },
          {
            "subject_id" : "Rachel",
            "confidence" : 0.63782,
            "enrollment_timestamp": "1416431816"
          }
        ]
      }
    ]
  }
Response
200
Content-Type: application/json{
    "images": [
    {
        "transaction": {
            "status": "success",
            "subject_id": "kairos-team",
            "width": 407,
            "height": 407,
            "topLeftX": 964,
            "topLeftY": 617,
            "confidence": 1,
            "gallery_name": "MyGallery",
            "face_id": 1
        },
        "candidates": [
        {
            "subject_id": "kairos-team",
            "confidence": 1,
            "enrollment_timestamp": "1479090066185"
        }
        ]
    },
    {
        "transaction": {
            "status": "success",
            "subject_id": "kairos-team",
            "width": 458,
            "height": 458,
            "topLeftX": 2615,
            "topLeftY": 721,
            "confidence": 1,
            "gallery_name": "MyGallery",
            "face_id": 2
        },
        "candidates": [
        {
            "subject_id": "kairos-team",
            "confidence": 1,
            "enrollment_timestamp": "1479090066191"
        }
        ]
    }
    ]
}



POST /compare

Takes two photo, finds the largest face in source image and compares it with faces of target image.

You can submit the photo either as a publicly accessible URL, Base64 encoded photo or as a file upload.

Introducting the "Liveness" feature:

Detects pixel-level patterns to predict spoof-attacks, enabling the best possible combination of user experience, speed and security robustness. To use this feature, simply include the "liveness" selector in your API request.
(see example below)

Note: This feature is only available for Business & Enterprise Cloud Plans, as well with On-Premises Solutions.

Note: As long as the request is able to perform a match then you will receive a status of "success". You should use the "confidence" value to determine whether the comparison is valid for your application. We find that confidence values in excess of 60% are almost always of the same person.

Required Parameters

source_image Publicly accessible URL, file upload or Base64 encoded photo.
target_image Publicly accessible URL, file upload or Base64 encoded photo.

Optional Parameters

threshold Is used to determine a confidence threshold for valid facial match.
selector LIVENESS used to predict spoof-attacks.

POST https://api.kairos.com/compare

POST https://api.kairos.com/compare

Try it in our API sandbox

Try it in our API sandbox

Request
POST /compare HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e{
    "source_image":" https://media.kairos.com/kairos-elizabeth.jpg ",
    "target_image":" https://media.kairos.com/kairos-elizabeth2.jpg "
}
Response
200
Content-Type: application/json
{
    "SourceImageFace": {
      "topLeftX": 378,
      "topLeftY": 427,
      "width": 771,
      "height": 1107,
      "confidence": 0.99908
    },
    "MatchedFaces": [
      {
        "chinTipX": 187,
        "rightEyeCenterX": 234,
        "yaw": 1,
        "chinTipY": 343,
        "rightEyeCenterY": 203,
        "leftEyeCenterY": 200,
        "leftEyeCenterX": 149,
        "pitch": 13,
        "quality": 0.87754,
        "roll": 3,
        "eyeDistance": 85,
        "topLeftX": 108,
        "topLeftY": 90,
        "width": 173,
        "height": 252,
        "confidence": 0.99913,
        "similarity": 0.81334,
        "attributes": {
          "lips": "Together",
          "glasses": "None"
        },
        "face_id": 1
      }
    ],
    "UnmatchedFaces": []
}
Request (includes "liveness" selector)

POST /compare HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e


{
    "source_image":" https://media.kairos.com/kairos-elizabeth.jpg ",
    "target_image":" https://media.kairos.com/kairos-elizabeth2.jpg ",
    "selector":"liveness"
}
Response (includes "liveness" attribute)
200
Content-Type: application/json


{
  "SourceImageFace": {
    "topLeftX": 378,
    "topLeftY": 427,
    "width": 771,
    "height": 1107,
    "confidence": 0.99908
  },
  "MatchedFaces": [
    {
      "chinTipX": 187,
      "rightEyeCenterX": 234,
      "yaw": 1,
      "chinTipY": 343,
      "rightEyeCenterY": 203,
      "leftEyeCenterY": 200,
      "leftEyeCenterX": 149,
      "pitch": 13,
      "quality": 0.87754,
      "roll": 3,
      "eyeDistance": 85,
      "topLeftX": 108,
      "topLeftY": 90,
      "width": 173,
      "height": 252,
      "confidence": 0.99913,
      "similarity": 0.81334,
      "attributes": {
        "lips": "Together",
        "glasses": "None",
        "liveness": 1
      },
      "face_id": 1
    }
  ],
  "UnmatchedFaces": []
}

Response
200
Content-Type: application/json{
    "Errors": [
    {
        "Message": "no faces found in the image",
        "ErrCode": 5002
    }]
}



POST /detect

Takes a photo and returns the facial features it finds.

To detect faces, all you need to do is submit a JPG or PNG photo. You can submit the photo either as a publicly accessible URL or Base64 encoded.

Introducting the "Liveness" feature:

Detects pixel-level patterns to predict spoof-attacks, enabling the best possible combination of user experience, speed and security robustness. To use this feature, simply include the "liveness" selector in your API request.
(see example below)

Note: This feature is only available for Business & Enterprise Cloud Plans, as well with On-Premises Solutions.

Finally, we have some advanced options available for your use. We have set these options to sensible defaults, but sometimes there is a need to override them and we have provided that facility for you.

One additional thing to note is that the returned coordinates all begin at the top left of the photo.

Required Parameters

image Publicly accessible URL or Base64 encoded photo.

Optional Parameters

minHeadScale Defined by you. Is used to set the ratio of the smallest face we should look for in the photo. Accepts a value between .015 (1:64 scale) and .5 (1:2 scale). By default it is set at .015 (1:64 scale) if not specified.
selector Is used to adjust the face detector. If not specified the default of FRONTAL is used. LIVENESS used to predict spoof-attacks. Note that these optional parameters are not reliable for face recognition, but may be useful for face detection uses.

POST https://api.kairos.com/detect

POST https://api.kairos.com/detect

Try it in our API sandbox

Try it in our API sandbox

Request
POST /detect HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e{
    "image":" https://media.kairos.com/kairos-elizabeth.jpg ",
    "selector":"ROLL"
}
Response
200
Content-Type: application/json{
    "images": [
        {
            "status": "Complete",
            "width": 1536,
            "height": 2048,
            "file": "kairos-elizabeth.jpg",
            "faces": [
                {
                    "topLeftX": 390,
                    "topLeftY": 706,
                    "chinTipX": 780,
                    "rightEyeCenterX": 587,
                    "yaw": -3,
                    "chinTipY": 1548,
                    "confidence": 0.99997,
                    "height": 780,
                    "rightEyeCenterY": 904,
                    "width": 781,
                    "leftEyeCenterY": 907,
                    "leftEyeCenterX": 955,
                    "pitch": -17,
                    "attributes": {
                        "lips": "Together",
                        "asian": 0.25658,
                        "gender": {
                            "type": "F"
                        },
                        "age": 26,
                        "hispanic": 0.41825,
                        "other": 0.11144,
                        "black": 0.16007,
                        "white": 0.05365,
                        "glasses": "None"
                    },
                    "face_id": 1,
                    "quality": 0.79333,
                    "roll": -1
                }
            ]
        }
    ]
}
+ Response 200 (application/json)
    + Body
{
    "Errors": [
    {
        "Message": "no faces found in the image",
        "ErrCode": 5002
    }]
}
Request (includes "liveness" selector)

POST /detect HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e


{
    "image":"  https://media.kairos.com/kairos-elizabeth.jpg  ",
    "selector":"ROLL, liveness"
}
Response (includes "liveness" attribute)
200
Content-Type: application/json


{
    "images": [
        {
            "status": "Complete",
            "width": 1536,
            "height": 2048,
            "file": "kairos-elizabeth.jpg",
            "faces": [
                {
                    "topLeftX": 390,
                    "topLeftY": 706,
                    "chinTipX": 780,
                    "rightEyeCenterX": 587,
                    "yaw": -3,
                    "chinTipY": 1548,
                    "confidence": 0.99997,
                    "height": 780,
                    "rightEyeCenterY": 904,
                    "width": 781,
                    "leftEyeCenterY": 907,
                    "leftEyeCenterX": 955,
                    "pitch": -17,
                    "attributes": {
                        "lips": "Together",
                        "asian": 0.25658,
                        "gender": {
                            "type": "F"
                        },
                        "age": 26,
                        "hispanic": 0.41825,
                        "other": 0.11144,
                        "black": 0.16007,
                        "white": 0.05365,
                        "glasses": "None",
                        "liveness": 0.99091
                    },
                    "face_id": 1,
                    "quality": 0.79333,
                    "roll": -1
                }
            ]
        }
    ]
}
Response
200
Content-Type: application/json{
  "images": [
    {
      "status": "Complete",
      "width": 3888,
      "height": 2592,
      "file": "kairos-team1.jpg",
      "faces": [
        {
          "topLeftX": 977,
          "topLeftY": 637,
          "chinTipX": 1144,
          "rightEyeCenterX": 1082,
          "yaw": 10,
          "chinTipY": 1051,
          "confidence": 0.99923,
          "height": 375,
          "rightEyeCenterY": 743,
          "width": 374,
          "leftEyeCenterY": 736,
          "leftEyeCenterX": 1254,
          "pitch": 22,
          "attributes": {
            "asian": 0.00026,
            "gender": {
              "type": "M"
            },
            "age": 40,
            "hispanic": 0.00284,
            "other": 0.00061,
            "black": 0.99598,
            "white": 0.00030
          },
          "face_id": 1,
          "quality": -1.85805,
          "roll": 4
        },
        {
          "topLeftX": 2616,
          "topLeftY": 732,
          "chinTipX": 2898,
          "rightEyeCenterX": 2751,
          "yaw": 38,
          "chinTipY": 1252,
          "confidence": 0.99888,
          "height": 464,
          "rightEyeCenterY": 866,
          "width": 464,
          "leftEyeCenterY": 831,
          "leftEyeCenterX": 2932,
          "pitch": 3,
          "attributes": {
            "asian": 0.00000,
            "gender": {
              "type": "M"
            },
            "age": 34,
            "hispanic": 0.00278,
            "other": 0.00005,
            "black": 0.00000,
            "white": 0.99717
          },
          "face_id": 2,
          "quality": -0.99489,
          "roll": -8
        }
      ]
    }
  ]
}



POST /gallery/list_all

Lists out all of the galleries you have created.

This method requires no parameters.

POST https://api.kairos.com/gallery/list_all

POST https://api.kairos.com/gallery/list_all

Try it in our API sandbox

Try it in our API sandbox

Request
POST /gallery/list_all HTTP/1.1
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e
Response
200
Content-Type: application/json{
    "status": "Complete",
    "gallery_ids": [
        "MyGallery",
        "testgallery1",
        "testgallery2",
        "testgallery3",
        "testgallery4"
    ]
}



POST /gallery/view

Lists out all of the faces you have enrolled in a gallery.

You just need to pass in the gallery_name and will receive back the list of subjects that you have enrolled within that gallery.

Required Parameters

gallery_name Defined by you. Is used to identify the gallery.

POST https://api.kairos.com/gallery/view

POST https://api.kairos.com/gallery/view

Try it in our API sandbox

Try it in our API sandbox

Request
POST /gallery/view HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e{
    "gallery_name":"MyGallery"
}
Response
200
Content-Type: application/json{
  "status": "Complete",
  "subject_ids": [
    "Elizabeth",
    "Rachel"
    ]
}
+ Response 200 (application/json)
    + Body
{
    "Errors": [
    {
        "Message": "gallery name not found",
        "ErrCode": 5004
    }]
}



POST /gallery/view_subject

Displays all face_id's and enrollment timestamps for each template you have enrolled from a given gallery_name and subject_id.

Required Parameters

subject_id Defined by you. Is used as an identifier for the face.
gallery_name Defined by you. Is used to identify the gallery.

POST https://api.kairos.com/gallery/view_subject

POST https://api.kairos.com/gallery/view_subject

Try it in our API sandbox

Try it in our API sandbox

Request
POST /gallery/view_subject HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e{
    "gallery_name":"MyGallery",
    "subject_id":"test1"
}
Response
200
Content-Type: application/json{
    "status": "Complete",
    "face_ids": [
        {
            "face_id": "58f9034731c662745482",
            "enrollment_timestamp": "1492714311586"
        },
        {
            "face_id": "58f903481094d4122021",
            "enrollment_timestamp": "1492714312208"
        },
        {
            "face_id": "58f90347400a95737838",
            "enrollment_timestamp": "1492714312839"
        },
        {
            "face_id": "58f9034819f899628551",
            "enrollment_timestamp": "1492714312957"
        },
        {
            "face_id": "58f90347efcd88306283",
            "enrollment_timestamp": "1492714313011"
        }
    ]
}
+ Response 200 (application/json)
    + Body
{
    "Errors": [
    {
        "Message": "gallery name not found",
        "ErrCode": 5004
    }]
}
Response
200
Content-Type: application/json{
    "Errors": [
    {
        "Message": "subject ID was not found",
        "ErrCode": 5003
    }]
}



POST /gallery/remove

Removes a gallery and all of its subjects.

Pass your gallery_name and it will be removed along with all of its enrolled subjects.

Required Parameters

gallery_name Defined by you. Is used to identify the gallery.

POST https://api.kairos.com/gallery/remove

POST https://api.kairos.com/gallery/remove

Try it in our API sandbox

Try it in our API sandbox

Request
POST /gallery/remove HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e{
    "gallery_name":"MyGallery"
}
Response
200
Content-Type: application/json{
    "status":"Complete",
    "message":"gallery MyGallery was removed"
}
Response
200
Content-Type: application/json{
    "Errors": [
    {
        "Message": "gallery name not found",
        "ErrCode": 5004
    }]
}



POST /gallery/remove_subject

Removes a face you have enrolled within a gallery.

Pass in a gallery_name and a subject_id and we will remove that subject from the gallery. Once the last subject is removed the gallery is removed automatically.

If the 'face_id' parameter is passed in the request, then the API will look for and only remove the individual enrolled template matching the corresponding 'face_id' but not all the matching subject_id's in the gallery.

Required Parameters

subject_id Defined by you. Is used as an identifier for the face.
gallery_name Defined by you. Is used to identify the gallery.

Optional Parameters

face_id A unique ID from the enroll output when an image has been enrolled.

POST https://api.kairos.com/gallery/remove_subject

POST https://api.kairos.com/gallery/remove_subject

Try it in our API sandbox

Try it in our API sandbox

Request
POST /gallery/remove_subject HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e{
    "gallery_name":"MyGallery",
    "subject_id":"test1"
}
Response
200
Content-Type: application/json{
    "status": "Complete",
    "message" "subject id test1 has been successfully removed"
}
Response
200
Content-Type: application/json{
    "status": "Complete",
    "message": "subject id test1 with face id 58f9034743ab64939482 has been successfully removed"
}
Response
200
Content-Type: application/json{
    "Errors": [
    {
        "Message": "gallery name not found",
        "ErrCode": 5004
    }]
}
Response
200
Content-Type: application/json{
    "Errors": [
    {
        "Message": "subject ID was not found",
        "ErrCode": 5003
    }]
}
Response
200
Content-Type: application/json{
    "Errors": [
    {
        "Message": "subject id with face id was not found",
        "ErrCode": 5003
    }]
}



Emotion Analysis

Overview

Analyze and understand emotion, demographics and attention in most videos and images. We look for faces in your footage and pass the facial features and expressions through our face analysis algorithms. We will return values for the 6 universal emotions, age, gender, and other useful meta data about the faces found.

Base URL

api.kairos.com

Authentication

Requests must be authenticated with your API key. This must be sent as an HTTP header:

app_id:  "YOUR APP_ID"
app_key: "YOUR APP_KEY"

You can create and manage your API Keys via your dashboard. It's free to sign-up and start testing.

Requests

Requests return a JSON object with the header:

Content-Type: application/json

Usage

It's free to sign-up and start testing.

GET /v2/analytics

Returns the overall impressions from a specific uploaded piece of media.

Required Parameters


id The id of the media.

GET https://api.kairos.com/v2/analytics/ {id}

GET https://api.kairos.com/v2/analytics/ {id}

Try it in our API sandbox

Try it in our API sandbox

Request
GET /v2/analytics/{id} HTTP/1.1
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e
Response
200
Content-Type: application/json{
    "id": "4bf01d6b1824e796686a1379",
    "impressions": [
        {
            "appearance": {
                "glasses": 2
            },
            "average_emotion": {
                "anger": 1.855,
                "disgust": 100,
                "fear": 2,
                "joy": 0.182,
                "sadness": 2,
                "surprise": 1.568
            },
            "demographics": {
                "age_group": "Young-Adult",
                "gender": 2
            },
            "duration": 0,
            "emotion_score": {
                "negative": 10.43,
                "neutral": 0.23,
                "positive": 89.04
            },
            "id": "0",
            "tracking": {
                "attention": 0,
                "dwell": 0,
                "glances": 1
            }
        }
    ],
    "media_info": {
        "filename": "4bf01d6b1824e796686a1379.flv",
        "length": 12,
        "mime_type": "video/flv",
        "type": "video"
    }
}
Response
200
Content-Type: application/json{
    "id": "0123Test",
    "status_code": 3,
    "status_message": "Error. Media record not found."
}



POST /v2/media

Create a new media object to be processed.

Required Parameters


source The source of the media. URL or file upload.

Optional Parameters


landmarks Set to 1 to receive the feature points, such as eyes, nose, mouth locations, in the JSON response.
timeout Set timeout in seconds to wait for the media to be processed. Default timeout is 10 seconds. Max timeout allowed is 60 seconds.

POST https://api.kairos.com/v2/media {?source}

POST https://api.kairos.com/v2/media {?source}

Try it in our API sandbox

Try it in our API sandbox

Request
POST /v2/media{?source} HTTP/1.1
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e
Response
200
Content-Type: application/json{
    "frames": [
        {
            "people": [
                {
                    "appearance": {
                        "glasses": "No"
                    },
                    "demographics": {
                        "age_group": "Young Adult",
                        "gender": "Male"
                    },
                    "distance": 109.005,
                    "emotions": {
                        "anger": 2,
                        "disgust": 0.068,
                        "fear": 2,
                        "joy": 1.006,
                        "sadness": 62.145,
                        "surprise": 2
                    },
                    "end_time": "2016-Aug-31 17:47:35.285368",
                    "face": {
                        "height": 248,
                        "width": 248,
                        "x": 298,
                        "y": 126
                    },
                    "landmarks": [
                        {
                            "leftEyeBrowOuterLeft": {
                                "x": 356,
                                "y": 171
                            }
                        },
                        {
                            "leftEyeBrowInnerLeft": {
                                "x": 373,
                                "y": 167
                            }
                        },
                        ...
                        {
                            "lowerLipTopInnerLeft": {
                                "x": 400,
                                "y": 324
                            }
                        }
                    ],
                    "person_id": "0",
                    "pose": {
                        "pitch": 0.900874,
                        "roll": -2.14441,
                        "yaw": -11.3128
                    },
                    "start_time": "2016-Aug-31 17:47:35.280681",
                    "tracking": {
                        "attention": 100,
                        "blink": "Yes",
                        "dwell": 0.004,
                        "glances": 1
                    }
                }
            ],
            "time": 83
        },
        {
            "people": [
                {
                    ...
                    }
                }
            ],
            "time": 166
        }
    ],
    "id": "e873eebce0d77bd6fed3b1b9",
    "length": 12,
    "media_info": {
        "file": "e873eebce0d77bd6fed3b1b9.flv",
        "length": 12,
        "mime_type": "video/flv",
        "type": "video"
    },
    "status_code": 4,
    "status_message": "Complete"
}
Response
202
Content-Type: application/json{
    "status_code": 2,
    "id": "012345678901234567890123",
    "status_message": "Processing"
}
Response
200
Content-Type: application/json{
    "code": 1002,
    "message": "Required source parameter missing."
}



GET /v2/media

Returns the results of a specific uploaded piece of media.

Required Parameters


id The id of the media.

GET https://api.kairos.com/v2/media/ {id}

GET https://api.kairos.com/v2/media/ {id}

Try it in our API sandbox

Try it in our API sandbox

Request
GET /v2/media/{id} HTTP/1.1
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e
Response
200
Content-Type: application/json{
    "frames": [
        {
            "people": [
                {
                    "appearance": {
                        "glasses": "No"
                    },
                    "demographics": {
                        "age_group": "Young Adult",
                        "gender": "Male"
                    },
                    "distance": 109.005,
                    "emotions": {
                        "anger": 2,
                        "disgust": 0.068,
                        "fear": 2,
                        "joy": 1.006,
                        "sadness": 62.145,
                        "surprise": 2
                    },
                    "end_time": "2016-Aug-31 17:47:35.285368",
                    "face": {
                        "height": 248,
                        "width": 248,
                        "x": 298,
                        "y": 126
                    },
                    "landmarks": [
                        {
                            "leftEyeBrowOuterLeft": {
                                "x": 356,
                                "y": 171
                            }
                        },
                        {
                            "leftEyeBrowInnerLeft": {
                                "x": 373,
                                "y": 167
                            }
                        },
                        ...
                        {
                            "lowerLipTopInnerLeft": {
                                "x": 400,
                                "y": 324
                            }
                        }
                    ],
                    "person_id": "0",
                    "pose": {
                        "pitch": 0.900874,
                        "roll": -2.14441,
                        "yaw": -11.3128
                    },
                    "start_time": "2016-Aug-31 17:47:35.280681",
                    "tracking": {
                        "attention": 100,
                        "blink": "Yes",
                        "dwell": 0.004,
                        "glances": 1
                    }
                }
            ],
            "time": 83
        },
        {
            "people": [
                {
                    ...
                    }
                }
            ],
            "time": 166
        }
    ],
    "id": "e873eebce0d77bd6fed3b1b9",
    "length": 12,
    "media_info": {
        "file": "e873eebce0d77bd6fed3b1b9.flv",
        "length": 12,
        "mime_type": "video/flv",
        "type": "video"
    },
    "status_code": 4,
    "status_message": "Complete"
}
Response
200
Content-Type: application/json{
    "id": "0123Test",
    "status_code": 3,
    "status_message": "Error. Media record not found."
}



DELETE /v2/media

Delete media results. It returns the status of the operation.

Required Parameters


id The id of the media.

DELETE https://api.kairos.com/v2/media/ {id}

DELETE https://api.kairos.com/v2/media/ {id}

Try it in our API sandbox

Try it in our API sandbox

Request
DELETE /v2/media/{id} HTTP/1.1
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e
Response
200
Content-Type: application/json{
    "id": "9187207b6f1b41c681a8f529",
    "status_code": "5",
    "status_message": "Deleted"
}
Response
200
Content-Type: application/json{
    "code": 5003,
    "message": "Unable to delete media."
}