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.


Credentials to access the APIs

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

Check the pricing section for more details on the different pricing options.


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


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: https://index.affectiva.com/. 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.

Example:

GET https://index.affectiva.com/ HTTP/1.1
Accept: application/json

Response:

{
    "development": {
        ...
        "project": "project service URL"
        ...
    },
    "v0": {
        ...
        "project": "project service URL"
        ...
    }
}

Example: Connecting to the Index Service

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.

curl

curl is a command-line tool for Unix systems, and it’s perhaps the simplest way to access a RESTful server. From a unix or linux command line (the ‘$’ below represents the unix prompt), run the following command:

$ curl --basic -u 'username:password' -H 'Accept: application/json' https://index.affectiva.com/

You will need to replace the username and password with your credentials or you will receive a 401 “unauthorized” response.

Ruby

This sample uses HTTP Basic authorization. You will need to replace the username and password with your credentials or you will receive a 401 “unauthorized” response.

require 'net/http'
require 'uri'

uri = URI 'https://index.affectiva.com/'

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

Java

This sample uses HTTP Basic authorization. You will need to replace the username and password with your credentials or you will receive a 401 “unauthorized” response.

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.IOException;
import java.net.URL;
import java.net.URLConnection;

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("https://index.affectiva.com/");
            URLConnection connection = url.openConnection();
            connection.setRequestProperty("Authorization", basicAuth);
            connection.setRequestProperty("Accept", "application/json");
            InputStream in = connection.getInputStream();
            dumpStream(in);
        } catch (IOException e) {
            e.printStackTrace();
            }
        }
    
        private static void dumpStream(InputStream in) throws IOException {
        BufferedReader br = new BufferedReader(new InputStreamReader(in));
        String readLine;
        while (((readLine = br.readLine()) != null)) {
            System.out.println(readLine);
        }
    }
}

C#

This sample uses HTTP Basic authorization. You will need to replace the username and password with your credentials or you will receive a 401 “unauthorized” response.

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.Clear();
        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) {
                result.Append(readLine);
            }                   
        }
    }
    return result.ToString();           
}

Python

This sample uses HTTP Basic authorization. You will need to replace the username and password with your credentials or you will receive a 401 “unauthorized” response.

import requests

auth=('username','password')
headers={"Accept":"application/json"}

uri = 'https://index.affectiva.com'

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

Versions

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.