智能多媒体 API

  • 1:N人脸比对

    最近更新时间:2018-09-13 17:54:19

    七牛1:N人脸比对服务可对一张含有人脸的图片进行智能识别,检测出图片中的人脸后在自定义的人像库中进行人脸检索,将相似度最高的人脸作为其身份返回。整个服务由多个API接口组合而成,可实现功能包括新建人像库、删除人像库、添加人脸、删除人脸、显示全部人像库、显示人脸、人脸检索。

    使用方式

    七牛1:N人脸比对服务支持对存储在七牛云 bucket(支持华东、华北和华南 bucket)或 非七牛云 bucket的图片进行智能识别。目前支持的图片格式有 png、jpg 和 bmp。

    组合接口信息

    接口名称 请求路径 请求方式 接口功能
    新建人像库 /v1/face/group/<id>/new POST 创建一个新的人像库并将人脸信息存入库中,返回录入人像库的人脸唯一标识,请求图片中人脸不能小于50* 50
    删除人像库 /v1/face/group/<id>/remove POST 删除指定的人像库,如果人像库中含有人脸也一并删除
    添加人脸 /v1/face/group/<id>/add POST 在指定人像库中添加人脸,返回新添加的人脸唯一标识,请求图片中人脸不能小于50* 50
    删除人脸 /v1/face/group/<id>/delete POST 删除指定人像库中的一个或多个人脸
    显示所有人像库 /v1/face/group GET 显示所有创建的人像库的唯一ID
    显示人脸 /v1/face/group/<id> GET 显示指定的人像库中的所有人脸
    人脸搜索 /v1/face/groups/search POST 对于待搜索图片中检测到的每张人脸,在指定的人像库中返回其相似度最高的多张人脸ID
    注意: 支持在多个库进行搜索
    人脸搜索
    (旧版本)
    /v1/face/group/<id>/search POST 对于待搜索图片中检测到的每张人脸,在指定的人像库中返回其相似度最高的一张人脸ID
    注意: 此接口用于给在2018年7月24日之前接入的用户进行对照查看,请新用户统一使用上一行新人脸搜索接口

    请求域名

    HOST: ai.qiniuapi.com
    

    具体调用方式及示例

    新建人像库

    创建一个新的人像库并将人脸(包括人脸图片和姓名信息)存入库中,返回录入人像库的人脸唯一标识。

    请求语法

    POST /v1/face/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>
                }
            },
            {
                "uri": "data:application/octet-stream;base64,xxx",
                "attribute": {
                    "id": <id>,
                    "name": <name>,
                    "mode": <mode>,
                    "desc": <additional information>
                }
            }
        ]
    }
    

    注意: 需要在 POST 请求的 head 部分添加七牛鉴权,以进行用户身份验证。

    请求字段说明:

    字段 取值 是否必选 说明
    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,人脸不能小于50 * 50
    attribute.desc map N 人脸图片的备注信息。内容可以是布尔值、数字、字符串、数组或json,最大允许长度为4096字节

    响应语法

    200 OK
    Content-Type: application/json
    
    {
        "faces": [
            <face_id>,
            "",
            ...
        ],
        "attributes": [
            {
                "bounding_box": {
                    "pts": [[205,400],[1213,400],[1213,535],[205,535]],
                    "score":0.998
                }
            },
            null,
            ...
        ],
        "errors": [
            null,
            {
                "code": xxx,
                "message": "xxx"
            },
            ...
        ]
    }
    
    

    返回字段说明:

    字段 取值 说明
    faces list 录入的所有人脸id列表,若某张人脸入库失败,则为空
    attributes list 录入的所有人脸相关信息,若某张人脸入库失败,则为null
    bounding_box map 图片中某张人脸的边框信息
    bounding_box.pst list 人脸边框在图片中的位置[左上,右上,右下,左下]
    bounding_box.score float 人脸位置检测准确度
    errors map 录入的所有人脸的错误信息,若某张人脸入库成功,则为null
    code int 错误码
    message string 错误描述信息

    返回示例

    200 ok
    {
        "attributes": [
            {
                "bounding_box": {
                    "pts": [
                        [
                            198, 
                            47
                        ], 
                        [
                            279, 
                            47
                        ], 
                        [
                            279, 
                            172
                        ], 
                        [
                            198, 
                            172
                        ]
                    ], 
                    "score": 0.99999535
                }
            }, 
            {
                "bounding_box": {
                    "pts": [
                        [
                            140, 
                            131
                        ], 
                        [
                            344, 
                            131
                        ], 
                        [
                            344, 
                            382
                        ], 
                        [
                            140, 
                            382
                        ]
                    ], 
                    "score": 0.99999595
                }
            }
        ], 
        "errors": [
            null, 
            null
        ], 
        "faces": [
            "1101", 
            "CAAAAJb_wJ5SQ0cV"
        ]
    }
    
    

    删除人像库

    删除指定的人像库,如果人像库中含有人脸也一并删除。

    请求语法

    POST /v1/face/group/<id>/remove  Http/1.1
    Authorization: Qiniu <AccessKey>:<Sign>
    
    

    注意: 需要在 POST 请求的 head 部分添加七牛鉴权,以进行用户身份验证。

    请求字段说明:

    字段 取值 是否必选 说明
    id string Y 人像库的唯一标识

    响应语法

    200 ok
    
    {}
    
    

    注意: 删除成功响应内容为空。

    添加人脸

    在指定人像库中添加人脸,返回新添加的人脸唯一标识

    请求语法

    POST /v1/face/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>
                }
            }
        ]
    }
    

    注意: 需要在 POST 请求的 head 部分添加七牛鉴权,以进行用户身份验证。

    请求字段说明:

    字段 取值 是否必选 说明
    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,人脸不能小于50 * 50
    attribute.desc map N 人脸图片的备注信息。内容可以是布尔值、数字、字符串、数组或json,最大允许长度为4096字节

    响应语法

    200 OK
    Content-Type: application/json
    
    {
        "faces": [
            <face_id>,
            "",
            ...
        ],
        "attributes": [
            {
                "bounding_box": {
                    "pts": [[205,400],[1213,400],[1213,535],[205,535]],
                    "score":0.998
                }
            },
            null,
            ...
        ],
        "errors": [
            null,
            {
                "code": xxx,
                "message": "xxx"
            },
            ...
        ]
    }
    
    
    字段 取值 说明
    faces list 录入的所有人脸id列表,若某张人脸入库失败,则为空
    attributes list 录入的所有人脸相关信息,若某张人脸入库失败,则为null
    bounding_box map 图片中某张人脸的边框信息
    bounding_box.pst list[4] 人脸边框在图片中的位置[左上,右上,右下,左下]
    bounding_box.score float 人脸位置检测准确度
    errors map 录入的所有人脸的错误信息,若某张人脸入库成功,则为null
    code int 错误码
    message string 错误描述信息

    返回示例

    200 ok
    {
        "attributes": [
            {
                "bounding_box": {
                    "pts": [
                        [
                            336, 
                            53
                        ], 
                        [
                            628, 
                            53
                        ], 
                        [
                            628, 
                            475
                        ], 
                        [
                            336, 
                            475
                        ]
                    ], 
                    "score": 0.99999905
                }
            }
        ], 
        "errors": [
            null
        ], 
        "faces": [
            "1102"
        ]
    }
    
    

    删除人脸

    删除指定人像库中一个或多个人脸

    请求语法

    POST /v1/face/group/<id>/delete  Http/1.1
    Content-Type: application/json
    Authorization: Qiniu <AccessKey>:<Sign>
    
    {
        "faces":[
            <face_id>,
            ...
        ]
    }
    
    

    注意: 需要在 POST 请求的 head 部分添加七牛鉴权,以进行用户身份验证。

    请求字段说明:

    字段 取值 是否必选 说明
    id string Y 需要删除的人脸所在人像库的唯一标识
    face_id string Y 需要删除的人脸ID

    响应语法

    200 ok
    
    {
        "code": 0,
        "message": "",
    }
    

    注意: 删除成功响应内容为空。

    显示所有的人像库

    显示所有已建立的人像库的唯一id

    请求语法

    GET /v1/face/group  Http/1.1
    Authorization: Qiniu <AccessKey>:<Sign>
    
    

    注意: 需要在 POST 请求的 head 部分添加七牛鉴权,以进行用户身份验证。

    响应语法

    200 ok
    
    {
        "code": 0,
        "message": "",
        "result": [
            <id>,
            ...
        ]
    }
    

    返回字段说明:

    字段 取值 说明
    code int 0:表示正确
    message string 结果描述信息
    id string 人像库唯一标识

    响应示例:

    {
        "code": 0, 
        "message": "", 
        "result": [
            "1",
            "2"
        ]
    }
    
    

    显示人脸

    显示指定的人像库中的所有人脸

    请求语法

    GET /v1/face/group/<id>  Http/1.1
    Authorization: Qiniu <AccessKey>:<Sign>
    
    

    注意: 需要在 POST 请求的 head 部分添加七牛鉴权,以进行用户身份验证。

    请求字段说明:

    字段 取值 是否必选 说明
    id string Y 人像库的唯一标识

    响应语法

    200 ok
    
    {
        "code": 0,
        "message": "",
        "result": [
            {
                "id": <id>,
                "value": {
                    "name": "xx"
                }
            },
            ...
        ]
    }
    

    返回字段说明:

    字段 取值 说明
    code int 0:表示正确
    message string 结果描述信息
    id string 人脸ID
    value.name string 人物姓名

    响应示例

    {
        "code": 0, 
        "message": "", 
        "result": [
            {
                "id": "1101", 
                "value": {
                    "name": "jack"
                }
            }, 
            {
                "id": "BwAAAGC9vHa7rDMV", 
                "value": {
                    "name": "anne"
                }
            }, 
                    {
                "id": "1102", 
                "value": {
                    "name": "jessica"
                }
            }
        ]
    }
    
    

    人脸库搜索

    人脸库搜索。对于待搜索图片中检测到的每张人脸,在指定的人像库中返回其相似度最高的多张人脸ID。

    注意: 支持在多个库内进行搜索。

    请求语法

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

    注意: 需要在 POST 请求的 head 部分添加七牛鉴权,以进行用户身份验证。

    请求字段说明:

    字段 取值 是否必选 说明
    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 匹配人脸TOPN,默认为1,最大允许10000。若为-1,则返回所有匹配人脸
    params.threshold float N 匹配人脸的精度阈值,默认使用系统设置值(根据特征提取版本不同会有微小变动,目前取值0.4)。若该值小于系统设置值,则仍使用系统设置值

    响应语法

    200 ok
    
    {
        "code": 0,
        "message": "",
        "result": {
            "faces": [
                {
                    "bounding_box": {
                        "pts": [[205,400],[1213,400],[1213,535],[205,535]],
                        "score":0.998
                    },
                    "faces": [
                        {
                            "bounding_box": {
                                "pts": [[105,200],[678,200],[678,480],[105,480]],
                                "score":0.956
                            },
                            "id": "xx",
                            "name": "xx",
                            "group": "xx",
                            "score":0.9998,
                            "desc": <additional information>
                        },
                        ...
                    ]
                }
            ]
        }
    }
    

    返回字段说明:

    字段 取值 说明
    code int 0:表示正确
    message string 结果描述信息
    result.faces list 图片中检测到的所有人脸
    result.faces[].bounding_box map 图片中某张人脸的边框信息
    result.faces.[].faces list 对于图片中某张人脸,检索出的相似人脸列表
    result.faces[].faces[].bounding_box map 检索得到的人脸的边框信息
    bounding_box.pst list[4] 人脸边框在图片中的位置[左上,右上,右下,左下]
    bounding_box.score float 人脸位置检测准确度
    id string 检索得到的人脸唯一标识
    name string 检索得到的人物姓名
    group string 检索得到的人脸所属的人像库id
    score float 0~1,检索结果的可信度,1为确定
    desc map 人脸图片入库时的备注信息

    响应示例:

     {
        "code": 0, 
        "message": "", 
        "result": {
            "faces": [
                {
                    "bounding_box": {
                        "pts": [
                            [
                                375, 
                                314
                            ], 
                            [
                                424, 
                                314
                            ], 
                            [
                                424, 
                                382
                            ], 
                            [
                                375, 
                                382
                            ]
                        ], 
                        "score": 0.98729205
                    }, 
                    "faces": []
                }, 
                {
                    "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", 
                            "group": "4", 
                            "id": "1101", 
                            "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", 
                            "group": "4", 
                            "id": "1102", 
                            "name": "jessica", 
                            "review": false, 
                            "score": 0.47173265
                        }
                    ]
                }
            ], 
            "review": false
        }
    }
    
    

    人脸库搜索(旧版本)

    对于待搜索图片中检测到的每张人脸,在指定的人脸库中返回其相似度最高的一张人脸ID。

    注意: 此接口用于给在2018年7月24日之前接入的用户进行对照查看,请新用户统一使用上方新人脸搜索接口。

    请求语法

    POST /v1/face/group/<id>/search Http/1.1
    Content-Type: application/json
    Authorization: Qiniu <AccessKey>:<Sign>
    
    {
        "data": {
            "uri": "http://xx.com/xxx"
        }
    }
    

    注意: 需要在 POST 请求的 head 部分添加七牛鉴权,以进行用户身份验证。

    请求字段说明:

    字段 取值 是否必选 说明
    id string Y 人像库的唯一标识
    uri string Y 图片资源。支持两种资源表达方式:
    1. 网络图片URL地址;
    2. 图片 base64 编码字符串,需在编码字符串前加上前缀 data:application/octet-stream;base64,。例:data:application/octet-stream;base64,xxx

    响应语法

    200 ok
    
    {
        "code": 0,
        "message": "",
        "result": {
            "detections": [
                {
                    "boundingBox": {
                        "pts": [[205,400],[1213,400],[1213,535],[205,535]],
                        "score":0.998
                    },
                    "value": {
                        "boundingBox": {
                            "pts": [[105,200],[678,200],[678,480],[105,480]],
                            "score":0.956
                        },
                        "id": "xx",
                        "name": "xx",
                        "score":0.9998,
                        "desc": <additional information>
                    }
                }
            ]
        }
    }
    

    返回字段说明:

    字段 取值 说明
    code int 0:表示正确
    message string 结果描述信息
    result.detections list 图片中检测到的所有人脸
    result.detections.[].boundingBox map 图片中某张人脸的边框信息
    result.detections.[].value map 对于图片中某张人脸,检索出的最相似的人脸信息
    result.detections.[].value.boundingBox map 对于图片中某张人脸,检索出的最相似的人脸坐标
    boundingBox.pst list[4] 人脸边框在图片中的位置[左上,右上,右下,左下]
    boundingBox.score float 人脸位置检测准确度
    id string 检索得到的人脸唯一标识
    name string 检索得到的人物姓名
    score float 0~1,检索结果的可信度,1为确定
    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
        }
    }
    
    

    服务价格

    总调用量P 费用
    单位:万张 单价(元/百张)
    0 < P ≤ 500 0.19
    500 < P ≤ 1500 0.18
    1500 < P ≤ 3000 0.17
    P > 3000 0.16

    注意:人像库在50万张以内不收底库费用,如底库超过50万张请提交工单与我们联系。

    计费示例

    某公司2018年5月使用七牛云1:N人脸比对别服务,共发起500万张请求,
    则当月使用七牛云1:N人脸比对服务产生的费用为:

    确定的结果产生费用:0.19元/百张 * 500万张 = 9500 元

    总计费用:9500 元

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