Face API Reference

The Azure Face API is a cognitive service that provides advanced algorithms for detecting, recognizing, and analyzing human faces in images.

API Endpoints

GET /face/v1.0/detect

Detect Faces

Detect faces in an image and return information about them. This includes face ID, bounding box, and attributes like age, gender, emotion, and more.

Query Parameters

Name Type Description Required
returnFaceId Boolean Whether to return the faceId of each face. No
returnFaceLandmarks Boolean Whether to return face landmarks of each face. No
returnFaceAttributes String Analysis attributes (e.g., "age,gender,emotion,hair,makeup,occlusion,accessories,blur,exposure,noise,mask"). No
recognitionModel String The name of the recognition model to use. Options include "recognition_01", "recognition_02", "recognition_03", "recognition_04". No
returnRecognitionModel Boolean Whether to return the recognition model name. No
detectionModel String The name of the detection model to use. Options include "detection_01", "detection_02", "detection_03". No
returnDetectionModel Boolean Whether to return the detection model name. No

Request Body

application/json


{
  "url": "http://example.com/image.jpg"
}

or an image binary stream.

Responses

Code Description Schema
200 OK Successfully detected faces. [DetectedFace]
400 Bad Request Invalid request. ErrorResponse
401 Unauthorized Authentication failed. ErrorResponse

Example Request (URL)


curl -X POST "https://your-cognitive-services-endpoint.cognitiveservices.azure.com/face/v1.0/detect?returnFaceId=true&returnFaceAttributes=age,gender" \
-H "Content-Type: application/json" \
-H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
--data-urlencode '{"url": "https://raw.githubusercontent.com/MicrosoftLearning/Face-API-Get-Started/master/PersonnelTracker/Data/image1.jpg"}'

Example Response


[
  {
    "faceId": "d00b1c13-85a1-4f9f-9a4c-70018f290c47",
    "faceRectangle": {
      "top": 108,
      "left": 161,
      "width": 147,
      "height": 157
    },
    "faceAttributes": {
      "gender": "female",
      "age": 30.0,
      "emotion": {
        "anger": 0.0,
        "contempt": 0.0,
        "disgust": 0.0,
        "fear": 0.0,
        "neutral": 0.98,
        "sadness": 0.0,
        "surprise": 0.02,
        "happiness": 0.0
      }
    }
  }
]
POST /face/v1.0/findsimilars

Find Similar Faces

Find faces that are similar to the target face from a person group or a large person group.

Query Parameters

Name Type Description Required
faceId String The faceId of the face to find similar faces for. Yes
mode String 'matchPerson' to find faces belonging to the same person. 'matchFace' to find faces with similar features. No (Defaults to 'matchPerson')
personGroupId String Specifies a person group or large person group to search within. Yes, if mode is 'matchPerson'
largePersonGroupId String Specifies a large person group to search within. Yes, if mode is 'matchPerson'
maxNumOfCandidatesReturned Integer The maximum number of similar faces to return. No (Defaults to 10)
confidenceThreshold Float Specifies the similarity confidence threshold for the search. No

Request Body

application/json


{
  "faceId": "d00b1c13-85a1-4f9f-9a4c-70018f290c47",
  "mode": "matchPerson",
  "personGroupId": "your_person_group_id",
  "maxNumOfCandidatesReturned": 5,
  "confidenceThreshold": 0.5
}

Responses

Code Description Schema
200 OK Successfully found similar faces. [SimilarFace]
400 Bad Request Invalid request. ErrorResponse
401 Unauthorized Authentication failed. ErrorResponse
POST /face/v1.0/verify

Verify Faces

Verify whether two faces belong to the same person or whether one face belongs to a person.

Request Body

application/json


{
  "faceId1": "d00b1c13-85a1-4f9f-9a4c-70018f290c47",
  "faceId2": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}

Or


{
  "faceId": "d00b1c13-85a1-4f9f-9a4c-70018f290c47",
  "personGroupId": "your_person_group_id",
  "personId": "your_person_id"
}

Responses

Code Description Schema
200 OK Successfully verified faces. { "isIdentical": true/false, "confidence": float }
400 Bad Request Invalid request. ErrorResponse
401 Unauthorized Authentication failed. ErrorResponse

Common Data Types

DetectedFace

Represents a detected face in an image.


{
  "faceId": "string",
  "faceRectangle": {
    "top": "integer",
    "left": "integer",
    "width": "integer",
    "height": "integer"
  },
  "faceLandmarks": {
    "pupilLeftEyeX": "number",
    "pupilLeftEyeY": "number",
    "pupilRightEyeX": "number",
    "pupilRightEyeY": "number",
    "noseTipX": "number",
    "noseTipY": "number",
    // ... other landmarks
  },
  "faceAttributes": {
    // Details about attributes like gender, age, emotion, etc.
  },
  "recognitionModel": "string",
  "detectionModel": "string"
}

ErrorResponse

Represents an error returned by the API.


{
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      // Array of error details
    ],
    "target": "string"
  }
}