Quickstart: Detect faces in an image using Java

In this quickstart, you detect human faces in an image using the 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. Create a new command-line app in your favorite Java IDE.
  2. Replace the Main class with the following code (keep any package statements).
  3. Replace <Subscription Key> with your valid subscription key.
  4. Change the uriBase value to use the location where you obtained your subscription keys, if necessary.
  5. Download these global libraries from the Maven Repository to the lib directory in your project:
    • org.apache.httpcomponents:httpclient:4.2.4
    • org.json:json:20170516
  6. Run 'Main'.

Face - Detect request

// This sample uses Apache HttpComponents:
// http://hc.apache.org/httpcomponents-core-ga/httpcore/apidocs/
// https://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/

import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.DefaultHttpClient;
import org.apache.http.util.EntityUtils;
import org.json.JSONArray;
import org.json.JSONObject;

public class Main
    // Replace <Subscription Key> with your valid subscription key.
    private static final String subscriptionKey = "<Subscription Key>";

    // NOTE: You must use the same region 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 URL
    // below with "westus".
    // Free trial subscription keys are generated in the westcentralus region. If you
    // use a free trial subscription key, you shouldn't need to change this region.
    private static final String uriBase =

    private static final String imageWithFaces =

    private static final String faceAttributes =

    public static void main(String[] args)
        HttpClient httpclient = new DefaultHttpClient();

            URIBuilder builder = new URIBuilder(uriBase);

            // Request parameters. All of them are optional.
            builder.setParameter("returnFaceId", "true");
            builder.setParameter("returnFaceLandmarks", "false");
            builder.setParameter("returnFaceAttributes", faceAttributes);

            // Prepare the URI for the REST API call.
            URI uri = builder.build();
            HttpPost request = new HttpPost(uri);

            // Request headers.
            request.setHeader("Content-Type", "application/json");
            request.setHeader("Ocp-Apim-Subscription-Key", subscriptionKey);

            // Request body.
            StringEntity reqEntity = new StringEntity(imageWithFaces);

            // Execute the REST API call and get the response entity.
            HttpResponse response = httpclient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null)
                // Format and display the JSON response.
                System.out.println("REST Response:\n");

                String jsonString = EntityUtils.toString(entity).trim();
                if (jsonString.charAt(0) == '[') {
                    JSONArray jsonArray = new JSONArray(jsonString);
                else if (jsonString.charAt(0) == '{') {
                    JSONObject jsonObject = new JSONObject(jsonString);
                } else {
        catch (Exception e)
            // Display error message.

Face - Detect response

A successful response is returned in JSON.

  "faceRectangle": {
    "top": 131,
    "left": 177,
    "width": 162,
    "height": 162
  "faceAttributes": {
    "makeup": {
      "eyeMakeup": true,
      "lipMakeup": true
    "facialHair": {
      "sideburns": 0,
      "beard": 0,
      "moustache": 0
    "gender": "female",
    "accessories": [],
    "blur": {
      "blurLevel": "low",
      "value": 0.06
    "headPose": {
      "roll": 0.1,
      "pitch": 0,
      "yaw": -32.9
    "smile": 0,
    "glasses": "NoGlasses",
    "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
    "emotion": {
      "contempt": 0,
      "surprise": 0.005,
      "happiness": 0,
      "neutral": 0.986,
      "sadness": 0.009,
      "disgust": 0,
      "anger": 0,
      "fear": 0
    "exposure": {
      "value": 0.67,
      "exposureLevel": "goodExposure"
    "occlusion": {
      "eyeOccluded": false,
      "mouthOccluded": false,
      "foreheadOccluded": false
    "noise": {
      "noiseLevel": "low",
      "value": 0
    "age": 22.9
  "faceId": "49d55c17-e018-4a42-ba7b-8cbbdfae7c6f"

Next steps

Learn how to create an Android application that uses the Face service to detect faces in an image. The application displays the image with a frame drawn around each face.