This topic explains how to use the facial attribute detection API to identify faces and their attributes in images.
1. Feature description
Facial attribute detection2.0can analyze various facial features in images, such as blurriness, angle, position, smile intensity, the presence of glasses, masks, hats, mustaches, bangs, and different hair types. The professional edition additionally recognizes exaggerated expressions and whether eyes are closed.
Service | Detection description |
Service Name: Facial Attribute Detection Service: faceDetect_global |
|
Service Name: Facial Attribute Detection Professional Edition Service: faceDetect_pro_global |
|
2. Billing description
Facial attribute detection2.0of images offers billing methods including pay-as-you-go.
Pay-as-you-go
Upon activating the Content Moderation2.0 service, the default billing option is pay-as-you-go. You are charged for the day based on the actual usage. If the service is not called, no charge will be made.
Moderation type | Supported business scenarios (Service) | Unit price |
Image Recognition Standard (image_standard) |
| USD 0.6/1,000 times Note Each call to any service on the left is billed once. Billing is based on actual call volume. For example, calling the facial attribute detection 100 times costs USD 0.06. |
Image Recognition Advanced (image_advanced) |
| USD 1.2/1,000 times Note Each call to any service on the left is billed once. Billing is based on actual call volume. For example, calling the facial attribute detection professional edition 100 times costs USD 0.12. |
The billing frequency for Content Moderation2.0is once in 24 hours. In the billing details, themoderationType corresponds to the moderation type field. You can view the Bill details.
3. Access guide
Create an Alibaba Cloud account: Register Now and follow the prompts to complete registration.
Activate Content Moderation pay-as-you-go: Ensure you have activated the service. You are not charged for activating this service. After you call API operations, the billing system automatically charges you based on your usage. For more information, see Billing Description.
Create an AccessKey: Make sure that you have created an AccessKey pair as a Resource Access Management (RAM) user. For more information, see Create AccessKey. If you want to use the AccessKey pair of the RAM user, use your Alibaba Cloud account to grant the AliyunYundunGreenWebFullAccess permission to the RAM user. For more information, see RAM Authorization.
Use SDKs: We recommend that you use SDKs to call the API. For more information, see Image Moderation 2.0 SDKs and access guide.
4. API operations
Usage description
You can call the Image Moderation 2.0 API to create a task for image moderation. For more information about how to construct an HTTP request, see the usage guide. You can also select an existing HTTP request. For more information, see SDK references.
Operation: ImageModeration
Supported regions and endpoints
Region | Public access address | Private access address | Supported services |
Singapore | https://green-cip.ap-southeast-1.aliyuncs.com | https://green-cip-vpc.ap-southeast-1.aliyuncs.com | faceDetect_global, faceDetect_pro_global |
Billing information:
You are charged for calling this operation. You are charged by using the pay-as-you-go billing method only for requests whose HTTP status code is 200. For more information, see Billing.
Image requirements:
The images must be in PNG, JPG, JPEG, BMP, WEBP, TIFF, SVG, HEIC (the longest side is less than 8192 pixels), GIF (extract the first frame), or ICO (extract the last layer) format.
The maximum size of an image is limited to 20 MB, the height or width cannot exceed 16,384 pixels, and the total pixels must not exceed 167 million pixels. We recommend that you specify images with a minimum resolution of 200 × 200 pixels to ensure that the results of Content Moderation detection algorithms are not affected.
The maximum download duration for an image is 3 seconds. If an image fails to be downloaded within 3 seconds, a timeout error is returned.
QPS limit
You can call this operation up to 10 times per second per account (professional edition: 5 times per second). If the number of calls per second exceeds the limit, throttling is triggered. As a result, your business may be affected. We recommend that you take note of the limit when you call this operation. If you require a higher queries per second (QPS) to meet business requirements or urgent scaling requirements, contact your customer business manager (CBM).
Debugging
Before access, you can debug the operation of Image Moderation 2.0 online via Alibaba Cloud OpenAPI, view example code and SDK dependencies, and familiarize yourself with the operation usage and parameters.
Before you call the Content Moderation API, you must log on to the Content Moderation console by using your Alibaba Cloud account. Therefore, the fees incurred by calling the operations are billed to the account.
Request parameters
For more information about the common request parameters that must be included in all Content Moderation API requests, see Image Moderation 2.0 SDKs and usage guide.
The request body is a JSON structure. The following table describes the parameters that are contained in the request body.
Name | Type | Required | Example | Description |
Service | String | Yes | faceDetect_global | The moderation service supported by Image Moderation 2.0. Valid values:
|
ServiceParameters | JSONString | Yes | The parameters related to the content moderation object. The value is a JSON string. For more information, see ServiceParameters. |
Table 1. ServiceParameters
Name | Type | Required | Example | Description |
imageUrl | String | Yes. The image recognition enhanced edition supports three ways to specify images. Please choose one of them:
| https://img.alicdn.com/tfs/TB1U4r9AeH2gK0jSZJnXXaT1FXa-2880-480.png | The URL of the object that you want to moderate. Make sure that the URL can be accessed over the Internet and that the URL cannot exceed 2,048 characters in length. Note The URL cannot contain Chinese characters. Make sure that you specify only one URL in each request. |
ossBucketName | String | bucket_01 | The bucket name of the authorized OSS bucket. Note When using the OSS image private network address, you must first use the Alibaba Cloud account (i.e., the main account) to access the Cloud Resource Access Authorization Page for authorization. | |
ossObjectName | String | 20240307/04/24/test.jpg | The file name of the authorized OSS bucket. | |
ossRegionId | String | cn-beijing | The region where the OSS bucket is located. | |
dataId | String | No | img123**** | The data ID corresponding to the detection object. The ID can contain uppercase letters, lowercase letters, digits, underscores (_), hyphens (-), and periods (.). The ID can be up to 64 characters in length and uniquely identifies your business data. |
referer | String | No | www.aliyun.com | The referer request header, which is used in scenarios such as hotlink protection. The length does not exceed 256 characters. |
Response parameters
Name | Type | Example | Description |
RequestId | String | 70ED13B0-BC22-576D-9CCF-1CC12FEAC477 | The ID of the request, which is used to locate and troubleshoot issues. |
Data | Object | The image content detection result. For more information, see Data. | |
Code | Integer | 200 | The response code. For more information, see Code Description. |
Msg | String | OK | The response message of this request. |
Table 2. Data
Name | Type | Example | Description |
Ext | Object | The facial attribute detection result. For more information, see Ext. | |
DataId | String | img123****** | The data ID corresponding to the detection object. Note If you specify the dataId parameter in the request, the value of the dataId parameter is returned in the response. |
Result | Array | The risk tags and confidence scores of the image moderation. For more information, see Result. Note When using facial attribute detection, this return value can be temporarily ignored. |
Table 3. Ext
Name | Type | Example | Description |
FaceData | Array | The facial attribute detection result. For more information, see FaceData. |
Table 4. FaceData
Name | Type | Example | Description |
Location | JSONObject | The face location information. For more information, see Location. | |
Smile | Float | 85.88 | The smile degree of the face. The value range is 0 to 100. The higher the score, the greater the smile degree. |
Glasses | String | None | The recognition result of whether wearing glasses. Valid values:
|
Age | Integer | 18 | The age recognition result. |
Quality | JSONObject | The quality information of the face image. For more information, see Quality. | |
Mask | JSONObject | The recognition result of whether wearing a mask. For more information, see Mask. | |
Hat | JSONObject | The recognition result of whether wearing a hat. For more information, see Hat. | |
Mustache | JSONObject | The recognition result of whether having a mustache. For more information, see Mustache. | |
Bang | JSONObject | The recognition result of whether having bangs. For more information, see Bang. | |
Hairstyle | JSONObject | The hairstyle recognition result. For more information, see Hairstyle. | |
Gender | JSONObject | The gender recognition result. For more information, see Gender. |
Table 5.Location
Name | Type | Example | Description |
X | Float | 41 | The distance from the top-left corner of the image to the y-axis of the top-left corner of the face region, in pixels. |
Y | Float | 84 | The distance from the top-left corner of the image to the x-axis of the top-left corner of the face region, in pixels. |
W | Float | 83 | The width of the face region, in pixels. |
H | Float | 26 | The height of the face region, in pixels. |
Table 6.Quality
Name | Type | Example | Description |
Blur | Float | 5.88 | The blur degree of the face image. The value range is 0 to 100. The higher the score, the more blurred it is. Recommended value range: 0 to 25. |
Integrity | Float | 100.0 | The integrity of the face. The value range is 0 to 100. The higher the score, the more complete it is. Recommended value range: 80 to 100. |
Pitch | Float | 5.88 | The pitch angle of the face. Recommended value range: -30 to 30. |
Yaw | Float | 5.18 | The yaw angle of the face. Recommended value range: -30 to 30. |
Roll | Float | 5.18 | The roll angle of the face. Recommended value range: -30 to 30. |
Table 7.Mask
Name | Type | Example | Description |
Value | String | None | The recognition result of whether wearing a mask. Valid values:
|
Confidence | Float | 99.99 | The confidence level of the mask recognition result. The value range is 0 to 100. The higher the value, the more reliable the result. |
Table 8.Hat
Name | Type | Example | Description |
Value | String | Wear | The recognition result of whether wearing a hat. Valid values:
|
Confidence | Float | 88.88 | The confidence level of the hat recognition result. The value range is 0 to 100. The higher the value, the more reliable the result. |
Table 9.Mustache
Name | Type | Example | Description |
Value | String | None | The recognition result of whether having a mustache. Valid values:
|
Confidence | Float | 99.99 | The confidence level of the mustache recognition result. The value range is 0 to 100. The higher the value, the more reliable the result. |
Table 10.Bang
Name | Type | Example | Description |
Value | String | None | The recognition result of whether having bangs. Valid values:
|
Confidence | Float | 81.88 | The confidence level of the bangs recognition result. The value range is 0 to 100. The higher the value, the more reliable the result. |
Table 11.Hairstyle
Name | Type | Example | Description |
Value | String | Short | The hairstyle recognition result. Valid values:
|
Confidence | Float | 81.88 | The confidence level of the hairstyle recognition result. The value range is 0 to 100. The higher the value, the more reliable the result. |
Table 12.Gender
Name | Type | Example | Description |
Value | String | Male | The gender recognition result. Valid values:
|
Confidence | Float | 81.88 | The confidence level of the gender recognition result. The value range is 0 to 100. The higher the value, the more reliable the result. |
Table 13. Result
Name | Type | Example | Description |
Label | String | nonLabel | The facial attribute detection professional edition will return attribute labels, including the following values:
Note The exaggerated expression and whether the eyes are closed are comprehensively judged based on the face in the image. We recommend that you use it in single-face scenarios. |
Confidence | Float | 99.99 | The score of the confidence level. Valid values: 0 to 100. The value is accurate to two decimal places. No confidence score is returned when nonLabel is returned. |
Example
Sample request
{
"Service": "faceDetect_global",
"ServiceParameters": {
"imageUrl": "https://img.alicdn.com/tfs/TB1U4r9AeH2gK0jSZJnXXaT1FXa-2880-480.png",
"dataId": "test0307****"
}
}Sample response
Facial attribute detection sample response
{
"Code": 200,
"Data": {
"DataId": "test0307****",
"Ext": {
"FaceData": [
{
"Age": 24,
"Bang": {
"Confidence": 100.0,
"Value": "None"
},
"Gender": {
"Confidence": 95.72,
"Value": "Male"
},
"Glasses": "None",
"Hairstyle": {
"Confidence": 98.23,
"Value": "Short"
},
"Hat": {
"Confidence": 99.99,
"Value": "None"
},
"Location": {
"H": 98,
"W": 98,
"X": 550,
"Y": 251
},
"Mask": {
"Confidence": 99.99,
"Value": "None"
},
"Mustache": {
"Confidence": 99.58,
"Value": "None"
},
"Quality": {
"Blur": 13.72,
"Integrity": 100.0,
"Pitch": 5.84,
"Roll": 3.66,
"Yaw": 21.22
},
"Smile": 82.49
}
]
},
"Result": [
{
"Confidence": null,
"Description": "No risk detected",
"Label": "nonLabel"
}
],
"RiskLevel": "none"
},
"Msg": "success",
"RequestId": "TEST001-2024-0307-0728-5201314YHX"
}Facial attribute detection professional edition sample response
{
"Code": 200,
"Data": {
"DataId": "test0307****",
"Ext": {
"FaceData": [
{
"Age": 24,
"Bang": {
"Confidence": 100.0,
"Value": "None"
},
"Gender": {
"Confidence": 95.72,
"Value": "Male"
},
"Glasses": "None",
"Hairstyle": {
"Confidence": 98.23,
"Value": "Short"
},
"Hat": {
"Confidence": 99.99,
"Value": "None"
},
"Location": {
"H": 98,
"W": 98,
"X": 550,
"Y": 251
},
"Mask": {
"Confidence": 99.99,
"Value": "None"
},
"Mustache": {
"Confidence": 99.58,
"Value": "None"
},
"Quality": {
"Blur": 13.72,
"Integrity": 100.0,
"Pitch": 5.84,
"Roll": 3.66,
"Yaw": 21.22
},
"Smile": 82.49
}
]
},
"Result": [
{
"Label": "face_exaggerated",
"Description": "The person in the image has an exaggerated expression",
"Confidence": 80.0
}
],
"RiskLevel": "high"
},
"Msg": "success",
"RequestId": "TEST001-2024-0307-0728-5201314YHX"
}The sample requests and responses in this topic are formatted to improve readability. Actual responses are not formatted with line breaks or indentation.
Code Description
The following table describes the response codes. You are charged by using the pay-as-you-go billing method only for requests whose response code is 200.
Code | Description |
200 | The request is successful. |
400 | Not all request parameters are configured. |
401 | The request parameter is invalid. |
402 | Invalid request parameters. Check and modify them and try again. |
403 | The QPS of requests exceeds the upper limit. Check and modify the number of requests that are sent at a time. |
404 | The specified image failed to be downloaded. Check the URL of the image or try again. |
405 | Downloading the specified image timed out. The possible cause is that the image cannot be accessed. Check and adjust the image and try again. |
406 | The specified image is excessively large. Check and change the image size and try again. |
407 | The format of the specified image is not supported. Check and change the image format and try again. |
408 | You do not have the required permissions. The possible cause is that this account is not activated, has overdue payments, or is not authorized to call this API operation. |
500 | A system exception occurs. |