智能多媒体 API

  • 1:N人脸比对

    最近更新时间:2018-11-12 20:24:44

    七牛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 元

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