Introduction

The aEi.ai provides Artificial Emotional Intelligence (AEI) as service by modelling affective features of people and virtual agents while interacting with each other, and making the models available through web services. The services allow developers to expand their Artificial Intelligence (AI) systems, such as virtual assistants, with emotional intelligence.

The service uses state-of-the-art deep learning algorithms to infer individual's affective features, including emotion, mood, personality, and satisfaction from difference input sources (e.g., text, speech, image, and video).

While modeling the affective features, we also model individuals' empathy, rapport, impression, and social perception towards each other, to be able to suggest appropriate reactions and behaviors (e.g., nonverbal behaviors, body gestures, facial expressions) for each individual during an interaction. Emotion and mood are represented based on Pleasure-Arousal-Dominance (PAD) theory of affect.

Personality is represented based on Big Five (i.e., openness, conscientiousness, extroversion, agreeableness, and neuroticism) theory of personality traits. Satisfaction is represented as a polarity score. All other features are represented in terms of one or few of aforementioned features.

Architecture

A central data structure in aEi.ai is called Interaction, which represents an interaction between one to multiple individuals. Individuals involved in an interaction -- referred to as Users -- may be real humans or virtual agents. As the messages (e.g., text, speech, image, video) are passed between users in an interaction, the aEi.ai service watches the interaction and keeps updating the affective models of each involved individual. At any point, models can be retrieved by querying the services.

How does aEi.ai watch an interaction?

Assuming there is an "AI system" which is interested in knowing more about individuals involved in an interaction, the AI system sends messages of each individual to the aEi.ai service as they are input by individuals to update the models. The following diagram shows an abstract architecture of the aEi.ai.

Data Structures

The aEi.ai services structure responses as data structures explained in this section. The services may return one or multiple of these objects based on the service.

Pleasure-Arousal-Dominance (PAD)

Pleasure-Arousal-Dominance (PAD) theory is the most popular emotion theory which defines emotions as a three dimensional concept: pleasure, arousal, and dominance.

Property Type Default Value Range Description
pleasure float 0.01 [-1, 1] Degree of individual's positivity vs. negativity (called sentiment in domains such as Natural Language Processing - NLP)
arousal float 0.01 [-1, 1] Degree of individual's energy
dominance float 0.01 [-1, 1] Degree of individual's control over the situation

Big Five

Big Five theory is the mostly used model for human personality traits. In this model, personality is described as a five dimensional concept: openness, conscientiousness, extroversion, agreeableness, and neuroticism.

Property Type Default Value Range Description
openness float 0.01 [0, 1] Degree to which a person is open to experiencing new things in the world
conscientiousness float 0.01 [0, 1] A person's degree of tendency to be organized and act thoughtfully
extroversion float 0.01 [0, 1] Degree to which a person is energetic and social, and has tendency to seek stimulation in the company of others
agreeableness float 0.01 [0, 1] Degree of a person's tendency to be compassionate and cooperative rather than suspicious and detached towards others
neuroticism float 0.01 [0, 1] Degree to which a person's tendency to easily experience unpleasant emotions such as anxiety, anger, or depression

Emotion

Emotion is represented in Pleasure-Arousal-Dominance (PAD) space. Also, based on the PAD scores of an emotion, we classify emotions into 173 different emotion categories (with different emotion names). An emotion model involves both its PAD representation and its name (category).

Property Type Default Description
pad Pad Default Pad PAD object representing pleasure, arousal, and dominance scores of emotion
emotionName String NEUTRAL Name (category) of the emotion based on its PAD scores

Mood

Similar to emotion, mood is represented in PAD space, based on which, we classify moods into different mood categories (with different mood names). A mood model involves both its PAD representation and its name (category).

Property Type Default Description
pad Pad Default Pad PAD object representing pleasure, arousal, dominance scores of mood
moodName String EXUBERANT Name (category) of mood based on its PAD scores

Personality

Personality is represented in both Big Five and PAD spaces. Because an individual may have different levels of personality traits, we do not classify personality into a single category as we do for emotion and mood. Instead, a percentage is assigned to each personality trait, showing the strength of that trait in corresponding user.

Property Type Default Description
bigFive BigFive default BigFive User's Big Five personality traits
pad Pad Default Pad PAD representation of personality

Satisfaction

Satisfaction is represented as a polarity by a float number between -1 (not satisfied at all) and +1 (completely satisfied).

Property Type Default Value Range Description
score float 0.0 [-1, +1] Polarity of satisfaction

Nonverbal Behavior

Nonverbal behaviors include emotional facial expressions, eye gaze, hand gestures, head gestures, body gestures, and prosody. A comprehensive list of supported nonverbal behaviors are provided in this section.

Property Type Default Value Range Description
name String Nonverbal behavior name
intensity Float null [0, +1.0] Intensity of the expression
duration Float null (0, +inf) Duration of the expression in seconds
start Integer null [0, +inf) Character index (inclusive) of the text where nonverbal behavior expression starts
end Integer null [1, +inf) Character index (exclusive) of the text where nonverbal behavior expression ends
side String null {LEFT, RIGHT, BOTH} Face, head, hand, or body side that nonverbal behavior is expressed

Supported nonverbal behaviors by the rapport model include, but not limited to, the following behaviors. We will keep this listed updated as more behaviors are added to the rapport model. Facial, eye, and head movements are all based on Facial Action Coding System (FACS).

Emotional Facial Expressions
Name Description
FACE_HAPPY Happy facial expression (AU6 + AU12)
FACE_SAD Sad facial expression (AU1 + AU4 + AU15)
FACE_ANGRY Angry facial expression (AU4 + AU5 + AU7 + AU23)
FACE_SURPRISED Surprised facial expression (AU1 + AU2 + AU5 + AU26)
FACE_FEARED Feared facial expression (AU1 + AU2 + AU4 + AU5 + AU7 + AU20 + AU26)
FACE_DISGUSTED Disgusted facial expression (AU9 + AU15 + AU16)
FACE_CONTEMPT Contempt facial expression (AU12R + AU14R)
FACE_PROUD Proud facial expression (AU12 + AU53 + AU58 + AU64)
FACE_CONFUSED Confused facial expression (AU4 + AU7 + AU15 + AU17)
FACE_EMBARRASSED Embarrassed facial expression (AU12 + AU52 + AU62 + AU64)
Eye Gazes
Name Description
GAZE_AWAY_FROM_HEARER AU61 or AU62
GAZE_TOWARDS_HEARER AU0
Hand Gesture
Name Description
HAND_FLICK A quick and short movement, usually from the wrist or hand
HAND_POINT_SELF Hand and/or fingers pointing to self
HAND_POINT_OTHER Hand and/or fingers pointing to hearer
HAND_QUESTION Hand gesture when a question is being asked
HAND_COMPARISON Hand gesture when comparing two things
HAND_CONTRAST Hand gesture when saying contrasting phrases
HAND_NEGATION Hand gesture when a negation is in the sentence
Head Gesture
Name Description
HEAD_NOD AUM59
HEAD_SHAKE AUM60
HEAD_SWEEP Sweeping head from side to side
AU51 Head turn to the left
AU52 Head turn to the right
AU55 Head tilt to the left
AU56 Head tilt to the right
Body Gesture
Name Description
BODY_LEAN_LEFT Body lean to the left
BODY_LEAN_RIGHT Body lean to the right
BODY_LEAN_FORWARD Body lean forward
BODY_LEAN_BACKWARD Body lean backward

