Quickstart: Detect faces in an image using cURL

In this quickstart, you detect faces in an image using Face API.


You need a subscription key to run the sample. You can get free trial subscription keys from Try Cognitive Services.

Detect faces in an image

Use the Face - Detect method to detect faces in an image and return face attributes including:

  • Face ID: Unique ID used in several Face API scenarios.
  • Face Rectangle: The left, top, width, and height indicating the location of the face in the image.
  • Landmarks: An array of 27-point face landmarks pointing to the important positions of face components.
  • Facial attributes including age, gender, smile intensity, head pose, and facial hair.

To run the sample, do the following steps:

  1. Open a Command Prompt.
  2. Replace <Subscription Key> with your valid subscription key.
  3. Change the URL (https://westcentralus.api.cognitive.microsoft.com/face/v1.0/detect) to use the location where you obtained your subscription keys, if necessary.
  4. Optionally, change the image ("{\"url\":...) to analyze.
  5. Paste the code in the command window.
  6. Run the command.

Face - Detect request


You must use the same location in your REST call as you used to obtain your subscription keys. For example, if you obtained your subscription keys from westus, replace "westcentralus" in the following URL with "westus".

curl -H "Ocp-Apim-Subscription-Key: <Subscription Key>" "https://westcentralus.api.cognitive.microsoft.com/face/v1.0/detect?returnFaceId=true&returnFaceLandmarks=false&returnFaceAttributes=age,gender,headPose,smile,facialHair,glasses,emotion,hair,makeup,occlusion,accessories,blur,exposure,noise" -H "Content-Type: application/json" --data-ascii "{\"url\":\"https://upload.wikimedia.org/wikipedia/commons/c/c3/RH_Louise_Lillian_Gish.jpg\"}"

Face - Detect response

A successful response is returned in JSON.

    "faceId": "49d55c17-e018-4a42-ba7b-8cbbdfae7c6f",
    "faceRectangle": {
      "top": 131,
      "left": 177,
      "width": 162,
      "height": 162
    "faceAttributes": {
      "smile": 0,
      "headPose": {
        "pitch": 0,
        "roll": 0.1,
        "yaw": -32.9
      "gender": "female",
      "age": 22.9,
      "facialHair": {
        "moustache": 0,
        "beard": 0,
        "sideburns": 0
      "glasses": "NoGlasses",
      "emotion": {
        "anger": 0,
        "contempt": 0,
        "disgust": 0,
        "fear": 0,
        "happiness": 0,
        "neutral": 0.986,
        "sadness": 0.009,
        "surprise": 0.005
      "blur": {
        "blurLevel": "low",
        "value": 0.06
      "exposure": {
        "exposureLevel": "goodExposure",
        "value": 0.67
      "noise": {
        "noiseLevel": "low",
        "value": 0
      "makeup": {
        "eyeMakeup": true,
        "lipMakeup": true
      "accessories": [],
      "occlusion": {
        "foreheadOccluded": false,
        "eyeOccluded": false,
        "mouthOccluded": false
      "hair": {
        "bald": 0,
        "invisible": false,
        "hairColor": [
            "color": "brown",
            "confidence": 1
            "color": "black",
            "confidence": 0.87
            "color": "other",
            "confidence": 0.51
            "color": "blond",
            "confidence": 0.08
            "color": "red",
            "confidence": 0.08
            "color": "gray",
            "confidence": 0.02

Next steps

Explore the Face APIs used to detect human faces in an image, demarcate the faces with rectangles, and return attributes such as age and gender.