SDK配合调用接口

• 1. get_token
• 2. liveness_idnumber_verification
• 3. liveness_hack_dectect
• 4. liveness_selfie_verification
• 5. parse_liveness_result

1./v2/sdk/get_token

• 1.1 接口描述
• 1.2 请求参数
• 1.3 返回参数
• 1.4 错误码
• 1.5 输入示例

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 请求参数

所有中文和特殊字符必需以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 返回参数

data详情：

输出示例:

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

1.4 错误码

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 接口描述
• 2.2 请求参数
• 2.3 返回参数
• 2.4 错误码
• 2.5 输入示例

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 请求参数

请求参数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 返回参数

code为0000且check_result为1时，charge为1收费；其他情况（code非0000或code为0000但check_result为2），charge为2，不收费；

data详情：

说明：当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 错误码

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 接口描述
• 3.2 请求参数
• 3.3 返回参数
• 3.4 错误码
• 5.输入示例

3.1 接口描述

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

请求方式

POST

请求 URL

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

3.2 请求参数

请求参数 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 返回参数

收费标准：code为0000，charge为1时收费；其他情况（code非0000），charge为2，不收费；

data详情：

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 错误码

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 接口描述
• 4.2 请求参数
• 4.3 返回参数
• 4.4 错误码
• 4.5 输入示例

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

4.2 请求参数

请求参数 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 返回参数

收费标准：code为0000，charge为1时收费；其他情况（code非0000），charge为2，不收费；

data详情：

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

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

输出示例：

成功返回示例：
{
    "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 错误码

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

5./v2/sdk/liveness/parse_liveness_result

• 5.1 接口描述
• 5.2 请求参数
• 5.3 返回参数
• 5.4 错误码
• 5.5 输入示例

5.1 接口描述

该 API 的功能是将活体检测SDK返回的加密文件进行解密，并输出相关信息。

请求方式

POST

请求 URL

https://cloudapi.linkface.cn/v2/sdk/liveness/parse_liveness_result

5.2 请求参数

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

5.3 返回参数

收费标准：code为0000，charge为1时收费；其他情况（code非0000），charge为2，不收费；

data详情：

输出示例：

成功返回示例：
{
    "request_id": "TID2af751b4bff24be781d60af10bf84101",
    "code": "0000",
    "msg": "成功",
    "data": {
        "liveness_result": true,
        "motion_process": [1,3,4],
        "image_id": "870c238affe60845a6db484df3bd1c24",
        "video_id": "870c238affe60845a6db484df3bd1c24"
    }
    "charge": 1
}

失败返回示例：
{
    "request_id": "TID2af751b4bff24be781d60af10bf84101",
    "code": "1000",
    "msg": "验签失败",
    "charge": 2
}

5.4 错误码

5.5 输入示例

• cURL 样例

curl -X POST "https://cloudapi.linkface.cn/v2/sdk/liveness/parse_liveness_result?sequence_id=SEQUENCE&api_id=ID" -F timestamp=TIMESTAMP -F sign=SIGN -F liveness_encrypt_data=@/PATH/TO/FILE