Affect

Affect is the main aEi.ai data structure represented as ensemble of emotion, mood, personality, and satisfaction with definitions provided in previous sections.

Property Type Default Description
emotion Emotion default Emotion User's emotion model
mood Mood Default Mood User's mood model
personality Personality Default Personality User's personality model
satisfaction Satisfaction Default Satisfaction User's satisfaction model

Empathy

Empathy is one's adaption of affective states to her understanding of someone else's affective states. A person empathizes with others in different levels: emotion, mood, personality, and satisfaction. In other words, a person adapts her emotion, mood, personality, and satisfaction to other people in order to empathize with them. So, we model empathy with an Affect model. Empathy towards users is not interaction-dependent, but cumulative over all interactions where both users are engaged.

Property Type Default Description
empathyId String Unique ID of user's empathy towards the target user
targetUserId String Unique user ID of the target user
affect Affect Default Affect User's adapted affective state to the target user

Rapport

Rapport is defined as a set of nonverbal behaviors (e.g., facial expressions, hand gestures, body movements) that a user expresses while speaking to other people (users), in order to (a) build rapport, (b) increase closeness between them, and (c) increase effectiveness of her speech. To reach these goals, the rapport model considers personality of the hearer users for selecting the nonverbal behaviors and frequency of them.

Property Type Default Description
nonverbalBehaviors List<NonverbalBehavior> Empty list Speaker user's rapport towards hearer users

Impression

An observer user builds different levels of impressions from other users in her brain: emotion, mood, personality, and satisfaction. So, we model impression with an Affect model. Note that impression is not the same as empathy. Impression is one's understanding of someone else's affective states, while empathy is one's adaption of affective states to her understanding of someone else's affective states. Impression towards users is not interaction-dependent, but cumulative over all interactions where both users are engaged. In other words, it represents how observer user has evaluated the target user over all their interactions.

Property Type Default Description
impressionId String Unique ID of observer user's impression of the target user
targetUserId String Unique user ID of the target user
affect Affect Default Affect Observer user's impression of the target user's affective state

Social Perception

Social perception of a user is her set of impressions about other people (users). An individual learns about others' feelings and emotions by combining the information she gathers from verbal and non-verbal (e.g., facial expressions, speech, hand gestures, body movements) communications with them over time.

Property Type Default Description
socialPerceptionId String Unique ID of social perception of observer user towards others
impressions List<Impression> Empty list Observer user's impression of every other individual

User

User is a human or virtual agent who can engage in interactions. Each user has (1) a unique ID, (2) an Affect model, (3) a Social Perception of other users, and (4) a set of optional attributes represented as string key-value pairs.

Property Type Default Description
userId String Unique user ID
affect Affect Default Affect User's affect model
socialPerception SocialPerception Default SocialPerception User's social perception of other users
empathies List<Empathy> Empty list User's empathy towards other users

Interaction

Interaction simulates a conversation/meeting between zero to many users. When no users are involved in an interaction, it simulates an empty meeting room, otherwise, it simulates a room with users who can join and leave the meeting at anytime. As long as a user is sitting in a meeting room (involved in an interaction), her model (including affect and social perception models) gets affected by what is discussed in that meeting.

Property Type Default Description
interactionId String Unique interaction ID
users List<User> Empty list Users involved in the interaction

Error Handling

The aEi.ai services return a status object, which uses standard HTTP response codes to indicate response status. Success is always indicated with a 200 response, failures with 4xx responses, and internal server errors with 5xx responses. Following is the Status data structure returned by the aEi.ai services:

Property Type Default Description
code Integer HTTP status code
error String null Description of the error
help String null Error resolution suggestions

Following are possible HTTP response codes:

Status code Description
200 OK. Request succeeded
400 Bad request. Request is not properly formatted; requested language is not supported; API version is not provided; or invalid version is provided, etc.
401 Unauthorized. Access is denied due to invalid service credentials or wrong/expired access token.
429 Too Many Requests. Either number of queries exceeded the account limit; or too many requests are being processed at the time, and you should try the request again later.
500 Internal Server Error. The service encountered an internal error.
504 Gateway Timeout. The request timed out; or input size is too large to process in reasonable time. If input size is too large, consider reducing its size, or sending it in smaller chunks.

API

All aEi.ai services are available through RESTful web services.

Register New Account

In order to use aEi.ai services, you need to create a FREE account with an email, username, and password on our Register Page. No credit card information is required to query the aEi.ai services 10,000 times per month. If you need more queries, login to your account in aEi.ai website with the same username/password used to create the account, go to your profile, and subscribe to a paid plan that fits your needs the best.

In addition to the website UI, you can also use the API to register a new account in aEi.ai by making a POST request to the register API, with header parameters named username, password, email, and agreed, which means you have read and agreed to the aEi.ai Terms of Service and Privacy Policy.

Request
API Type HTTP Method URL
FREE POST https://aei.ai/register
Parameters
Parameter Type Required Description
username Header Yes Account username
password Header Yes Account password
email Header Yes Account email
agreed Header Yes true if you have read and agreed to the aEi.ai Terms of Service and Privacy Policy, false otherwise.
Response
Property Type Description
status Status Response status object

Sample query would look like the following:

curl -X POST 'https://aei.ai/register' -H 'username: <your username>' -H 'password: <your password>' -H 'email: <your email>' -H 'agreed: true'

Expected output looks like this:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    }
}

Authenticate Client

The authentication API generates an access token, which authenticates your other API calls. Access token expires after 30 minutes. When token expires, you need to make a new authentication API call to acquire a new access token. The same account username and password used to register are used to generate the access token.

You can authenticate the client you registered in step 2 by making a POST request to the authentication API, with Authentication header set to Base64 encoding of your username:password, and grant_type set to client_credentials. In order to encode <your username>:<your password> to Base64 format, you can use the Base64 encoding capability provided in different programming languages, for example, base64 in cURL, base64_encode() in PHP, base64.b64encode() in Python, encode_base64() in Perl, System.Convert.ToBase64String() in Visual Basic, System.Convert.ToBase64String() in C#, Base64.getEncoder().encodeToString() in Java, or Base64.encode64() in Ruby. If your username is "test" and your password is "Pass123!", the Base64 encoding for "test:Pass123!" is "dGVzdDpQYXNzMTIzIQ==".

Request
API Type HTTP Method URL
FREE POST https://aei.ai/oauth/token
Parameters
Parameter Type Required Description
grant_type Request Param Yes Value should always be set to 'client_credentials'
Authorization Header Yes Value should be set to 'Basic <your username>:<your password>', where <your username>:<your password> should be Base64 encoded
Response
Property Type Description
access_token String Access token to be included in all API calls to authenticate them
token_type String Authentication token type
expires_in int Access token expiration in seconds
scope String Space-separated list of client access types to database

