get_biz_token

接口说明

此接口只适用于FaceID MegLiveStill SDK 3.0.0及以上版本

SDK 2.0版本请参考 v2.0.0 文档

SDK 1.3版本及以下版本请参考 v1.2.0 文档

通过此接口设置后续活体检测和比对的相关参数，并获取biz_token。

biz_token会作为SDK的输入参数，有效期为1小时。参见android SDK说明和iOS SDK说明。
biz_token也会作为verify接口的输入参数，进行云端活体检测和人脸比对，有效期为1小时。参见文档。

接口地址

POST https://api.megvii.com/faceid/v3/sdk/get_biz_token

参数

参数名	可选/必选	类型	说明
sign	必选	String	客户签名，签名算法参见文档
sign_version	必选	String	签名算法版本，目前仅支持: "hmac_sha1"
liveness_type	必选	String	活体验证流程的选择，目前仅取以下值： meglive：动作活体 still：静默活体 flash：炫彩活体
comparison_type	必选	Int	本次验证服务的类型。 0：表示活体照片和上传照片进行比对(人脸比对)。 1：表示活体照片和参考数据进行比对（KYC验证）
idcard_name	comparison_type=1时，必选	String	姓名
idcard_number	comparison_type=1时，必选	String	身份证号
image_ref1	comparison_type = 0时，必选	File	上传照片1。说明： - 当comparison_type = 0时，支持用户传1～2张上传照片（最少传入1张） - 当comparison_type = 1时，用户也可以传1～2张上传照片 - 如果在任一张上传照片图中都没有找到人脸，将返回错误码400(NO_FACE_FOUND:image_ref1)； - 如果这些图片中任一张中有多张脸，将选择最大人脸进行比对。
image_ref2	可选	File	上传照片2，规则参数上面的描述
uuid	comparison_type = 0时，必选	String	用于标志本次识别对应的用户的唯一ID，不长于128字节。建议您对来自同一用户的比对请求使用同样的ID，这非常有利于您反查验证结果以及获得更好的报表服务体验。
biz_no	可选	String	客户业务流水号，建议设置为您的业务相关的流水串号并且唯一，不长于128字节
liveness_timeout	可选	Int	超时时间，示用户进入活体识别流程后的超时时间，若未在规定时间完成操作，则本次活体失败。超时时间设定：单位秒， ∈ [5, 60] 动作活体时，设置每个动作的超时时间，默认 10 静默活体时，设置照镜子的超时时间，默认 60
liveness_action_count	可选	Int	动作活体时动作个数，默认值为3（即3个随机动作），可选值1，2，3
eyes_close_detection	可选	String	表示炫彩活体的超时时间，默认值为 120秒。表示用户进入活体识别流程后的超时时间，若未在规定时间完成操作，则本次活体失败。超时时间设定：单位秒， ∈ [60, 180]。若参数值超过限定范围，则返回BAD_ARGUMENTS错误。
flash_liveness_timeout	可选	String	表示静默活体是否进行闭眼检测，取值如下： 0：默认值，不进行睁闭眼检测； 1：开启睁闭眼检测，若用户全程闭眼，则活体检测失败。
verbose	可选	String	表示返回数据的详细程度，取值如下： 0：默认值，仅返回结论 1：返回结论与摘要信息
security_level	可选	Int	表示对比对结果的严格程度限制，请根据您的场景，选择安全规则，越严格，准确性要求越高，通过率也会相应下降 1：宽松(误识率为千分之一)； 2：标准(误识率为万分之一，默认值）； 3：严格(误识率为十万分之一）；
force_compare	可选	Int	表示云端判断为假脸后，是否依然进行比对； 0: 默认值，云端判断为假脸，则直接返回结果，不执行比对，可以节省成本； 1: 云端判断为假脸后，依然进行比对
multi_oriented_detection	可选	Int	对于image_ref1,image_ref2 上传照片，当检测不出人脸时，是否旋转90度、180度、270度后再检测人脸。 "1": 默认值，要旋转检测； “0”：不旋转；其他值：返回错误码400（BAD_ARGUMENTS）请注意：设置此参数为1可能会轻微增加误检人脸的概率，如果您明确您的业务场景里不存在非正向的人脸图片、或概率极低，建议勿设置此参数。
liveness_level	可选	Int	表示活体SDK端严格等级（当前仅静默活体使用），取值如下： 0：严格模式，默认值； 1：标准模式； 2：极速模式。
maximum_brightness	可选	Int	表示活体SDK进入活体时是否将屏幕亮度调到最大(针对V3.3.3以上SDK中动作与静默生效)，取值如下： 0：不调整，默认值； 1：调整到最大亮度。

Python 请求示例

# comparison_type=1
import requests
data = {
    "sign": "XXXXX",
    "sign_version": "hmac_sha1",
    "liveness_type": "meglive",
    "comparison_type": "1",
    "idcard_name": "张三",
    "idcard_number": "123456789012345678",
    }
url = "https://api.megvii.com/faceid/v3/sdk/get_biz_token"
res = requests.post(url=url, data=data)
print(res.json())

# comparison_type=0
import requests
data = {
    "sign": "XXXXX",
    "sign_version": "hmac_sha1",
    "liveness_type": "meglive",
    "comparison_type": "0",
    "uuid": "123456",
    "image_ref1": "XXXX",  # File类型
    }
url = "https://api.megvii.com/faceid/v3/sdk/get_biz_token"
res = requests.post(url=url, data=data)
print(res.json())

返回值

参数	类型	参数说明
request_id	string	用于区分每一次请求的唯一的字符串
time_used	int	整个请求所花费的时间，单位为毫秒
biz_token	string	该返回值作为调用SDK的输入参数注：biz_token唯一且只能使用一次，且有效期为1小时。
error	string	当请求失败时才会返回此字符串，具体返回内容见错误码列表

返回结果示例：成功

{
    "biz_token": "1532412036,c26a7243-d47c-440f-ade1-6c09dd9cba46",
    "request_id": "1532412036,5df6bb83-d4ab-407d-9eb2-b12dd9f6ca55",
    "time_used": 813
}

返回结果示例：失败

{
    "error": "MISSING_ARGUMENTS:sign",
    "request_id": "1532412061,8e001d6b-8396-401a-86a1-108d13c66c80",
    "time_used": 196
}

错误码列表

HTTP状态码	错误信息	说明
400	MISSING_ARGUMENTS:<key>	缺少某个必选参数。
400	BAD_ARGUMENTS:<key>	某个参数解析出错（比如必须是数字，但是输入的是非数字字符串; 或者长度过长）
400	IMAGE_ERROR_UNSUPPORTED_FORMAT:<param>	参数<param>对应的图像无法解析，有可能不是图像文件、或有数据破损。<param>为 image_ref1、 image_ref2中的一个。请注意：<param>只会有一项，即第一个满足条件的名称。
400	NO_FACE_FOUND:<param>	表示上传的 image_ref 的图像中，没有检测到人脸。param>为 image_ref1、 image_ref2中的一个。请注意：<param>只会有一项，即第一个满足条件的名称。
400	INVALID_IMAGE_SIZE:<param>	客户上传的图像太大，具体是指像素尺寸的长或宽超过4096像素。<param>为 image_ref1、 image_ref2中的一个。请注意：<param>只会有一项，即第一个满足条件的名称。
400	MULTIPLE_FACES	image图片中的有多张人脸。
403	AUTHENTICATION_ERROR	无效签名
403	AUTHORIZATION_ERROR:<reason>	api_key被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限。 <reason> 取值： 1、 API_KEY_BE_DISCONTINUED:api_key被停用 2、 IP_NOT_ALLOWED:不允许访问的IP（预留设计） 3、 MORE_RETRY_TIMES：比对重试次数达到上限 4、 EXPIRED_SIGN：签名已过期 5、 INVALID_SIGN：无效签名其他可能的错误码，请预留处理方案
403	CONCURRENCY_LIMIT_EXCEEDED	并发数超过限制
404	API_NOT_FOUND	所调用的API不存在
413	Request Entity Too Large	客户发送的请求大小超过了20MB限制。该错误的返回格式为纯文本，不是json格式。
500	INTERNAL_ERROR	服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系 FaceID 客服或商务

当前版本

v3.0.0

历史版本

v2.0.0 文档
v1.2.0 文档