Faces - Compare

Service:

Azure AI Services

API Version:

2025-05-01-preview

Compare the similarity between two faces.

POST {endpoint}/contentunderstanding/faces:compare?api-version=2025-05-01-preview

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string (uri)	Content Understanding service endpoint.
api-version	query	True	string minLength: 1	The API version to use for this operation.

Request Header

Name	Required	Type	Description
x-ms-client-request-id		string (uuid)	An opaque, globally-unique, client-generated string identifier for the request.

Request Body

Name	Required	Type	Description
faceSource1	True	FaceSource	First face to compare.
faceSource2	True	FaceSource	Second face to compare.

Responses

Name	Type	Description
200 OK	CompareFacesResult	The request has succeeded.
Other Status Codes	Azure.Core.Foundations.ErrorResponse	An unexpected error response. Headers x-ms-error-code: string

Security

Ocp-Apim-Subscription-Key

Type: apiKey
In: header

OAuth2Auth

Type: oauth2
Flow: accessCode
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize
Token URL: https://login.microsoftonline.com/common/oauth2/token

Scopes

Name	Description
https://cognitiveservices.azure.com/.default

Examples

Compare the Similarity Between Two Faces

Sample request

HTTP

POST {endpoint}/contentunderstanding/faces:compare?api-version=2025-05-01-preview

{
  "faceSource1": {
    "url": "https://mystorageaccount.blob.core.windows.net/images/faces/face1.jpg",
    "targetBoundingBox": {
      "left": 33,
      "top": 73,
      "width": 262,
      "height": 324
    }
  },
  "faceSource2": {
    "data": "RXhhbXBsZSBGaWxl"
  }
}

Sample response

Status code:

200

{
  "detectedFace1": {
    "boundingBox": {
      "left": 33,
      "top": 73,
      "width": 262,
      "height": 324
    }
  },
  "detectedFace2": {
    "boundingBox": {
      "left": 87,
      "top": 96,
      "width": 235,
      "height": 345
    }
  },
  "confidence": 0.95
}

Definitions

Name	Description
Azure.Core.Foundations.Error	The error object.
Azure.Core.Foundations.ErrorResponse	A response containing error details.
Azure.Core.Foundations.InnerError	An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#handling-errors.
BoundingBox	Bounding box in an image.
CompareFacesParameters	Compare faces parameters.
CompareFacesResult	Compare faces response.
DetectedBoundingBox	Detected bounding box of an object.
FaceSource	Input face source with an optional target bounding box. If not specified, the largest face will be used.

Azure.Core.Foundations.Error

Object

The error object.

Name	Type	Description
code	string	One of a server-defined set of error codes.
details	Azure.Core.Foundations.Error[]	An array of details about specific errors that led to this reported error.
innererror	Azure.Core.Foundations.InnerError	An object containing more specific information than the current object about the error.
message	string	A human-readable representation of the error.
target	string	The target of the error.

Azure.Core.Foundations.ErrorResponse

Object

A response containing error details.

Name	Type	Description
error	Azure.Core.Foundations.Error	The error object.

Azure.Core.Foundations.InnerError

Object

An object containing more specific information about the error. As per Microsoft One API guidelines - https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#handling-errors.

Name	Type	Description
code	string	One of a server-defined set of error codes.
innererror	Azure.Core.Foundations.InnerError	Inner error.

BoundingBox

Object

Bounding box in an image.

Name	Type	Description
height	integer (int32)	Height of the bounding box.
left	integer (int32)	Left coordinate of the bounding box.
top	integer (int32)	Top coordinate of the bounding box.
width	integer (int32)	Width of the bounding box.

CompareFacesParameters

Object

Compare faces parameters.

Name	Type	Description
faceSource1	FaceSource	First face to compare.
faceSource2	FaceSource	Second face to compare.

CompareFacesResult

Object

Compare faces response.

Name	Type	Description
confidence	number (float)	Confidence score of the face comparison.
detectedFace1	DetectedBoundingBox	Details of the first detected face.
detectedFace2	DetectedBoundingBox	Details of the second detected face.

DetectedBoundingBox

Object

Detected bounding box of an object.

Name	Type	Description
boundingBox	BoundingBox	Bounding box of the detected face.

FaceSource

Object

Input face source with an optional target bounding box. If not specified, the largest face will be used.

Name	Type	Description
data	string (byte)	Base64-encoded image data. Only one of url or data should be specified.
imageReferenceId	string	User provided identifier for the source image.
targetBoundingBox	BoundingBox	Bounding box specifying the region of interest.
url	string (uri)	Image URL. Only one of url or data should be specified.