Face Recognition with Azure Cognitive Services Face API


In this post we will build a face recognition system for verifying individuals in images. For this, we will be using the Azure Cognitive Services Face API and a few simple lines of Python code.
The Face API in Azure allows you to easily detect faces in images and extract facial landmarks such as the position of eyes, mouth, nose, and many more. Furthermore, you can use it to re-identify previously trained persons in images.

Getting started

First, we need to create subscription key in Azure Portal. In this example, we’ll be using the West US region, as this is the default for the free tier.
Nexy, install the Python library via pip:
$ pip install cognitive_face
Alternatively, you can directly call the RESTful API via requests.
Connecting to the Face API Service is straight forward, just specify the endpoint URL (we’ll be using West US), and the subscription key which you created in the Azure portal.
import cognitive_face as CF
BASE_URL = 'https://westus.api.cognitive.microsoft.com/face/v1.0/'
PERSON_GROUP_ID = 'known-persons'

Learning new faces

The Face API uses the concept of person groups and persons:
  • A person group contains zero or more persons and is referred to by a person_group_id
  • A person is identified by a person_id and has a name and some custom user data
  • A person has zero or more face images associated to it
Let’s start by creating a new person group where we store the faces we want to verify later:
CF.person_group.create(PERSON_GROUP_ID, 'Known Persons')
Next, let’s add a new person with some optional user data to it:
name = "Clemens Siebler"
user_data = 'More information can go here'
response = CF.person.create(PERSON_GROUP_ID, name, user_data)

# Get person_id from response
person_id = response['personId']
Now we can start adding face images to the person for training our system:
CF.person.add_face('clemens.jpg', PERSON_GROUP_ID, person_id)
Training image
Training image

In this case, we assume that the image only contains one face. If there are multiple faces, you can specify the target_face parameter via add_face(image, person_group_id, person_id, user_data=None, target_face=None).

We can list all persons in our person group quickly:
print CF.person.lists(PERSON_GROUP_ID)
As we can see, our person has been successfully persisted, including the face image we uploaded:
As we added a new face to our person group, we need to re-train our model:
As training is running asynchronously and thus not might happen immediately, we need to check the status to make sure it has completed:
response = CF.person_group.get_status(PERSON_GROUP_ID)
status = response['status']
Once successfully trained, we get the following response:
  u'status': u'succeeded',
  u'createdDateTime': u'2/15/201811:56:43AM',
  u'message': None,
  u'lastActionDateTime': u'2/15/201811:56:43AM'
Training should take less than a second in our example, but obviously might take a longer when the person group includes many persons and images.

Verification of faces

Verification Image
Verification Image
Lasty, we can pass in a new image with one more faces in it and check if we can identify any of our perviously registered faces:
response = CF.face.detect('test.jpg')
face_ids = [d['faceId'] for d in response]
print face_ids

identified_faces = CF.face.identify(face_ids, PERSON_GROUP_ID)
print identified_faces
As we can see, Face API didn’t find any candidates for the first left face, but found a match with 73% confidence for the second face:
Let’s visualize the result:
Test recognition result
Test recognition result
When using Face API, it is important to understand the difference between face_id and persisted_face_id:
  • Generated for each detected face in an image by using the face.detect() call
  • Persisted within the API subscription scope for 24 hours
  • Generated when adding face images to a person_id via the person.add_face() call
  • Persisted within the API subscription scope until manually deleted


With the Azure Cognitive Services Face API we can easily build a system for recognizing previously trained persons. We have achieved this by:
  1. Creating a person_group
  2. Adding one or more persons to it
  3. Adding one or more face images that belong to each person
  4. Training the person_group
  5. Verifying new faces against the known persons
If you have any questions, feel free to reach out to me on Twitter @clemenssiebler. Thanks to @kaparora for the images.

Leave a Reply

Your email address will not be published. Required fields are marked *