Find similar faces


Face service access is limited based on eligibility and usage criteria in order to support our Responsible AI principles. Face service is only available to Microsoft managed customers and partners. Use the Face Recognition intake form to apply for access. For more information, see the Face limited access page.

The Find Similar operation does face matching between a target face and a set of candidate faces, finding a smaller set of faces that look similar to the target face. This is useful for doing a face search by image.

This guide demonstrates how to use the Find Similar feature in the different language SDKs. The following sample code assumes you have already authenticated a Face client object. For details on how to do this, follow a quickstart.

Set up sample URL

This guide uses remote images that are accessed by URL. Save a reference to the following URL string. All of the images accessed in this guide are located at this URL path.

Detect faces for comparison

You need to detect faces in images before you can compare them. In this guide, the following remote image, called findsimilar.jpg, will be used as the source:

Photo of a man who is smiling.

The following face detection method is optimized for comparison operations. It doesn't extract detailed face attributes, and it uses an optimized recognition model.

private static async Task<List<DetectedFace>> DetectFaceRecognize(IFaceClient faceClient, string url, string recognition_model)
    // Detect faces from image URL. Since only recognizing, use the recognition model 1.
    // We use detection model 3 because we are not retrieving attributes.
    IList<DetectedFace> detectedFaces = await faceClient.Face.DetectWithUrlAsync(url, returnFaceId: true, recognitionModel: recognition_model, detectionModel: DetectionModel.Detection03, FaceAttributes: new List<FaceAttributeType> { FaceAttributeType.QualityForRecognition });
    List<DetectedFace> sufficientQualityFaces = new List<DetectedFace>();
    foreach (DetectedFace detectedFace in detectedFaces){
        var faceQualityForRecognition = detectedFace.FaceAttributes.QualityForRecognition;
        if (faceQualityForRecognition.HasValue && (faceQualityForRecognition.Value >= QualityForRecognition.Medium)){
    Console.WriteLine($"{detectedFaces.Count} face(s) with {sufficientQualityFaces.Count} having sufficient quality for recognition detected from image `{Path.GetFileName(url)}`");

    return sufficientQualityFaces.ToList();

The following code uses the above method to get face data from a series of images.

Console.WriteLine("========FIND SIMILAR========");

List<string> targetImageFileNames = new List<string>

string sourceImageFileName = "findsimilar.jpg";
IList<Guid?> targetFaceIds = new List<Guid?>();
foreach (var targetImageFileName in targetImageFileNames)
    // Detect faces from target image url.
    var faces = await DetectFaceRecognize(client, $"{base_url}{targetImageFileName}", recognition_model);
    // Add detected faceId to list of GUIDs.

// Detect faces from source image url.
IList<DetectedFace> detectedFaces = await DetectFaceRecognize(client, $"{base_url}{sourceImageFileName}", recognition_model);

Find and print matches

In this guide, the face detected in the Family1-Dad1.jpg image should be returned as the face that's similar to the source image face.

Photo of a man who is smiling; this is the same person as the previous image.

The following code calls the Find Similar API on the saved list of faces.

// Find a similar face(s) in the list of IDs. Comapring only the first in list for testing purposes.
IList<SimilarFace> similarResults = await client.Face.FindSimilarAsync(detectedFaces[0].FaceId.Value, null, null, targetFaceIds);

The following code prints the match details to the console:

foreach (var similarResult in similarResults)
    Console.WriteLine($"Faces from {sourceImageFileName} & ID:{similarResult.FaceId} are similar with confidence: {similarResult.Confidence}.");

Next steps

In this guide, you learned how to call the Find Similar API to do a face search by similarity in a larger group of faces. Next, learn more about the different recognition models available for face comparison operations.