Getting started

The cloud APIs provide access to Affectiva’s latest Emotion AI. Clients using the APIs can upload and analyze images and videos to look for emotion metrics, and can also submit annotations (such as age and gender) that are associated with the uploaded media.

1. Obtain Credentials to access the APIs

To get credentials to use the API, please contact us.

2. Connect to the APIs

Our APIs use HTTP Basic Access Authentication to authenticate clients. HTTP Basic Authentication relies on a TLS transport to ensure that the credentials cannot be seen by a third party, so all API communications must be transmitted over a TLS-protected channel. Please ensure that your Index Service URL begins with “https” before using it.

Credentials should be encoded in an Authorization header per section 10.2 of RFC 1945. This technique is recommended and is typically well-supported by HTTP client programming toolkits. The user names typically include an @ character which needs to be URL-encoded as %40. The password also needs to be URL-encoded.

3. The Index Service

The index service is the “root” of our APIs. Begin the API session by requesting the index from the index service which can then be used to locate the API to interact with. An API client should be able to perform all of its operations given only one pre-configured URL: Any other URL should be provided by the service.

The index service is read-only, so the only HTTP operation supported is GET. The index is available in two representations: JSON, and HTML. JSON is intended for machine consumption and HTML is human-readable.

To request the JSON index, use an Accept: application/json header.

The JSON index is a hash where the keys are the API versions available. The value associated with each key is in turn a hash of service names to the service URLs available to that API version. This allows us to evolve the API without breaking backwards compatibility, to phase out older versions of the API/services in an orderly fashion, and to expose service suites that may be under development or experimental.

To request the HTML index, use an Accept: text/html header.

Here's an example:

Accept: application/json

And here's a typical response:

    "development": {
        "project": "project service URL"
    "v0": {
        "project": "project service URL"

These examples connect to the API service and request the index, so they test http communication, basic authentication, and content negotiation. Once you can get a simple program like these to work in your language of choice, you’ve got a solid platform to build on.

Example: Connecting to the Index Service

Here are examples in several languages to show you how to connect to the indexing service:

$ curl --basic -u 'username:password' -H 'Accept: application/json'
require 'net/http'
require 'uri'

uri = URI ''

Net::HTTP.start(, uri.port, use_ssl: true) do |http|
  request = uri
  request.basic_auth 'username', 'password'
  request['Accept'] = 'application/json'
  response = http.request request
  puts response.body

public class index_w_basic {
    public static final void main(final String[] args) {
        try {
            String credentials = "username" + ":" + "password";
            String basicAuth = "Basic " + javax.xml.bind.DatatypeConverter.printBase64Binary(credentials.getBytes());

            URL url = new URL("");
            URLConnection connection = url.openConnection();
            connection.setRequestProperty("Authorization", basicAuth);
            connection.setRequestProperty("Accept", "application/json");
            InputStream in = connection.getInputStream();
        } catch (IOException e) {
        private static void dumpStream(InputStream in) throws IOException {
        BufferedReader br = new BufferedReader(new InputStreamReader(in));
        String readLine;
        while (((readLine = br.readLine()) != null)) {
public static async Task<string> GetResponse(string url, string username, string password) {
    var result = new StringBuilder();
    using (var client = new HttpClient()) {
        client.BaseAddress = new Uri(url);               
        client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
        string credentials = string.Format("{0}:{1}", username, password);
        string encodedCredentials = Convert.ToBase64String(ASCIIEncoding.ASCII.GetBytes(credentials));
        client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", encodedCredentials);

        HttpResponseMessage response = await client.GetAsync("");
        if (response.IsSuccessStatusCode) {
            Stream stream = await response.Content.ReadAsStreamAsync();
            var sr = new StreamReader(stream);
            string readLine = null;
            while ((readLine = sr.ReadLine()) != null) {
    return result.ToString();           
import requests


uri = ''

print requests.get(uri, auth=auth, headers=headers).json()


The Index Service allows clients to choose which version of the API they would like to use. In general, API versions denote incompatible changes, so “v1” should be considered incompatible with “v2”. The special “development” version is volatile and shouldn’t be used for production code.

Updated about a year ago

Getting started

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.