--- title: "POST /detect" method: POST path: "/detect" --- # POST /detect `POST /detect` Detect human faces in an image, return face rectangles, and optionally with faceIds, landmarks, and attributes.
* No image will be stored. Only the extracted face feature will be stored on server. The faceId is an identifier of the face feature and will be used in [Face - Identify](https://docs.microsoft.com/rest/api/faceapi/face/identify), [Face - Verify](https://docs.microsoft.com/rest/api/faceapi/face/verifyfacetoface), and [Face - Find Similar](https://docs.microsoft.com/rest/api/faceapi/face/findsimilar). The stored face feature(s) 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 age, gender, headPose, smile, facialHair, glasses, emotion, hair, makeup, 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. * 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 [Face - Identify](https://docs.microsoft.com/rest/api/faceapi/face/identify), [Face - Verify](https://docs.microsoft.com/rest/api/faceapi/face/verifyfacetoface), and [Face - Find Similar](https://docs.microsoft.com/rest/api/faceapi/face/findsimilar) ('returnFaceId' is true), please use faces that are: frontal, clear, and with a minimum size of 200x200 pixels (100 pixels between eyes). * 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. * Different 'detectionModel' values can be provided. To use and compare different detection models, please refer to [How to specify a detection model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/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 [Specify a recognition model](https://docs.microsoft.com/azure/cognitive-services/face/face-api-how-to-topics/specify-recognition-model). ## Query parameters - `returnFaceId` boolean - `returnFaceLandmarks` boolean - `returnFaceAttributes` string[] - `recognitionModel` 'recognition_01' | 'recognition_02' | 'recognition_03' | 'recognition_04' - `returnRecognitionModel` boolean - `detectionModel` 'detection_01' | 'detection_02' | 'detection_03' - `faceIdTimeToLive` integer ## Parameters - `../../../Common/Parameters.json#/components/parameters/ImageUrl` — unresolved $ref ## 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. - DetectedFace[] - `faceId` string, uuid - `recognitionModel` 'recognition_01' | 'recognition_02' | 'recognition_03' | 'recognition_04' — Name of recognition model. Recognition model is used when the face features are extracted and associated with detected faceIds, (Large)FaceList or (Large)PersonGroup. A recognition model name can be provided when performing Face - Detect or (Large)FaceList - Create or (Large)PersonGroup - Create. The default value is 'recognition_01', if latest model needed, please explicitly specify the model you need. - `faceRectangle` FaceRectangle, required — A rectangle within which a face can be found - `width` integer, required — The width of the rectangle, in pixels. - `height` integer, required — The height 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. - `top` integer, required — The distance from the top edge if the image to the top edge of the rectangle, in pixels. - `faceLandmarks` FaceLandmarks — A collection of 27-point face landmarks pointing to the important positions of face components. - `pupilLeft` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `pupilRight` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `noseTip` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `mouthLeft` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `mouthRight` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `eyebrowLeftOuter` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `eyebrowLeftInner` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `eyeLeftOuter` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `eyeLeftTop` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `eyeLeftBottom` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `eyeLeftInner` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `eyebrowRightInner` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `eyebrowRightOuter` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `eyeRightInner` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `eyeRightTop` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `eyeRightBottom` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `eyeRightOuter` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `noseRootLeft` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `noseRootRight` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `noseLeftAlarTop` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `noseRightAlarTop` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `noseLeftAlarOutTip` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `noseRightAlarOutTip` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `upperLipTop` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `upperLipBottom` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `underLipTop` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `underLipBottom` Coordinate — Coordinates within an image - `x` number, required — The horizontal component, in pixels. - `y` number, required — The vertical component, in pixels. - `faceAttributes` FaceAttributes — Face Attributes - `age` number — Age in years - `gender` 'male' | 'female' — Possible gender of the face. - `smile` number — A number ranging from 0 to 1 indicating the intensity level associated with a property. - `facialHair` FacialHair — Properties describing facial hair attributes. - `moustache` number — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `beard` number — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `sideburns` number — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `glasses` 'noGlasses' | 'readingGlasses' | 'sunglasses' | 'swimmingGoggles' — Glasses type if any of the face. - `headPose` HeadPose — Properties indicating head pose of the face. - `roll` number - `yaw` number - `pitch` number - `emotion` Emotion — Properties describing facial emotion in form of confidence ranging from 0 to 1. - `anger` number — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `contempt` number — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `disgust` number — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `fear` number — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `happiness` number — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `neutral` number — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `sadness` number — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `surprise` number — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `hair` Hair — Properties describing hair attributes. - `bald` number — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `invisible` boolean — A boolean value describing whether the hair is visible in the image. - `hairColor` HairColor[] - `color` 'unknown' | 'white' | 'gray' | 'blond' | 'brown' | 'red' | 'black' | 'other' — Name of the hair color. - `confidence` number — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `makeup` Makeup — Properties describing the presence of makeup on a given face. - `eyeMakeup` boolean — A boolean value describing whether eye makeup is present on a face. - `lipMakeup` boolean — A boolean value describing whether lip makeup is present on a face. - `occlusion` Occlusion — Properties describing occlusions on a given face. - `foreheadOccluded` boolean — A boolean value indicating whether forehead is occluded. - `eyeOccluded` boolean — A boolean value indicating whether eyes are occluded. - `mouthOccluded` boolean — A boolean value indicating whether the mouth is occluded. - `accessories` Accessory[] — Properties describing any accessories on a given face. - `type` 'headWear' | 'glasses' | 'mask' — Type of an accessory - `confidence` number — A number ranging from 0 to 1 indicating a level of confidence associated with a property. - `blur` Blur — Properties describing any presence of blur within the image. - `blurLevel` 'Low' | 'Medium' | 'High' — An enum value indicating level of blurriness. - `value` number — A number ranging from 0 to 1 indicating the intensity level associated with a property. - `exposure` Exposure — Properties describing exposure level of the image. - `exposureLevel` 'UnderExposure' | 'GoodExposure' | 'OverExposure' — An enum value indicating level of exposure. - `value` number — A number ranging from 0 to 1 indicating the intensity level associated with a property. - `noise` Noise — Properties describing noise level of the image. - `noiseLevel` 'Low' | 'Medium' | 'High' — An enum value indicating level of noise. - `value` number — A number ranging from 0 to 1 indicating the intensity level associated with a property. - `mask` Mask — Properties describing the presence of a mask on a given face. - `type` 'noMask' | 'faceMask' | 'otherMaskOrOcclusion' | 'uncertain' — Mask type if any of the face - `noseAndMouthCovered` boolean — A boolean value indicating whether nose and mouth are covered. - `qualityForRecognition` 'Low' | 'Medium' | 'High' — Properties describing the overall image quality regarding whether the image being used in the detection is of sufficient quality to attempt face recognition on. ## Other responses - `default` — Error response. --- [API](https://skmtc.net/azure/apis/cognitiveservices-face.md) · [All operations](https://skmtc.net/azure/apis/cognitiveservices-face/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/azure/cognitiveservices-face/revisions/106051bfd7b7/schema)