ecologyDoc/AI/人脸识别接口文档.md

### 注意事项
1. 以下接口请求头必须加入`Authorization`，值为授权token([如何获取token](../core/Token使用文档.md))
2. 接口数据格式 `Json`

### 人脸比对
> 用于照片+照片，或者照片+视频的对比，视频支持做出指定动作<br>
> 请求方式  ` POST http://172.20.109.105:7007/tech/ai/face/match` <br> 


| 请求参数  || 类型 | 是否必填 | 说明 |
| --- | --- |--- | --- | --- | 
| async || boolean| 否 | 是否开启异步反馈模式，默认为false |
| extData  || | 否 | 附加参数登记，详见[接口调用附加信息登记](./接口调用附加信息登记.md) |
| liveCode || String| 否 | 传入对比数据为视频并选择LIP模式时必传，值通过[数字验证码接口](#yanzhengma)获取 | 
| image || -| - | 对比时要参照的客户照片 |
|| origin | String| 否 | image的数据类型。<br/> base64字符串：self (**base64内容需在400k以内**)<br/>来自文件服务器：fds （**带压缩效果，推荐使用，详见[fds使用文档](../file/文件服务器接口.md)）**<br/>图片链接：uri <br/>默认为 self |
|| data | String| 是 | 图片数据（base64，文件服务器文件路径或链接） |
| faceData| | -| - | 需要比对的客户照片或视频 |
| |type | String| 是 | 照片：image <br/> 视频：video |
| |videoType | String| 否 | type为video时生效。<br/>SILENT：默认，静默模式，视频不需要做动作 <br/> LIP：数字模式，视频需读出指定数字<br/>传该字段时，不能为空字符串|
| |origin | String| 否 | faceData的数据类型。<br/> base64字符串：self (**base64内容需在400k以内**)<br/>来自文件服务器：fds （**带压缩效果，推荐使用，详见[fds使用文档](../file/文件服务器接口.md)）**<br/>视频链接：uri <br/>默认为 self <br/>传该字段时，不能为空字符串|
| |data | String| 是 | 视频数据（base64，文件服务器文件路径或链接） |


| 返回参数  || | 类型 | 是否必返 | 说明 |
| --- | --- | --- |--- | --- | --- |
| errcode ||| Num| 是 | 0交易成功<br>其它为异常情况 |
| errmsg ||| String | 否 | errcode不为0时有值 | 
| data| || - | - | 包含数据见下 |
| |status || String | 是 | “SUCCESS”为业务成功 |
| |traceNo || String | 是 | 当前业务的唯一id |
| |result|| String | 是 | 业务结果 |
| ||success | String | 否 | true：人脸比对成功<br>false：人脸比对出错 |
| ||score | String | 否 | 匹配分数，建议达到80分可认为是同一人照片 |

请求示例

```
{
     "async":false,
     "liveCode":"1232",
     "image":{
         "origin":"fds",
         "data":"xxxxxxxxxxxxxx.jpg"
     },
     "faceData":{
         "type":"video",
         "videoType":"SILENT",
         "origin":"fds",
         "data":"xxxxxxxxxxxxxx.mp4"
     }
}
```

返回示例

```
{
    "errcode":0,
    "data":{
        "status":"SUCCESS",
        "traceNo":"45646513218465123",
        "result":{
            "success":"true",
            "score":"99"
        }, 
    },
    "errmsg":"SUCCESS"
}
```

### 身份验证
> 用于身份证查到的公安库照片+传入照片，或者公安库照片+视频的对比，视频支持做出指定动作<br>
> 请求方式  ` POST http://172.20.109.105:7007/tech/ai/face/match/idno`

| 请求参数  || 类型 | 是否必填 | 说明 |
| --- | ---| --- | --- | --- | 
| async || boolean| 否 | 是否开启异步反馈模式，默认为false |
| extData  || | 否 | 附加参数登记，详见[接口调用附加信息登记](./接口调用附加信息登记.md) |
| idNum || String| 是 | 验证人的身份证号 |
| name || String| 是 | 验证人的姓名 |
| liveCode || String| 是 | 数字验证码，选择LIP模式时必传，值通过[数字验证码接口](#yanzhengma)获取 |
| faceData || -| - | 需要比对的客户照片或视频 |
| |type | String| 是 | 照片：image <br/> 视频：video |
| |videoType | String| 是 | type为video时生效。<br/>SILENT：默认，静默模式，视频不需要做动作 <br/> LIP：数字模式，视频需读出指定数字<br/>传该字段时，不能为空字符串|
| |origin | String| 否 | faceData的数据类型。<br/> base64字符串：self (**base64内容需在400k以内**)<br/>来自文件服务器：fds （**带压缩效果，推荐使用，详见[fds使用文档](../file/文件服务器接口.md)）**<br/>视频链接：uri <br/>默认为 self <br/>传该字段时，不能为空字符串|
| |data | String| 是 | 视频数据（base64，文件服务器文件路径或链接） |
| personType || String| 否 | 人员类型，normal-普通客户 vip-高级客户 inner-内部员工 | 


| 返回参数  || | 类型 | 是否必返 | 说明 |
| --- | --- | --- |--- | --- | --- |
| errcode ||| Num| 是 | 0交易成功<br>其它为异常情况 |
| errmsg ||| String | 否 | errcode不为0时有值 | 
| data| || - | - | 包含数据见下 |
| |status || String | 是 | “SUCCESS”为业务成功 |
| |traceNo || String | 是 | 当前业务的唯一id |
| |result|| String | 是 | 业务结果 |
| ||success | String | 否 | true：验证通过<br>false：验证不通过 |
| ||score | String | 否 | 匹配分数，验证通过时返回，推荐达到70时可判断为同一人（70的误通过率为千分之一，80的误通过率是万分之一，根据具体场景自行调整阈值）|

请求示例

```
{
     "async":false,
     "idNum":"身份证号码",
     "name":"姓名",
     "liveCode":"1232",
     "faceData":{
         "type":"video",
         "videoType":"SILENT",
         "origin":"fds",
         "data":"xxxxxxxxxxxxxx.mp4"
     }
}
```

返回示例

```
{
    "errcode":0,
    "data":{
        "status":"SUCCESS",
        "traceNo":"45646513218465123",
        "result":{
            "success":"true",
            "score":"99"
        }, 
        

    },
    "errmsg":"SUCCESS"
}
```


<span id='yanzhengma'></span>

### 获取数字验证码
> 请求方式  ` POST http://172.20.109.105:7007/tech/ai/face/match/validateData` <br> 

| 请求参数  | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- | 
| 无 | -| - | - |

| 返回参数  || | 类型 | 是否必返 | 说明 |
| --- | --- | --- |--- | --- | --- |
| errcode ||| Num| 是 | 0交易成功<br>其它为异常情况 |
| errmsg ||| String | 否 | errcode不为0时有值 | 
| data| || - | - | 包含数据见下 |
| |status || String | 是 | “SUCCESS”为业务成功 |
| |traceNo || String | 是 | 当前业务的唯一id |
| |result|| String | 是 | 业务结果 |
| ||code | String | 是 | 数字验证码 |


请求示例

```
{
    
}
```

返回示例

```
{
    "errcode":0,
    "data":{
        "status":"SUCCESS",
        "traceNo":"45646513218465123",
        "result":{
            "code":"2312
        }, 
        

    },
    "errmsg":"SUCCESS"
}
```