SDK配合调用接口

1./v2/sdk/get_token

1.1 接口描述

该API的功能是配合活体检测SDK使用,在SDK启动前获取token,get_token 接口是与 liveness_auth 配对使用的,使用get_token 获取token,活体检测初始化时调用liveness_auth 对token进行验证

请求方式

POST

请求 URL

https://cloudapi.linkface.cn/v2/sdk/get_token

1.2 请求参数

字段 类型 必需 描述
sequence_id string 客户请求流水号(建议使用64位的随机字符串,用于客户查询日志使用)
api_id string API账户
detection_type string 检测类型(取值范围:liveness、idcard_ocr、bankcard_ocr),如果传其他值过来,则报入参错误,1002,请求参数错误
timestamp string 时间戳
sign string 签名(api_id+api_secret+timestamp使用SHA256算法获取)

所有中文和特殊字符必需以UTF-8编码转义。

签名sign说明:

我们会为每位公有云用户分配一个账户API ID和对应秘钥API SECRET。为了保证安全性,用户的每次接口调用都需要上传一个签名(基于API ID和API SECRET获取)。

Java示例代码:

SHA256Util.getSHA256Str(LF_APP_ID + LF_APP_SECRET + timeStamp)
/**
     * 利用java原生的摘要实现SHA256加密
     *
     * @param str 加密后的报文
     */
    public static String getSHA256Str(String str) {
        MessageDigest messageDigest;
        String encodeStr = "";
        try {
            messageDigest = MessageDigest.getInstance("SHA-256");
            messageDigest.update(str.getBytes("UTF-8"));
            encodeStr = byte2Hex(messageDigest.digest());
        } catch (NoSuchAlgorithmException e) {
            e.printStackTrace();
        } catch (UnsupportedEncodingException e) {
            e.printStackTrace();
        }
        return encodeStr;
    }
    /**
     * 将byte转为16进制
     */
    private static String byte2Hex(byte[] bytes) {
        StringBuffer stringBuffer = new StringBuffer();
        String temp = null;
        for (int i = 0; i < bytes.length; i++) {
            temp = Integer.toHexString(bytes[i] & 0xFF);
            if (temp.length() == 1) {
                //1得到一位的进行补0操作
                stringBuffer.append("0");
            }
            stringBuffer.append(temp);
        }
        return stringBuffer.toString();
    }

1.3 返回参数

字段 类型 描述
request_id string 本次请求的唯一流水号(建议使用64位的随机字符串,用于客户查询日志使用)
code string 业务响应码
msg string 消息说明
data object 消息体(只有0000调用成功时返回)
charge int 是否收费,1收费,2不收费

data详情:

字段 类型 描述
token string SDK鉴权token,token的有效期是5分钟,超过5分钟后,客户服务端需重新调用get_token获取token。

输出示例:

成功返回示例:
{
  "request_id": "TID2af751b4bff24be781d60af10bf84101",
  "code": "0000",
  "msg": "调用成功",
"data": {
  "token":"dstj2af751b4bff24be781d60af10bf84101"
}
  "charge": 2
}
失败返回示例:
{
  "request_id": "TID2af751b4bff24be781d60af10bf84101",
  "code": "1008",
  "msg": "服务无权限",
  "charge": 2
}

1.4 错误码

状态码code msg 字段 说明
0000 调用成功 成功
1000 验签失败 验签失败
1001 参数非UTF-8编码 参数非UTF-8编码
1002 请求参数错误 请求参数错误
1007 应用冻结 未授权
1008 应用过期 账号过期
1009 调用频率过高 调用频率超出限额
1011 服务无权限 无调用权限
9999 其他错误 服务器内部错误

1.5 输入示例

  • cURL 样例
curl -X POST "https://cloudapi.linkface.cn/v2/sdk/get_token?sequence_id=SEQUENCE&api_id=ID"  -F detection_type=DETECTION -F timestamp=TIMESTAMP -F sign=SIGN

