调用ListFaceGroups接口获取一个媒体集中的人脸分组列表。

注意事项

如果需要根据标记信息等查询人脸分组，必须已调用UpdateFaceGroup接口为人脸分组配置相应信息。

说明 接口公测中，如有任何使用问题请加入钉钉用户群（钉钉群号：21714099）实时交流。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String 是 ListFaceGroups

操作接口名称，系统规定参数，固定取值为ListFaceGroups。
SetId String 是 set001

媒体集的唯一标识。
Project String 是 immimagetest

项目名称。
RegionId String 否 cn-hangzhou

项目所在地域的ID。

地域Endpoint格式为imm.RegionId.aliyuncs.com，例如当RegionId为cn-hangzhou时，地域Endpoint为imm.cn-hangzhou.aliyuncs.com。

Marker String 否 CAESEQoPCg0KCUZhY2VDb3VudBABGAEirQEKCQAFAAAAAAAAAAqfAQOaAAAAMVMzMTM3MzQzNjM0MzkzNTM4MzUzNzM2MzAzMjM3MzQzNTNhNjk2ZDZkNjk2ZDYxNjc2NTNhNzM2NTc0NzQ2NTczNzQuUzQ3NzI2Zjc1NzAyZDM0Mzg2NjY0NjQzNDYyNjQyZDM2MzI2MzMzMmQzNDY0NjE2MTJkNjE2NDM5MzgyZDYxNjUzNjYxMzQzMTM3MzM2MTMxMzMzMA==

从Marker开始按字典序返回人脸分组信息列表。如果不设置此参数，则从头开始返回人脸分组信息。
Limit Integer 否 5

返回人脸分组的最大个数，默认值为20，取值范围为1~100。
Order String 否 DESC

排序方式，默认值为DESC。

  • ASC：升序
  • DESC：降序
OrderBy String 否 FaceCount

排序字段，默认值为FaceCount。

  • CreateTime：人脸分组的创建时间。
  • ModifyTime：人脸分组的修改时间。
  • FaceCount：人脸分组中的人脸数量。
RemarksAQuery String 否 {"PREFIX": "start-with-this","NOT-PREFIX": "not-start-with-this","IN": ["ONE","OF","THIS"],"NOT-IN": ["NONE","FROM","THOSE"]}

标记信息查询条件，包括如下四种查询方式，可根据实际选择其中若干项条件进行查询。

  • PREFIX：前缀匹配。
  • NOT-PREFIX：非前缀匹配。
  • IN：全字匹配，必须完全符合IN中指定的任意一个字符串。
  • NOT-IN：全字匹配，必须不符合NOT-IN中指定的任意一个字符串。
RemarksBQuery String 否 {"PREFIX": "start-with-this","NOT-PREFIX": "not-start-with-this","IN": ["ONE","OF","THIS"],"NOT-IN": ["NONE","FROM","THOSE"]}

标记信息查询条件，包括如下四种查询方式，可根据实际选择其中若干项条件进行查询。

  • PREFIX：前缀匹配。
  • NOT-PREFIX：非前缀匹配。
  • IN：全字匹配，必须完全符合IN中指定的任意一个字符串。
  • NOT-IN：全字匹配，必须不符合NOT-IN中指定的任意一个字符串。
RemarksCQuery String 否 {"PREFIX": "start-with-this","NOT-PREFIX": "not-start-with-this","IN": ["ONE","OF","THIS"],"NOT-IN": ["NONE","FROM","THOSE"]}

标记信息查询条件，包括如下四种查询方式，可根据实际选择其中若干项条件进行查询。

  • PREFIX：前缀匹配。
  • NOT-PREFIX：非前缀匹配。
  • IN：全字匹配，必须完全符合IN中指定的任意一个字符串。
  • NOT-IN：全字匹配，必须不符合NOT-IN中指定的任意一个字符串。
RemarksDQuery String 否 {"PREFIX": "start-with-this","NOT-PREFIX": "not-start-with-this","IN": ["ONE","OF","THIS"],"NOT-IN": ["NONE","FROM","THOSE"]}

标记信息查询条件，包括如下四种查询方式，可根据实际选择其中若干项条件进行查询。

  • PREFIX：前缀匹配。
  • NOT-PREFIX：非前缀匹配。
  • IN：全字匹配，必须完全符合IN中指定的任意一个字符串。
  • NOT-IN：全字匹配，必须不符合NOT-IN中指定的任意一个字符串。
RemarksArrayAQuery String 否 {"PREFIX": "start-with-this","NOT-PREFIX": "not-start-with-this","IN": ["ONE","OF","THIS"],"NOT-IN": ["NONE","FROM","THOSE"]}

