Detect faces in an image and retrieve attribute data such as age, expression, accessories, and pose angles.
1. Feature
Facial attribute detectionenhanced edition detects various facial attributes in an image, such as blurriness, angle, position, smile intensity, glasses, mask, hat, mustache, bangs, and hair type. The professional edition also detects attributes such as exaggerated expression and closed eyes.
|
Service |
Description |
|
Service name: Facial attribute detection Service: faceDetect |
|
|
Service name: Facial attribute detection professional edition Service: faceDetect_pro |
|
2. Billing
Facial attribute detection enhanced edition supports pay-as-you-go billing and resource plan.
Pay-as-you-go
When you activate Content Moderation enhanced edition, billing defaults to pay-as-you-go. Charges are calculated based on actual usage, and you are not charged if no calls are made.
|
Type |
Supported services |
Unit price |
|
Image Recognition Standard (image_standard) |
|
CNY 15 per 10,000 calls Note
You are billed once for each call to the service listed on the left. Billing is based on actual call volume. For example, 100 calls to Facial Attribute Detection cost CNY 0.15. |
|
Image Recognition Advanced (image_advanced) |
|
CNY 30 per 10,000 calls Note
You are billed once for each call to the service listed on the left. Billing is based on actual call volume. For example, 100 calls to Facial Attribute Detection Professional Edition cost CNY 0.30. |
Pay-as-you-go Content Moderation enhanced edition is billed hourly. In the billing details, moderationType indicates the moderation type. You can view the billing details.
Resource plan offsets
For high-volume or predictable usage, purchase a resource plan to receive a discount. Larger plans offer greater discounts, and you can purchase and use multiple plans. For more information, see Purchase resource plans for Content Moderation 2.0.
This resource plan offsets usage for Content Moderation 2.0 and is not compatible with data transfer plans for Content Moderation 1.0. The offset factors are as follows:
|
Type |
Offset factor |
|
Image Recognition Standard (image_standard) |
2: Each successful API call uses 2 units. For example, if your resource plan has a capacity of 10 units, one successful API call uses 2 units, leaving a balance of 8 units. |
|
Image Moderation Advanced (image_advanced) |
4: Each successful API call uses 4 units. For example, if your resource plan has a capacity of 10 units, one successful API call uses 4 units, leaving a balance of 6 units. |
After you purchase a resource plan, usage from image moderation APIs is first offset by your plan's balance. If the balance is insufficient, any overage is automatically billed on a pay-as-you-go basis. Monitor your resource plan's remaining balance and pay-as-you-go bills. You can set low-balance alerts in the Resource Plan System, which is available in Alibaba Cloud Billing Management.
3. Getting started
-
Register an Alibaba Cloud account: Register now and follow the on-screen instructions.
-
Activate pay-as-you-go for Content Moderation: Ensure that you have activated the service. Service activation is free of charge. After you make API calls, billing automatically starts based on your usage. For more information, see billing description. You can also purchase a resource plan, which offers tiered discounts and is ideal for users with high or predictable usage.
-
Create an AccessKey: Use RAM to create an AccessKey. If you use a RAM user's AccessKey, you must use your Alibaba Cloud account to grant that user the AliyunYundunGreenWebFullAccess permission. For instructions, see RAM authorization.
-
Integrate the service: Use an SDK to make API calls. For detailed instructions, see Image Moderation 2.0 SDKs and access guide.
4. API
Usage
Call this API to create an image moderation task. To construct an HTTP request, see the usage guide. You can also use a pre-built SDK request as detailed in the SDK references.
-
Operation: ImageModeration
-
Supported regions and endpoints:
|
Region |
Public access address |
Private access address |
Supported services |
|
China (Shanghai) |
https://green-cip.cn-shanghai.aliyuncs.com |
https://green-cip-vpc.cn-shanghai.aliyuncs.com |
faceDetect, faceDetect_pro |
|
China (Hangzhou) |
https://green-cip.cn-hangzhou.aliyuncs.com |
https://green-cip-vpc.cn-hangzhou.aliyuncs.com |
-
Billing:
This is a pay-as-you-go operation. You are charged only for requests that return an HTTP status code of 200; requests that result in any other status code are not billed. For more information, see Billing.
-
Image requirements:
-
The image format must be PNG, JPG, JPEG, BMP, WEBP, TIFF, SVG, HEIC (longest side < 8,192 pixels), GIF (first frame extracted), or ICO (last layer extracted).
-
The image size cannot exceed 20 MB. The height or width cannot exceed 16,384 pixels, and the total pixels cannot exceed 167 million. We recommend a resolution of at least 200 × 200 pixels for optimal results. A low resolution can affect the accuracy of the Content Moderation algorithm.
-
The download timeout for an image is 3 seconds. If an image fails to download within this time, the operation times out.
-
QPS limit
The per-user QPS limit for this API is 10 QPS (5 QPS for the professional edition). Exceeding this limit throttles your API calls, which may impact your business. To request a higher QPS for high traffic or urgent scaling requirements, contact your customer business manager (CBM).
Debugging
You can use Alibaba Cloud OpenAPI to debug the Image Moderation enhanced edition operation before integrating. You can view example code, check SDK dependencies, and review usage and parameters.
The online debugging feature calls the Content Moderation API under your account. These calls count towards your billable usage.
Request parameters
For the common parameters required in requests, see the Image Scan Pro 2.0 SDK and integration guide.
The request body is a JSON structure with the following fields:
|
Parameter |
Type |
Required |
Example |
Description |
|
Service |
String |
Yes |
faceDetect |
The moderation service offered by Image Moderation 2.0. Valid values:
|
|
ServiceParameters |
JSONString |
Yes |
Parameters for the content moderation object. For more information, see ServiceParameters. |
Table 1. ServiceParameters
|
Parameter |
Type |
Required |
Example |
Description |
|
imageUrl |
String |
Yes. Specify the image using one of the following methods:
|
https://img.alicdn.com/tfs/TB1U4r9AeH2gK0jSZJnXXaT1FXa-2880-480.png |
The URL of the image to scan. The URL must be accessible over the public network and must not exceed 2,048 characters in length. Note
The URL cannot contain Chinese characters. Each request must contain only one URL. |
|
ossBucketName |
String |
bucket_01 |
The name of the authorized OSS bucket. Note
If you use the private network address of an OSS image, you must first use your main Alibaba Cloud account to grant permissions on the Cloud Resource Access Authorization Page. |
|
|
ossObjectName |
String |
20240307/04/24/test.jpg |
The name of the object in the authorized OSS bucket. |
|
|
ossRegionId |
String |
cn-beijing |
The region where the OSS bucket is located. |
|
|
dataId |
String |
No |
img123**** |
A unique data ID for the object to be scanned. Use this ID to correlate the scan results with your business data. The ID can be up to 64 characters in length and can consist of uppercase and lowercase letters, digits, underscores (_), hyphens (-), and periods (.). |
|
referer |
String |
No |
www.aliyun.com |
The Referer header of the request, used for features like hotlink protection. The value cannot exceed 256 characters. |
Response parameters
|
Parameter |
Type |
Example |
Description |
|
RequestId |
String |
70ED13B0-BC22-576D-9CCF-1CC12FEAC477 |
The unique ID of the request, generated by Alibaba Cloud. Use this ID for troubleshooting. |
|
Data |
Object |
The image content detection result. For details, see Data. |
|
|
Code |
Integer |
200 |
The status code. For details, see Code Description. |
|
Msg |
String |
OK |
The response message. |
Table 2. Data
|
Parameter |
Type |
Value |
Description |
|
Ext |
Object |
The facial attribute detection result. For more information, see Ext. |
|
|
DataId |
String |
img123****** |
The data ID of the detection object. Note
If you specify the |
|
Result |
Array |
The risk tags and confidence scores generated by image moderation. For more information, see Result. Note
This return value can be ignored when using facial attribute detection. |
Table 3. Ext
|
Parameter |
Type |
Value |
Description |
|
FaceData |
Array |
An array of facial attribute detection results. For details, see FaceData. |
Table 4. FaceData
|
Parameter |
Type |
Value |
Description |
|
Location |
JSONObject |
The location of the face. For details on the structure, see Location. |
|
|
Smile |
Float |
85.88 |
The smile score, on a scale of 0 to 100. A higher score indicates a more prominent smile. |
|
Glasses |
String |
None |
Indicates whether the person is wearing glasses. Valid values:
|
|
Age |
Integer |
18 |
The detected age of the person. |
|
Quality |
JSONObject |
The quality of the face image. For details on the structure, see Quality. |
|
|
Mask |
JSONObject |
The mask detection results. For details on the structure, see Mask. |
|
|
Hat |
JSONObject |
The hat detection results. For details on the structure, see Hat. |
|
|
Mustache |
JSONObject |
The mustache detection results. For details on the structure, see Mustache. |
|
|
Bang |
JSONObject |
The bang detection results. For details on the structure, see Bang. |
|
|
Hairstyle |
JSONObject |
The hairstyle detection results. For details on the structure, see Hairstyle. |
|
|
Gender |
JSONObject |
The gender detection results. For details on the structure, see Gender. |
Table 5. Location
|
Parameter |
Type |
Value |
Description |
|
X |
Float |
41 |
The x-coordinate of the face region's top-left corner, measured in pixels from the left edge of the image. |
|
Y |
Float |
84 |
The y-coordinate of the face region's top-left corner, measured in pixels from the top edge of the image. |
|
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
|
Parameter |
Type |
Example |
Description |
|
Blur |
Float |
5.88 |
The blurriness of the face. The value ranges from 0 to 100, where a higher value indicates a blurrier image. The recommended range is 0 to 25. |
|
Integrity |
Float |
100.0 |
The integrity of the face, indicating how complete and unoccluded it is. The value ranges from 0 to 100, where a higher value indicates better integrity. The recommended range is 80 to 100. |
|
Pitch |
Float |
5.88 |
The pitch angle of the face, indicating upward or downward rotation. The recommended range is -30 to 30. |
|
Yaw |
Float |
5.18 |
The yaw angle of the face, indicating leftward or rightward rotation. The recommended range is -30 to 30. |
|
Roll |
Float |
5.18 |
The roll angle of the face, indicating in-plane rotation or tilt. The recommended range is -30 to 30. |
Table 7. mask
|
Parameter |
Type |
Example |
Description |
|
Value |
String |
None |
Indicates whether a mask was detected. Valid values:
|
|
Confidence |
Float |
99.99 |
The confidence score for the mask detection result. The value ranges from 0 to 100. A larger value indicates higher confidence. |
Table 8. Hat
|
Parameter |
Type |
Example |
Description |
|
Value |
String |
Wear |
Specifies whether a hat is detected. Valid values:
|
|
Confidence |
Float |
88.88 |
The confidence of the hat detection result. The value ranges from 0 to 100, with higher values indicating greater reliability. |
Table 9. Mustache
|
Parameter |
Type |
Example |
Description |
|
Value |
String |
None |
Indicates whether a mustache is detected. Valid values:
|
|
Confidence |
Float |
99.99 |
The confidence in the mustache detection. The value ranges from 0 to 100. A higher value indicates a more reliable result. |
Table 10: Bang
|
Parameter |
Type |
Example |
Description |
|
Value |
String |
None |
Indicates whether the face has bangs. Valid values:
|
|
Confidence |
Float |
81.88 |
The confidence score for the bangs detection, on a scale of 0 to 100. A higher value indicates a more reliable result. |
Table 11. Hairstyle
|
Parameter |
Type |
Example |
Description |
|
Value |
String |
Short |
The recognized hairstyle. Valid values:
|
|
Confidence |
Float |
81.88 |
The confidence score for the recognized hairstyle. The value ranges from 0 to 100. The higher the value, the more reliable the result. |
Table 12.Gender
|
Parameter |
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 is between 0 and 100. The higher the value, the more reliable the result. |
Table 13. Result
|
Parameter |
Type |
Value |
Description |
|
Label |
String |
nonLabel |
The facial attribute detection professional edition returns an attribute label. Possible values include:
Note
The exaggerated expression and closed-eyes attributes are determined based on a comprehensive analysis of the face. This feature is recommended for single-face scenarios. |
|
Confidence |
Float |
99.99 |
Indicates the confidence score for the detected attribute. The value ranges from 0 to 100 and is accurate to two decimal places. A confidence score is not returned when |
Example
Sample request
{
"Service": "faceDetect",
"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 request and response samples in this document are formatted for readability. The actual responses are unformatted and do not include line breaks or indentation.
Code
Only requests that return a code of 200 are billed. Requests with any other code are not billed.
|
Code |
Description |
|
200 |
The request was successful. |
|
400 |
The request is missing a required request parameter. |
|
401 |
The request parameter is invalid. |
|
402 |
The length of a request parameter is invalid. Verify the parameter length and try again. |
|
403 |
The number of requests exceeds the QPS limit. Check and adjust your request concurrency. |
|
404 |
The image download failed. Verify the image and try again. |
|
405 |
The request timed out while downloading the image. This can occur if the image is inaccessible. Ensure the image is accessible and try again. |
|
406 |
The image exceeds the size limit. Verify the image size and try again. |
|
407 |
The image format is not supported. Verify the image format and try again. |
|
408 |
The account is not authorized to call this API. This can occur if the service is not activated for the account, the account has an overdue payment, or the account lacks the required authorization. |
|
500 |
A system exception occurred. |