Microsoft Face

The microsoft_face integration integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] is the main integration for Microsoft Azure Cognitive service Face. All data are stored in your own private instance in the Azure cloud.

Setup

You need an API key, which is free, but requires an Azure registration using your Microsoft ID. The free resource (F0) is limited to 20 requests per minute and 30k requests in a month. If you don’t want to use the Azure cloud, you can also get an API key by registering with cognitive-services. Please note that all keys on cognitive services must be recreated every 90 days.

Configuration

To enable the Microsoft Face integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more], add the following to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:

# Example configuration.yaml entry
microsoft_face:
  api_key: YOUR_API_KEY
  azure_region: eastus2

Person and Groups

For most services, you need to set up a group or a person. This limits the processing and detection to elements provided by the group. Home Assistant creates an entity for all groups and allows you to show the state, person, and IDs directly on the frontend.

The following actions are available for managing this feature and can be called via the Frontend, a script, or the REST API.

• microsoft_face.create_group
• microsoft_face.delete_group

action: microsoft_face.create_group
data:
  name: "Family"

• microsoft_face.create_person
• microsoft_face.delete_person

action: microsoft_face.create_person
data:
  group: family
  name: "Hans Maier"

You need to add an image of a person. You can add multiple images for every person to make the detection better. You can take a picture from a camera or send a local image to your Azure resource.

• microsoft_face.face_person

action: microsoft_face.face_person
data:
  group: family
  name: "Hans Maier"
  camera_entity: camera.door

For the local image we need curl. The {personId} is present in group entity as attribute.

$ curl -v -X POST "https://westus.api.cognitive.microsoft.com/face/v1.0/persongroups/{GroupName}/persons/{personId}/persistedFaces" \
  -H "Ocp-Apim-Subscription-Key: YOUR_API_KEY" \
  -H "Content-Type: application/octet-stream" --data-binary "@/tmp/image.jpg"

After we’re done with changes on a group, we need train this group to teach the AI how to handle the new data.

• microsoft_face.train_group

action: microsoft_face.train_group
data:
  group: family