全部产品
云市场

CreateGroupFacesJob 人脸聚类

更新时间:2019-03-21 10:18:31

描述

接口公测中,如有任何使用问题请 联系我们

聚类功能仅对 2019.3.12 后使用 IndexImage 接口将图片索引至 媒体集 Set 内的图片有效。历史图片如需使用,请从 Set 中删除并重新索引。

对媒体集 Set 内的人脸进行聚类操作,即将同一人物的人脸分为一组,并将组信息保存至人脸的 GroupId 中。

一些原则

该接口为增量聚类。每次调用会对 Set 内新增图片进行分类,同时已经分好的类,以及尚未能够分类的图片也会参与到该次聚类操作。

对同一个 Set ,同一时间只能有一个人脸聚类任务进行。因此在调用该接口时,应确保上一次调用已经结束。可以通过 Notify 订阅来获得任务执行结果的通知。

每个聚类任务最长执行时间为 2 分钟。单次聚类最多处理 5100 张图片中的人脸。如果在 Set 中添加了超过限制数量的图片,则需要多次调用接口。

一旦人脸已经被分组,本接口就不会修改其分组,即使有更适合的分组出现。

一旦一个组已经形成,则该组也不会被合并到其他分组。

可以通过 ListFaceGroups 接口查看已经有的分组列表,并可以通过 FindImages 接口,根据 GroupId 搜索该组的人脸图片。

GroupId 分组 ID 的命名规则

一个已经形成的分组,通常以 Group-{UUID-v4} 格式命名,即 Group- 后接一个 UUIDv4 格式的字符串。

如下分组为保留的特殊分组命名:

  • group-none 该人脸暂时没有合适的分组,未来新增图片后该人脸可能被分入组中
  • group-not-grouped 该人脸暂时没有被检测过分组,即新增图片 IndexImage 后未调用 CreateGroupFacesJob API。
  • group-none-by-user 由用户手动操作,记录该人脸没有合适的分组,未来新增图片后该人脸 仍不会 被分入组中

请求参数

Parameter Type Required Comment
Project string Y Project
SetId string Y 媒体集 SetId
NotifyTopicName string N MNS 订阅的 Topic 主题名称
NotifyEndpoint string N MNS 订阅的 Endpoint

关于 MNS 的使用方式,参考 消息服务 MNS 概述

返回参数

Parameter Type Comment
JobType string 任务类型,返回固定值 GroupImageFacesJob
JobId string 任务唯一 ID
SetId string 媒体集 ID

示例

请求示例

  1. POST https://imm.cn-shanghai.aliyuncs.com
  2. ?Action=GroupImageFacesJob
  3. &Project=test-project
  4. &SetId=test-set
  5. ...

此处的示例,目的是展示关键参数,还需要其他的公共参数才能正常调用,推荐使用 SDK 来发送 API

成功返回示例

  1. {
  2. "JobType": "GroupImageFacesJob",
  3. "JobId": "GroupImageFacesJob-9bab56e8-e596-421a-b1f5-9ad1ab875fe4",
  4. "RequestId": "B121940C-9794-4EE3-8D6E-F8EC525F138A",
  5. "SetId": "t-group-s"
  6. }

订阅消息返回示例

返回参数

Parameter Type Comment
eventName string 任务类型,返回固定值 GroupImageFacesJob
imm.JobId string 任务唯一 ID
imm.SetId string 媒体集 ID
imm.NewGroupCount string 新增人脸分组数量
imm.UpdateFaceCount string 更新人脸分组的人脸数量,包括新增图片,和旧有图片被分组
imm.UpdateGroupCount string 更新的人脸分组

MNS 返回的消息格式如:

  1. {
  2. "events": [
  3. {
  4. "eventName": "GroupImageFacesJob",
  5. "eventSource": "acs:imm",
  6. "eventTime": "2019-02-20T11:06:25.264Z",
  7. "eventVersion": "1.0",
  8. "imm": {
  9. "ErrorCode": "",
  10. "JobId": "GroupImageFacesJob-a7c8f7a4-5c22-42df-8615-74a61efc4374",
  11. "NewGroupCount": "1",
  12. "SetId": "t-group-s",
  13. "Success": "true",
  14. "UpdateFaceCount": "10",
  15. "UpdateGroupCount": "1"
  16. }
  17. }
  18. ]
  19. }

若在使用中有疑问,请参考 FAQ,或者进入 钉钉用户群 实时交流。