The facial recognition feature uses artificial intelligence (AI) to detect the bounding boxes and facial attributes of faces in images. If an image contains multiple faces, the bounding boxes and attributes for all faces are detected. This metadata can be used for statistical analysis based on age and gender.
New features and optimizations for Intelligent Media Management (IMM) are available only in the new version. The previous version is being phased out. For an improved experience, we recommend that you use the face detection feature provided by the new version of IMM. For more information, see Face detection. For a comparison between the new and old versions of IMM, see New and old version guide.
Prerequisites
You have activated IMM and bound it to Object Storage Service (OSS). For more information, see Quick Start.
If you use a Resource Access Management (RAM) user to use IMM features, make sure the RAM user has the following permissions:
System permissions:
AliyunOSSReadOnlyAccessandAliyunIMMFullAccessFor more information, see Manage the permissions of a RAM user.
Custom permissions:
oss:ProcessImmandram:GetRoleTo grant custom permissions to a RAM user, create a custom policy and then grant it to the user. For more information, see Grant custom policies to a RAM user.
Function overview
Bounding box
The bounding box of a face contains four values: the y-coordinate of the upper-left corner, the x-coordinate of the upper-left corner, the width, and the height.
Facial attributes
Facial attributes include the following: gender, age, head posture, eye status, facial blur, and face quality.
Parameters
Operation: imm/detectface
Sample response:
{
"Faces":[
{
"Age":29,
"Attractive":0.95,
"Emotion":"HAPPY",
"EmotionConfidence":0.9875330924987793,
"EmotionDetails":{
"ANGRY":0.000016857109585544094,
"CALM":0.012278525158762932,
"DISGUSTED":0.000012325451280048583,
"HAPPY":0.9875330924987793,
"SAD":0.0000388074986403808,
"SCARED":0.000006888585176056949,
"SURPRISED":0.000054363932576961815
},
"FaceAttributes":{
"Beard":"NONE",
"BeardConfidence":1,
"FaceBoundary":{
"Height":928,
"Left":607,
"Top":628,
"Width":894
},
"Glasses":"NONE",
"GlassesConfidence":1,
"Mask":"NONE",
"MaskConfidence":0.9999999403953552
},
"FaceConfidence":0.9704222083091736,
"FaceId":"4199e1985b6d3bb075f0994c82e6d2fd82a274c11ce183e1fdb222dd3aa8c7ce",
"Gender":"MALE",
"GenderConfidence":1,
}
],
"ImageUri":"oss://image-demo/person.jpg",
"RequestId":"5C3D854A3243A93A275E9C99",
"httpStatusCode":200,
"success":true
}Examples
In this example, the request bucket is `imm-demo` and is located in the China (Hangzhou) region. The corresponding endpoint is `oss-cn-hangzhou.aliyuncs.com`. The requested image is `person.jpg`. The following is the unsigned request URL:
http://image-demo.oss-cn-hangzhou.aliyuncs.com/person.jpg?x-oss-process=imm/detectfaceThe following code shows how to call the operation using the Python SDK:
import json
import oss2
import os
# Configure information.
access_key_id = os.getenv('OSS_ACCESS_KEY_ID')
access_key_secret = os.getenv('OSS_ACCESS_KEY_SECRET')
endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'
bucket_name = 'imm-demo'
objectKey = 'person.jpg'
# Create a bucket instance. All file-related methods must be called through the bucket instance.
bucket = oss2.Bucket(oss2.Auth(access_key_id, access_key_secret), endpoint, bucket_name)
# Detect faces.
style = 'imm/detectface'
result = bucket.get_object(objectKey, process=style)
# Parse the result.
buf = result.read(result.content_length)
print(json.dumps(json.loads(buf), indent=4, sort_keys=True))