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

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.

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

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

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: "297kj4ncqi83tqis1ovidam508le41tg1n59u2j72ls0ovlql4sb5ae0hsih3jl9" , assetType: "POST" , originalAsset: "me3.jpg" , storeAssetURL: " https://s3.eu-central-1.amazonaws.com/visagecloud-ops-xd31vmo8gohlm8zjaexj/rf5kq9l0ini9kdm9h0otggpfud1oe4dd6lmimvo8t2b2a150/297kj4ncqi83tqis1ovidam508le41tg1n59u2j72ls0ovlql4sb5ae0hsih3jl9 " , scaling: 1 , faces: [

{ index: 0 , hash: "efd48a9c6cc44f65693cec1bdb81ecedd5fdc394841fa3249fd966f39672abe0" , viewType: "FRONTAL" , keypoints: {}, features: [], boundingBox: {}, pose: {}, attributes: {}

} ], time: 1354 , timestamp: 1488014598247 , debugInfo: ""

} }

}

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">

<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: {

6814d5ab8ea1e8d030d8196b3408d7abe4fe4c6d4e3b6e45bcb54210ac3c82ac: [

{ id: "9jjnabivlhumjfnjbl0hnc9f942c4qhnassalld8ser94bs4vip8h8f4lc31d72d", screenName: "Sudhhy Kopa", externalId: "sudhhy-kopa", collection: "tud186o53iunku2rs269d390k5f96jk3jm35g5vd097f6vj6qrkgop1s8893fucq", labels: [ ], distance: 0.6123357934120521, matchRate: 0.4771970479055374, attributes: {

gender:

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