注意
接口描述
接口请求域名:
https://recognition.image.myqcloud.com/face/livedetectfour
本接口(livedetectfour)用于判断录制的唇语视频中人物是否为真人(活体检测),同时判断唇语视频中的人脸与给定的一张人脸照片的人脸相似度,即判断视频中的人与给定一张照片的人是否为同一人。注意
本接口支持 HTTPS 协议,如果您现在使用的是 HTTP 协议,为了保障您的数据安全,请切换至 HTTPS。
如果开发者使用的是原域名(service.image.myqcloud.com),为获得更好的体验,请及时切换到以上域名。
请求头 header
所有请求都要求含有下表列出的头部信息:
参数名 | 必选 | 值 | 描述 |
host | 是 | recognition.image.myqcloud.com | 腾讯云人脸核身服务器域名。 |
content-length | 否 | 包体总长度 | 建议视频的大小为3MB 以下。 |
content-type | 是 | multipart/form-data | 仅支持上传本地视频文件。 |
authorization | 是 | 鉴权签名 |
注意
选择 multipart/form-data,请使用 HTTP 框架/库推荐的方式设置请求的 content-type,不推荐直接调用 setHeader 等方法设置,否则可能导致 boundary 缺失引起请求失败。
输入参数
使用 multipart/form-data 格式:
参数名 | 必选 | 类型 | 说明 |
appid | 是 | String | |
validate_data | 是 | String | livegetfour 得到的唇语验证数据。 |
video | 是 | Binary | 录制的视频(建议对视频进行压缩处理,减少视频大小有助于减少上传时间和节约流量)。 |
compare_flag | 是 | Bool | video 中的照片和 Card 做对比: |
在设置 form-data 数据时设置为字符串"true"、"false"。 | - | - | - |
参数为 True 时做对比,card 是对比的照片,会返回活体检测和对比的结果。 | - | - | - |
参数为 False 时只做活体检测,card 字段可不填,只返回活体检测的结果。 | - | - | - |
card | 否 | Binary | 需要检测的另一张照片。 |
seq | 否 | String | 标识请求的序列号。 |
注意
录制的视频里,用户需缓慢清晰念出 livegetfour 得到的唇语验证数字。
输出参数
字段 | 类型 | 说明 |
data.live_status | Int | 返回活体检测错误码,非0值为出错。 |
data.live_msg | String | 返回错误描述。 |
data.compare_status | Int | 返回人脸对比检测错误码,非0值为出错( compare_flag 是 True 的时候才返回)。 |
data.compare_msg | String | 返回错误描述( compare_flag 是 True 的时候才返回)。 |
data.sim | Int | 相似度,取值范围 [0, 100],推荐相似度大于70时可判断为同一人,可根据具体场景自行调整阈值(阈值70的误通过率为千分之一,阈值80的误通过率是万分之一)( compare_flag 是 True 并且识别成功的时候才返回)。 |
data.photo | String | 返回相似度最高的 video 中的一张图像( compare_flag 是 True 并且识别成功的时候才返回, base64编码)。 |
code | Int | 错误码。 |
message | String | 错误描述。 |
注意: 此处分为两个流程:活体检测和人脸比对。其中live_status表示活体检测成功与否,compare_status表示对比成功与否,只有 compare_status为 0 时,才有 sim 和 photo 字段。您在使用本接口时,需要先判断活体检测是否成功( live_status ),再判断人脸比对是否成功( compare_status ),最后判断 sim 是否大于阈值(如 sim > 75 )。
示例
输入示例
POST /face/livedetectfour HTTP/1.1Authorization: FCHXdPTEwMDAwMzc5Jms9QUtJRGVRZDBrRU1yM2J4ZjhRckJi==Host: service.image.myqcloud.comContent-Length: 641Content-Type: multipart/form-data;boundary=--------------acebdf13572468----------------acebdf13572468Content-Disposition: form-data; name="appid";123456----------------acebdf13572468Content-Disposition: form-data; name="validate_data";9532----------------acebdf13572468Content-Disposition: form-data; name="compare_flag";true----------------acebdf13572468Content-Disposition: form-data; name="video"; filename="video.flv"yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy----------------acebdf13572468Content-Disposition: form-data; name="card"; filename="face.jpg"Content-Type: image/jpegxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx----------------acebdf13572468--
输出示例
HTTP/1.1 200 OKConnection: keep-aliveContent-Length: 168Content-Type: application/json{"data":{"live_status":0,"live_msg":"OK","compare_status":0,"compare_msg":"OK","sim":90,"photo":"xxxxxxxxxxxxxx",},"code":0,"message":"OK"}
错误码
错误码 | 含义 |
3 | 错误的请求;其中 message:account abnormal,errorno is:2 为账号欠费停服 |
4 | 签名为空 |
5 | 签名串错误 |
6 | 签名中的 APPID/Bucket 与操作目标不匹配 |
9 | 签名过期 |
10 | APPID 不存在 |
11 | SecretId 不存在 |
12 | APPID 和 SecretId 不匹配 |
13 | 重放攻击 |
14 | 签名校验失败 |
15 | 操作太频繁,触发频控 |
16 | Bucket 不存在 |
21 | 无效参数 |
23 | 请求包体过大 |
24 | 无权限,未申请服务 |
107 | 鉴权服务不可用 |
108 | 鉴权服务不可用 |
213 | 内部错误 |
-4006 | 视频中自拍照特征提取失败 |
-4007 | 视频中自拍照之间对比失败 |
-4009 | Card 照片提取特征失败 |
-4010 | 自拍照与 Card 照片相似度计算失败 |
-4011 | 照片解码失败 |
-4012 | 照片人脸检测失败 |
-4015 | 自拍照人脸检测失败 |
-4016 | 自拍照解码失败 |
-4017 | Card 照片人脸检测失败 |
-4018 | Card 照片解码失败 |
-5001 | 视频无效,上传文件不符合视频要求 |
-5002 | 唇语失败 |
-5005 | 自拍照解析照片不足,视频里检测到的人脸较少 |
-5007 | 视频没有声音 |
-5008 | 语音识别失败,视频里的人读错数字 |
-5009 | 视频人脸检测失败,没有嘴或者脸 |
-5010 | 唇动检测失败,视频里的人嘴巴未张开或者张开幅度小 |
-5011 | 活体检测失败(活体其他错误都归类到里面) |
-5012 | 视频中噪声太大 |
-5013 | 视频里的声音太小 |
-5014 | 活体检测 level 参数无效 |
-5015 | 视频像素太低,最小 270 * 480 |
-5016 | 视频里的人不是活体(翻拍等攻击) |
-5801 | 请求缺少身份证号码或身份证姓名 |
-5802 | 服务器内部错误,服务暂时不可用 |
-5803 | 身份证姓名与身份证号码不一致 |
-5804 | 身份证号码无效(因户口变动,极少数正常用户也会返回这个结果,此类用户无法使用本服务) |
-5805 | 用户未输入图像或者 url 下载失败 |