1.
Set up Face Detection & Recognition in 5 Easy
Steps. Coding is optional.
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 hassle. In this document, we’ll go
through the domain model and some example API calls.
In this post, we’ll go from getting your API key to creating your collection of known profiles (a profile
represents a person) to detecting faces in photos and mapping them to profile (this is like tagging on
Facebook) and then finally to using that collection to recognize people in new photos.
All you need is to make HTTP calls to our API. You can do this from any language on choice (Java,
Python, PHP, Node.js, .NET). If you’re unfamiliar with programming, worry not, you can just use the
Postman extension for Chrome​, while allows you to make HTTP calls without a line of code. If you’re
more comfortable with the command line, we also provide cURL examples.
So let’s get crackin’...
Step #0: Request an API key
To request an API key, just ​fill out this form
Ideally, provide us with some details about your intended use case, so we can properly tune your
account and offer the proper guidance. After we send you the keys, do not forget to replace them in
the example calls provided below. For security reasons, we have not provided keys in the examples
below.
We will provide three keys:
● accessKey​ - this uniquely identifies your account
● secretKey​ - this is the master key of your account which allows the holder to either perform
detections/recognitions, to create, modify, delete collections and profiles and to access
sensitive information about the account (like the list of last operations performed)
● readOnlyKey​ - this key should also be secret, but it only allow you to command
detection/recognitions, ​without​ having the options to change data pertaining to the account
or to view sensitive information

2.
You must authenticate all calls to the API by setting the GET parameter “accessKey” to the
value of accessKey and the parameter “secretKey” to the value of secretKey for write calls or
to the value of readOnlyKey for detection/recognition calls.
The analysis and recognition end-points can be accessed by setting the GET parameter
“accessKey” to the value of accessKey and the parameter “secretKey” to the value of readOnlyKey.
Using readOnlyKey makes sense if, for instance, you perform detection/recognition calls directly
from a mobile app, without proxying it through your backend server component: you don’t want to
leave a key that allows modifying your collection (i.e. secretKey) in a device you don’t control (the
user’s device). As best-practice, consider all three keys as being secret and do not expose them to
the user, either in client-side code or binaries.
Step #1: Create a collection
In order to group all the people you want to register in your system in a more manageable way, you
need to create a collection. Think of a collection a set or a group of registered people. You have to
create a profile, give it a name (like “Actors”, “Models”, “Celebrities”, “Friends of Donald Trump”).
VisageCloud will return a ​collectionId​. Copy this and store it, as you’ll be needing it later.
Perform a POST call to /collection/collection in either Postman, cURL or any other language you
prefer.

3.
cURL command
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d
'accessKey=XXXXXXX&secretKey=YYYYYYY&collectionName=test-create-empty-collection-01'
"https://visagecloud.com/rest/v1.1/collection/collection"
Step #2: Create profiles for each person in your collection
A profile represents a person. While it does not have to be named, it’s an element which guarantees
that person A (and their faces) are treated differently from person B.
Assuming you’re adding a profile to the actors collection, that profile would represent “Jessica
Lange” or “Robert DeNiro” or “Summer Glau”.
Each profile creating call should have these:
● accessKey, secretKey
● collectionId - defines the collection you want to create the profile into
● externalId - this allows to link a profile to a database external to VisageCloud, where you can
potentially store additional information you don’t want to share with VisageCloud (a user’s
email address, passwords, user activity, description). In case you do not provide an
externalId, it will be set to the same value as the profileId. If you set an externalId which
already exists in the collection, the existing profile with that externalId will be returned
(externalId must be unique for each profile in the collection)
● screenName - this is a human-readable label for each profile. It is not mandatory, but setting
it will allow you to more easily trace and debug responses from Visage Cloud (for instance, it
can be “Bogdan Bocse” or “Al Pacino” or “Donald Trump”)
● labels - labels are like tags which will later allow you to do finer filtering in face recognition.
Let us say you have several types of user divided by citizenship (eg. “us”, “uk”, “poland”,
“romania”). If you label the profile accordingly, you can then only do the recognition by
comparing only with those users with the label “uk”. You can do this without having to go
through the trouble of maintaining separate collections and you can also query the full
collection without any label restriction,.
Perform a POST call to /profile/profile

