AnalyzeFace

Last updated: 2021-01-18 14:23:46

1. API Description

Domain name for API request: iai.tencentcloudapi.com.

This API is used to perform facial feature localization (aka facial keypoint localization) on a given image and calculate 90 facial keypoints that make up the contour of the face, including eyebrows (8 points on the left and 8 on the right), eyes (8 points on the left and 8 on the right), nose (13 points), mouth (22 points), face contour (21 points), and eyeballs or pupils (2 points).

  • Please use the signature algorithm v3 to calculate the signature in the common parameters, that is, set the SignatureMethod parameter to TC3-HMAC-SHA256.
We recommend you to use API Explorer
Try it
API Explorer provides a range of capabilities, including online call, signature authentication, SDK code generation, and API quick search. It enables you to view the request, response, and auto-generated examples.

2. Input Parameters

The following request parameter list only provides API request parameters and some common parameters. For the complete common parameter list, see Common Request Parameters.

Parameter Name Required Type Description
Action Yes String Common parameter. The value used for this API: AnalyzeFace.
Version Yes String Common parameter. The value used for this API: 2020-03-03.
Region Yes String Common parameter. For more information, please see the list of regions supported by the product.
Mode No Integer Detection mode. 0: detect all faces that appear; 1: detect the largest face. Default value: 0. The facial feature localization information (facial keypoints) of up to 10 faces can be returned.
Image No String Base64-encoded image data, which cannot exceed 5 MB.
The long side cannot exceed 4,000 px for images in JPG format or 2,000 px for images in other formats.
PNG, JPG, JPEG, and BMP images are supported, while GIF images are not.
Url No String Image URL. The image cannot exceed 5 MB in size after being Base64-encoded.
The long side cannot exceed 4,000 px for images in JPG format or 2,000 px for images in other formats.
Either Url or Image must be provided; if both are provided, only Url will be used.
We recommend storing the image in Tencent Cloud, as a Tencent Cloud URL can guarantee higher download speed and stability.
The download speed and stability of non-Tencent Cloud URLs may be low.
PNG, JPG, JPEG, and BMP images are supported, while GIF images are not.
FaceModelVersion No String Algorithm model version used by the Face Recognition service. Valid values: 2.0, 3.0.
This parameter is 3.0 by default starting from April 2, 2020. If it is left empty for accounts that used this API previously, 2.0 will be used by default.
Different algorithm model versions correspond to different face recognition algorithms. The new version has a better overall effect than the legacy version and is thus recommended.
NeedRotateDetection No Integer Whether to enable the support for rotated image recognition. 0: no; 1: yes. Default value: 0. When the face in the image is rotated and the image has no EXIF information, if this parameter is not enabled, the face in the image cannot be correctly detected and recognized. If you are sure that the input image contains EXIF information or the face in the image will not be rotated, do not enable this parameter, as the overall time consumption may increase by hundreds of milliseconds after it is enabled.

3. Output Parameters

Parameter Name Type Description
ImageWidth Integer Width of requested image.
ImageHeight Integer Height of requested image.
FaceShapeSet Array of FaceShape Specific information of facial feature localization (facial keypoints).
FaceModelVersion String Algorithm model version used for face recognition.
RequestId String The unique request ID, which is returned for each request. RequestId is required for locating a problem.

4. Example

Example1 Performing facial feature localization

Input Example

https://iai.tencentcloudapi.com/?Action=AnalyzeFace
&Mode=0
&Url=http://test.image.myqcloud.com/testA.jpg
&<Common request parameters>

Output Example

