人脸对比
一、接口描述
1.功能描述
人脸 1比1 比对 API 主要用于对传入的两张图的人脸进行比较，得到两张脸的相似度。
2. 接口使用
在获得使用权限后，您可使用已经封装好的SDK进行相应开发，整体流程详见调用方法 。
3.图片要求
- 图片格式：bmp, jpg, jpeg, png, jfif
- 图片像素尺寸：最小 48*48 像素，最大 2048*2048 像素
- 图片 Base64 大小：小于2MB
二、请求说明
1. 接口地址 ：
https://aiapi.jdcloud.com/jdai/faceCompareV1
2. 请求方式：
https post aiapi.jdcloud.com/jdai/faceCompareV1
3. 请求参数
（1）header请求参数
业务请求参数
| 名称 | 类型 | 必填 | 示例值 | 描述 |
|---|---|---|---|---|
| Authorization | string | 是 | JDCLOUD2-HMAC-SHA256Credential=access... | 签名 |
（2）body请求参数
业务请求参数
| 名称 | 类型 | 必填 | 示例值 | 描述 |
| imgBase64A | string | 是 | 图像Base64编码值，去掉图片头"data:image/png;base64,"，imgBase64A=iVBORw0K...（由于过长，不给出示例） | 第一张图片Base64编码 |
| imgBase64B | string | 是 | 图像Base64编码值，去掉图片头"data:image/png;base64,"，imgBase64B=iVBORw0K...（由于过长，不给出示例） | 第二张图片Base64编码 |
4. 请求代码示例
建议您使用我们提供的SDK进行调用，SDK获取及调用方式详见sdk的使用方法
三、返回说明
1、返回参数
（1）公共返回参数
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| code | string | 1000 | 参见错误码-系统级错误码 |
| charge | boolean | false 或 true | false：不扣费， true：扣费 |
| remain | long | 1305 | 按天计算剩余调用次数 |
| msg | string | 查询成功 | 参见错误码-系统级错误码 |
| result | object | {...} | 查询结果 |
（2）业务返回参数
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| code | int | 0 | 状态码，0 为成功，非 0 请参考以下 业务错误码 |
| msg | string | Accept | 状态码对应的说明 |
| processTimeInMs | long | 34 | 从接收请求到处理结束的耗时，毫秒 |
| timestamp | long | 1576728627956 | 返回时的时间戳 |
| score | float | 0.65 | 人脸相似度：万分之一误识率下阈值: 0.49, 十万分之一误识率下阈值: 0.54, 百万分之一误识率下阈值：0.58 |
| faceItemsA | array | [ ] | 每个人脸的检测结果；具体类型请参考下方 |
| faceItemsB | array | [ ] | 每个人脸的检测结果；具体类型请参考下方 |
faceItems 数组中单个元素的结构：
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| boundingBox | object | { "left" : 490.11, "top" : 85.42, "width" : 108.84, "height" : 143.84 } | 人脸识别矩形框的位置，包括以下属性值： left：矩形框左上角像素点的横坐标 top：矩形框左上角像素点的纵坐标 width：矩形框的宽度 height：矩形框的高度 |
| posture | object | { "yaw" : -11.58, "pitch" : -4.56, "roll" : -2.37 } | 人脸角度，包括以下属性值： yaw：人脸旋转角度，偏航角（Y轴），单位 度 pitch：人脸旋转角度，俯仰角（X轴），单位 度 roll：人脸旋转角度，翻滚角（Z轴），单位 度 |
| isValidPosture | bool | true | 人脸角度是否在合理的阈值内 |
| blurScore | float | 0.03 | 人脸模糊度，值越低越模糊，越高越清晰 |
2、返回示例
{ "code": "10000", "charge": true, "remain": 998, "remainTimes": 998, "remainSeconds": -1, "msg": "查询成功,扣费", "result": { "code": 0, "faceItemsA": [ { "blurScore": "0.21", "boundingBox": { "height": "133.65", "left": "365.02", "top": "20.81", "width": "102.35" }, "isValidPosture": true, "posture": { "pitch": "-4.59", "roll": "-9.92", "yaw": "-3.87" } } ], "faceItemsB": [ { "blurScore": "0.21", "boundingBox": { "height": "133.64", "left": "365.01", "top": "20.81", "width": "102.35" }, "isValidPosture": true, "posture": { "pitch": "-4.59", "roll": "-9.92", "yaw": "-3.87" } } ], "msg": "Accept", "processTimeInMs": 170, "score": "1.00", "timestamp": 1585188492431 } } 3、业务错误码
| 业务错误码（status） | 对应msg | 说明 |
| 1 | NoRequiredFields | 参数缺失 |
| 2 | ImageIsTooSmall | 图片太小 |
| 3 | ImageIsTooLarge | 图片太大 |
| 4 | Base64IsInvalid | 图片 Base64 不合法 |
| 5 | Base64IsTooLarge | 图片 Base64 大小超过 2MB |
| 10 | NoFaceDetected | 没有检测到人脸 |
| 11 | InvalidFaceQuality | 人脸不够清晰，质量分小于阈值 |
| 12 | InvalidFacePosture | 人脸角度太大，大于阈值 |
| 15 | FeatureCompareFail | 人脸比对失败，比对分值 大于阈值 |
| 31 | RequestBodyIsNotJson | 请求的 body 需要 json 字符串 |
| 41 | TimeoutException | 处理超时（> 10秒的处理立即返回） |
更新时间：2020-04-28 21:14:26
文档反馈