2./v2/sdk/identity/liveness_idnumber_verification

2.1 接口描述

该API的功能是将活体检测SDK返回的加密文件中的活体数据与身份证件照片进行比对,来判断是否同一个人。配合活体检测SDK使用,活体检测通过后,对活体加密数据做人证比对检验,返回人脸和证件比对分值,客户可根据分值判断是否匹配为同一个人。

  • 图片要求
    1. 格式为 JPG(JPEG),BMP,PNG,GIF,TIFF
    2. 宽和高大于 8px,小于等于4000px
    3. 小于等于 2 MB,建议100KB以内
    4. 人脸双眼间距不小于30像素,建议90像素以上
    5. 图像中人脸图像较清晰,不因镜头散焦或运动而模糊
    6. 眼睛的瞳孔清晰可见,镜面无反光,禁止戴墨镜,且眼镜框不得遮挡眼睛,不要带宽框眼镜
    7. 人脸光线均匀且无阴影,亮度在200-800Lux,面部无明显反光、逆光、侧光
    8. 要求头发及饰物不能遮挡人脸,禁止戴口罩,帽子
    9. 表情自然、放松、无夸张动作,脸部区域完整、轮廓清晰、人脸比例不失真
    10. 照片中只允许有1张人脸,且背景简单,无复杂场景
    11. 人脸姿态要求,平面旋转(roll)±15°,俯仰变化(pitch)±10°,姿态偏转(yaw)±15°

请求方式

POST

请求 URL

https://cloudapi.linkface.cn/v2/sdk/identity/liveness_idnumber_verification

2.2 请求参数

字段 类型 必需 描述
sequence_id string 客户请求流水号(建议使用64位的随机字符串,用于客户查询日志使用)
api_id string API 账户
name string 姓名
id_number string 身份证号码
auto_hack string 可选 开启防hack功能。开通:true,不开通:false。默认true
liveness_encrypt_data file 可选 活体检测SDK返回的加密文件,上传本地文件时选取此参数。加密文件大小不可超过10M
liveness_encrypt_data_url string 可选 活体检测SDK返回的加密文件的url。采用抓取网络文件方式时选取此参数
liveness_encrypt_data_id string 可选 活体检测SDK返回的加密文件的id。已上传过加密文件的可选取此参数
timestamp string 时间戳
sign string 签名

请求参数liveness_encrypt_data, liveness_encrypt_data_url与 liveness_encrypt_data_id 三选一。 如同时传入多个参数,本API使用顺序为liveness_encrypt_data_id优先,其次liveness_encrypt_data、liveness_encrypt_data_url。

2.3 返回参数

字段 类型 描述
request_id string 本次请求的唯一流水号(建议使用64位的随机字符串,用于客户查询日志使用)
code string 业务响应码
msg string 消息说明
data object 消息体(只有0000调用成功时返回)
charge int 是否收费,1收费,2不收费

code为0000且check_result为1时,charge为1收费;其他情况(code非0000或code为0000但check_result为2),charge为2,不收费;

data详情:

字段 类型 描述
check_result int 查询结果 1人证比对查得 2图片质量校验不合格
id_name_result int 身份核验结果 1姓名身份证号一致 2姓名身份证号不一致 3库无
photo_result int 图片校验结果 1比对成功 2库中无照片 3特征提取失败
certificate_score double 人脸和证件照比对结果系统判断为不同人:[0,40) 不确定是否为同一人:[40,45) 系统判断为同一人:[45,100]
hack_score double 防hack得分(auto_hack=true时返回)取值范围是0~1。值越大表示被hack的可能性越大
liveness_encrypt_data_id string 云端加密文件的id

