1:N人脸比对
接口简介
- 七牛1:N人脸比对服务可对一张含有人脸的图片进行智能识别，检测出图片中的人脸后在自定义的人像库中进行人脸检索，返回最相似的一个或多个人脸信息。整个服务由多个API接口组合而成，可实现功能包括新建人像库、删除人像库、添加或删除人脸、显示所有或指定人像库信息、显示所有或指定人脸信息以及人脸搜索。适用于刷脸签到，会议签到，身份识别等多种场景。
- 本接口可对入库图片进行质量检测，禁止模糊，大姿态等低质量人脸入库，帮助用户规范人像库图片质量，提升识别精度。人脸搜索接口可根据用户定义对检索图片中的最大人脸或者所有人脸进行识别，并且支持在多库中搜索，接口灵活度可以满足用户各种使用姿势。
组合接口描述
| 接口名称 | 请求路径 | 请求方式 | 接口功能描述 |
|---|---|---|---|
| 新建人像库 | /v1/face/group/<group_id>/new | POST | 创建一个新的人像库并将人脸信息存入库中，返回录入人像库的人脸唯一标识 |
| 删除人像库 | /v1/face/group/<group_id>/remove | POST | 删除指定的人像库，如果人像库中含有人脸也一并删除 |
| 添加人脸 | /v1/face/group/<group_id>/add | POST | 在指定人像库中添加人脸，返回新添加的人脸唯一标识 |
| 删除人脸 | /v1/face/group/<group_id>/delete | POST | 删除指定人像库中的一个或多个人脸 |
| 显示所有人像库 | /v1/face/group | GET | 显示所有创建的人像库的唯一 id |
| 显示指定人像库信息 | /v1/face/group/<group_id>/info | GET | 显示指定人像库中人脸个数 |
| 显示所有人脸 | /v1/face/group/<group_id>?marker=<marker>&limit=<limit> | GET | 显示指定的人像库中的所有人脸 |
| 显示指定人脸信息 | /v1/face/group/<group_id>/face | POST | 显示某人像库中指定一张人脸信息 |
| 人脸搜索 | /v1/face/groups/search | POST | 对于待搜索图片中检测到的每张人脸，在指定的人像库中返回其相似度最高的多张人脸 id 注意： 支持在多个库进行搜索 |
| 人脸搜索 （旧版本） |
/v1/face/group/<group_id>/search | POST | 对于待搜索图片中检测到的每张人脸，在指定的人像库中返回其相似度最高的一张人脸 id 注意： 此接口用于给在2018年7月24日之前接入的用户进行对照查看，请新用户统一使用上一行新人脸搜索接口 |
具体调用方式及示例
新建人像库
创建一个新的人像库并将人脸（包括人脸图片和姓名信息）存入库中，返回录入人像库的人脸唯一标识。
注意: 每个人像库最多存入50万张图片。
请求方式：POST
请求url: http://ai.qiniuapi.com/v1/face/group/<group_id>/new
Header
| 字段 | 取值 |
|---|---|
| Content-Type | application/json |
| Authorization | Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SecretKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权 |
请求字段说明
| 字段 | 取值 | 是否必选 | 说明 |
|---|---|---|---|
| group_id | string | Y | 人像库的唯一标识 |
| uri | string | Y | 图片资源。支持两种资源表达方式： 1. 网络图片URL地址； 2. 图片 base64 编码字符串，需在编码字符串前加上前缀 data:application/octet-stream;base64, 例：data:application/octet-stream;base64,xxx |
| attribute.id | string | N | 自定义人脸 id，在返回结果中显示 |
| attribute.name | string | N | 人物姓名 |
| attribute.mode | string | N | 人脸选择策略，可以设置为 SINGLE（只允许图片里面出现单张人脸，否则API返回错误） 或者 LARGEST（如果存在多张人脸，使用最大的人脸），默认SINGLE |
| attribute.desc | map | N | 人脸图片的备注信息。内容可以是布尔值、数字、字符串、数组或 json，最大允许长度为4096字节 |
| attribute.reject_bad_face | bool | N | 是否拒绝低质量人脸入库，默认为不拒绝false。允许入库的人脸必须同时满足人脸质量为清晰clear以及方向为正脸up，人脸质量和人脸方向具体分类见表1 和表2 注意： 当 reject_bad_face为false时，返回人脸的质量信息，并且低质量人脸会正常入库 |
表1 人脸质量分类
| 标签 | 说明 | 入库情况 |
|---|---|---|
clear |
清晰 | 允许入库 |
small |
人脸小于50* 50 | 低质量 |
blur |
模糊 | 低质量 |
cover |
人脸被遮挡 | 低质量 |
pose |
人脸大姿态 | 低质量 |
表2 人脸方向分类
| 标签 | 说明 | 入库情况 |
|---|---|---|
up |
正脸（平面旋转角度为0） | 允许入库 |
up_left |
平面内逆时针旋转45度 | 低质量 |
left |
平面内逆时针旋转90度 | 低质量 |
down_left |
平面内逆时针旋转135度 | 低质量 |
down |
平面内旋转180度 | 低质量 |
down_right |
平面内顺时针旋转135度 | 低质量 |
right |
平面内顺时针旋转90度 | 低质量 |
up_right |
平面内顺时针旋转45度 | 低质量 |
请求语法
POST /v1/face/group/<group_id>/new Http/1.1
Content-Type: application/json
Authorization: Qiniu <AccessKey>:<Sign>
{
"data": [
{
"uri": "http://xx.com/xxx",
"attribute": {
"id": <id>,
"name": <name>,
"mode": <mode>,
"desc": <additional information>,
"reject_bad_face": false
}
},
{
"uri": "data:application/octet-stream;base64,xxx",
"attribute": {
"id": <id>,
"name": <name>,
"mode": <mode>,
"desc": <additional information>,
"reject_bad_face": true
}
}
]
}
返回字段说明
| 字段 | 取值 | 说明 |
|---|---|---|
| faces | list | 录入的所有人脸 id 列表，若某张人脸入库失败，则为空 |
| attributes | list | 录入的所有人脸相关信息，若某张人脸入库失败，则为null |
| bounding_box | map | 图片中某张人脸的边框信息 |
| bounding_box.pst | list | 人脸边框在图片中的位置[左上，右上，右下，左下] |
| bounding_box.score | float | 人脸位置检测准确度 |
| face_quality | map | 图片中某张人脸的人脸质量信息 |
| face_quality.orientation | string | 人脸方向分类，指人脸平面旋转角度，具体取值见上方表2 |
| face_quality.quality | string | 人脸质量分类，具体取值见上方表1 |
| errors | list | 录入的所有人脸的错误信息，若某张人脸入库成功，则为null |
| errors.code | int | 错误码 |
| errors.message | string | 错误描述信息 |
返回示例
200 ok
{
"attributes": [
{
"bounding_box": {
"pts": [
[
198,
47
],
[
279,
47
],
[
279,
172
],
[
198,
172
]
],
"score": 0.99999535
},
"face_quality":{
"orientation": "up",
"quality": "clear"
}
},
{
"bounding_box": {
"pts": [
[
140,
131
],
[
344,
131
],
[
344,
382
],
[
140,
382
]
],
"score": 0.99999595
},
"face_quality":{
"orientation": "up",
"quality": "small"
}
}
],
"errors": [
null,
null
],
"faces": [
"1101",
"CAAAAJb_wJ5SQ0cV"
]
}
删除人像库
删除指定的人像库，如果人像库中含有人脸也一并删除。
请求方式：POST
请求url: http://ai.qiniuapi.com/v1/face/group/<group_id>/remove
Header
| 字段 | 取值 |
|---|---|
| Authorization | Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权 |
请求字段说明
| 字段 | 取值 | 是否必选 | 说明 |
|---|---|---|---|
| group_id | string | Y | 人像库的唯一标识 |
注意： 请求 body 为空。
请求语法
POST /v1/face/group/<group_id>/remove Http/1.1
Authorization: Qiniu <AccessKey>:<Sign>
返回语法
200 ok
{}
注意： 删除成功返回内容为空。
添加人脸
在指定人像库中添加人脸，返回新添加的人脸唯一标识。
请求方式：POST
请求url: http://ai.qiniuapi.com/v1/face/group/<group_id>/add
Header
| 字段 | 取值 |
|---|---|
| Content-Type | application/json |
| Authorization | Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权 |
请求字段说明
| 字段 | 取值 | 是否必选 | 说明 |
|---|---|---|---|
| group_id | string | Y | 人像库的唯一标识 |
| uri | string | Y | 图片资源。支持两种资源表达方式： 1. 网络图片URL地址； 2. 图片 base64 编码字符串，需在编码字符串前加上前缀 data:application/octet-stream;base64, 例：data:application/octet-stream;base64,xxx |
| attribute.id | string | N | 自定义人脸 id，用于返回信息中的人脸 id |
| attribute.name | string | N | 人物姓名 |
| attribute.mode | string | N | 人脸选择策略，可以设置为 SINGLE（只允许图片里面出现单张人脸，否则API返回错误） 或者 LARGEST（如果存在多张人脸，使用最大的人脸），默认SINGLE |
| attribute.desc | map | N | 人脸图片的备注信息。内容可以是布尔值、数字、字符串、数组或 json，最大允许长度为4096字节 |
| attribute.reject_bad_face | bool | N | 是否拒绝低质量人脸入库，默认为不拒绝false。允许入库的人脸必须同时满足人脸质量为清晰clear以及方向为正脸up，人脸质量和人脸方向具体分类见表1 和表2 注意： 当 reject_bad_face为false时，返回人脸的质量信息，并且低质量人脸会正常入库 |
请求语法
POST /v1/face/group/<group_id>/add Http/1.1
Content-Type: application/json
Authorization: Qiniu <AccessKey>:<Sign>
{
"data": [
{
"uri": "http://xx.com/xxx",
"attribute": {
"id": <id>,
"name": <name>,
"mode": <mode>,
"desc": <additional information>
}
},
{
"uri": "data:application/octet-stream;base64,xxx",
"attribute": {
"id": <id>,
"name": <name>,
"mode": <mode>,
"desc": <additional information>
}
}
]
}
返回字段说明
| 字段 | 取值 | 说明 |
|---|---|---|
| faces | list | 录入的所有人脸 id 列表，若某张人脸入库失败，则为空 |
| attributes | list | 录入的所有人脸相关信息，若某张人脸入库失败，则为null |
| bounding_box | map | 图片中某张人脸的边框信息 |
| bounding_box.pst | list | 人脸边框在图片中的位置[左上，右上，右下，左下] |
| bounding_box.score | float | 人脸位置检测准确度 |
| face_quality | map | 图片中某张人脸的人脸质量信息 |
| face_quality.orientation | string | 人脸方向分类，指的人脸水平旋转角度，具体取值见上方表2 |
| face_quality.quality | string | 人脸质量分类，具体取值见上方表1 |
| errors | list | 录入的所有人脸的错误信息，若某张人脸入库成功，则为null |
| errors.code | int | 错误码 |
| errors.message | string | 错误描述信息 |
返回示例
{
"attributes": [
{
"bounding_box": {
"pts": [
[
336,
53
],
[
628,
53
],
[
628,
475
],
[
336,
475
]
],
"score": 0.99999905
},
"face_quality": {
"orientation": "up",
"quality": "clear"
}
}
],
"errors": [
null
],
"faces": [
"1102"
]
}
删除人脸
删除指定人像库中一个或多个人脸
请求方式：POST
请求url: http://ai.qiniuapi.com/v1/face/group/<group_id>/delete
Header
| 字段 | 取值 |
|---|---|
| Content-Type | application/json |
| Authorization | Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权 |
请求字段说明
| 字段 | 取值 | 是否必选 | 说明 |
|---|---|---|---|
| group_id | string | Y | 需要删除的人脸所在人像库的唯一标识 |
| face_id | string | Y | 需要删除的人脸 id |
请求语法
POST /v1/face/group/<group_id>/delete Http/1.1
Content-Type: application/json
Authorization: Qiniu <AccessKey>:<Sign>
{
"faces":[
<face_id>,
...
]
}
返回语法
200 ok
{}
注意： 删除成功返回内容为空。
显示所有的人像库
显示所有已建立的人像库的唯一id。
请求方式：GET
请求url: http://ai.qiniuapi.com/v1/face/group
Header
| 字段 | 取值 |
|---|---|
| Authorization | Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权 |
请求语法
GET /v1/face/group Http/1.1
Authorization: Qiniu <AccessKey>:<Sign>
返回字段说明
| 字段 | 取值 | 说明 |
|---|---|---|
| code | int | 处理状态：0表示调用成功 |
| message | string | 与code对应的状态描述信息 |
| result | list | 人像库 id 列表 |
返回示例
{
"code": 0,
"message": "",
"result": [
"1",
"2"
]
}
显示指定人像库信息
显示指定人像库中人脸个数。
请求方式：GET
请求url: http://ai.qiniuapi.com/v1/face/group/<group_id>/info
Header
| 字段 | 取值 |
|---|---|
| Authorization | Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权 |
请求字段说明
| 字段 | 取值 | 是否必选 | 说明 |
|---|---|---|---|
| group_id | string | Y | 人像库的唯一标识 |
请求语法
GET /v1/face/group/<group_id>/info Http/1.1
Authorization: Qiniu <AccessKey>:<Sign>
返回字段说明
| 字段 | 取值 | 说明 |
|---|---|---|
| count | int | 指定人像库中人脸个数 |
返回示例
{
"count": 4
}
显示所有人脸
显示指定的人像库中的所有人脸。
请求方式：GET
请求url: http://ai.qiniuapi.com/v1/face/group/<group_id>?marker=<marker>&limit=<limit>
Header
| 字段 | 取值 |
|---|---|
| Authorization | Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权 |
请求字段说明
| 字段 | 取值 | 是否必选 | 说明 |
|---|---|---|---|
| group_id | string | Y | 人像库的唯一标识 |
| marker | string | N | 上一次请求返回的标记，作为本次请求的起点信息，默认值为空字符串 |
| limit | int | N | 返回数量，范围为 1-1000，默认值为 1000 |
注意： 如果请求时不需要设置marker或者limit，则请求url中不加此参数，例如：http://ai.qiniuapi.com/v1/face/group/<group_id>或http://ai.qiniuapi.com/v1/face/group/<group_id>?limit=<limit>
请求语法
GET /v1/face/group/<group_id>?marker=<marker>&limit=<limit> Http/1.1
Authorization: Qiniu <AccessKey>:<Sign>
返回字段说明
| 字段 | 取值 | 说明 |
|---|---|---|
| code | int | 处理状态：0表示调用成功 |
| message | string | 与code对应的状态描述信息 |
| marker | string | 本次请求的标记信息，可作为下一次请求的参数传入，如果没有剩余条目则返回空字符串 |
| result.id | string | 生成的该人脸的唯一标识 |
| result.value | object | 已入库的某张人脸的具体信息，具体内容见表3 |
表3 result.value具体内容
| 字段 | 取值 | 说明 |
|---|---|---|
| name | string | 人物姓名 |
| desc | map | 人脸图片入库时的备注信息 |
| bounding_box | map | 人脸图片入库时的边框信息 |
| bounding_box.pst | list | 人脸边框在图片中的位置[左上，右上，右下，左下] |
| bounding_box.score | float | 人脸位置检测准确度 |
| value.face_quality | map | 人脸图片入库时的人脸质量信息 |
| face_quality.orientation | string | 人脸方向分类，指的人脸水平旋转角度，具体取值见上方表2 |
| face_quality.quality | string | 人脸质量分类，具体取值见上方表1 |
返回示例
{
"code": 0,
"marker": "",
"message": "",
"result": [
{
"id": "CAAAAFV8J-vXylgV",
"value": {
"bounding_box": {
"pts": [
[
140,
131
],
[
344,
131
],
[
344,
382
],
[
140,
382
]
],
"score": 0.99999595
},
"face_quality": {
"orientation": "up",
"quality": "clear"
},
"name": ""
}
},
{
"id": "1",
"value": {
"bounding_box": {
"pts": [
[
198,
47
],
[
279,
47
],
[
279,
172
],
[
198,
172
]
],
"score": 0.99999535
},
"desc": "a female politican",
"face_quality": {
"orientation": "up",
"quality": "clear"
},
"name": "anne"
}
}
]
}
显示指定人脸信息
显示某人像库指定一张人脸信息。
请求方式：POST
请求url: http://ai.qiniuapi.com/v1/face/group/<group_id>/face
Header
| 字段 | 取值 |
|---|---|
| Content-Type | application/json |
| Authorization | Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权 |
请求字段说明
| 字段 | 取值 | 是否必选 | 说明 |
|---|---|---|---|
| group_id | string | Y | 人像库的唯一标识 |
| id | string | Y | 人脸的唯一标识 |
请求语法
POST /v1/face/group/<group_id>/face Http/1.1
Content-Type: application/json
Authorization: Qiniu <AccessKey>:<Sign>
{
"id": "xxx"
}
返回说明
| 字段 | 取值 | 说明 |
|---|---|---|
| name | string | 人物姓名 |
| desc | map | 人脸图片入库时的备注信息 |
| bounding_box | map | 人脸图片入库时的边框信息 |
| bounding_box.pst | list | 人脸边框在图片中的位置[左上，右上，右下，左下] |
| bounding_box.score | float | 人脸位置检测准确度 |
| value.face_quality | map | 人脸图片入库时的人脸质量信息 |
| face_quality.orientation | string | 人脸方向分类，指的人脸水平旋转角度，具体取值见上方表2 |
| face_quality.quality | string | 人脸质量分类，具体取值见上方表1 |
返回示例
{
"bounding_box": {
"pts": [
[
336,
53
],
[
628,
53
],
[
628,
475
],
[
336,
475
]
],
"score": 0.99999905
},
"desc": "a Hollywood star",
"face_quality": {
"orientation": "up",
"quality": "clear"
},
"name": "jessica"
}
人脸库搜索
人脸库搜索。对于待搜索图片中检测到的每张人脸，在指定的人像库中返回其相似度最高的多张人脸 id。
注意： 支持在多个库内进行搜索，最多5个。
请求方式：POST
请求url: http://ai.qiniuapi.com/v1/face/groups/search
Header
| 字段 | 取值 |
|---|---|
| Content-Type | application/json |
| Authorization | Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权 |
请求字段说明
| 字段 | 取值 | 是否必选 | 说明 |
|---|---|---|---|
| data.uri | string | Y | 图片资源。支持两种资源表达方式： 1. 网络图片URL地址； 2. 图片 base64 编码字符串，需在编码字符串前加上前缀 data:application/octet-stream;base64, 例：data:application/octet-stream;base64,xxx |
| params.groups | list | Y | 搜索的人像库列表，最多只能在5个库里面搜索 |
| params.groups.[] | string | Y | 人像库 id |
| params.limit | int | N | 返回匹配度最高的前n个人脸，默认为1，最大允许10000。若为-1，则返回所有匹配人脸 |
| params.threshold | float | N | 匹配人脸的精度阈值，默认使用系统设置值（根据特征提取版本不同会有微小变动，目前取值0.4）。若该值小于系统设置值，则仍使用系统设置值 |
| params.mode | string | N | 人脸选择策略。可以设置为ALL（对图片中所有检测到的人脸进行搜索） 或者LARGEST（只对图片中最大的人脸进行搜索），默认ALL |
| params.use_quality | bool | N | 搜索前是否使用人脸质量评估过滤人脸，默认为false。该值为true则不搜索待检测图片中的低质量人脸，false则对检测到的所有人脸进行搜索。低质量定义见上方表1 和 表2，该参数的优先级低于参数mode，即mode过滤后的人脸再使用该参数过滤。 |
请求语法
POST /v1/face/groups/search Http/1.1
Content-Type: application/json
Authorization: Qiniu <AccessKey>:<Sign>
{
"data": {
"uri": "http://xx.com/xxx"
},
"params": {
"groups": [
<group_id>
],
"limit": 5,
"threshold": 0.85,
"use_quality": true,
"mode": "ALL"
}
}
返回字段说明
| 字段 | 取值 | 说明 |
|---|---|---|
| code | int | 处理状态：0表示调用成功 |
| message | string | 与code对应的状态描述信息 |
| result | list | 图片中检测到的所有人脸以及对应的识别信息列表，详情信息参考表3 |
表3 result中一张人脸的具体识别信息
| 字段 | 取值 | 说明 |
|---|---|---|
| bounding_box | map | 图片中某张人脸的边框信息 |
| bounding_box.pts | list | 此人脸边框在图片中的位置为 [左上，右上，右下，左下] |
| bounding_box.score | float | 人脸位置检测准确度 |
| faces | list | 对应上述 bounding_box 中检测出的人脸，检索出的相似人脸列表，详细信息参考表4 |
表4 faces 中检索出的一张相似人脸的信息
| 字段 | 取值 | 说明 |
|---|---|---|
| bounding_box | map | 检索得到的底库图片中人脸的边框信息 |
| bounding_box.pst | list | 人脸边框在图片中的位置[左上，右上，右下，左下] |
| bounding_box.score | float | 人脸位置检测准确度 |
| id | string | 检索得到的人脸唯一标识 |
| name | string | 检索得到的人物姓名 |
| group | string | 检索得到的人脸所属的人像库 id |
| score | float | 检索结果的可信度 |
| desc | map | 人脸图片入库时的备注信息 |
| face_quality | map | 人脸图片入库时的人脸质量信息 |
| face_quality.orientation | string | 人脸方向分类，指的人脸水平旋转角度，具体取值见上方表2 |
| face_quality.quality | string | 人脸质量分类，具体取值见上方表1 |
返回示例
{
"code": 0,
"message": "",
"result": {
"faces": [
{
"bounding_box": {
"pts": [
[
375,
314
],
[
424,
314
],
[
424,
382
],
[
375,
382
]
],
"score": 0.98729205
},
"faces": null
},
{
"bounding_box": {
"pts": [
[
188,
127
],
[
348,
127
],
[
348,
349
],
[
188,
349
]
],
"score": 0.9999807
},
"faces": [
{
"bounding_box": {
"pts": [
[
198,
47
],
[
279,
47
],
[
279,
172
],
[
198,
172
]
],
"score": 0.99999535
},
"desc": "a female politican",
"face_quality": {
"orientation": "up",
"quality": "clear"
},
"group": "5",
"id": "1",
"name": "anne",
"review": false,
"score": 0.78255147
}
]
},
{
"bounding_box": {
"pts": [
[
558,
196
],
[
720,
196
],
[
720,
433
],
[
558,
433
]
],
"score": 0.9999678
},
"faces": [
{
"bounding_box": {
"pts": [
[
336,
53
],
[
628,
53
],
[
628,
475
],
[
336,
475
]
],
"score": 0.99999905
},
"desc": "a Hollywood star",
"face_quality": {
"orientation": "up",
"quality": "clear"
},
"group": "5",
"id": "1102",
"name": "jessica",
"review": false,
"score": 0.4717328
}
]
}
],
"review": false
}
}
人脸库搜索(旧版本）
对于待搜索图片中检测到的每张人脸，在指定的人脸库中返回其相似度最高的一张人脸id。
注意： 此接口用于给在2018年7月24日之前接入的用户进行对照查看，请新用户统一使用上方新人脸搜索接口。
请求方式：POST
请求url: http://ai.qiniuapi.com/v1/face/group/<group_id>/search
Header
| 字段 | 取值 |
|---|---|
| Content-Type | application/json |
| Authorization | Qiniu <AccessKey>:<Sign> 注意: 用户请根据 AccessKey 和 SuccessKey 生成鉴权，以便进行身份验证。<Sign> 的取值请参考七牛鉴权 |
请求字段说明
| 字段 | 取值 | 是否必选 | 说明 |
|---|---|---|---|
| group_id | string | Y | 人像库的唯一标识 |
| uri | string | Y | 图片资源。支持两种资源表达方式： 1. 网络图片URL地址； 2. 图片 base64 编码字符串，需在编码字符串前加上前缀 data:application/octet-stream;base64, 例：data:application/octet-stream;base64,xxx |
请求语法
POST /v1/face/group/<group_id>/search Http/1.1
Content-Type: application/json
Authorization: Qiniu <AccessKey>:<Sign>
{
"data": {
"uri": "http://xx.com/xxx"
}
}
返回字段说明
| 字段 | 取值 | 说明 |
|---|---|---|
| code | int | 处理状态：0表示调用成功 |
| message | string | 与code对应的状态描述信息 |
| result | list | 图片中检测到的所有人脸以及对应的识别信息列表，详情信息参考表5 |
表5 result中一张人脸的具体识别信息
| 字段 | 取值 | 说明 |
|---|---|---|
| bounding_box | map | 图片中检测出的某张人脸的边框信息 |
| bounding_box.pts | list | 此人脸边框在图片中的位置为 [左上，右上，右下，左下] |
| bounding_box.score | float | 人脸位置检测准确度 |
| value | list | 对应上述 bounding_box 中检测出的人脸，检索出的相似人脸列表，详细信息参考表6 |
表6 value 中检索出的一张相似人脸的信息
| 字段 | 取值 | 说明 |
|---|---|---|
| bounding_box | map | 检索得到的底库图片中人脸的边框信息 |
| bounding_box.pst | list | 人脸边框在图片中的位置[左上，右上，右下，左下] |
| bounding_box.score | float | 人脸位置检测准确度 |
| id | string | 检索得到的人脸唯一标识 |
| name | string | 检索得到的人物姓名 |
| score | float | 检索结果的可信度 |
| desc | map | 人脸图片入库时的备注信息 |
返回示例
{
"code": 0,
"message": "",
"result": {
"detections": [
{
"boundingBox": {
"pts": [
[
188,
127
],
[
348,
127
],
[
348,
349
],
[
188,
349
]
],
"score": 0.9999807
},
"value": {
"boundingBox": {
"pts": [
[
198,
47
],
[
279,
47
],
[
279,
172
],
[
198,
172
]
],
"score": 0.99999535
},
"desc": "a female politican",
"id": "1101",
"name": "anne",
"review": false,
"score": 0.78255147
}
},
{
"boundingBox": {
"pts": [
[
558,
196
],
[
720,
196
],
[
720,
433
],
[
558,
433
]
],
"score": 0.9999678
},
"value": {
"boundingBox": {
"pts": [
[
336,
53
],
[
628,
53
],
[
628,
475
],
[
336,
475
]
],
"score": 0.99999905
},
"desc": "a Hollywood star",
"id": "1102",
"name": "jessica",
"review": false,
"score": 0.47173265
}
},
{
"boundingBox": {
"pts": [
[
375,
314
],
[
424,
314
],
[
424,
382
],
[
375,
382
]
],
"score": 0.98729205
},
"value": {
"boundingBox": {
"pts": null,
"score": 0
},
"id": "",
"name": "",
"review": false,
"score": 0
}
}
],
"review": false
}
}
文件适用规格
可处理的图片文件：
- 图片大小不超过10M
- 图片尺寸不小于50x50，不超过4999x4999，图片过小则无法正确进行人脸识别。
- RGB通道数为3和3以内的图片，不能包含alpha通道
- 图片格式支持 png、jpg、jpeg、bmp、webp 和 gif
服务价格
| 总调用量P | 费用 |
|---|---|
| 单位：万张 | 单价（元/百张） |
| 0 < P ≤ 500 | 0.19 |
| 500 < P ≤ 1500 | 0.18 |
| 1500 < P ≤ 3000 | 0.15 |
| P > 3000 | 0.12 |
计费示例
某公司2018年5月使用七牛云1:N人脸比对别服务，共发起500万张请求，
则当月使用七牛云1:N人脸比对服务产生的费用为：
确定的结果产生费用：0.19元/百张 * 500万张 = 9500 元
总计费用：9500 元
文档反馈
(如有产品使用问题，请 提交工单)