更新时间：2021 年 7 月 21 日

# 服务介绍

相册聚类服务是在一个照片相册中，将所有包含相同人脸的照片划分为一组的处理。

# 技术特色

• 响应快速：提供毫秒级响应速度
• 不限相册数量：海量照片归类处理

您可以通过 相册聚类 页面进行在线体验。

# 应用场景

• 云端相册：基于人脸的智能分类
• 照片直播：在一场活动的照片中找到包含某个人所有照片
• 赛事活动：赛后查询包含某个选手的所有照片

# 业务流程设计参考

# 流程简介

Face++ 在收到业务系统发送的照片后，首先对每张照片生成 image_id，然后抽取照片中每张人脸的特征，并为每张人脸生成唯一特征标识 face_token 返回给业务系统（请注意：Face++ 不保存照片）；而业务系统需要保存每个相册中每张照片与人脸特征标识 (face_token) 的映射关系。Face++ 在进行聚类处理后，将输出人脸特征标识 (face_token) 的分组信息 Group_id，相同的人脸包含相同的 Group_id，从而分为一组。

# 核心业务流程说明

使用 Face++ 实现基于人脸的云端相册分类处理，大致流程如下：

# 数据映射关系

Face++ 的聚类服务以“相册”为单位，针对每个相册，数据的映射关系如下：

# 说明

1. 业务系统中，照片 1、照片 2、照片 n 中，分别包含 2 张、3 张、3 张人脸，系统向 Face++ 添加照片后，Face++ 会为每张人脸创建一个 FaceToken 并返回给业务系统：
   a) 照片1：FaceToken1、FaceToken2；
   b) 照片2：FaceToken3、FaceToken4、FaceToken5
   c) 照片n：FaceTokenK、FaceTokenL、FaceTokenM
   业务系统和 Face++ 都要保存这些 FaceToken。

2. Face++ 进行聚类处理时，会为每张人脸生成一个 Group_id 并返回给业务系统，相同的 Group_id 即为相同的人脸。

# 相关术语说明

1. 业务系统：使用 Face++ 服务的客户的系统，包括处理用户交互、存储照片、照片展示等。
2. faceAlbumtoken：每个相册（FaceAlbum）的唯一标识。
3. image_id：每张照片的唯一标识。请注意：Face++ 不保存照片本身。
4. face_token：对每张图片检测时，检测到照片中每张人脸的唯一特征标识。请注意：对不同照片中的同一个人脸进行检测时，会得到不同的人脸特征标识 (face_token)。
5. group_id：对一个相册中所有照片“聚类”后，得到的每一个face_token的分组结果。

# 接口说明

1. 创建相册 API：Face++ 的相册 (Album) 与业务系统的“相册”相对应，一个用户的云端相册中所有照片或者一场活动中的所有照片，保存在一个 FaceAlbum 中。
   
   主要参数：无
   
   主要输出：facealbum_token，用于标识一个唯一的 FaceAlbum。
   
   业务流程如图所示：
   

2. 添加图片 API：向 FaceAlbum 中添加照片，用于后续的人脸聚类。每个 FaceAlbum 中，最多存储 1 万张人脸特征标识 (face_token)。
   
   主要参数：
   facealbum_token，用于指定FaceAlbum
   image_url/image_file/image_base64：用于指定图片
   
   主要输出：
   faces：包含照片中每个人脸特征标识 (face_token) 以及对应的矩形框位置
   image_id：这张照片在 Face++ 系统中的唯一标识
   
   业务流程如图所示：
   

3. 聚类人脸（异步） API：调用本接口，为 FaceAlbum 中所有的人脸特征标识 (face_token) 进行聚类（分组）处理，处理结果是为每个 face_token 分配一个 group_id，表示聚类（分组）结果，相同的group_id 意味着相同的分组，即相同的人脸。注：此接口为异步接口，需要后续再调用“查询聚类结果”接口查询聚类结果。
   
   主要参数：
   facealbum_token，用于指定 FaceAlbum
   operation_type：用于指定分组类型
   entirefacealbum：全量操作，针对当前 FaceAlbum 中所有的照片进行聚类操作。
   incremental：增量操作（默认），针对已经进行过聚类操作的 FaceAlbum，新添加图片后，可以采用增量的方式进行聚类，只把新图片进行聚类操作，提高效率。
   
   主要输出：
   task_id：标识聚类请求的任务id，用户后续查询结果
   
   业务流程如图所示：
   

4. 搜索图片（异步） API：用于用户上传一张图片，在相册中搜索所有包含图片中人脸的照片。注：此接口为异步接口，需要后续再调用“查询聚类结果”接口查询聚类结果。
   
   主要参数：
   facealbum_token
   image_url/image_file/image_base64：用于指定图片
   
   主要输出：
   task_id：搜索图片请求的任务id，用户后续查询结果
   

5. 搜索图片结果查询 API：用查询搜索图片的结果，返回分组信息 group_id。
   
   主要参数：
   task_id：搜索图片请求的任务 id
   
   主要输出：
   Status：搜索图片任务是否已经完成
   face_rectangle：返回人脸在图片中的位置
   image_id_set：拥有该人脸的所有图片的 image_id

# 计费方式

相册聚类 API 组有如下 2 种计费模式：

1. 按量计费：组内每一个 API 的详细计费请见 API 价目表 - 人脸识别 - 按量计费。

2. 包时计费：按天或按月订购，在付费时段内无限量调用，可灵活指定服务起始时间。并发数可根据实际需求开通。
   a. 按天：400 元 / 天 / QPS。如 5 QPS 使用 3 天，价格是 400 x 5 x 3 = 6000 元。
   b. 按月（30天）：5000 元 / 月 / QPS。如 2 QPS 使用 1 个月，价格是 5000 x 2 x 1 = 10000 元。

详细计费说明可见 API 价目表。