说明:当check_result为1时,会返回id_name_result,当id_name_result为1时,会返回photo_result,当photo_result为1时,会返回certificate_score;当check_result为2时,不返回id_name_result、photo_result、certificate_score的内容;当id_name_result非1时,不返回photo_result、certificate_score的内容;当photo_result非1时,不返回certificate_score的内容 hack_score阈值为0.98,由行业大数据训练得到,大于0.98是hack行为,小于等于0.98是正常活人

输出示例:

查询成功,返回全部结果
{
  "request_id": "TID2af751b4bff24be781d60af10bf84101",
  "code": "0000",
  "msg": "调用成功",
"data": {
  "result":1,
  "id_name":01,
  "photo":01,
  "score":50,
}
  "charge": 1
}
返回部分结果(库中无照片)
{
  "request_id": "TID2af751b4bff24be781d60af10bf84101",
  "code": "0000",
  "msg": "调用成功",
"data": {
  "result":1,
  "id_name":1,
  "photo":2,
}
  "charge": 1
}
返回部分结果(二要素比对不一致)
{
  "request_id": "TID2af751b4bff24be781d60af10bf84101",
  "code": "0000",
  "msg": "调用成功",
"data": {
  "result":1,
  "id_name":2,
}
  "charge": 1
}
返回部分结果(图片前置校验不通过)
{
  "request_id": "TID2af751b4bff24be781d60af10bf84101",
  "code": "0000",
  "msg": "调用成功",
"data": {
  "result":2,
}
  "charge": 2
}
查询失败
{
  "request_id": "TID2af751b4bff24be781d60af10bf84101",
  "code": "1000",
  "msg": "验签失败",
  "charge": 2
}

2.4 错误码

状态码code msg 字段 说明
0000 调用成功 成功
1000 验签失败 验签失败
1001 参数非UTF-8编码 参数非UTF-8编码
1002 请求参数错误 请求参数错误
1003 加密文件错误 加密文件错误
1004 未检测出人脸 图片未检测出人脸
1005 网络图片获取超时 网络地址图片获取超时
1006 网络图片获取失败 网络地址图片获取失败
1007 应用冻结 未授权
1008 应用过期 账号过期
1009 调用频率过高 调用频率超出限额
1010 免费次数用尽 调用次数超出限额
1011 服务无权限 无调用权限
1012 请求路径错误 请求路径错误
1017 数据源服务出错 数据源服务出错
9999 其他错误 服务器内部错误

2.5 输入示例

  • cURL 样例
curl -X POST "https://cloudapi.linkface.cn/v2/sdk/identity/liveness_idnumber_verification?sequence_id=SEQUENCE&api_id=ID" -F name=NAME -F id_number=NUMBER -F timestamp=TIMESTAMP -F sign=SIGN -F liveness_encrypt_data=@/PATH/TO/FILE

3./v2/sdk/liveness_hack_dectect

3.1 接口描述

该API的功能为检测用户拍摄的活体数据是否活人。配合活体检测SDK使用,活体检测通过后,对活体加密数据做防hack检验,返回hack分值。

请求方式

POST

请求 URL

https://cloudapi.linkface.cn/v2/sdk/hackness/liveness_hack_detect

3.2 请求参数

字段 类型 必需 描述
sequence_id string 客户请求流水号(建议使用64位的随机字符串,用于客户查询日志使用)
api_id string API账户
liveness_encrypt_data file 见下方注释 活体检测SDK返回的加密文件,上传本地文件时选取此参数。加密文件大小不可超过10M
liveness_encrypt_data_url string 见下方注释 活体检测SDK返回的加密文件的url。采用抓取网络文件方式时选取此参数
liveness_encrypt_data_id string 见下方注释 活体检测SDK返回的加密文件的id。已上传过加密文件的可选取此参数
timestamp string 时间戳
sign string 签名(api_id+api_secret+timestamp使用SHA256算法获取)

请求参数 liveness_encrypt_data, lliveness_encrypt_data_url与 lliveness_encrypt_data_id 三选一。如同时传入多个参数,本API使用顺序为lliveness_encrypt_data_id优先,其次liveness_encrypt_data、lliveness_encrypt_data_url

