All Products
Search

This Product

    ID Verification:Add a face image to a specified face group

    Document Center

    ID Verification:Add a face image to a specified face group

    Last Updated:Jun 24, 2026

    This API operation adds a face image to a specified face group for face retrieval. You can also create face groups and add face images in the ID Verification console.

    API information

    • API name: AddFaceRecord

    • Request method: POST

    • Transport protocol: HTTPS

    • This API has a QPS limit of 50 per tenant.

    • Endpoints:

      Note

      • Different ID Verification solutions support different regions, and data is isolated between them. To access your data, you must use the API domain name for the region where your data is stored.

      Singapore

      • Public endpoint: cloudauth-intl.ap-southeast-1.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.ap-southeast-1.aliyuncs.com

      Indonesia (Jakarta)

      • Public endpoint: cloudauth-intl.ap-southeast-5.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com

      China (Hong Kong)

      • Public endpoint: cloudauth-intl.cn-hongkong.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

      Malaysia (Kuala Lumpur)

      • Public endpoint: cloudauth-intl.ap-southeast-3.aliyuncs.com

      • Internal endpoint: cloudauth-intl-vpc.ap-southeast-3.aliyuncs.com

    Online debugging and integration

    Note

    Before you debug or integrate, read the Debug and integrate server-side APIs with OpenAPI guide to understand how to call APIs on the OpenAPI platform and how to obtain the SDK.

    You can run and debug this API in OpenAPI Explorer, and generate an SDK code example.

    Image requirements

    • Image format: JPG or JPEG.

    • Image size: 50 KB to 100 KB is recommended. The maximum size is 10 MB. We recommend uploading images larger than 1 MB by using a URL or file stream.

    • Image resolution: A resolution of 640x480 pixels (height x width) is recommended. The maximum resolution is 1920x1080 pixels (height x width). The image height must be greater than its width. For best results, scale the shorter side to 720 pixels with a compression ratio of 0.8.

    • Image quality: The image must be clear and properly exposed. The face must not be too dark, too bright, or have halos.

    • Multiple faces: If an image contains multiple faces, the system detects and processes the largest face by default.

    Request parameters

    Note

    When uploading a face image, provide it using only one of the following parameters: FacePicture, FacePictureUrl, or FacePictureFileObject.

    Parameter

    Type

    Description

    Required

    Example

    ProductCode

    string

    The product code. Set the value to FACE_ENROLL.

    Yes

    FACE_ENROLL

    FaceGroupCode

    string

    The code of the face group.

    Yes

    sgl****7uc

    MerchantUserId

    string

    A custom unique ID for the user, with a maximum length of 32 characters.

    • If provided, this ID is used for registration.

    • If omitted, the system generates a default ID.

    No

    130A2C10B9EE4D8488E35384FF03hst

    FacePicture

    string

    The Base64-encoded string of the face image.

    No

    base64

    FacePictureUrl

    string

    The URL of the face image.

    No

    https://example.com/test.jpg

    FacePictureFileObject

    InputStream

    The local file stream of the face image.

    To upload a file using this parameter, you must call the Advance API operation and pass a valid InputStream object. For more information, see Special scenario: Configure the Advance API for file uploads.

    No

    The InputStream object of the image

    FaceQualityCheck

    string

    Specifies whether to check the quality of the face image.

    • Y: Enables quality check. (Default)

    • N: Disables quality check.

    If enabled, the system automatically rejects low-quality images, such as those that are blurry or occluded, and does not add them to the face group. For rejected images, the system returns a 401 (UnqualifiedPhoto) error.

    No

    Y

    Response parameters

    Parameter

    Type

    Description

    Example

    HTTP status code

    integer

    The HTTP status code.

    200

    HTTP Body

    RequestId

    string

    The request ID.

    130A2C10-B9EE-4D84-88E3-5384FF03****

    Code

    string

    Return code: For more information, see Server-side HTTP status codes.

    Success

    Message

    string

    The description of the return code.

    The request was successful.

    Result.Passed

    string

    The registration result.

    • Y: Registration succeeded.

    • N: Registration failed.

    Y

    Result.ExtFaceInfo

    Object

    Contains the face image analysis results. See the example for the JSON format.

    For more information, see ExtFaceInfo.

    {
  "FaceQualityScore": 66.3,
  "OcclusionScore": 100,
  "SharpnessScore": 70.3,
  "KaOcclusionScore": 80,
  "IlluminationScore": 90.79
}

    ExtFaceInfo

    Parameter

    Type

    Description

    Example

    FaceQualityScore

    Double

    The overall face quality score. The value ranges from 0 to 100. A higher score indicates better quality.

    88.62

    OcclusionScore

    Double

    A quality sub-score for occlusion. The value ranges from 0 to 100. A higher score indicates better quality (less occlusion).

    99.99

    KaOcclusionScore

    Double

    A quality sub-score for occlusion in key facial areas. The value ranges from 0 to 100. A higher score indicates better quality.

    100

    IlluminationScore

    Double

    A quality sub-score for illumination. The value ranges from 0 to 100. A higher score indicates better quality.

    97.43

    SharpnessScore

    Double

    A quality sub-score for image sharpness. The value ranges from 0 to 100. A higher score indicates better quality.

    60.78

    Billing

    This API operation is billable. For more information, see Billing overview.

    Note

    The following operations are not billed:

    • Manually adding a face image in the console.

    • Automatic enrollment during a liveness verification flow.