智能多媒体服务

  • 智能多媒体服务 > API 文档 > 1:N人脸比对

    1:N人脸比对

    最近更新时间: 2018-11-16 10:30:30

    接口简介

    • 七牛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_facefalse时,返回人脸的质量信息,并且低质量人脸会正常入库

    表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_facefalse时,返回人脸的质量信息,并且低质量人脸会正常入库

    请求语法

    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
        }
    }
    
    

    文件适用规格


    可处理的图片文件:

    1. 图片大小不超过10M
    2. 图片尺寸不小于50x50,不超过4999x4999,图片过小则无法正确进行人脸识别。
    3. RGB通道数为3和3以内的图片,不能包含alpha通道
    4. 图片格式支持 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 元

    以上内容是否对您有帮助?
  • Qvm free helper
    Close