The VisageCloud Domain Model

VisageCloud makes face recognition as easy as possible, so you can focus your energy on your creativity and the specifics of your app, without having to worry about managing deep learning, classifiers, perspective alignment, color space and all the other hassles. In this document, we’ll go through the domain model and some example API calls.

Domain Model

In the VisageCloud domain model there are only four key elements: Account, Collection, Profile and Face. To understand the domain model in a nutshell, consider the following:

  • An account gives you access to manage several collections
  • A collection groups together several profile of distinct persons. Eg. actors, employees.
  • A profile identifies a distinct individual (eg. Jane, John, Anna, Tom) which belongs to a collection.
  • A face is an instance of an individual’s face, as captured in a photo. Having several faces associated with a profile (preferably with different lighting, perspective, make-up, facial expression or other contextual features) helps improve the accuracy of facial recognition.

Now let’s look at the entities in more detail.

VisageCloud Domain Model


The Account identifies your access and your permissions to use the API. Specifically, it identifies how many requests you can make, how many collections you can create and how many profiles (individual identities) you can store. To perform operations in the API, you will authenticate with accessKey and secretKey for read-write operations (eg. creating a new collection, creating a new profile in a collection and adding a new face to a profile) and you will authenticate with accessKey and readOnlyKey for read-only, stateless operations (eg. running an analysis on a photo or comparing the people in photo to an existent collection of profiles). In case you are using VisageCloud as a service, you’ll receive the an accessKey, a secretKey and a readOnlyKey. In case you are using VisageCloud in an on-premise installation, you will receive a masterKey that will allow you to create an account with whatever permission you like.


The Collection groups together several individuals who belong to the same set. Examples of such sets would be “employees”, “actors”, “models”, “high-value-customers”. Each collection is uniquely identified by an identifier and it belongs to only one account which can manage its contents. A collection contains several profiles.


A Profile is the representation of a specific person’s face under several circumstances. A profile can belong to Mary or John or Jane or Tom or Anna. All the known face instances belonging to that person should be added to that person’s profile. A profile can only belong to one collection. In order to give more flexibility in querying the face collection, you can compare the face in a new picture to all profiles in collection “actors” which have the label “oscar-winner” or “oscar-nominee”. This allows you more freedom than when managing different collections with overlapping profiles. The profile also has an externalReference, which is enforced as unique in a collection. This is helpful for mapping the profile entity to an external system (like a CRM, an identity manager or your application’s database). Think of this as a foreign key from an external system. As an optional parameter, each profile has a screenName, which is not constrained as unique and which you can use to make results from the API more human readable (eg. “Anne Koch” or “Thomas Yong”).


The Face defines a recognized photo from an image. It is described by the features used in the recognition process, by the keypoints (eg. nose, jaw, mouth) resulting from the face detection and alignment and by the attributes coming from the face classification (gender, age group, hair color, skin color, eye color). Without being associated to a profile, a face is originally anonymous. After such an association is done, a face can be used for comparison to other faces. A profile can have several faces, which improves the accuracy of the recognition. For instance, each profile in the “actors” collection can have five faces, each coming from a different picture. When presented with a new, untagged, unknown photo, VisageCloud can then see which of the existent profiles has all of its faces closer to the newly presented picture.

Contact us

Let us explore together how VisageCloud can best work for your use case


P: +40.724.714.234

Bucharest, Romania

© 2018 VisageCloud