Tutorial: Detect and frame faces with the Face API and Python

In this tutorial, you will learn to invoke the Face API via the Python SDK to detect human faces in an image.


To use the tutorial, you will need to do the following:

  • Install either Python 2.7+ or Python 3.5+.
  • Install pip.
  • Install the Python SDK for the Face API as follows:
pip install cognitive_face
  • Obtain a subscription key for Microsoft Cognitive Services. You can use either your primary or your secondary key in this tutorial. (Note that to use any Face API, you must have a valid subscription key.)

Detect a Face in an Image

import cognitive_face as CF

KEY = '<Subscription Key>'  # Replace with a valid subscription key (keeping the quotes in place).

BASE_URL = 'https://westus.api.cognitive.microsoft.com/face/v1.0/'  # Replace with your regional Base URL

# You can use this example JPG or replace the URL below with your own URL to a JPEG image.
img_url = 'https://raw.githubusercontent.com/Microsoft/Cognitive-Face-Windows/master/Data/detection1.jpg'
faces = CF.face.detect(img_url)

Below is an example result. It's a list of detected faces. Each item in the list is a dict instance where faceId is a unique ID for the detected face and faceRectangle describes the position of the detected face. A face ID expires in 24 hours.

[{u'faceId': u'68a0f8cf-9dba-4a25-afb3-f9cdf57cca51', u'faceRectangle': {u'width': 89, u'top': 66, u'height': 89, u'left': 446}}]

Draw rectangles around the faces

Using the json coordinates that you received from the previous command, you can draw rectangles on the image to visually represent each face. You will need to pip install Pillow to use the PIL imaging module. At the top of the file, add the following:

import requests
from io import BytesIO
from PIL import Image, ImageDraw

Then, after print(faces), include the following in your script:

#Convert width height to a point in a rectangle
def getRectangle(faceDictionary):
    rect = faceDictionary['faceRectangle']
    left = rect['left']
    top = rect['top']
    bottom = left + rect['height']
    right = top + rect['width']
    return ((left, top), (bottom, right))

#Download the image from the url
response = requests.get(img_url)
img = Image.open(BytesIO(response.content))

#For each face returned use the face rectangle and draw a red box.
draw = ImageDraw.Draw(img)
for face in faces:
    draw.rectangle(getRectangle(face), outline='red')

#Display the image in the users default image browser.

Further Exploration

To help you further explore the Face API, this tutorial provides a GUI sample. To run it, first install wxPython then run the commands below.

git clone https://github.com/Microsoft/Cognitive-Face-Python.git
cd Cognitive-Face-Python
python sample


In this tutorial, you have learned the basic process for using the Face API via invoking the Python SDK. For more information on API details, please refer to the How-To and API Reference.