标记信息查询条件，包括如下四种查询方式，可根据实际选择其中若干项条件进行查询。

  • PREFIX：前缀匹配。
  • NOT-PREFIX：非前缀匹配。
  • IN：全字匹配，必须完全符合IN中指定的任意一个字符串。
  • NOT-IN：全字匹配，必须不符合NOT-IN中指定的任意一个字符串。
RemarksArrayBQuery String 否 {"PREFIX": "start-with-this","NOT-PREFIX": "not-start-with-this","IN": ["ONE","OF","THIS"],"NOT-IN": ["NONE","FROM","THOSE"]}

标记信息查询条件，包括如下四种查询方式，可根据实际选择其中若干项条件进行查询。

  • PREFIX：前缀匹配。
  • NOT-PREFIX：非前缀匹配。
  • IN：全字匹配，必须完全符合IN中指定的任意一个字符串。
  • NOT-IN：全字匹配，必须不符合NOT-IN中指定的任意一个字符串。
ExternalId String 否 externalId001

外部ID，用于和您的应用层的ID（如果有）进行绑定。查询类型为精确匹配。

返回数据

名称 类型 示例值 描述
FaceGroups Array of FaceGroups

人脸分组信息列表。
AverageAge Float 26.4

人脸分组中人脸的平均年龄。
CreateTime String 2021-01-11T02:18:26.174Z

人脸分组的创建时间。
ExternalId String externalIdtest

外部ID，用于和您的应用层的ID（如果有）进行绑定。
FaceCount Integer 5

人脸分组中的人脸数量。
Gender String MALE

人脸的性别。
GroupCoverFace Struct

人脸分组封面图信息。
FaceBoundary Struct

人脸位置框信息。
Height Integer 45

人脸位置框高度。单位为px。
Left Integer 80

顶点X坐标，距离左端距离。单位为px。
Top Integer 49

顶点Y坐标，距离顶端距离。单位为px。
Width Integer 46

人脸位置框宽度。单位为px。
FaceId String b30a7a36997ce986965680fed90c397fc70a533af511346f819976c6a138c594

人脸分组封面图的FaceId，可以使用媒体集图片处理相关接口（例如GetImage、ListImages等）获得该FaceId。

FaceId必须为同一分组 （即GroupId相同）中的人脸ID。
ImageUri String oss://imm-test/testcases/face1.jpg

图片的OSS URI。

OSS地址规则为oss://bucket/object，其中bucket为和当前项目处于同一区域的OSS Bucket名称，object为文件路径。

GroupId String Group-48fdd4bd-62c3-4daa-ad98-ae6a4173a130

人脸分组的唯一标识。
GroupName String facegrouptest

人脸分组名称。
ImageCount Integer 5

人脸分组中的图片数量。
MaxAge Float 28

人脸分组中人脸的最大年龄。
MinAge Float 23

人脸分组中人脸的最小年龄。
ModifyTime String 2021-01-11T02:18:26.174Z

人脸分组的修改时间。
RemarksA String oss://imm-test/testcases/

人脸分组的标记信息，为使用者预留的筛选参数，用于记录所需要的信息。
RemarksArrayA String ["remarksa1","remarksa2"]

标记信息列表，格式为数组。
RemarksArrayB String ["remarksb1","remarksb2"]

标记信息列表，格式为数组。
RemarksB String face1.jpg

人脸分组的标记信息，为使用者预留的筛选参数，用于记录所需要的信息。
RemarksC String 浙江省杭州市

人脸分组的标记信息，为使用者预留的筛选参数，用于记录所需要的信息。
RemarksD String 浙江省杭州市

人脸分组的标记信息，为使用者预留的筛选参数，用于记录所需要的信息。
NextMarker String CAESEQoPCg0KCUZhY2VDb3VudBABGAEirQEKCQAFAAAAAAAAAAqfAQOaAAAAMVMzMTM3MzQzNjM0MzkzNTM4MzUzNzM2MzAzMjM3MzQzNTNhNjk2ZDZkNjk2ZDYxNjc2NTNhNzM2NTc0NzQ2NTczNzQuUzQ3NzI2Zjc1NzAyZDM0Mzg2NjY0NjQzNDYyNjQyZDM2MzI2MzMzMmQzNDY0NjE2MTJkNjE2NDM5MzgyZDYxNjUzNjYxMzQzMTM3MzM2MTMxMzMzMA==

下一次列出人脸分组信息时以此值为Marker，将未返回的结果返回。

当人脸分组未全部返回时，此参数才有值。
RequestId String 6CD6F064-6999-4B64-B057-5FBD09E48C46

当次请求的Request ID。

