You are looking at version 1 of the API documentation. Looking for version 2? Click here

 

Introduction

 

Overview

 

We're building a platform that lets you quickly add Emotion Analysis and Face Recognition into your apps and services. We’ve made it simple to connect with Kairos via our REST-style APIs. We also have some pre-built libraries for interacting with Kairos.

 

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 queries in our knowledge base or you can ask us a question. Failing that, feel free to This email address is being protected from spambots. You need JavaScript enabled to view it..

Get your API key

 
 

 

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.

 

POST /media

 

Create a new media object to be processed.

Required Parameters


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

Optional Parameters


timeout Set timeout in seconds to wait for the media to be processed. Default timeout is 10 seconds. Max timeout allowed is 60 seconds.

Request
POST /media{?source} HTTP/1.1
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e
 
Response
200
Content-Type: application/json{
    "id": "012345678901234567890123",
    "status" : "complete",
    "length" : 123,
    "frames": [
        {
            "person": {
                "id": 0,
                "time": 0,
                "emotions": {
                    "smile": 1.527,
                    "surprise": 2,
                    "negative": 10.303,
                    "attention": 100
                }
            }
        },
        {
            "person" : {
                "id" : 0,
                ...
            }
        }
        ...
     ]
}
 
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 /media

 

Returns the results of a specific uploaded piece of media.

Required Parameters


id The id of the media.

Request
GET /media/{id} HTTP/1.1
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e
 
Response
200
Content-Type: application/json{
    "id": "012345678901234567890123",
    "status" : "complete",
    "length" : 123,
    "frames": [
        {
            "person": {
                "id": 0,
                "time": 0,
                "emotions": {
                    "smile": 1.527,
                    "surprise": 2,
                    "negative": 10.303,
                    "attention": 100
                }
            }
        },
        {
            "person" : {
                "id" : 0,
                ...
            }
        }
        ...
     ]
}
 
Response
200
Content-Type: application/json{
    "id": "0123Test",
    "status_code": 3,
    "status_message": "Error. Media record not found."
}



DELETE /media

 

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

Required Parameters


id The id of the media.

Request
DELETE /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."
}



 

 

Face Recognition

 

Overview

Detect human faces in photos and images. We will return 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

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.

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.

Request
POST /enroll HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e{
    "image":" http://media.kairos.com/kairos-elizabeth.jpg ",
    "subject_id":"Elizabeth",
    "gallery_name":"MyGallery"
}
 
Response
200
Content-Type: application/json{
  "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"
      },
      "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
      }
    }
  ]
}
 
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
    }]
}



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.

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.

Request
POST /verify HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e{
    "image":" http://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"
      }
    }
  ]
}
 
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, which by default is set at 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.

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.

Request
POST /recognize HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e{
    "image":" http://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
    }]
}
 
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 /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.

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. Note that these optional parameters are not reliable for face recognition, but may be useful for face detection uses.

Request
POST /detect HTTP/1.1
Content-Type: application/json
app_id: 4985f625
app_key: aa9e5d2ec3b00306b2d9588c3a25d68e{
    "image":" http://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
    }]
}
 
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.

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.

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/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.

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.

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.

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{
    "Errors": [
    {
        "Message": "gallery name not found",
        "ErrCode": 5004
    }]
}
 
Response
200
Content-Type: application/json{
    "Errors": [
    {
        "Message": "subject ID was not found",
        "ErrCode": 5003
    }]
}