本文介绍了调用图片同步检测（imageScan）接口进行自定义人脸检索的方法。自定义人脸检索能够从指定的个体库中检索特定的人脸图片，并返回与目标最相似的5个个体。
场景说明
自定义人脸检索根据您传入的待识别人脸图片（face），在个体组（group）中查找并返回Top 5最相似的个体（person），返回的Top 5个体按照相似度从大到小排序。
参数 | 说明 | 相关接口 |
person | 个体，表示一个自然人。 | |
face | 人脸，表示个体关联的人脸图片。 一个个体可以关联多个人脸图片。 | |
group | 个体组，表示个体的集合。 一个个体可以属于多个组，一个组也可以包含多个个体。 |
使用说明
您可以调用imageScan接口创建图片同步检测任务。关于如何构造HTTP请求，请参见请求结构；您也可以直接选用已构造好的HTTP请求，更多信息，请参见SDK概览。
计费信息：
该接口为收费接口。关于计费方式，请参见内容安全产品定价。
检测超时：
同步检测允许的最长检测时间是6秒，如果检测在该时间限制内没有完成，系统会强制返回超时错误码。如果您对实时性要求不高，可以选择异步检测，其他情况下请选择同步检测，同步检测接口的调用相对简单些。对于同步检测接口的调用，建议您将超时时间设置为6秒。
返回结果：
同步检测请求一般会在一秒内同步返回结果，但在一些特殊场景（例如系统繁忙导致堆积严重、图片较大、含有OCR内容较多等），耗时可能会增加。
图片要求：
图片链接支持以下协议：HTTP和HTTPS。
图片支持以下格式：PNG、JPG、JPEG、BMP、GIF、WEBP。
图片大小限制为20 MB以内（适用于同步和异步调用），高度或者宽度不能超过30,000像素（px），且图像总像素不超过2.5亿（px）。
说明其中，GIF格式的图片，图像总像素不超过4,194,304（px），高度或者宽度不能超过30,000像素（px）。
图片下载时间限制为3秒内，如果下载时间超过3秒，返回下载超时。
图片像素建议不低于256*256（px），像素过低可能会影响识别效果。
图片检测接口的响应时间依赖图片的下载时间。请保证被检测图片所在的存储服务稳定可靠，建议您使用阿里云OSS存储或者CDN缓存等。
QPS限制
本接口的单用户QPS限制为50次/秒。超过限制，API调用会被限流，这可能会影响您的业务，请合理调用。
请求语法
POST /green/image/scan HTTPS|HTTP请求头
该接口使用公共请求头，无特殊请求头。请参见公共请求头。
请求参数
名称 | 类型 | 是否必选 | 示例值 | 描述 |
clientInfo | JSONObject | 否 | {"userId":"120234234","userNick":"Mike","userType":"others"} | 客户端信息，由ClientInfo结构体通过JSON序列化获得，包含umid、imei等信息，具体结构描述，请参见ClientInfo。 |
RequestBody
RequestBody中还需要填入以下参数，用来指定检测场景和任务信息。
名称 | 类型 | 是否必选 | 示例值 | 描述 |
bizType | String | 否 | edu | 业务场景类型。自定义人脸检索场景下无需传入该参数。 |
scenes | StringArray | 是 | ["sface-n"] | 检测场景，取值：sface-n，表示自定义人脸检索。 |
tasks | JSONArray | 是 | 待检测人脸图片的信息。具体结构描述，请参见task。 |
表 1. task
名称 | 类型 | 是否必选 | 示例值 | 描述 |
dataId | String | 否 | test2NInmOtAON6qYUrtCRgLo-1mwxdi | 检测对象对应的数据ID。 由大小写英文字母、数字、下划线（_）、短划线（-）、英文句号（.）组成，不超过128个字符，可以用于唯一标识您的业务数据。 |
url | String | 是 | https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png | 待检测人脸图片的URL。 |
extras | JSONObject | 是 | {"groupId":"group"} | 额外请求参数，传入与待检测图片进行比对的个体组ID（groupId）。 您可以调用/green/sface/groups查询所有的个体组ID。 |
返回数据
所有请求均返回JSON格式的数据。关于返回数据中的公共字段，请参见公共返回参数。返回数据中的data字段表示与业务相关的数据，一般是一个JSON结构体或数组。
响应出错的情况下，data字段可能为空。
该接口返回的data字段包含以下参数。
名称 | 类型 | 示例值 | 描述 |
code | Integer | 200 | 错误码，和HTTP状态码一致。 更多信息，请参见公共错误码。 |
results | JSONArray | 返回结果。调用成功时（code=200），返回结果中包含一个或多个result元素。每个result元素是个结构体，具体结构描述，请参见result。 |
表 2. result
名称 | 类型 | 示例值 | 描述 |
scene | String | sface-n | 检测场景，取值：sface-n，表示自定义人脸检索。 |
label | String | sface-n | 检测结果的分类，取值：
|
suggestion | String | review | 建议您执行的操作，取值：
|
rate | Float | 0.999 | 结果属于当前分类的概率，取值范围：0.00~1.00。值越高，表示越有可能属于当前分类。 |
topPersonData | JSONArray | 与目标人脸图片最相似的5个个体信息。具体结构描述，请参见topPersonData。 说明 如果未检索到相似个体，则返回空值。 |
表 3. topPersonData
名称 | 类型 | 示例值 | 描述 |
persons | JSONArray | Top 5匹配个体的信息。具体结构描述，请参见person。 | |
faceItem | JSONObject | 检测图像中的人脸属性。具体结构描述，请参见faceItem。 |
表 4. person
名称 | 类型 | 示例值 | 描述 |
personId | String | person1 | 匹配个体的ID。 |
faceId | String | 14736649593638 | 匹配个体的人脸图片ID。 |
rate | Float | 0.999 | 个体的匹配概率。匹配概率越高，对应的误识率越低，具体如下：
推荐您使用匹配概率取值在0.9以上的结果。 |
表 5. faceItem
名称 | 类型 | 示例值 | 描述 |
x | Float | 467 | 人脸在x轴的坐标，单位：像素。 |
y | Float | 199 | 人脸在y轴的坐标，单位：像素。 |
width | Float | 422 | 人脸宽度，单位：像素。 |
height | Float | 422 | 人脸高度，单位：像素。 |
示例
请求示例
POST /green/image/scan HTTP/1.1
公共请求头
{
"scenes": [
"sface-n"
],
"tasks": [
{
"dataId": "test2NInmOtAON6qYUrtCRgLo-1mwxdi",
"url": "https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png",
"extras": {
"groupId": "group"
}
}
]
}正常返回示例
{
"code": 200,
"data": [
{
"code": 200,
"dataId": "test2NInmOtAON6qYUrtCRgLo-1mwxdi",
"msg": "调用成功。",
"results": [
{
"topPersonData": [
{
"faceItem": {
"height": 422,
"width": 422,
"x": 467,
"y": 199
},
"persons": [
{
"faceId": "14736649593638",
"personId": "person1",
"rate": "0.999"
},
{
"faceId": "14736649593637",
"personId": "person2",
"rate": "0.998"
}
]
}
],
"label": "sface-n",
"rate": 0.999,
"scene": "sface-n",
"suggestion": "review"
}
],
"taskId": "img2MVcKPU1QGD64LoAb4cK6w-1mwxdi",
"url": "https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
}
],
"msg": "OK",
"requestId": "36D384DA-8023-4E84-BCFD-0C5581352C16"
}