--- title: "Face Analytics" url: https://docs.catalyst.zoho.com/en/api/code-reference/zia-services/face-analytics/ description: "This API enables you to perform facial detection and analytics in an image file and obtain the gender, age, and emotion predictions in the detected faces." last_updated: 2026-08-28T06:26:16Z service: Zia Services type: api --- # Face Analytics [Zia Face Analytics](https://docs.catalyst.zoho.com/en/zia-services/help/face-analytics/introduction/) performs facial detection in images, and analyzes the facial features to provide information such as the gender, age, and emotion of the detected faces. Face Analytics also provides the confidence levels of each attribute prediction that enables you to make informed decisions. It can detect up to 10 faces in an image, and it provides predictions of the attributes for each detected face. # Execute Face Analytics ### Description You can use this API to perform facial detection and analytics in an image file, and specify the path to it in the API request as shown in the sample request. You can optionally specify an analysis mode which determines the number of facial landmarks to be detected in a face. You can also enable or disable the attributes to be predicted, such as the emotion, age, and gender. This API is used to pass input for Face Analytics prediction. You must pass an input image file and the data in a JSON format in the request as described below. ### Request Details #### Request URL `POST` {api-domain}/baas/v1/project/{project_id}/ml/faceanalytics - **api-domain** (URL): The DC-specific domain to access Catalyst API - **project_id** (Numerical): The [unique ID](https://docs.catalyst.zoho.com/en/getting-started/set-up-a-catalyst-project/general-settings/) of the project #### Request Headers **Authorization:** Zoho-oauthtoken {oauth_token} **content-type:** multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW **Optional Headers** **CATALYST-ORG:** {org_id} **Environment:** Development #### Scope ZohoCatalyst.mlkit.READ #### Request JSON Properties - **image** (file, mandatory): The input file to be processed. You must provide the path to it in your local system. Allowed formats: *.webp, .jpeg, .png* Image size limit: 10 MB - **mode** (string, optional): Denotes the number of facial landmarks to be detected in a face Allowed values: `basic`, `moderate`, `advanced` Default value: `advanced` * `basic`: 0-point landmark detector that detects the boundary of the face alone * `moderate`: 5-point landmark detector that detects- Eyes: The center of both eyes, Nose: Nose tip, Lips: The center of both lips * `advanced`: 68-point landmark detector that detects- Jawline: Face boundary, Eyebrows: Left and right eyebrow, Eyes: Left and right eye, Nose bridge, Nostril line, Upper lips: Upper and lower edge, Lower lips: Upper and lower edge - **emotion** (boolean, optional): Allowed values: `false`: Emotion will not be detected `true`: Emotion will be detected Default value: `true` - **age** (boolean, optional): Allowed values: `false`: Age will not be detected `true`: Age will be detected Default value: `true` - **gender** (boolean, optional): Allowed values: `false`: Gender will not be detected `true`: Gender will be detected Default value: `true` ### Response Details The response returns the details of the facial landmarks of the detected faces, and the predictions for emotion, age, and gender, based on the parameters and mode set in the API request in the `data` key. The overall probability of the co-ordinates of the facial landmark detection, and the probability of the predictions made for the emotion, age, and gender parameters will be returned as `confidence` scores. **Sample Request: Basic** ```bash curl -X POST \ https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/faceanalytics \ -H "Authorization: Zoho-oauthtoken 1000.910*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*16.2f*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*57" \ -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" \ -F "image=@face.jpeg" \ -d '{ "mode": "basic", "emotion": "true", "age": "true", "gender": "true" }' ``` **Sample Response: Basic** ```json { "status": "success", "data": { "faces": [ { "confidence": 1.0, "id": 0, "co_ordinates": [ 267, 39, 153, 227 ], "emotion": { "prediction": "not_smiling", "confidence": { "smiling": "0.0", "not_smiling": "1.0" } }, "age": { "prediction": "3-9", "confidence": { "0-2": "0.005", "10-19": "0.33", "20-29": "0.12", "3-9": "0.509", "30-39": "0.032", "40-49": "0.003", "50-59": "0.0", "60-69": "0.0", ">70": "0.0" } }, "gender": { "prediction": "female", "confidence": { "female": "0.92", "male": "0.08" } } } ] } } ``` **Sample Request: Moderate** ```bash curl -X POST \ https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/faceanalytics \ -H "Authorization: Zoho-oauthtoken 1000.910*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*16.2f*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*57" \ -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" \ -F "image=@face.jpeg" \ -d '{ "mode": "moderate", "emotion": "false", "age": "false", "gender": "true" }' ``` **Sample Response: Moderate** ```json { "status": "success", "data": { "faces": [ { "confidence": 1.0, "id": 0, "co_ordinates": [ 267, 39, 153, 227 ], "landmarks": { "left_eye": [337,135], "right_eye": [400,130], "nose": [ 400, 165 ], "mouth_left": [ 353, 217 ], "mouth_right": [ 404, 211 ] }, "gender": { "prediction": "female", "confidence": { "female": "0.92", "male": "0.08" } } } ] } } ``` **Sample Request: Advanced** ```bash curl -X POST \ https://api.catalyst.zoho.com/baas/v1/project/4000000006007/ml/faceanalytics \ -H "Authorization: Zoho-oauthtoken 1000.910*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*16.2f*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*\*57" \ -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" \ -F "image=@face.jpeg" \ -d '{ "mode": "advanced", "emotion": "true", "age": "false", "gender": "false" }' ``` **Sample Response: Advanced** ```json { "status": "success", "data": { "faces": [ { "co_ordinates" : [ 185, 96, 275, 18], "confidence" : 0.99 "landmarks" : { 'mouth': [ [259, 440], [287, 423], [312, 413], [325, 418], [338, 414], [354, 424], [368, 442], [355, 461], [339, 470], [325, 472], [310, 470], [285, 460], [269, 440], [311, 435], [324, 436], [338, 436], [359, 442], [339, 440], [326, 441], [312, 439] ], 'right_eyebrow': [ [189, 245], [216, 230], [244, 227], [273, 234], [301, 248] ], 'left_eyebrow': [ [356, 249], [379, 238], [401, 232], [422, 235], [436, 252] ], 'right_eye': [ [225, 288], [245, 281], [265, 282], [280, 295], [263, 297], [244, 297] ], 'left_eye': [ [358, 299], [376, 288], [393, 290], [408, 298], [393, 305], [376, 304] ], 'nose': [ [329, 287], [331, 311], [334, 336], [337, 360], [301, 385], [315, 389], [329, 392], [341, 390], [352, 385] ], 'jaw': [ [131, 283], [136, 340], [145, 393], [158, 442], [180, 484], [212, 513], [250, 530], [287, 542], [319, 545], [347, 535], [370, 512], [393, 487], [411, 456], [423, 419], [432, 381], [437, 342], [439, 303] ] }, "emotion": { "prediction": "not_smiling", "confidence": { "smiling": "0.0", "not_smiling": "1.0" } } } ] } } ``` ### SDK Documentation [Face Analytics- Java SDK](https://docs.catalyst.zoho.com/en/sdk/java/v1/zia-services/face-analytics)

[Face Analytics- Node.js SDK](https://docs.catalyst.zoho.com/en/sdk/nodejs/v2/zia-services/face-analytics)

[Face Analytics- Python SDK](https://docs.catalyst.zoho.com/en/sdk/python/v1/zia-services/face-analytics)