本文介绍了调用图片同步检测(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)
    • 图片下载时间限制为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 检测结果的分类,取值:
  • sface-n:表示检索到相似人脸。
  • normal:表示未检索到相似人脸。
suggestion String review 建议您执行的操作,取值:
  • pass:无需进行其余操作。
  • review:进行人工审核。
rate Float 0.999 结果属于当前分类的概率,取值范围:0.00~1.00。值越高,表示越有可能属于当前分类。
topPersonData JSONObject 与目标人脸图片最相似的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.50,误识率0.05
  • 取值0.60,误识率0.01
  • 取值0.70,误识率0.005
  • 取值0.80,误识率0.001
  • 取值0.90,误识率0.0001
  • 取值0.92,误识率0.00001
  • 取值0.94,误识率0.000001
  • 取值0.96,误识率0.0000001

推荐您使用匹配概率取值在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"
}