接入文档
RAW纯接口接入
静默活体
上传读数视频进行活体验证
上传读数视频进行活体验证

# 描述

通过自拍一段人脸视频进行活体认证。上传视频成功后使用回传的标识token_still调用Raw-Verify接口进行比对和活体结果获取。

仅当appkey有使用API服务的静默活体验证权限时,才可以调用此API,否则返回错误码 403(AUTHORIZATION_ERROR:Denied)。

# 调用URL

https://api.megvii.com/faceid/lite/raw/validate_still

注意:在生产环境中,请使用HTTPS的通信方式。HTTP方式的通信属于不安全链路,存在安全风险,请勿在生产环境中使用。在生产环境中使用HTTP方式的,将无法得到服务可靠性保障。

# 调用方法

POST  注意:用 form-data 格式请求

参数

必选/可选 参数 类型 参数说明
必选 api_key String 调用此API的api_key。
必选 api_secret String 调用此API的api_key的secret。
必选 video File 需用户上传的视频,视频要求为ffmpeg所支持的格式及码率,视频建议时长为1~3秒,容量不大于20MB。
可选 biz_no String 用于标志一次验证流程,不超过128字符。如果使用此参数,强烈建议对一次验证流程中调用的API(比如Raw-ValidateStill*、Raw-Verify*)使用同一个biz_no,对不同的验证流程使用不同的biz_no
可选 liveness_preferences String 本参数可选,表示一系列可以放松或加强活体检测的特别的选项。目前可用的选项有:“none”:表示没有特别的选项,此为默认值。"still_strict":表示针对上传的视频进行相对严格的活体检测,此设置会提高安全性,但在一定程度上影响通过率。设置其他值,均会返回400(BAD_ARGUMENTS)。本参数对静默活体可用,视频活体严格程度的调节在verify接口中设置。
可选 return_image String 此参数为可选参数,决定了是否返回从视频中截取的最佳质量图像:0(默认):不需要图像1:需要返回最佳质量图 (仅当API调用成功后才返回)
可选 face_occlusion_detection String 用于设置是否开启人脸遮挡检测。0(默认):不开启;1:开启,如发生全程人脸遮挡,则活体不通过

# 返回值说明

字段 类型 说明
request_id String 用于区分每一次请求的唯一的字符串。此字段必定返回。
time_used Int 整个请求所花费的时间,单位为毫秒。此字段必定返回。
biz_no String **此参数仅当调用时设置了biz_no参数才返回,但是如果设置了则即使API调用失败也返回,**值与传入的biz_no保持完全一致。
token_still String **本字段仅调用成功才返回,**返回的token仅供Raw-Verify API使用。本字段不超过1024字节。**注意:**Token有效期为24小时
image_best String 本字段仅调用成功才返回,返回为将会用于人脸比对的视频中的最佳质量的人脸照片。return_image字段配置为0,或者没有配置,则不返回这个字段。return_image字段配置为1,并用Base64字符串返回,图像格式为JPEG。在异常情况下,该字段有可能返回null。
error_message String 当请求失败时才会返回此字符串,具体返回内容见后续错误信息章节。否则此字段不存在。

成功

{
  "time_used": 6206,
  "biz_no": "12345",
  "token_still": "68d32116d9ba2d2662812df30705dcb5",
  "request_id": "1491803871,dc23ec02-5ab5-48a4-8fe9-95f4eeb37699",
  "image_best": "data:image/jpeg;base64,..."
 
}

失败

{
  "time_used": 1,
  "error_message": "MISSING_ARGUMENTS: video",
  "request_id": "1491803987,5c52c7c6-e974-4c83-9f22-9d268d6e35b0"
}

Raw-ValidateStill API特有的 ERROR_MESSAGE

HTTP 状态代码 错误信息 说明
400 VIDEO_FACE_NOT_FOUND 上传的视频中没有检测到人脸
400 VIDEO_LOW_FACE_QUALITY 上传的视频中人脸质量太差
400 VIDEO_INVALID_DURATION 上传的视频时长不对
400 VIDEO_UNSUPPORTED_FORMAT 视频无法解析,有可能是ffmpeg不支持的格式或视频有破损
400 VIDEO_FACE_OCCLUDE 上传的视频中人脸被遮挡

错误码列表通用的ERROR_MESSAGE

HTTP 状态代码 错误信息 说明
403 AUTHENTICATION_ERROR api_key 和 api_secret 不匹配。
403 AUTHORIZATION_ERROR: api_key被停用、调用次数超限、没有调用此API的权限,或者没有以当前方式调用此API的权限。目前的有:Denied. (没有权限调用当前API)
403 CONCURRENCY_LIMIT_EXCEEDED 并发数超过限制。
400 MISSING_ARGUMENTS: 缺少某个必选参数。
400 BAD_ARGUMENTS: 某个参数解析出错(比如必须是数字,但是输入的是非数字字符串; 长度过长;不允许的输入值。)
404 API_NOT_FOUND 所调用的API不存在。
500 INTERNAL_ERROR 服务器内部错误,当此类错误发生时请再次请求,如果持续出现此类错误,请及时联系 FaceID 客服或商务。
该文档未解决您的疑问?查看常见问题