Getting Started with Face API in Python Tutorial

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

# You can use this example JPG or replace the URL below with your own URL to a JPEG image.
img_url = ''
result = CF.face.detect(img_url)
print result

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 postion 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}}]

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