Knowing the Base64 encoding of your username:password, you can get an access token as follows:

credentials=$(echo -n <YOUR USERNAME>:<YOUR PASSWORD> | base64)
curl -X POST 'https://aei.ai/oauth/token?grant_type=client_credentials' -H "Authorization: Basic $credentials"

Expected output looks like this:

{
    "access_token": "5cfb2d54-0375-4572-a6d7-93717ad3505d",
    "token_type": "bearer",
    "expires_in": 31533117,
    "scope": "trust read write"
}

Create New User

For every individual involved in an interaction, a new user with a unique ID should be created. This unique user ID is used in all interactions where that specific user is involved in order to incrementally improve the user's affect models.

You can create new users by making POST requests to the post_users API. NOTE: replace the access_token with the one you received in authentication step.

Request
API Type HTTP Method URL
PAID POST https://aei.ai/api/v1/users
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
Body
Required Description
No Optional String key-value pairs as user attributes, e.g., {'first_name': 'John'}
Response
Property Type Description
status Status Response status object
user User A new User object

Knowing the access token, you can get create a new user as follows:

curl -X POST 'https://aei.ai/api/v1/users' -H 'Authorization: Bearer <your access_token>>'

Expected response from aEi.ai service after each call looks like the following with a different userId. As shown below, all affective qualities of a new user are set to their default values:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    },
    "user": {
        "userId": "f3e2ee0c-620e-4260-b6fa-8b46139b7971",
        "affect": {
            "emotion": {
                "pad": {
                    "pleasure": 0.01,
                    "arousal": 0.01,
                    "dominance": 0.01
                },
                "emotionName": "NEUTRAL"
            },
            "mood": {
                "pad": {
                    "pleasure": 0.1,
                    "arousal": 0.1,
                    "dominance": 0.1
                },
                "moodName": "EXUBERANT"
            },
            "personality": {
                "pad": {
                    "pleasure": 0.1,
                    "arousal": 0.1,
                    "dominance": 0.1
                },
                "bigFive": {
                    "openness": 0.01,
                    "conscientiousness": 0.01,
                    "extroversion": 0.01,
                    "agreeableness": 0.01,
                    "neuroticism": 0.01
                }
            },
            "satisfaction": {
                "score": 0.0
            }
        },
        "socialPerception": {
            "impressions": []
        },
        "empathies": []
    }
}

Get User(s)

At any point during or after an interaction, you can query all users' affect models or a specific user's affect model from the aEi.ai service. This can be done by making a GET request to the get_users API with your target user ID as path variable.

Request
API Type HTTP Method URL
PAID GET https://aei.ai/api/v1/users/{user_id}
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
user_id Path Variable No Unique user ID of the target user. If not provided, list of all users involved in all your interactions will be returned
Response
Property Type Description
status Status Response Status object
user OR users User OR List<User> If user_id is provided in URL, the corresponding User object is return with 'user' key. If no user_id is provided, list of all users in your account will be returned with 'users' key. We do not suggest calling this API without user_id too often as it might be very resource and time intensive. Instead, we suggest to get specific users involved in a specific interaction as explained in Get User(s) section

Knowing the access token, you can get a user as follows:

curl -X GET 'https://aei.ai/api/v1/users/<your target userId>' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai would look the same as when we created a new user in Create New User section.

Also, you can get all users in your account as follows:

curl -X GET 'https://aei.ai/api/v1/users' -H 'Authorization: Bearer <your access_token>'

Assuming you have two newly created users in you account, expected response from aEi.ai would look the following:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    },
    "users": [
        {
            "userId": "6782d2c8-0e46-4c33-8e1d-a9484d8da0eb",
            "affect": {
                "emotion": {
                    "pad": {
                        "pleasure": 0.01,
                        "arousal": 0.01,
                        "dominance": 0.01
                    },
                    "emotionName": "NEUTRAL"
                },
                "mood": {
                    "pad": {
                        "pleasure": 0.1,
                        "arousal": 0.1,
                        "dominance": 0.1
                    },
                    "moodName": "EXUBERANT"
                },
                "personality": {
                    "pad": {
                        "pleasure": 0.1,
                        "arousal": 0.1,
                        "dominance": 0.1
                    },
                    "bigFive": {
                        "openness": 0.01,
                        "conscientiousness": 0.01,
                        "extroversion": 0.01,
                        "agreeableness": 0.01,
                        "neuroticism": 0.01
                    }
                },
                "satisfaction": {
                    "score": 0.0
                }
            },
            "socialPerception": {
                "impressions": []
            },
            "empathies": []
        },
        {
            "userId": "fcc60b6e-264d-4df9-83d2-346a3799c688",
            "affect": {
                "emotion": {
                    "pad": {
                        "pleasure": 0.01,
                        "arousal": 0.01,
                        "dominance": 0.01
                    },
                    "emotionName": "NEUTRAL"
                },
                "mood": {
                    "pad": {
                        "pleasure": 0.1,
                        "arousal": 0.1,
                        "dominance": 0.1
                    },
                    "moodName": "EXUBERANT"
                },
                "personality": {
                    "pad": {
                        "pleasure": 0.1,
                        "arousal": 0.1,
                        "dominance": 0.1
                    },
                    "bigFive": {
                        "openness": 0.01,
                        "conscientiousness": 0.01,
                        "extroversion": 0.01,
                        "agreeableness": 0.01,
                        "neuroticism": 0.01
                    }
                },
                "satisfaction": {
                    "score": 0.0
                }
            },
            "socialPerception": {
                "impressions": []
            },
            "empathies": []
        }
    ]
}

Get User's Emotion Model

At any point during or after an interaction, users' emotion model can be queried from the aEi.ai service. If you need incremental updates of a user's emotion model during an interaction, it should be queried after every new input to the interaction.

You can query a user's emotion model by making a GET request to the get_user_emotion API with your target user ID as path variable.

Request
API Type HTTP Method URL
PAID GET https://aei.ai/api/v1/users/{user_id}/emotion
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
user_id Path Variable Yes Unique user ID of the target user
Response
Property Type Description
status Status Response status object
userId String Unique user ID of the target user
emotion Emotion Emotion model of the target user

An example of emotion model query looks like the following:

curl -X GET 'https://aei.ai/api/v1/users/<target user_id>/emotion' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai would look like this:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    },
    "userId": "fcc60b6e-264d-4df9-83d2-346a3799c688",
    "emotion": {
        "pad": {
            "pleasure": 0.01,
            "arousal": 0.01,
            "dominance": 0.01
        },
        "emotionName": "NEUTRAL"
    }
}

Get User's Mood Model

At any point during or after an interaction, users' mood model can be queried from the aEi.ai service. If you need incremental updates of a user's mood model during an interaction, it should be queried after every new input to the interaction.

You can query a user's mood model by making a GET request to the get_user_mood API with your target user ID as path variable.