示例

请求示例

http(s)://[Endpoint]/?Action=ListFaceGroups
&SetId=set001
&Project=immimagetest
&<公共请求参数>

正常返回示例

XML 格式 

<RequestId>6CD6F064-6999-4B64-B057-5FBD09E48C46</RequestId>
<NextMarker>CAESEQoPCg0KCUZhY2VDb3VudBABGAEirQEKCQAFAAAAAAAAAAqfAQOaAAAAMVMzMTM3MzQzNjM0MzkzNTM4MzUzNzM2MzAzMjM3MzQzNTNhNjk2ZDZkNjk2ZDYxNjc2NTNhNzM2NTc0NzQ2NTczNzQuUzQ3NzI2Zjc1NzAyZDM0Mzg2NjY0NjQzNDYyNjQyZDM2MzI2MzMzMmQzNDY0NjE2MTJkNjE2NDM5MzgyZDYxNjUzNjYxMzQzMTM3MzM2MTMxMzMzMA==</NextMarker>
<FaceGroups>
    <GroupName>facegrouptest</GroupName>
    <GroupCoverFace>
        <FaceId>b30a7a36997ce986965680fed90c397fc70a533af511346f819976c6a138c594</FaceId>
        <FaceBoundary>
            <Left>80</Left>
            <Top>49</Top>
            <Height>45</Height>
            <Width>46</Width>
        </FaceBoundary>
        <ImageUri>oss://imm-test/testcases/face1.jpg</ImageUri>
    </GroupCoverFace>
    <ModifyTime>2021-01-11T02:18:26.174Z</ModifyTime>
    <ExternalId>externalIdtest</ExternalId>
    <CreateTime>2021-01-11T02:18:26.174Z</CreateTime>
    <MaxAge>28</MaxAge>
    <Gender>MALE</Gender>
    <AverageAge>26.4</AverageAge>
    <RemarksA>oss://imm-test/testcases/</RemarksA>
    <RemarksB>face1.jpg</RemarksB>
    <GroupId>Group-48fdd4bd-62c3-4daa-ad98-ae6a4173a130</GroupId>
    <RemarksArrayB>["remarksb1","remarksb2"]</RemarksArrayB>
    <MinAge>23</MinAge>
    <ImageCount>5</ImageCount>
    <RemarksC>浙江省杭州市</RemarksC>
    <RemarksD>浙江省杭州市</RemarksD>
    <RemarksArrayA>["remarksa1","remarksa2"]</RemarksArrayA>
    <FaceCount>5</FaceCount>
</FaceGroups>

JSON 格式 

{
    "RequestId": "6CD6F064-6999-4B64-B057-5FBD09E48C46",
    "NextMarker": "CAESEQoPCg0KCUZhY2VDb3VudBABGAEirQEKCQAFAAAAAAAAAAqfAQOaAAAAMVMzMTM3MzQzNjM0MzkzNTM4MzUzNzM2MzAzMjM3MzQzNTNhNjk2ZDZkNjk2ZDYxNjc2NTNhNzM2NTc0NzQ2NTczNzQuUzQ3NzI2Zjc1NzAyZDM0Mzg2NjY0NjQzNDYyNjQyZDM2MzI2MzMzMmQzNDY0NjE2MTJkNjE2NDM5MzgyZDYxNjUzNjYxMzQzMTM3MzM2MTMxMzMzMA==",
    "FaceGroups": [
        {
            "GroupName": "facegrouptest",
            "GroupCoverFace": {
                "FaceId": "b30a7a36997ce986965680fed90c397fc70a533af511346f819976c6a138c594",
                "FaceBoundary": {
                    "Left": 80,
                    "Top": 49,
                    "Height": 45,
                    "Width": 46
                },
                "ImageUri": "oss://imm-test/testcases/face1.jpg"
            },
            "ModifyTime": "2021-01-11T02:18:26.174Z",
            "ExternalId": "externalIdtest",
            "CreateTime": "2021-01-11T02:18:26.174Z",
            "MaxAge": 28,
            "Gender": "MALE",
            "AverageAge": 26.4,
            "RemarksA": "oss://imm-test/testcases/",
            "RemarksB": "face1.jpg",
            "GroupId": "Group-48fdd4bd-62c3-4daa-ad98-ae6a4173a130",
            "RemarksArrayB": "[\"remarksb1\",\"remarksb2\"]",
            "MinAge": 23,
            "ImageCount": 5,
            "RemarksC": "浙江省杭州市",
            "RemarksD": "浙江省杭州市",
            "RemarksArrayA": "[\"remarksa1\",\"remarksa2\"]",
            "FaceCount": 5
        }
    ]
}