3.3 返回参数

字段 类型 描述
request_id string 本次请求的唯一流水号(建议使用64位的随机字符串,用于客户查询日志使用)
code string 业务响应码
data object 消息体(只有0000调用成功时返回)
charge int 是否收费,1收费,2不收费

收费标准:code为0000,charge为1时收费;其他情况(code非0000),charge为2,不收费;

data详情:

字段 类型 描述
hack_score double 防hack得分取值范围是0~1。值越大表示被hack的可能性越大
liveness_encrypt_data_id string 云端加密文件的id

hack_score阈值为0.98,由行业大数据训练得到,大于0.98是hack行为,小于等于0.98是正常活人

输出示例:

成功返回示例:
{
  "request_id": "TID2af751b4bff24be781d60af10bf84101",
  "code": "0000",
  "msg": "调用成功",
"data": {
  "hack_score":0.73737747347734,
  “liveness_encrypt_data_id”:“TID2af751b4bff24be781d60af10bf84101”
}
  "charge": 1
}
失败返回示例:
{
  "request_id": "TID2af751b4bff24be781d60af10bf84101",
  "code": "1000",
  "msg": "验签失败",
  "charge": 2
}

3.4 错误码

状态码code msg 字段 说明
0000 调用成功 成功
1000 验签失败 验签失败
1001 参数非UTF-8编码 参数非UTF-8编码
1002 请求参数错误 请求参数错误
1003 加密文件错误 加密文件错误
1004 未检测出人脸 图片未检测出人脸
1005 网络图片获取超时 网络地址图片获取超时
1006 网络图片获取失败 网络地址图片获取失败
1007 应用冻结 未授权
1008 应用过期 账号过期
1009 调用频率过高 调用频率超出限额
1010 免费次数用尽 调用次数超出限额
1011 服务无权限 无调用权限
1012 请求路径错误 请求路径错误
9999 其他错误 服务器内部错误

3.5 输入示例

  • cURL 样例
curl -X POST "https://cloudapi.linkface.cn/v2/sdk/hackness/liveness_hack_detect?sequence_id=SEQUENCE&api_id=ID" -F timestamp=TIMESTAMP -F sign=SIGN -F liveness_encrypt_data=@/PATH/TO/FILE

4./v2/sdk/identity/liveness_selfie_verification

4.1 接口描述

该 API 的功能是将活体检测SDK返回的加密文件中的活体数据与自拍照片进行比对,来判断是否同一个人。配合活体检测SDK使用,活体检测通过后,对活体加密数据做人脸比对检验,返回人脸比对分值,客户可根据分值判断是否为同一个人。

  • 自拍照要求
    1. 格式为 JPG(JPEG),BMP,PNG,GIF,TIFF
    2. 宽和高大于 8px,小于等于4000px
    3. 小于等于 5 MB

请求方式

POST

请求 URL

https://cloudapi.linkface.cn/v2/sdk/identity/liveness_selfie_verification

2.请求参数

字段 类型 必需 描述
api_id string API 账户
sequence_id string 客户请求流水号,建议唯一性(建议使用64位的随机字符串,用于客户查询日志使用)
selfie_file file 选择照片,上传本地图片进行检测时选取此参数
selfie_url string 选择照片的网络地址,采用抓取网络图片方式时需选取此参数
selfie_image_id string 自拍照片的id,在云端上传过自拍照片可采用选取此参数
selfie_auto_rotate string 开启图片自动旋转功能。开通:true,不开通:false。默认false
selfie_auto_hack string 开启防hack功能。开通:true,不开通:false。默认true
liveness_encrypt_data file 活体检测SDK返回的加密文件,上传本地文件时选取此参数。加密文件大小不可超过10M
liveness_encrypt_data_url string 活体检测SDK返回的加密文件的url。采用抓取网络文件方式时选取此参数
liveness_encrypt_data_id string 活体检测SDK返回的加密文件的id。已上传过加密文件的可选取此参数
timestamp string 时间戳
sign string 签名(api_id+api_secret+timestamp使用SHA256算法获取)