Request
API Type HTTP Method URL
PAID GET https://aei.ai/api/v1/users/{user_id}/mood
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
user_id Path Variable Yes Unique user ID of the target user
Response
Property Type Description
status Status Response status object
userId String Unique user ID of the target user
mood Mood Mood model of the target user

An example of mood model query looks like the following:

curl -X GET 'https://aei.ai/api/v1/users/<target user_id>/mood' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai would look like this:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    },
    "userId": "fcc60b6e-264d-4df9-83d2-346a3799c688",
    "mood": {
        "pad": {
            "pleasure": 0.1,
            "arousal": 0.1,
            "dominance": 0.1
        },
        "moodName": "EXUBERANT"
    }
}

Get User's Personality Model

At any point during or after an interaction, users' personality model can be queried from the aEi.ai service. If you need incremental updates of a user's personality model during an interaction, it should be queried after every new input to the interaction.

Query a user's personality model by making a GET request to the get_user_personality API with your target user ID as path variable.

Request
API Type HTTP Method URL
PAID GET https://aei.ai/api/v1/users/{user_id}/personality
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
user_id Path Variable Yes Unique user ID of the target user
Response
Property Type Description
status Status Response status object
userId String Unique user ID of the target user
personality Personality Personality model of the target user

Knowing the access token, you can query user's personality model as follows:

curl -X GET 'https://aei.ai/api/v1/users/<target user_id>/personality' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai would look like this:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    },
    "userId": "fcc60b6e-264d-4df9-83d2-346a3799c688",
    "personality": {
        "pad": {
            "pleasure": 0.1,
            "arousal": 0.1,
            "dominance": 0.1
        },
        "bigFive": {
            "openness": 0.01,
            "conscientiousness": 0.01,
            "extroversion": 0.01,
            "agreeableness": 0.01,
            "neuroticism": 0.01
        }
    }
}

Get User's Satisfaction Model

At any point during or after an interaction, users' satisfaction model can be queried from the aEi.ai service. If you need incremental updates of a user's satisfaction model during an interaction, it should be queried after every new input to the interaction.

Query a user's satisfaction model by making a GET request to the get_user_satisfaction API with your target user ID as path variable.

Request
API Type HTTP Method URL
PAID GET https://aei.ai/api/v1/users/{user_id}/satisfaction
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
user_id Path Variable Yes Unique user ID of the target user
Response
Property Type Description
status Status Response status object
userId String Unique user ID of the target user
satisfaction Satisfaction Satisfaction model of the target user

Knowing the access token, you can query user's satisfaction model as follows:

curl -X GET 'https://aei.ai/api/v1/users/<target user_id>/satisfaction' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai would look like this:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    },
    "userId": "fcc60b6e-264d-4df9-83d2-346a3799c688",
    "satisfaction": {
        "score": 0.0
    }
}

Get User's Empathy Towards Other Users

At any point during or after an interaction, users' empathy model can be queried from the aEi.ai service. If you need incremental updates of a user's empathy model during an interaction, it should be queried after every new input by target user.

Query a user's empathy model by making a GET request to the get_user_empathy API with your observer user ID as path variable, and target user IDs as request parameters.

Request
API Type HTTP Method URL
PAID GET https://aei.ai/api/v1/users/{user_id}/empathy
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
user_id Path Variable Yes Unique user ID of the observer user
target_user_id Request Param No Zero or more target user IDs. Every target user ID is passed as a separate parameter, e.g., target_user_id=1A3&target_user_id=4B6
Response
Property Type Description
status Status Response status object
userId String Unique user ID of the observer user
empathies List<Empathy> Empathy models of observer user towards target users

An example empathy query looks like the following:

curl -X GET 'https://aei.ai/api/v1/users/<observer user_id>/empathy?target_user_id=<target_user_id>' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai would look like this:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    },
    "userId": "6c979353-2ceb-4877-8620-5d190d6cddf8",
    "empathies": [
        {
            "targetUserId": "f3e2ee0c-620e-4260-b6fa-8b46139b7971",
            "affect": {
                "emotion": {
                    "pad": {
                        "pleasure": 0.31495,
                        "arousal": 0.51922,
                        "dominance": -0.01554
                    },
                    "emotionName": "CURIOUS"
                },
                "mood": {
                    "pad": {
                        "pleasure": 0.10178,
                        "arousal": 0.12116,
                        "dominance": 0.07043
                    },
                    "moodName": "EXUBERANT"
                },
                "personality": {
                    "pad": {
                        "pleasure": 0.08547,
                        "arousal": 0.08796,
                        "dominance": 0.08145
                    },
                    "bigFive": {
                        "openness": 0.0085,
                        "conscientiousness": 0.0085,
                        "extroversion": 0.0085,
                        "agreeableness": 0.0085,
                        "neuroticism": 0.0085
                    }
                },
                "satisfaction": {
                    "score": 0.11945708713599999
                }
            }
        }
    ]
}

Get User's Social Perception Towards Other Users

At any point during or after an interaction, users' social perception model can be queried from the aEi.ai service. If you need incremental updates of a user's social perception model during an interaction, it should be queried after every new input by target user.

Query a user's social perception model by making a GET request to the get_user_social_perception API with your observer user ID as path variable, and target user IDs as request parameters.

Request
API Type HTTP Method URL
PAID GET https://aei.ai/api/v1/users/{user_id}/social-perception
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
user_id Path Variable Yes Unique user ID of the observer user
target_user_id Request Param No Zero or more target user IDs. Every target user ID is passed as a separate parameter, e.g., target_user_id=1A3&target_user_id=4B6
Response
Property Type Description
status Status Response status object
userId String Unique user ID of the target user
socialPerception SocialPerception Social perception model of observer user towards target users

An example social perception query looks like the following:

curl -X GET 'https://aei.ai/api/v1/users/<observer user_id>/social-perception?target_user_id=<target_user_id>' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai would look like this:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    },
    "userId": "6c979353-2ceb-4877-8620-5d190d6cddf8",
    "socialPerception": {
        "impressions": [
            {
                "targetUserId": "f3e2ee0c-620e-4260-b6fa-8b46139b7971",
                "affect": {
                    "emotion": {
                        "pad": {
                            "pleasure": 0.31495,
                            "arousal": 0.51922,
                            "dominance": -0.01554
                        },
                        "emotionName": "CURIOUS"
                    },
                    "mood": {
                        "pad": {
                            "pleasure": 0.10178,
                            "arousal": 0.12116,
                            "dominance": 0.07043
                        },
                        "moodName": "EXUBERANT"
                    },
                    "personality": {
                        "pad": {
                            "pleasure": 0.08547,
                            "arousal": 0.08796,
                            "dominance": 0.08145
                        },
                        "bigFive": {
                            "openness": 0.0085,
                            "conscientiousness": 0.0085,
                            "extroversion": 0.0085,
                            "agreeableness": 0.0085,
                            "neuroticism": 0.0085
                        }
                    },
                    "satisfaction": {
                        "score": 0.11945708713599999
                    }
                }
            }
        ]
    }
}

Create New Interaction

