调用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
        }
    ]
}