请求参数 selfie_file , selfie_url与 selfie_image_id 三选一,如同时传入多个参数,优先级:selfie_image_id、selfie_file、selfie_url 请求参数 liveness_encrypt_data, lliveness_encrypt_data_url与 liveness_encrypt_data_id 三选一。 如同时传入多个参数,本API使用顺序为liveness_encrypt_data_id优先,其次liveness_encrypt_data、liveness_encrypt_data_url。

4.3 返回参数

字段 类型 描述
request_id string 本次请求的唯一流水号(建议使用64位的随机字符串,用于客户查询日志使用)
code string 业务响应码
msg string 消息说明
data object 消息体(只有code为0000调用成功时返回)
charge int 是否收费,1收费,2不收费

收费标准:code为0000,charge为1时收费;其他情况(code非0000),charge为2,不收费;

data详情:

字段 类型 说明
face_score double 人脸比对置信度值为 0~1,值越大表示两张照片是同一个人的可能性越大。
hack_score double 防hack得分(selfie_auto_hack=true时返回)取值范围是0~1。值越大表示被hack的可能性越大
liveness_encrypt_data_id string 云端加密文件的id。
image_id string 使用file、url方式上传公安部后台预留返回的公安部后台预留的带水印照片的id

hack_score阈值为0.98,由行业大数据训练得到,大于0.98是hack行为,小于等于0.98是正常活人

face_score置信度阈值与错误率对应关系:

阈值 0.4 0.5 0.6 0.7 0.8 0.9
错误率 十分之一 百分之一 千分之一 万分之一 十万分之一 百万分之一

输出示例:

成功返回示例:
{
  "request_id": "TID2af751b4bff24be781d60af10bf84101",
  "code": "0000",
  "msg": "调用成功",
"data": {
 "face_score":0.76737747347734,
  "hack_score":0.97737747347734,
 “liveness_encrypt_data_id”:“2af751b4bff24be781d60af10bf84101”,
  “image_id”:"2af751b4bff24be781d60af10bf84101"
}
  "charge": 1
}
失败返回示例:
{
  "request_id": "TID2af751b4bff24be781d60af10bf84101",
  "code": "1000",
  "msg": "验签失败",
  "charge": 2
}

4.4 错误码

code msg 说明
0000 调用成功 成功
1000 验签失败 验签失败
1001 参数非UTF-8编码 参数非UTF-8编码
1002 请求参数错误 请求参数错误
1003 加密文件错误 liveness_data 出错
1004 未检测出人脸 图片未检测出人脸
1005 网络图片获取超时 网络地址图片获取超时
1006 网络图片获取失败 网络地址图片获取失败
1007 应用冻结 未授权
1008 应用过期 账号过期
1009 调用频率过高 调用频率超出限额
1010 免费次数用尽 调用次数超出限额
1011 服务无权限 无调用权限
1012 请求路径错误 请求路径错误
1013 图片体积过大 图片体积过大
1014 图片不存在 图片不存在
1015 文件不是图片或已损坏 文件不是图片文件或已经损坏
1016 图片大小或格式不符合要求 图片大小或格式不符合要求
9999 其他错误 服务器内部错误

4.5 输入示例

  • cURL 样例
curl -X POST "https://cloudapi.linkface.cn/v2/sdk/identity/liveness_selfie_verification?sequence_id=SEQUENCE&api_id=ID" -F timestamp=TIMESTAMP -F sign=SIGN -F liveness_encrypt_data=@/PATH/TO/FILE1 -F selfie_file=@/PATH/TO/FILE2
?>

results matching ""

    No results matching ""