For every interaction (i.e., conversation) between one to multiple users, a new interaction with a unique ID is created. This unique interaction ID will be used later for sending user messages to the interaction. An interaction may be initialized with zero to multiple users by passing user IDs when creating a new interaction.

You can create a new interaction by making a POST request to the post_interactions API with involved user IDs as optional request parameters.

Request
API Type HTTP Method URL
PAID POST https://aei.ai/api/v1/interactions
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
user_id Request Param No Zero or more unique user IDs of users involved in the new interaction. Every user ID is passed as a separate parameter, for example, user_id=1A3&user_id=4B6
Response
Property Type Description
status Status Response status object
interaction Interaction Newly created interaction

An example query to create an interaction between two users looks loke the following:

curl -X POST 'https://aei.ai/api/v1/interactions?user_id=<1st userId>&user_id=<2nd userId>' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai service looks like the following:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    },
    "interaction": {
        "interactionId": "16326fa9-374d-4bb0-bb8d-6accea3427c0",
        "users": [
            {
                "userId": "f3e2ee0c-620e-4260-b6fa-8b46139b7971",
                "affect": {
                    "emotion": {
                        "pad": {
                            "pleasure": 0.01,
                            "arousal": 0.01,
                            "dominance": 0.01
                        },
                        "emotionName": "NEUTRAL"
                    },
                    "mood": {
                        "pad": {
                            "pleasure": 0.1,
                            "arousal": 0.1,
                            "dominance": 0.1
                        },
                        "moodName": "EXUBERANT"
                    },
                    "personality": {
                        "pad": {
                            "pleasure": 0.1,
                            "arousal": 0.1,
                            "dominance": 0.1
                        },
                        "bigFive": {
                            "openness": 0.01,
                            "conscientiousness": 0.01,
                            "extroversion": 0.01,
                            "agreeableness": 0.01,
                            "neuroticism": 0.01
                        }
                    },
                    "satisfaction": {
                        "score": 0.0
                    }
                },
                "socialPerception": {
                    "impressions": []
                },
                "empathies": []
            },
            {
                "userId": "6c979353-2ceb-4877-8620-5d190d6cddf8",
                "affect": {
                    "emotion": {
                        "pad": {
                            "pleasure": 0.01,
                            "arousal": 0.01,
                            "dominance": 0.01
                        },
                        "emotionName": "NEUTRAL"
                    },
                    "mood": {
                        "pad": {
                            "pleasure": 0.1,
                            "arousal": 0.1,
                            "dominance": 0.1
                        },
                        "moodName": "EXUBERANT"
                    },
                    "personality": {
                        "pad": {
                            "pleasure": 0.1,
                            "arousal": 0.1,
                            "dominance": 0.1
                        },
                        "bigFive": {
                            "openness": 0.01,
                            "conscientiousness": 0.01,
                            "extroversion": 0.01,
                            "agreeableness": 0.01,
                            "neuroticism": 0.01
                        }
                    },
                    "satisfaction": {
                        "score": 0.0
                    }
                },
                "socialPerception": {
                    "impressions": []
                },
                "empathies": []
            }
        ]
    }
}

Get Interaction(s)

You can query all interactions created with your account or a specific interaction by making a GET request to the get_interactions API with your target interaction ID (received when created the interaction) passed as a path variable.

Getting an interaction which involves many users can take longer time due to the large data size. So, if you are interested in a specific user's affect model, consider querying that individual's affect model through users API instead.

Request
API Type HTTP Method URL
PAID GET https://aei.ai/api/v1/interactions/{interaction_id}
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
interaction_id Path Variable No Unique interaction ID of the target interaction. If not provided, list of all interactions created with your account will be returned
Response
Property Type Description
status Status Response status object
interaction OR interactions Interaction OR List<Interaction> If interaction_id is provided in URL, the corresponding Interaction object is returned with 'interaction' key. If no interaction_id is provided, list of all interactions in your account will be returned with 'interactions' key. We do not suggest calling this API without interaction_id too often as it might be very resource and time intensive. Instead, we suggest to get specific target users involved in a specific interaction as explained in Get User(s) section

A sample get interaction query looks like the following:

curl -X GET 'https://aei.ai/api/v1/interactions/<target interactionId>' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai would be the same as the response received when a new interaction was created (shown in Create New Interaction section).

Also, you can get all interactions in your account as follows:

curl -X GET 'https://aei.ai/api/v1/interactions' -H 'Authorization: Bearer <your access_token>'

Assuming you have one newly created interactions with two users in you account, expected response from aEi.ai would look the following:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    },
    "interactions": [
        {
            "interactionId": "16326fa9-374d-4bb0-bb8d-6accea3427c0",
            "users": [
                {
                    "userId": "f3e2ee0c-620e-4260-b6fa-8b46139b7971",
                    "affect": {
                        "emotion": {
                            "pad": {
                                "pleasure": 0.01,
                                "arousal": 0.01,
                                "dominance": 0.01
                            },
                            "emotionName": "NEUTRAL"
                        },
                        "mood": {
                            "pad": {
                                "pleasure": 0.1,
                                "arousal": 0.1,
                                "dominance": 0.1
                            },
                            "moodName": "EXUBERANT"
                        },
                        "personality": {
                            "pad": {
                                "pleasure": 0.1,
                                "arousal": 0.1,
                                "dominance": 0.1
                            },
                            "bigFive": {
                                "openness": 0.01,
                                "conscientiousness": 0.01,
                                "extroversion": 0.01,
                                "agreeableness": 0.01,
                                "neuroticism": 0.01
                            }
                        },
                        "satisfaction": {
                            "score": 0.0
                        }
                    },
                    "socialPerception": {
                        "impressions": []
                    },
                    "empathies": []
                },
                {
                    "userId": "6c979353-2ceb-4877-8620-5d190d6cddf8",
                    "affect": {
                        "emotion": {
                            "pad": {
                                "pleasure": 0.01,
                                "arousal": 0.01,
                                "dominance": 0.01
                            },
                            "emotionName": "NEUTRAL"
                        },
                        "mood": {
                            "pad": {
                                "pleasure": 0.1,
                                "arousal": 0.1,
                                "dominance": 0.1
                            },
                            "moodName": "EXUBERANT"
                        },
                        "personality": {
                            "pad": {
                                "pleasure": 0.1,
                                "arousal": 0.1,
                                "dominance": 0.1
                            },
                            "bigFive": {
                                "openness": 0.01,
                                "conscientiousness": 0.01,
                                "extroversion": 0.01,
                                "agreeableness": 0.01,
                                "neuroticism": 0.01
                            }
                        },
                        "satisfaction": {
                            "score": 0.0
                        }
                    },
                    "socialPerception": {
                        "impressions": []
                    },
                    "empathies": []
                }
            ]
        }
    ]
}

Add a User to Interaction

A new or existing user can be added to an interaction at any time during an interaction using their unique IDs.

You can add a user to an interaction by making a PUT request to the put_interactions_user API with corresponding interaction ID and user ID as path variables.

