人脸比对sensetime API 文档
接口说明
基于商汤的人脸算法，对两张通过接口上传的人脸照片进行比对，来判断是否为同一个人。若上传的照片中包含 exif 方向信息，我们会按此信息旋转、翻转后再做后续处理。同时，我们还提供自动旋转功能，当照片方向混乱且 exif 方向信息不存在或不正确的情况下，服务会根据照片中人脸方向来检查可能正确的方向，并按照正确的方向提供人脸检测结果。
部分开发语言demo如下，其他开发语言请参照文档进行开发，也欢迎热心的开发者到 讯飞开放平台社区 分享你们的demo。
人脸比对demo go语言
- 集成人脸比对API时，需按照以下要求:
| 内容 | 说明 |
|---|---|
| 请求协议 | http[s] (为提高安全性，强烈推荐https) |
| 请求地址 | http[s]: //api.xfyun.cn/v1/service/v1/image_identify/face_verification 注：服务器IP不固定，为保证您的接口稳定，请勿通过指定IP的方式调用接口，使用域名方式调用 |
| 请求方式 | POST |
| 接口鉴权 | 签名机制，见授权认证 |
| 字符编码 | UTF-8 |
| 响应格式 | 统一采用JSON格式 |
| 开发语言 | 任意，只要可以向讯飞云服务发起HTTP请求的均可 |
| 适用范围 | 任意操作系统，但因不支持跨域不适用于浏览器，请在后端调用接口 |
| 照片属性 | 宽和高必须大于8px，小于等于4000px |
| 照片格式 | JPG/BMP/PNG/GIF/TIFF |
| 照片大小 | 图像数据按要求编码后(base64编码后进行urlencode)大小不超过5M |
白名单
在调用该业务接口时
- 若关闭IP白名单，接口认为IP不限，不会校验IP。
- 若打开IP白名单，则服务端会检查调用方IP是否在讯飞开放平台配置的IP白名单中，对于没有配置到白名单中的IP发来的请求，服务端会拒绝服务。
注： 若需配置IP白名单，请前往控制台。
IP白名单规则
- IP白名单，在 控制台-我的应用-相应服务的应用管理卡片上 编辑，保存后五分钟左右生效；
- 不同Appid的不同服务都需要分别设置IP白名单；
- IP白名单需设置为外网IP，请勿设置局域网IP；；
- 如果服务器返回结果如下所示(illegal client_ip)，则表示由于未配置IP白名单或配置有误，服务端拒绝服务。
{
"code":"10105",
"desc":"illegal access|illegal client_ip",
"data":"",
"sid":"xxxxxx"
}
请求参数
- 通过接口密钥基于MD5计算签名，将签名以及其他参数放在Http Request Header中，详见下方 请求头 。
- 将图片数据放在Http Request Body中，以POST表单的形式提交，详见下方 请求体 。
接口地址示例：
POST http[s]://api.xfyun.cn/v1/service/v1/image_identify/face_verification HTTP/1.1
Content-Type:application/x-www-form-urlencoded; charset=utf-8
请求头
在 Http Request Header 中配置以下参数。
鉴权说明
以下参数用于授权认证：
| 参数 | 格式 | 说明 | 必须 |
|---|---|---|---|
| X-Appid | string | 讯飞开放平台注册申请应用的应用ID(appid) | 是 |
| X-CurTime | string | 当前UTC时间戳 从1970年1月1日0点0 分0 秒开始到现在的秒数 | 是 |
| X-Param | string | 相关参数JSON串经Base64编码后的字符串，详见业务参数 | 是 |
| X-CheckSum | string | 令牌，计算方法：MD5(APIKey + X-CurTime + X-Param)，三个值拼接的字符串，进行MD5哈希计算（32位小写） | 是 |
注：
- APIKey：接口密钥，在讯飞开放平台控制台添加相应服务后即可获取，调用方注意保管，如泄露，可到控制台提交工单联系技术人员重置；
- X-CheckSum 有效期：出于安全性考虑，每个 X-CheckSum 的有效期为 5 分钟(用 X-CurTime 计算)，同时 X-CurTime 要与标准时间同步，否则时间相差太大，服务端会直接认为 X-CurTime 无效；
- BASE64 编码采用 MIME 格式，字符包括大小写字母各26个，加上10个数字，和加号 + ，斜杠 / ，一共64个字符。
*X-CheckSum *生成示例：
String APIKey="abcd1234";
String X-CurTime="1502607694";
String X-Param="eyAiYXVmIjogImF1ZGlvL0wxNjtyYXR...";
String X-CheckSum=MD5(apiKey + X-CurTime + X-Param);
业务参数
X-Param 为各配置参数组成的 JSON 串经 BASE64 编码之后的字符串，原始 JSON 串各字段说明如下：
| 参数 | 类型 | 必须 | 说明 | 示例 |
|---|---|---|---|---|
| auto_rotate | bool | 否 | 是否对图片进行自动旋转，true旋转，false不旋转，默认false | true |
X-Param生成示例：
原始JSON串：
{
"auto_rotate": True,
}
BASE64编码（即X-Param）：
ewoJICAgICJhdXRvX3JvdGF0ZSI6ICJ0cnVlIiwKCX0=
请求体
以POST表单的形式提交以下参数：
| 参数 | 类型 | 必须 | 说明 |
|---|---|---|---|
| first_image | string | 是 | 图片数据1，base64编码后进行URLEncode |
| second_image | string | 是 | 图片数据2，base64编码后进行URLEncode |
注：
图片格式必须为JPG（JPEG）、BMP、PNG、GIF、TIFF之一。
图片宽和高必须大于 8px，小于等于 4000px。
要求两张图片编码后大小不超过5M。
一般基础类库会默认进行urlencode处理，请注意不要重复处理。
java示例(可参考示例demo)：
first_image = urlencode(base64(图片1)) & second_image = urlencode(base64(图片2))
返回结果
如出现错误码，可到 这里 查询。
返回参数示例：
失败：
{
"code": "10105",
"data": 0,
"desc": "illegal access|illegal X-CheckSum",
"sid": "wsr00127c......"
}
成功：
{
"code": "0",
"data": 0.903714,
"desc": "success",
"sid": "wsr000f06......"
}
返回参数说明：
| 参数 | 类型 | 说明 |
|---|---|---|
| code | string | 结果码(具体见SDK&API错误码查询) |
| desc | string | 结果码描述 |
| data | float | 得分，值为 0~1，值越大表示是同一个人的可能性越大 |
| sid | string | 会话ID，用来唯一标识本次请求会话，如果会话出现问题无法解决，可以通过工单提供 sid 给讯飞技术人员分析解决。 |
data中得分阈值与错误率对应关系：
| 阈值 | 0.4 | 0.5 | 0.6 | 0.7 | 0.8 | 0.9 |
|---|---|---|---|---|---|---|
| 错误率 | 十分之一 | 百分之一 | 千分之一 | 万分之一 | 十万分之一 | 百万分之一 |
建议阈值：0.7~0.8
常见问题
人脸比对主要有什么功能？
答：对两张上传的人脸照片进行比对，来判断是否为同一个人。
人脸比对对上传的图片有什么要求？
答：（1）格式必须为 JPG（JPEG），BMP，PNG，GIF，TIFF 之一； （2）宽和高必须大于 8px，小于等于 4000px； （3）文件尺寸小于等于 5 MB。
人脸比对支持活体检测吗？
答：人脸比对是支持静态照片的对比，不支持活体检测功能。
人脸比对支持什么应用平台？
答：支持Web api应用平台。
人脸比对怎么免费使用？
答：登录讯飞开放平台，进入人脸比对产品页面，点击“服务管理”，创建应用，可免费使用500次，授权期限为1个月。
人脸比对服务量怎么购买？
答：控制台对应人脸比对服务--->实时用量--->点击购买服务量，填好相关信息，商务工作人员会及时与您联系。