--- title: "Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes." method: POST path: "/detect" --- # Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes. `POST /detect` > [!IMPORTANT] > Microsoft has retired or limited facial recognition capabilities that can be used to try to infer emotional states and identity attributes which, if misused, can subject people to stereotyping, discrimination or unfair denial of services. The retired capabilities are emotion and gender. The limited capabilities are age, smile, facial hair, hair and makeup. Email [Azure Face API](mailto:azureface@microsoft.com) if you have a responsible use case that would benefit from the use of any of the limited capabilities. Read more about this decision [here](https://azure.microsoft.com/blog/responsible-ai-investments-and-safeguards-for-facial-recognition/). * * No image will be stored. Only the extracted face feature(s) will be stored on server. The faceId is an identifier of the face feature and will be used in "Identify", "Verify", and "Find Similar". The stored face features will expire and be deleted at the time specified by faceIdTimeToLive after the original detection call. * Optional parameters include faceId, landmarks, and attributes. Attributes include headPose, glasses, occlusion, accessories, blur, exposure, noise, mask, and qualityForRecognition. Some of the results returned for specific attributes may not be highly accurate. * JPEG, PNG, GIF (the first frame), and BMP format are supported. The allowed image file size is from 1KB to 6MB. * The minimum detectable face size is 36x36 pixels in an image no larger than 1920x1080 pixels. Images with dimensions higher than 1920x1080 pixels will need a proportionally larger minimum face size. * Up to 100 faces can be returned for an image. Faces are ranked by face rectangle size from large to small. * For optimal results when querying "Identify", "Verify", and "Find Similar" ('returnFaceId' is true), please use faces that are: frontal, clear, and with a minimum size of 200x200 pixels (100 pixels between eyes). * Different 'detectionModel' values can be provided. The availability of landmarks and supported attributes depends on the detection model specified. To use and compare different detection models, please refer to [here](https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-detection-model). * Different 'recognitionModel' values are provided. If follow-up operations like "Verify", "Identify", "Find Similar" are needed, please specify the recognition model with 'recognitionModel' parameter. The default value for 'recognitionModel' is 'recognition_01', if latest model needed, please explicitly specify the model you need in this parameter. Once specified, the detected faceIds will be associated with the specified recognition model. More details, please refer to [here](https://learn.microsoft.com/azure/ai-services/computer-vision/how-to/specify-recognition-model). ## Query parameters - `detectionModel` 'detection_01' | 'detection_02' | 'detection_03' - `recognitionModel` 'recognition_01' | 'recognition_02' | 'recognition_03' | 'recognition_04' - `returnFaceId` boolean - `returnFaceAttributes` string[] - `returnFaceLandmarks` boolean - `returnRecognitionModel` boolean - `faceIdTimeToLive` integer ## Request body - object - `url` string, uri, required — URL of input image. ## Response `200` A successful call returns an array of face entries ranked by face rectangle size in descending order. An empty response indicates no faces detected. - FaceDetectionResult[] - `faceId` string, uuid — Universally Unique Identifier - `recognitionModel` 'recognition_01' | 'recognition_02' | 'recognition_03' | 'recognition_04' — The recognition model for the face. - `faceRectangle` FaceRectangle, required — A rectangle within which a face can be found. - `top` integer, required — The distance from the top edge if the image to the top edge of the rectangle, in pixels. - `left` integer, required — The distance from the left edge if the image to the left edge of the rectangle, in pixels. - `width` integer, required — The width of the rectangle, in pixels. - `height` integer, required — The height of the rectangle, in pixels. - `faceLandmarks` FaceLandmarks — A collection of 27-point face landmarks pointing to the important positions of face components. - `pupilLeft` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `pupilRight` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `noseTip` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `mouthLeft` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `mouthRight` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `eyebrowLeftOuter` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `eyebrowLeftInner` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `eyeLeftOuter` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `eyeLeftTop` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `eyeLeftBottom` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `eyeLeftInner` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `eyebrowRightInner` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `eyebrowRightOuter` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `eyeRightInner` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `eyeRightTop` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `eyeRightBottom` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `eyeRightOuter` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `noseRootLeft` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `noseRootRight` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `noseLeftAlarTop` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `noseRightAlarTop` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `noseLeftAlarOutTip` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `noseRightAlarOutTip` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `upperLipTop` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `upperLipBottom` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `underLipTop` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `underLipBottom` LandmarkCoordinate, required — Landmark coordinates within an image. - `x` number, float, required — The horizontal component, in pixels. - `y` number, float, required — The vertical component, in pixels. - `faceAttributes` FaceAttributes — Face attributes for the detected face. - `age` number, float — Age in years. - `smile` number, float — Smile intensity, a number between [0,1]. - `facialHair` FacialHair — Properties describing facial hair attributes. - `moustache` number, float, required — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `beard` number, float, required — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `sideburns` number, float, required — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `glasses` 'noGlasses' | 'readingGlasses' | 'sunglasses' | 'swimmingGoggles' — Glasses type of the face. - `headPose` HeadPose — 3-D roll/yaw/pitch angles for face direction. - `pitch` number, float, required — Value of angles. - `roll` number, float, required — Value of angles. - `yaw` number, float, required — Value of angles. - `hair` HairProperties — Properties describing hair attributes. - `bald` number, float, required — A number describing confidence level of whether the person is bald. - `invisible` boolean, required — A boolean value describing whether the hair is visible in the image. - `hairColor` HairColor[], required — An array of candidate colors and confidence level in the presence of each. - `color` 'unknown' | 'white' | 'gray' | 'blond' | 'brown' | 'red' | 'black' | 'other', required — Name of the hair color. - `confidence` number, float, required — Confidence level of the color. Range between [0,1]. - `occlusion` OcclusionProperties — Properties describing occlusions on a given face. - `foreheadOccluded` boolean, required — A boolean value indicating whether forehead is occluded. - `eyeOccluded` boolean, required — A boolean value indicating whether eyes are occluded. - `mouthOccluded` boolean, required — A boolean value indicating whether the mouth is occluded. - `accessories` AccessoryItem[] — Properties describing any accessories on a given face. - `type` 'headwear' | 'glasses' | 'mask', required — Type of the accessory. - `confidence` number, float, required — Confidence level of the accessory type. Range between [0,1]. - `blur` BlurProperties — Properties describing any presence of blur within the image. - `blurLevel` 'low' | 'medium' | 'high', required — Indicates level of blurriness. - `value` number, float, required — A number indicating level of blurriness ranging from 0 to 1. - `exposure` ExposureProperties — Properties describing exposure level of the image. - `exposureLevel` 'underExposure' | 'goodExposure' | 'overExposure', required — Indicates level of exposure. - `value` number, float, required — A number indicating level of exposure level ranging from 0 to 1. [0, 0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is over exposure. - `noise` NoiseProperties — Properties describing noise level of the image. - `noiseLevel` 'low' | 'medium' | 'high', required — Indicates level of noise. - `value` number, float, required — A number indicating level of noise level ranging from 0 to 1. [0, 0.25) is under exposure. [0.25, 0.75) is good exposure. [0.75, 1] is over exposure. [0, 0.3) is low noise level. [0.3, 0.7) is medium noise level. [0.7, 1] is high noise level. - `mask` MaskProperties — Properties describing the presence of a mask on a given face. - `noseAndMouthCovered` boolean, required — A boolean value indicating whether nose and mouth are covered. - `type` 'faceMask' | 'noMask' | 'otherMaskOrOcclusion' | 'uncertain', required — Type of the mask. - `qualityForRecognition` 'low' | 'medium' | 'high' — Indicates quality of image for recognition. ## Other responses - `default` — An unexpected error response. --- [API](https://skmtc.net/azure/apis/ai-face.md) · [All operations](https://skmtc.net/azure/apis/ai-face/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/azure/ai-face/versions/e9a68c525be6/schema)