Request
API Type HTTP Method URL
PAID PUT https://aei.ai/api/v1/interactions/{interaction_id}/users
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
interaction_id Path Variable Yes Unique interaction ID of the target interaction
user_id Request Param Yes One or more unique user IDs of users involved in the new interaction. Every user ID is passed as a separate parameter, for example, user_id=1A3&user_id=4B6
Response
Property Type Description
status Status Response status object

A sample PUT query to add a user to an interaction is as follows:

curl -X PUT 'https://aei.ai/api/v1/interactions/<target interactionId>/users/?user_id=<1st userId>&user_id=<2nd userId>' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai would look like this:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    }
}

Remove User from Interaction

Users can leave an interaction at any time during a conversation. A user's unique user ID can be used to remove her from an interaction. User's affect model is updated according to an interaction as far as user is present in an interaction. When user leaves an interaction, her affect model does not get affected from that interaction anymore, unless she joins the same interaction again. If a user joins another interaction, her affect model is incrementally updated.

You can remove a user from an interaction by making a DELETE request to the delete_interactions_user API with your interaction ID and target user ID as path variables.

Request
API Type HTTP Method URL
PAID DELETE https://aei.ai/api/v1/interactions/{interaction_id}/users/{user_id}
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
interaction_id Path Variable Yes Unique interaction ID of the target interaction.
user_id Path Variable Yes Unique user IDs of user to be removed from the interaction
Response
Property Type Description
status Status Response status object

Following is an example of removing a user from an interaction.

curl -X DELETE 'https://aei.ai/api/v1/interactions/<target interactionId>/users/<target userId>' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai would look like this:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    }
}

Send Text Message to Interaction

Every user can send different types of messages, including text, speech, image (e.g., facial image), and video (e.g., stream of facial images) to an interaction, using the unique user ID and the unique interaction ID. When a message from user, say John, is sent to an interaction where users Bob and Mary are also involved:

  1. John's affect model is updated based on his input message;
  2. Impression models of Bob and Mary from John are updated (which also updates their social perception models);
  3. Empathy models of Bob and Mary are updated to empathize with John;
  4. Affect models of Bob and Mary are updated to simulates their affective state changes due to John's message;
  5. Rapport is modeled for John, in order to suggest appropriate behaviors (e.g., nonverbal) while speaking out this message.

You can add a text input from one of users involved in an interaction by making a POST request to the post_inputs_text API, with the text input as request body and interaction and user IDs as request parameters.

Request
API Type HTTP Method URL
PAID POST https://aei.ai/api/v1/inputs/text
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
interaction_id Request Param Yes Unique interaction ID of the target interaction
user_id Request Param Yes Unique user ID of the speaker user
Body
Required Description
Yes Text message to send to the interaction
Response
Property Type Description
status Status Response status object
rapport Rapport Nonverbal behaviors to build rapport with other users while uttering input text

An example usage of this API is as follows:

curl -X POST 'https://aei.ai/api/v1/inputs/text?interaction_id=<your interactionId>&user_id=<speaker userId>' -d 'I am surprised by aEi.ai' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai service looks like the following:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    },
    "rapport": {
        "nonverbalBehaviors": [
            {
                "name": "FACE_SURPRISED",
                "intensity": 0.41124678848763024,
                "start": 0,
                "end": 24
            },
            {
                "name": "HAND_POINT_SELF",
                "start": 0,
                "end": 4
            },
            {
                "name": "AU55",
                "intensity": 0.3,
                "start": 0,
                "end": 4
            }
        ]
    }
}

Send Image Message to Interaction

You can add an image input from one of users involved in an interaction by making a POST request to the post_inputs_image API, with the image URL as request body and interaction and user IDs as request parameters.

Request
API Type HTTP Method URL
PAID POST https://aei.ai/api/v1/inputs/image
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
interaction_id Request Param Yes Unique interaction ID of the target interaction
user_id Request Param Yes Unique user ID of the user who posts the image
Body
Required Description
Yes URL of the image message to send to the interaction
Response
Property Type Description
status Status Response status object
rapport Rapport Nonverbal behaviors to build rapport with other users while posting this image message

An example usage of this API is as follows:

curl -X POST 'https://aei.ai/api/v1/inputs/image?interaction_id=<your interactionId>&user_id=<speaker userId>' -d 'https://aei.ai/img/faces.jpg' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai service looks like the following:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    },
    "rapport": {
        "nonverbalBehaviors": [
            {
                "name": "FACE_HAPPY",
                "intensity": 0.6166450160214774
            },
            {
                "name": "GAZE_TOWARDS_HEARER",
                "side": "BOTH"
            },
            {
                "name": "AU51",
                "intensity": 0.3
            },
            {
                "name": "HAND_FLICK",
                "side": "LEFT"
            },
            {
                "name": "BODY_LEAN_FORWARD",
                "intensity": 0.8100000000000002
            },
            {
                "name": "AU55",
                "intensity": 0.3
            }
        ]
    }
}

Analyze a List of Interactions

You can analyze a list of interactions in a single API call by loading them as a JSON object. Using this API you can analyze offline interactions in bulk. The input JSON object should follow this schema:

[
  {
    "interactionId": "<INTERACTION ID>",
    "interactionTurns": [
      {
        "userId": "<USER ID>",
        "text": "<USER UTTERANCE>",
        "image": "<IMAGE URL>",
        "voice": null,
        "video": null,
      },
      ...
    ]
  },
  ...
]

To analyze a list of interactions, make a POST request to the post_inputs_interaction_list API, with the interaction list passed in request body.

Request
API Type HTTP Method URL
PAID POST https://aei.ai/api/v1/inputs
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
Body
Required Description
Yes List of interactions as a JSON object with above schema
Response
Property Type Description
status Status Response status object

An example usage of this API is as follows:

curl -X POST 'https://aei.ai/api/v1/inputs' -H 'Authorization: Bearer <your access_token>' -d '[
  {
    "interactionId": "16326fa9-374d-4bb0-bb8d-6accea3427c0",
    "interactionTurns": [
      {
        "userId": "109ddf80-e1a1-490c-ba74-ac21eb8b7fe9",
        "text": "I am happy",
        "image": "https://aei.ai/img/faces.jpg"
      },
      {
        "userId": "33dabbdc-b430-4864-92ff-971c10f96fc3",
        "text": "But I am sad"
      }
    ]
  },
  {
    "interactionId": "16326fa9-374d-4bb0-bb8d-6accea3427c0",
    "interactionTurns": [
      {
        "userId": "6782d2c8-0e46-4c33-8e1d-a9484d8da0eb",
        "text": "I am angry"
      },
      {
        "userId": "6c979353-2ceb-4877-8620-5d190d6cddf8",
        "text": "I am scared"
      }
    ]
  }
]'

Expected response from aEi.ai service looks like the following:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    }
}

Get Number of Queries to Paid Services

You can get number of queries to paid API services (endpoints) from given start date-time (in GMT time-zone) to given end date-time (in GMT time-zone) by making a GET request to the metrics/queries API.