4.
cURL command
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d
'accessKey=XXXXX&secretKey=YYYYYYYY&collectionId=ZZZZZZZ&externalId=some-profile-5&scr
eenName=Test-03&labels=actor,model,designer "https://visagecloud.com/rest/v1.1/profile/profile"
Step #3: Detect the faces in photos
Now here comes the interesting part: detecting the faces and face attributes in a photo.
You most likely want to try to copy-paste the code below in an HTML file and load it into a browser.
In the example below we marked the parameter “storePicture” to “false”, indicating that VisageCloud
will discard the original picture after the analysis is done; in this case, the “storeAssetURL” will be
empty in the response..
The following code will perform a POST call to /analysis/detection
<​form ​action=​"https://visagecloud.com/rest/v1.1/analysis/detection"
method=​"POST" ​enctype=​"multipart/form-data"​>
​<​input ​type=​"file" ​name=​"picture"​/>
​<​input ​type=​"hidden" ​name=​"accessKey" ​value=​"insert-accesKey-here"​>
<​input ​type=​"hidden" ​name=​"storePicture" ​value=​"false"​>
​<​input ​type=​"hidden" ​name=​"secretKey"
​value=​"insert-readOnlyKey-here"​>
​<​input ​type=​"submit"​/>
</​form​>
Alternatively, you can perform the detection on a pictureURL. In this case, VisageCloud will retrieve
the picture from the URL you indicate and return the response when the detection is done:
cURL command

5.
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d
'accessKey=XXXXXX&secretKey=YYYYYYYY&pictureURL=https://scontent-fra3-1.xx.fbcdn.net/v/t1.
0-9/14732386_10210111301966375_1358646233657322761_n.jpg?oh%3Dc1b9227fd53b5b8fc24e
d681712c2ddf%26oe%3D59360B49' "​https://visagecloud.com/rest/v1.1/analysis/detection​"
The response from the server will contain a JSON with all the faces detected, as the example below.
The picture you uploaded may contain several faces, and each of them will be contained in the array
“faces”. If no faces are detected in the picture, this array will be empty. Each face instance will have
an unique “hash” attribute, which you can consequently add to a face instance to a profile (person).
This association between faceHash and profile is like saying “this face belongs to Mary Jones” or
“this face belongs to Penelope Cruz”.
{
status: ​"OK"​,
message: ​"Done"​,
payload​:
{
detection​:
{
jobId​:
"297kj4ncqi83tqis1ovidam508le41tg1n59u2j72ls0ovlql4sb5ae0hs
ih3jl9"​,
assetType​: ​"POST"​,
originalAsset​: ​"me3.jpg" ​,
storeAssetURL​:
"​https://s3.eu-central-1.amazonaws.com/visagecloud-ops-xd31
vmo8gohlm8zjaexj/rf5kq9l0ini9kdm9h0otggpfud1oe4dd6lmimvo8t2
b2a150/297kj4ncqi83tqis1ovidam508le41tg1n59u2j72ls0ovlql4sb
5ae0hsih3jl9 ​"​,
scaling​: ​1​,
faces​:
[
{
index​: ​0​,
hash​:
"efd48a9c6cc44f65693cec1bdb81ecedd5
fdc394841fa3249fd966f39672abe0" ​,
viewType​: ​"FRONTAL" ​,
keypoints​:
{},
features​:
[],
boundingBox​:
{},
pose​:
{},
attributes​:
{}
}
],
time​: ​1354​,
timestamp​: ​1488014598247 ​,
debugInfo​: ​""
}
}

6.
}
Step #4: Add each detected face to a profile
This associates a particular face instance detected from a photo to an existing profile. It’s like telling
VisageCloud “Hey, this is Norah Jones” and “And this is Julianne Moore”.
Perform a POST call to /profile/map
cURL command
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d
'faceHash=AAAAA&accessKey=XXXXXX&secretKey=YYYYYYYY&collectionId=ZZZZZZ&profileId=
BBBBBB&=' "​https://visagecloud.com/rest/v1.1/profile/map​"
Step #5: Perform the face recognition
After you have created a few profiles and mapped one or several faceHashes to each of them, it’s
time to test the recognition service. This means you can give a new image to VisageCloud and it will
tell you who that person looks like most.
In order to do this, you must also specify the collection you want VisageCloud to look into by
collectionId.
You can achieve this by copy-pasting the code below in a web page and loading it in a browser.
<​form ​action=​"https://visagecloud.com/rest/v1.1/analysis/recognition"
method=​"POST" ​enctype=​"multipart/form-data"​>