{
  "Response": {
    "ImageWidth": 550,
    "ImageHeight": 366,
    "FaceShapeSet": [
      {
        "FaceProfile": [
          {
            "X": 63,
            "Y": 335
          },
          {
            "X": 63,
            "Y": 374
          },
          {
            "X": 66,
            "Y": 412
          },
          {
            "X": 74,
            "Y": 450
          },
          {
            "X": 85,
            "Y": 487
          },
          {
            "X": 100,
            "Y": 522
          },
          {
            "X": 121,
            "Y": 554
          },
          {
            "X": 147,
            "Y": 582
          },
          {
            "X": 176,
            "Y": 608
          },
          {
            "X": 208,
            "Y": 627
          },
          {
            "X": 245,
            "Y": 634
          },
          {
            "X": 282,
            "Y": 627
          },
          {
            "X": 315,
            "Y": 607
          },
          {
            "X": 344,
            "Y": 582
          },
          {
            "X": 370,
            "Y": 554
          },
          {
            "X": 391,
            "Y": 522
          },
          {
            "X": 405,
            "Y": 487
          },
          {
            "X": 416,
            "Y": 449
          },
          {
            "X": 423,
            "Y": 411
          },
          {
            "X": 427,
            "Y": 372
          },
          {
            "X": 426,
            "Y": 334
          }
        ],
        "LeftEye": [
          {
            "X": 114,
            "Y": 333
          },
          {
            "X": 128,
            "Y": 345
          },
          {
            "X": 146,
            "Y": 349
          },
          {
            "X": 165,
            "Y": 347
          },
          {
            "X": 183,
            "Y": 341
          },
          {
            "X": 169,
            "Y": 325
          },
          {
            "X": 150,
            "Y": 318
          },
          {
            "X": 130,
            "Y": 321
          }
        ],
        "RightEye": [
          {
            "X": 378,
            "Y": 331
          },
          {
            "X": 364,
            "Y": 343
          },
          {
            "X": 345,
            "Y": 348
          },
          {
            "X": 327,
            "Y": 346
          },
          {
            "X": 309,
            "Y": 340
          },
          {
            "X": 322,
            "Y": 323
          },
          {
            "X": 341,
            "Y": 316
          },
          {
            "X": 361,
            "Y": 319
          }
        ],
        "LeftEyeBrow": [
          {
            "X": 79,
            "Y": 280
          },
          {
            "X": 108,
            "Y": 275
          },
          {
            "X": 138,
            "Y": 274
          },
          {
            "X": 168,
            "Y": 277
          },
          {
            "X": 198,
            "Y": 279
          },
          {
            "X": 173,
            "Y": 256
          },
          {
            "X": 139,
            "Y": 251
          },
          {
            "X": 105,
            "Y": 256
          }
        ],
        "RightEyeBrow": [
          {
            "X": 410,
            "Y": 277
          },
          {
            "X": 380,
            "Y": 273
          },
          {
            "X": 350,
            "Y": 272
          },
          {
            "X": 320,
            "Y": 275
          },
          {
            "X": 290,
            "Y": 277
          },
          {
            "X": 315,
            "Y": 255
          },
          {
            "X": 349,
            "Y": 249
          },
          {
            "X": 384,
            "Y": 254
          }
        ],
        "Mouth": [
          {
            "X": 173,
            "Y": 522
          },
          {
            "X": 193,
            "Y": 541
          },
          {
            "X": 217,
            "Y": 554
          },
          {
            "X": 244,
            "Y": 558
          },
          {
            "X": 272,
            "Y": 554
          },
          {
            "X": 297,
            "Y": 541
          },
          {
            "X": 317,
            "Y": 522
          },
          {
            "X": 291,
            "Y": 517
          },
          {
            "X": 264,
            "Y": 512
          },
          {
            "X": 245,
            "Y": 517
          },
          {
            "X": 225,
            "Y": 512
          },
          {
            "X": 199,
            "Y": 517
          },
          {
            "X": 196,
            "Y": 528
          },
          {
            "X": 220,
            "Y": 532
          },
          {
            "X": 244,
            "Y": 535
          },
          {
            "X": 269,
            "Y": 532
          },
          {
            "X": 293,
            "Y": 528
          },
          {
            "X": 293,
            "Y": 525
          },
          {
            "X": 269,
            "Y": 527
          },
          {
            "X": 245,
            "Y": 530
          },
          {
            "X": 221,
            "Y": 528
          },
          {
            "X": 197,
            "Y": 525
          }
        ],
        "Nose": [
          {
            "X": 244,
            "Y": 428
          },
          {
            "X": 245,
            "Y": 341
          },
          {
            "X": 231,
            "Y": 367
          },
          {
            "X": 217,
            "Y": 392
          },
          {
            "X": 203,
            "Y": 418
          },
          {
            "X": 187,
            "Y": 448
          },
          {
            "X": 217,
            "Y": 464
          },
          {