Start and end date-times are in ISO-8601 format of yyyy-MM-dd[Thh:mm[:ss]], in which time is optional. If time is provided, seconds are optional as well. For example, 2019-01-23, 2019-01-23T13:34, and 2019-01-23T13:34:12 are all valid date-times.

  • If neither of start or end date-times are provided, total number of times this client had queried the paid endpoints in current month is returned.
  • If only start date-time is given, number of all paid queries starting from given date-time (inclusive) and ending to present date-time is returned.
  • If only end date-time is provided, number of all paid queries before that date-time (exclusive) is returned.
  • Finally, if both start and end date-time are provided, number of all paid queries starting from start date-time (inclusive) and ending to end date-time (exclusive) is returned.
Request
API Type HTTP Method URL
FREE GET https://aei.ai/api/v1/metrics/queries
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
start Request Param No Search start date-time in yyyy-MM-dd[Thh:mm[:ss]] format in GMT time-zone
end Request Param No Search end date-time in yyyy-MM-dd[Thh:mm[:ss]] format in GMT time-zone
Response
Property Type Description
status Status Response status object
queries Long Number of queries to paid API services (endpoints) from start date-time to end date-time

An example usage of this API is as follows:

curl -X GET 'https://aei.ai/api/v1/metrics/queries?start=2019-10-01&end=2019-11-01' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai service looks like the following:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    },
    "queries": 27
}

Get Number of Queries to a Given Endpoint

You can get number of queries to a specific API endpoint starting from a given start date-time (inclusive) and ending to a given end date-time (exclusive) by making a GET request to the metrics/queries/endpoints API.

Start and end date-times are in ISO-8601 format of yyyy-MM-dd[Thh:mm[:ss]], in which time is optional. If time is provided, seconds are optional as well. For example, 2019-01-23, 2019-01-23T13:34, and 2019-01-23T13:34:12 are all valid date-times.

  • If neither of start or end date-times are provided, total number of times this client had queried the target endpoint in current month is returned.
  • If only start date-time is given, number of queries to the target endpoint starting from given date-time (inclusive) and ending to present date-time is returned.
  • If only end date-time is provided, number of queries to the target endpoint before that date-time (exclusive) is returned.
  • Finally, if both start and end date-time are provided, number of queries to the target endpoint starting from start date-time (inclusive) and ending to end date-time (exclusive) is returned.
Request
API Type HTTP Method URL
FREE GET https://aei.ai/api/v1/metrics/queries/endpoint
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
start Request Param No Search start date-time in yyyy-MM-dd[Thh:mm[:ss]] format in GMT time-zone
end Request Param No Search end date-time in yyyy-MM-dd[Thh:mm[:ss]] format in GMT time-zone
endpoint Request Param Yes One of the following endpoint names: 
post_users, get_users, get_user_emotion, get_user_mood, get_user_personality, get_user_satisfaction, get_user_social_perception, get_user_empathy, post_interactions, put_interactions_user, delete_interactions_user, get_interactions, post_inputs_text
Response
Property Type Description
status Status Response status object
queries Long Number of queries to the API service (endpoints) with given name, from start date-time to end date-time

An example usage of this API is as follows, which gets number of API calls to the get_users endpoint, between 2019-10-01 and 2019-11-01:

curl -X GET 'https://aei.ai/api/v1/metrics/queries/endpoint?start=2019-10-01&end=2019-11-01&endpoint=get_users' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai would be the same as the response received when we got number of PAID queries in previous section.

Get Number of Used Free Queries

You can get number of used queries out of 10,000 free queries in current month by making a GET request to the metrics/queries/used API.

Request
API Type HTTP Method URL
FREE GET https://aei.ai/api/v1/metrics/queries/used
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
Response
Property Type Description
status Status Response status object
queries Long Number of used queries out of current month's 10,000 FREE queries

An example usage of this API is as follows:

curl -X GET 'https://aei.ai/api/v1/metrics/queries/used' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai would be the same as the response received when we got number of PAID queries in previous sections.

Get Number of Remaining Free Queries

You can get number of remaining free queries of current month by making a GET query to the metrics/queries/remaining API.

Request
API Type HTTP Method URL
FREE GET https://aei.ai/api/v1/metrics/queries/remaining
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
Response
Property Type Description
status Status Response status object
queries Long Number of remaining queries out of current month's FREE 1000 queries

An example usage of this API is as follows:

curl -X GET 'https://aei.ai/api/v1/metrics/queries/remaining' -H 'Authorization: Bearer <your access_token>'

Expected response from aEi.ai would be the same as the response received when we got number of PAID queries in previous sections.

Update Account Status

You can update/switch your account status to to one of active, inactive, or deleted by making a PUT request to the clients/status API with the new status as a request parameter.

Request
API Type HTTP Method URL
FREE PUT https://aei.ai/api/v1/clients/status
Parameters
Parameter Type Required Description
Authorization Header Yes Value should be 'Bearer <your access_token>'
status Request Param Yes One of the following account statuses: active, inactive, or deleted
Response
Property Type Description
status Status Response status object

An example usage of this API to change the account status to "inactive" mode is as follows:

curl -X PUT 'https://aei.ai/api/v1/clients/status?stauts=inactive' -H 'Authorization: Bearer <your access_token>'

Expected response looks like the following:

{
    "status": {
        "code": 200,
        "error": null,
        "help": null
    }
}

Versioning

API queries require a version parameter (as a path parameter). When we change the API in a backward-incompatible way, a new API version is released. So, before changing the version to the latest, make sure your application is ready for the latest changes in API responses. Details of changes in every version are provided in release notes.

API version is different from our application (i.e., aEi.ai service) version. When we improve our models or add features to our services, we increment the application version, which does not affect the way clients call our services. We only increment the API version if request or response format of calling aEi.ai services is changed.

Sample Code

Sample code snippets for different programming and scripting languages are provided here to help you have an easier experience with aEi.ai services.

In addition to the code snippets below, you can find a sample project in our Github page where a chat engine is connected to the aEi.ai RESTful API to demonstrate aEi.ai capabilities in action.

Java

Get our Java API from this Github repository and use the following code snippet to invoke the aEi.ai Java API:

public class AeiClient {

    // replace username with your username
    private static final String USERNAME = "<YOUR USERNAME>";
    // replace email with your email
    private static final String EMAIL = "<YOUR EMAIL>";
    // replace password with your password
    private static final String PASSWORD = "<YOUR PASSWORD>";
    // change registered to false if you have not registered an account in aEi.ai yet
    private static final boolean REGISTERED = true;

