Queries face groups based on given conditions.
Operation description
Before you call this operation, make sure that you are familiar with the billing of Intelligent Media Management (IMM).****
Before you call this operation, make sure that a face clustering task is created to group all faces in a dataset. For information about how to create a face clustering task, see CreateFigureClusteringTask. For information about how to create a dataset, see CreateDataset.
Try it now
Test
RAM authorization
|
Action |
Access level |
Resource type |
Condition key |
Dependent action |
|
imm:QueryFigureClusters |
list |
*Dataset
|
None | None |
Request parameters
|
Parameter |
Type |
Required |
Description |
Example |
| ProjectName |
string |
Yes |
The name of the project. You can obtain the name of the project from the response of the CreateProject operation. |
test-project |
| DatasetName |
string |
Yes |
The name of the dataset. You can obtain the name of the dataset from the response of the CreateDataset operation. |
test-dataset |
| Sort |
string |
No |
The sort field. If you leave this parameter empty, the group ID is used as the sort field. Valid values:
Valid values:
|
ImageCount |
| Order |
string |
No |
The sort order. Default value: asc. Valid values:
Valid values:
|
asc |
| CustomLabels |
string |
No |
The custom labels, which can be used as query conditions. |
key=value |
| MaxResults |
integer |
No |
The maximum number of entries to return. Valid values: 0 to 100. Default value: 100. |
100 |
| NextToken |
string |
No |
The pagination token that is used in the next request to retrieve a new page of results. You do not need to specify this parameter for the first request. You must specify the token that is obtained from the previous query as the value of NextToken. |
CAESEgoQCg4KCkltYWdlQ291bnQQARgBIr0ECgkABAAAAAAAAAAKrwQDKgIAADFTMzEzMDMyMzMzMjMxMzAzMDMyMzQzNjM3MzczOTMzMzQzYTY5NmQ2ZDJkNjk2ZDYxNjc2NTJkNzQ2NTczNzQyZDY4N2E2NDY1NzYyZDMyMzUzMjM0MzIzOTMzMzczMTJkMzY1NDZhNzk3MzU2Njk3MjM0M2E2OTZkNmQyZDc0NjU3Mzc0MmQ3MzY1NzQyZDYzMzYzNjY0MzY2NjYxMzQyZDM1MzMzODM3MmQzMTMxNjU2NjJkNjI2NTM5MzYyZDM5MzgzMDMzMzk2MjMwMzE2NDYzNjMzMjNhNjY2OTY3NzU3MjY1MmQ2MzZjNzU3Mzc0NjU3MjNhNDM2Yzc1NzM3NDY1NzIyZDYxNjUzOTY0MzQzMzMxNjEyZDM3MzQ2NTY2MmQzNDM5Mzc2MjJkMzg2MjMxMzUyZDM0MzUzOTM1MzYzNzYxMzQ2NDM2MzE2Ni5TMzEzMDMyMzMzMjMxMzAzMDMyMzQzNjM3MzczOTMzMzQzYTY5NmQ2ZDJkNjk2ZDYxNjc2NTJkNzQ2NTczNzQyZDY4N2E2NDY1NzYyZDMyMzUzMjM0MzIzOTMzMzczMTJkMzY1NDZhNzk3MzU2Njk3MjM0M2E2OTZkNmQyZDc0NjU3Mzc0MmQ3MzY1NzQyZDYzMzYzNjY0MzY2NjYxMzQyZDM1MzMzODM3MmQzMTMxNjU2NjJkNjI2NTM5MzYyZDM5MzgzMDMzMzk2MjMwMzE2NDYzNjM***** |
| CreateTimeRange | TimeRange |
No |
The time range within which the face group was created. |
|
| UpdateTimeRange | TimeRange |
No |
The time range within which the face group was last updated. |
|
| WithTotalCount |
boolean |
No |
Specifies whether to return the total number of face groups that match the current query conditions. Default value: false. |
false |
Response elements
|
Element |
Type |
Description |
Example |
|
object |
The response parameters. |
||
| RequestId |
string |
The request ID. |
CA995EFD-083D-4F40-BE8A-BDF75FFF**** |
| NextToken |
string |
A pagination token. It can be used in the next request to retrieve a new page of results. |
CAESEgoQCg4KCkltYWdlQ291bnQQARgBIr0ECgkABAAAAAAAAAAKrwQDKgIAADFTMzEzMDMyMzMzMjMxMzAzMDMyMzQzNjM3MzczOTMzMzQzYTY5NmQ2ZDJkNjk2ZDYxNjc2NTJkNzQ2NTczNzQyZDY4N2E2NDY1NzYyZDMyMzUzMjM0MzIzOTMzMzczMTJkMzY1NDZhNzk3MzU2Njk3MjM0M2E2OTZkNmQyZDc0NjU3Mzc0MmQ3MzY1NzQyZDYzMzYzNjY0MzY2NjYxMzQyZDM1MzMzODM3MmQzMTMxNjU2NjJkNjI2NTM5MzYyZDM5MzgzMDMzMzk2MjMwMzE2NDYzNjMzMjNhNjY2OTY3NzU3MjY1MmQ2MzZjNzU3Mzc0NjU3MjNhNDM2Yzc1NzM3NDY1NzIyZDYxNjUzOTY0MzQzMzMxNjEyZDM3MzQ2NTY2MmQzNDM5Mzc2MjJkMzg2MjMxMzUyZDM0MzUzOTM1MzYzNzYxMzQ2NDM2MzE2Ni5TMzEzMDMyMzMzMjMxMzAzMDMyMzQzNjM3MzczOTMzMzQzYTY5NmQ2ZDJkNjk2ZDYxNjc2NTJkNzQ2NTczNzQyZDY4N2E2NDY1NzYyZDMyMzUzMjM0MzIzOTMzMzczMTJkMzY1NDZhNzk3MzU2Njk3MjM0M2E2OTZkNmQyZDc0NjU3Mzc0MmQ3MzY1NzQyZDYzMzYzNjY0MzY2NjYxMzQyZDM1MzMzODM3MmQzMTMxNjU2NjJkNjI2NTM5MzYyZDM5MzgzMDMzMzk2MjMwMzE2NDYzNjM***** |
| FigureClusters |
array |
The face groups. |
|
| FigureCluster |
The face group details. |
||
| TotalCount |
integer |
The total number of face groups that matches the current query conditions. |
100 |
Examples
Success response
JSON format
{
"RequestId": "CA995EFD-083D-4F40-BE8A-BDF75FFF****",
"NextToken": "CAESEgoQCg4KCkltYWdlQ291bnQQARgBIr0ECgkABAAAAAAAAAAKrwQDKgIAADFTMzEzMDMyMzMzMjMxMzAzMDMyMzQzNjM3MzczOTMzMzQzYTY5NmQ2ZDJkNjk2ZDYxNjc2NTJkNzQ2NTczNzQyZDY4N2E2NDY1NzYyZDMyMzUzMjM0MzIzOTMzMzczMTJkMzY1NDZhNzk3MzU2Njk3MjM0M2E2OTZkNmQyZDc0NjU3Mzc0MmQ3MzY1NzQyZDYzMzYzNjY0MzY2NjYxMzQyZDM1MzMzODM3MmQzMTMxNjU2NjJkNjI2NTM5MzYyZDM5MzgzMDMzMzk2MjMwMzE2NDYzNjMzMjNhNjY2OTY3NzU3MjY1MmQ2MzZjNzU3Mzc0NjU3MjNhNDM2Yzc1NzM3NDY1NzIyZDYxNjUzOTY0MzQzMzMxNjEyZDM3MzQ2NTY2MmQzNDM5Mzc2MjJkMzg2MjMxMzUyZDM0MzUzOTM1MzYzNzYxMzQ2NDM2MzE2Ni5TMzEzMDMyMzMzMjMxMzAzMDMyMzQzNjM3MzczOTMzMzQzYTY5NmQ2ZDJkNjk2ZDYxNjc2NTJkNzQ2NTczNzQyZDY4N2E2NDY1NzYyZDMyMzUzMjM0MzIzOTMzMzczMTJkMzY1NDZhNzk3MzU2Njk3MjM0M2E2OTZkNmQyZDc0NjU3Mzc0MmQ3MzY1NzQyZDYzMzYzNjY0MzY2NjYxMzQyZDM1MzMzODM3MmQzMTMxNjU2NjJkNjI2NTM5MzYyZDM5MzgzMDMzMzk2MjMwMzE2NDYzNjM*****",
"FigureClusters": [
{
"OwnerId": "102321002****",
"ProjectName": "immtest",
"DatasetName": "dataset001",
"ObjectType": "figure-cluster",
"ObjectId": "Cluster-ae6e3472-999e-410b-b54e-cd5dba****",
"UpdateTime": "2022-01-14T10:10:52.83948013+08:00",
"CreateTime": "2022-01-14T10:10:52.83948013+08:00",
"Name": "abc",
"Gender": "female",
"FaceCount": 3,
"ImageCount": 5,
"VideoCount": 3,
"AverageAge": 26,
"MinAge": 12,
"MaxAge": 44,
"Cover": {
"OwnerId": "102321002467****",
"ProjectName": "test-project",
"DatasetName": "test-dataset",
"ObjectType": "file",
"ObjectId": "75d5de2c50754e3dadd5c35dbca5f9949369e37eb342a73821f690c94c36c7f7",
"UpdateTime": "2021-06-29T14:50:13.011643661+08:00",
"CreateTime": "2021-06-29T14:50:13.011643661+08:00",
"URI": "oss://test-bucket/test-object.jpg",
"OSSURI": "oss://examplebucket/sampleobject.jpg",
"Filename": "sampleobject.jpg",
"MediaType": "image",
"ContentType": "image/jpeg",
"Size": 1000,
"FileHash": "1d9c280a7c4f67f7ef873e28449dbe17",
"FileModifiedTime": "2021-06-29T14:50:13.011643661+08:00",
"FileCreateTime": "2021-06-29T14:50:13.011643661+08:00",
"FileAccessTime": "2021-06-29T14:50:13.011643661+08:00",
"ProduceTime": "2021-06-29T14:50:13.011643661+08:00",
"LatLong": "30.134390,120.074997",
"Timezone": "\"\"",
"Addresses": [
{
"Language": "zh-Hans",
"AddressLine": "中国浙江省杭州市余杭区文一西路969号",
"Country": "中国",
"Province": "浙江省",
"City": "杭州市",
"District": "余杭区",
"Township": "文一西路"
}
],
"TravelClusterId": "-",
"Orientation": 0,
"Figures": [
{
"FigureId": "868a9e74-cde5-4c7a-9013-28bb984****",
"FigureConfidence": 1,
"FigureClusterId": "Cluster-dbe72fec-b84c-4ab6-885b-3678e64****",
"FigureClusterConfidence": 1,
"FigureType": "face",
"Age": 29,
"AgeSD": 5,
"Gender": "female",
"GenderConfidence": 1,
"Emotion": "happiness",
"EmotionConfidence": 0.70784568786621,
"FaceQuality": 0.960875928401947,
"Boundary": {
"Width": 200,
"Height": 300,
"Left": 10,
"Top": 30,
"Polygon": [
{
"X": 10,
"Y": 10
}
]
},
"Mouth": "close",
"MouthConfidence": 1,
"Beard": "none",
"BeardConfidence": 1,
"Hat": "none",
"HatConfidence": 1,
"Mask": "none",
"MaskConfidence": 1,
"Glasses": "none",
"GlassesConfidence": 0.8,
"Sharpness": 0.7,
"Attractive": 0.96,
"HeadPose": {
"Pitch": 18.385589599609375,
"Roll": 4.204030513763428,
"Yaw": 2.4945924282073975
}
}
],
"FigureCount": 10,
"Labels": [
{
"Language": "zh-Hans",
"LabelName": "椅子",
"LabelLevel": 2,
"LabelConfidence": 0.95,
"ParentLabelName": "家具",
"CentricScore": 0.877,
"LabelAlias": "",
"Clips": [
{
"TimeRange": [
0
]
}
]
}
],
"Title": "test",
"ImageWidth": 270,
"ImageHeight": 500,
"EXIF": "{\"Compression\":{\"value\":\"6\"},\"DateTime\":{\"value\":\"2020:08:19 17:11:11\"}}",
"ImageScore": {
"OverallQualityScore": 0.736
},
"CroppingSuggestions": [
{
"AspectRatio": "2:3",
"Confidence": 0.742,
"Boundary": {
"Width": 200,
"Height": 300,
"Left": 10,
"Top": 30,
"Polygon": [
{
"X": 10,
"Y": 10
}
]
}
}
],
"OCRContents": [
{
"Language": "zh-hans",
"Contents": "欢迎使用智能媒体管理",
"Confidence": 0.8254936695098877,
"Boundary": {
"Width": 200,
"Height": 300,
"Left": 10,
"Top": 30,
"Polygon": [
{
"X": 10,
"Y": 10
}
]
}
}
],
"VideoWidth": 1080,
"VideoHeight": 1920,
"VideoStreams": [
{
"Index": 0,
"Language": "en",
"CodecName": "h264",
"CodecLongName": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
"Profile": "High",
"CodecTimeBase": "1373627/83160000",
"CodecTagString": "avc1",
"CodecTag": "0x31637661",
"Width": 1280,
"Height": 720,
"HasBFrames": 2,
"SampleAspectRatio": "1:1",
"DisplayAspectRatio": "16:9",
"PixelFormat": "yuv420p",
"Level": 40,
"FrameRate": "25/1",
"AverageFrameRate": "25/1",
"TimeBase": "1/12800",
"StartTime": 0,
"Duration": 22.88,
"Bitrate": 5407765,
"FrameCount": 572,
"Rotate": "90",
"BitDepth": 8,
"ColorSpace": "bt709",
"ColorRange": "tv",
"ColorTransfer": "bt709",
"ColorPrimaries": "bt709"
}
],
"Subtitles": [
{
"Index": 2,
"Language": "en",
"CodecName": "mov_text",
"CodecLongName": "MOV text",
"CodecTagString": "tx3g",
"CodecTag": "0x67337874",
"StartTime": 0,
"Duration": 71.378,
"Bitrate": 74,
"Content": "欢迎",
"Width": 600,
"Height": 30
}
],
"AudioStreams": [
{
"Index": 1,
"Language": "en",
"CodecName": "aac",
"CodecLongName": "AAC (Advanced Audio Coding)",
"CodecTimeBase": "1/44100",
"CodecTagString": "mp4a",
"CodecTag": "0x6134706d",
"TimeBase": "1/48000",
"StartTime": 0.0235,
"Duration": 3.690667,
"Bitrate": 320087,
"FrameCount": 173,
"Lyric": "test",
"SampleFormat": "fltp",
"SampleRate": 48000,
"Channels": 2,
"ChannelLayout": "stereo"
}
],
"Artist": "Jane",
"AlbumArtist": "Jane",
"AudioCovers": [
{
"ImageWidth": 500,
"ImageHeight": 820,
"EXIF": "{\"FileSize\":{\"value\":\"29304\"},\"Format\":{\"value\":\"jpg\"}}",
"ImageScore": {
"OverallQualityScore": 0.736
},
"CroppingSuggestions": [
{
"AspectRatio": "2:3",
"Confidence": 0.742
}
],
"OCRContents": [
{
"Language": "zh-hans",
"Contents": "欢迎使用智能媒体管理",
"Confidence": 0.8254936695098877
}
]
}
],
"Composer": "Jane",
"Performer": "Jane",
"Language": "eng",
"Album": "FirstAlbum",
"PageCount": 5,
"ETag": "\"1D9C280A7C4F67F7EF873E28449****\"",
"CacheControl": "no-cache",
"ContentDisposition": "attachment; filename =test.jpg",
"ContentEncoding": "UTF-8",
"ContentLanguage": "zh-CN",
"AccessControlAllowOrigin": "https://aliyundoc.com",
"AccessControlRequestMethod": "PUT",
"ServerSideEncryptionCustomerAlgorithm": "SM4",
"ServerSideEncryption": "AES256",
"ServerSideDataEncryption": "SM4",
"ServerSideEncryptionKeyId": "9468da86-3509-4f8d-a61e-6eab1eac****",
"OSSStorageClass": "Standard",
"OSSCRC64": "559890638950338001",
"ObjectACL": "default",
"ContentMd5": "HZwoCnxPZ/fvhz4oRJ2+Fw==",
"OSSUserMeta": {
"key": "val"
},
"OSSTaggingCount": 2,
"OSSTagging": {
"key": "val"
},
"OSSExpiration": "2120-01-01T12:00:00.000Z",
"OSSVersionId": "CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****",
"OSSDeleteMarker": "CAEQMhiBgIDXiaaB0BYiIGQzYmRkZGUxMTM1ZDRjOTZhNjk4YjRjMTAyZjhl****",
"OSSObjectType": "Normal",
"CustomId": "\t\nmember-image-id-0001",
"CustomLabels": {
"MemberName": "Tim",
"Enabled": "True",
"ItemCount": "10"
},
"StreamCount": 1,
"ProgramCount": 1,
"FormatName": "mov",
"FormatLongName": "QuickTime / MOV",
"StartTime": 0,
"Bitrate": 13091201,
"Duration": 15.263,
"SemanticTypes": [
"content"
],
"Elements": [
{
"ElementContents": [
{
"Type": "text",
"Content": "文本片段",
"URL": "http://aliyun.com",
"TimeRange": [
500
]
}
],
"ObjectId": "id1",
"ElementType": "title - 标题； image - 图片 ； table - 表格 ； narrative-text - 正文",
"SemanticSimilarity": 0.8,
"ElementRelations": [
{
"Type": "child，parent",
"ObjectId": "id1"
}
]
}
],
"SceneElements": [
{
"TimeRange": [
100
],
"FrameTimes": [
30
],
"VideoStreamIndex": 0,
"Labels": [
{
"Language": "zh-Hans",
"LabelName": "椅子",
"LabelLevel": 2,
"LabelConfidence": 0.95,
"ParentLabelName": "家具",
"CentricScore": 0.877,
"LabelAlias": "",
"Clips": [
{
"TimeRange": [
0
]
}
]
}
]
}
],
"OCRTexts": "阿里云IMM",
"Reason": "[InternalError] The request has been failed due to some unknown error. status: 500, requestId: CC5ACFBD-BB7A-496D-A9D6-****",
"ObjectStatus": "Indexed",
"Insights": {
"Video": {
"Description": "无。",
"Caption": "视频中展示了两个不同场景：一个是静止的白色盘子、黑色瓶子和透明玻璃杯，另一个是手拿着标有“YEZOLU”的洗发水瓶在浴室中缓慢上移。"
},
"Image": {
"Caption": "无。",
"Description": "图片中有一人，穿着深色西装外套，内搭白色衬衫。背景为渐变的浅蓝色至灰色。"
}
}
},
"CustomId": "abc",
"CustomLabels": {
"Bucket": "examplebucket"
},
"MetaLockVersion": 0
}
],
"TotalCount": 100
}Error codes
See Error Codes for a complete list.
Release notes
See Release Notes for a complete list.