7.
​<​input ​type=​"file" ​name=​"picture"​/>
​<​input ​type=​"hidden" ​name=​"collectionId" ​value=​"insert-collection-id-here"​>
​<​input ​type=​"hidden" ​name=​"accessKey" ​value=​"insert-accesKey-here"​>
​<​input ​type=​"hidden" ​name=​"secretKey"
​value=​"insert-readOnlyKey-here"​>
​<​input ​type=​"submit"​/>
</​form​>
Alternatively, you can use cURL to indicate a pictureURL, which VisageCloud will download.
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -H "Cache-Control: no-cache"
-H "Postman-Token: 77cb58f0-6715-b3b1-87b1-db8e0e74c9b5" -d
'collectionId=ZZZZZ&accessKey=XXXXX&secretKey=YYYYY&pictureURL=https://scontent-fra3-1.xx
.fbcdn.net/v/t1.0-9/14732386_10210111301966375_1358646233657322761_n.jpg?oh%3Dc1b9227f
d53b5b8fc24ed681712c2ddf%26oe%3D59360B49'
"https://visagecloud.com/rest/v1.1/analysis/recognition"
You will notice in the JSON response will contain an additional element called “recognition”. In the
“comparison” sub-object you will notice that for each faceHash detected you will have an array of
matches, ordered from highest matchRate (lowest distance) to lowest matchRate (highest distance).
By default, the API returns the first 10 matches, so as not overload you with unnecessary data.
recognition​:
{
jobId​:
"uvc08kmku3svc7m6d1366gc6hoo15roi3mgdpbruauo7epla50rjvpo8jencbhoc"​,
comparison​:
{
6814d5ab8ea1e8d030d8196b3408d7abe4fe4c6d4e3b6e45bcb
54210ac3c82ac​:
[
{
id​:
"9jjnabivlhumjfnjbl0hnc9f942c4qhnassalld8ser
94bs4vip8h8f4lc31d72d"​,
screenName​: ​"Sudhhy Kopa"​,
externalId​: ​"sudhhy-kopa"​,
collection​:
"tud186o53iunku2rs269d390k5f96jk3jm35g5v
d097f6vj6qrkgop1s8893fucq"​,
labels​: [ ],
distance​: ​0.6123357934120521​,
matchRate​: ​0.4771970479055374​,
attributes​:
{
gender​:

8.
{
name​: ​"gender"​,
value​: ​"male"​,
confidence​:
0.9926260233039899
},
ageGroup​:
{
name​: ​"ageGroup"​,
value​: ​"20-32"​,
confidence​:
0.6116148617757478
}
}
},
{},
{},
{},
{},
{},
{},
{},
{},
{}
]
},
Of course, you can build more complex setups by leveraging labels or attribute filtering. Adding
profiles to collections and faces to profile may be an iterative process, which involves feedback from
your user or from your other data sources.
Feel free to ​contact us​ and describe your particular use case, so that we can advise on best
practices and make your integration fast, secure and seamless.