    public static void main(String[] args) throws Exception {
        // replace user1Id and user2Id with IDs of users you had created before
        // if you have not created users before, set user1Id and user2Id to null
        String user1Id = null; // OR "<1ST USER ID>"
        String user2Id = null; // OR "<2nd USER ID>"
        // replace interactionId with Id of an interaction you had created before
        // if you have not created an interaction before, set interactionId to null
        String interactionId = null; // OR "<INTERACTION ID>"

        // register a new user (if you don't have an account in aEi.ai yet)
        if (!REGISTERED) {
            AeiResponse response = AeiApi.register(USERNAME, EMAIL, PASSWORD, true);
            if (!AeiApi.isSuccess(response.getStatus())) {
                System.exit(1);
            }
        }

        // login (authentication)
        AuthResponse authResponse = AeiApi.login(USERNAME, PASSWORD);
        String accessToken = authResponse.getAccess_token();
        System.out.println("Access token: " + accessToken);

        // create two users
        if (user1Id == null) {
            user1Id = AeiApi.createNewUser(null, accessToken).getUser().getUserId();
            System.out.println("User1 ID: " + user1Id);
        }
        if (user2Id == null) {
            user2Id = AeiApi.createNewUser(null, accessToken).getUser().getUserId();
            System.out.println("User2 ID: " + user2Id);
        }

        // create an interaction and add users to it
        if (interactionId == null) {
            List<String> userIds = new ArrayList<>();
            userIds.add(user1Id);
            userIds.add(user2Id);
            interactionId = AeiApi.createNewInteraction(userIds, accessToken).getInteraction().getInteractionId();
            System.out.println("Interaction ID: " + interactionId);
        }

        // send an utterance by user1 to the interaction
        String text = "I am happy";
        AeiResponse response = AeiApi.newTextInput(user1Id, interactionId, text, accessToken);
        if (!AeiApi.isSuccess(response.getStatus())) {
            System.exit(1);
        }

        // get all user models
        List<User> users = AeiApi.getUserList(accessToken).getUsers();
        // NOTICE: user1 says she is happy, and user2 empathizes with her (e.g., check out emotion pleasure scores)
        for(User user : users) {
            Pad pad = user.getAffect().getEmotion().getPad();
            System.out.printf("User[%s] ", user.getUserId());
            System.out.printf("Emotion PAD: (%1.2f, %1.2f, %1.2f)\n", pad.getPleasure(), pad.getArousal(), pad.getDominance());
        }

        // check how many free queries you've made until now
        long queries = AeiApi.getUsedFreeQueries(accessToken).getQueries();
        System.out.println("Free queries: " + queries);
    }
}

Python

Get our Python API from this Github repository and use the following code snippet to invoke the aEi.ai Python API:

import sys
from api.aei_api import *

# replace username with your username
USERNAME = "<YOUR USERNAME>"
# replace email with your email
EMAIL = "<YOUR ACCOUNT EMAIL>"
# replace password with your password
PASSWORD = "<YOU PASSWORD>"
# change registered to false if you have not registered an account in aEi.ai yet
REGISTERED = True


def main():

    # replace user1_id and user2_id with IDs of users you had created before
    # if you have not created users before, set user1_id and user2_id to None
    user1_id = None  # OR "<1ST USER ID>"
    user2_id = None  # OR "<2nd USER ID>"
    # replace interaction_id with ID of an interaction you had created before
    # if you have not created an interaction before, set interaction_id to None
    interaction_id = None  # OR "<INTERACTION ID>"

    # register a new user (if you don't have an account in aEi.ai yet)
    if not REGISTERED:
        response = register(username=USERNAME, email=EMAIL, password=PASSWORD, agreed=True)
        if not is_success(status=response.json()["status"]):
            sys.exit(1)

    # login (authentication)
    auth_response = login(username=USERNAME, password=PASSWORD)
    access_token = auth_response.json()["access_token"]
    print(f"Access token: {access_token}")

    # create two users
    if user1_id is None:
        user1_id = create_new_user(access_token=access_token).json()["user"]["userId"]
    print(f"User1 ID: {user1_id}")

    if user2_id is None:
        user2_id = create_new_user(access_token=access_token).json()["user"]["userId"]
    print(f"User2 ID: {user2_id}")

    # create an interaction and add users to it
    if interaction_id is None:
        interaction_id = create_new_interaction(user_ids=[user1_id, user2_id], access_token=access_token).json()["interaction"]["interactionId"]
    print(f"Interaction ID: {interaction_id}")

    # send an utterance by user1 to the interaction
    text = "I am happy"
    response = new_text_input(user_id=user1_id, interaction_id=interaction_id, text=text, access_token=access_token)
    if not is_success(status=response.json()["status"]):
        sys.exit(1)

    # get all user models
    users = get_user_list(access_token=access_token).json()["users"]
    # NOTICE: user1 says she is happy, and user2 empathizes with her (e.g., check out emotion pleasure scores)
    for user in users:
        pad = user["affect"]["emotion"]["pad"]
        print("User[%s] Emotion PAD: (%1.2f, %1.2f, %1.2f)" % (user['userId'], pad['pleasure'], pad['arousal'], pad['dominance']))

    # check how many free queries you've made until now
    queries = get_used_free_queries(access_token=access_token).json()["queries"]
    print(f"Free queries: {queries}")


if __name__ == '__main__':
    main()

cURL

Create a bash (.sh) file and copy/paste the following set of cURL commands in that. This code demonstrates how to register an aEi.ai account programmatically, authenticate to the account, and analyze a chat between two users. In this code we use jq for parsing JSON in command-line.

#!/bin/bash

# install jq for json parsing if not already installed
# brew install jq

# replace username, password, and email with yours and uncomment this line in order to register a new user (if you don't have an account in aEi.ai yet)
# curl -X POST 'https://aei.ai/register' -H 'username: <YOUR USERNAME>' -H 'password: <YOUR PASSWORD>' -H 'email: <YOUR EMAIL>' -H 'agreed: true'

# replace username and password with yours to login (authenticate)
credentials=$(echo -n <YOUR USERNAME>:<YOUR PASSWORD> | base64)
access_token=$(curl -X POST 'https://aei.ai/oauth/token?grant_type=client_credentials' -H "Authorization: Basic $credentials" | jq -r '.access_token')
echo "Access Code: $access_token"

# create two users
user1_id=$(curl -X POST 'https://aei.ai/api/v1/users' -H "Authorization: Bearer $access_token" | jq -r '.user.userId')
echo "User1 ID: $user1_id"
user2_id=$(curl -X POST 'https://aei.ai/api/v1/users' -H "Authorization: Bearer $access_token" | jq -r '.user.userId')
echo "User2 ID: $user2_id"

# create an interaction and add users to it
interaction_id=$(curl -X POST "https://aei.ai/api/v1/interactions?user_id=$user1_id&user_id=$user2_id" -H "Authorization: Bearer $access_token" | jq -r '.interaction.interactionId')
echo "Interaction ID: $interaction_id"

# send an utterance by user1 to the interaction
curl -X POST "https://aei.ai/api/v1/inputs/text?interaction_id=$interaction_id&user_id=$user1_id" -d 'I am happy' -H "Authorization: Bearer $access_token"

# get all user models
users=$(curl -X GET 'https://aei.ai/api/v1/users' -H "Authorization: Bearer $access_token" | jq -r '.users')
echo "$users"

# check how many free queries you've made until now
queries=$(curl -X GET 'https://aei.ai/api/v1/metrics/queries/used' -H "Authorization: Bearer $access_token")
echo "Free queries: $queries"

Help

You can ask all your questions via creating an issue in our demo Github page , sending an email to support@aei.ai, or calling us at +1(234) 22-AEIAI.