人臉實名認證
更新時間 2025-09-16 16:02:16
最近更新時間: 2025-09-16 16:02:16
分享文章
提供基于權威庫的實名認證服務，支持二代居民身份證的三要素（姓名、身份號碼+人像正臉照片）核驗
接口描述
提供基于權威庫的實名認證服務，支持二代居民身份證的三要素（姓名、身份號碼+人像正臉照片）核驗。
請求方法
POST
接口要求
- 圖片格式限制：支持 jpeg格式，BASE64 字符串無需包含格式頭，注意去除換行符
- 圖片大小限制：原始尺寸需壓縮至 10~40KB，否則可能會因為過小或過大而導致人像比對不通，影響比對效率；
請求URI
/v1/aiop/api/348c0ca2pkw0/gcapi/simpauth66
請求參數
1.請求頭header參數
| 參數 | 是否必填 | 參數類型 | 說明 | 示例 | 下級對象 |
|---|---|---|---|---|---|
| Content-Type | 是 | String | json 格式 | application/json | |
| appkey | 是 | String | 平臺應用appkey | 562b89493b1a40e1b97ea05e50dd8170 | |
| ctyun-eop-request-id | 是 | String | 用戶請求 id，由用戶構造，用戶可以通過 uuid 等方法自行生成唯一字符串，用于日志請求追蹤。 詳見文檔：Python3調用示例 |
33dfa732-b27b-464f-b15a-21ed6845afd5 | |
| eop-date | 是 | String | 請求時間，由用戶構造，形如 yyyymmddTHHMMSSZ。 詳見文檔：Python3調用示例 |
20211221T163014Z | |
| host | 是 | String | 終端節點域名，固定字段 | ai-global.ctapi.daliqc.cn | |
| Eop-Authorization | 是 | String | 由天翼云官網 accessKey 和 securityKey 經簽名后生成，參與簽名生成的字段包括天翼云官網 accessKey 、securityKey、平臺應用的appkey（非必須），用戶請求id（非必須），請求時間，終端節點域名（非必須）以及請求體內容。 簽名邏輯詳見文檔：認證鑒權和Python3調用示例 |
2.請求體body參數
| 參數 | 是否必填 | 參數類型 | 說明 | 示例 | 下級對象 |
|---|---|---|---|---|---|
| portrait | 是 | String | BASE64 編碼的人像圖;原始尺寸需壓縮至 10~40KB，否則可能會因為過小或過大而導致人像比對不通，影響比對效率； BASE64 字符串無需包含格式頭，注意去除換行符 | "_9j_4AAQSkZJRgA..." | |
| idNum | 是 | String | 認證的用戶身份證號碼（號碼最后一位 X 約定為大寫） | 13x6xx199x07xx98xx | |
| fullName | 是 | String | 認證的用戶姓名（注意去除空格等非常規字符） | 龍傲天 |
請求代碼示例
Curl -X POST
"//ai-global.ctapi.daliqc.cn/v1/aiop/api/348c0ca2pkw0/gcapi/simpauth66"
-H "Content-Type: application/json"
-H "ctyun-eop-request-id:33dfa732-b27b-464f-b15a-21ed6845afd5"
-H "appkey:XXX"
-H "Eop-Authorization:XXX"
-H "eop-date:20211109T104641Z"
-H "host:ai-global.ctapi.daliqc.cn"
--data '{"portrait": "_9j_4AAQSkZJRgA...","idNum": "13x6xx199x07xx98xx","fullName": "龍傲天"}'
返回值說明
1.請求成功返回響應參數
| 參數 | 是否必填 | 參數類型 | 說明 | 示例 | 下級對象 |
|---|---|---|---|---|---|
| statusCode | 是 | Int | 返回狀態，返回 0 表示成功，返回錯誤代碼參考下面的錯誤代碼列表。 | 0 | |
| retMessage | 是 | String | 接口調用結果/認證結果文字說明 | "success" | |
| certToken | 是 | String | 本次認證的記錄憑證，建議記錄起來，方便后續定位排查，當code為0、4101、4109時，該字段不為空 | ||
| resStr | 是 | String | 本次認證結果的具體說明，詳看“認證結果代碼說明”；若僅判斷認證是否成功，可直接通過code判斷，當code為0、4101、4109時，該字段不為空 |
認證結果代碼說明
| 結果字節 | 所表示的結果 |
|---|---|
| 第一字節 | 姓名，身份號碼比對結果 |
| 第二字節 | 人像比對結果 |
| 第三字節 | 可忽略 |
| 第四字節 | 可忽略 |
第一字節說明
| 返回代碼 | 代碼說明 | 可能出現原因 | 下一步建議 |
|---|---|---|---|
| 0 | 身份信息有效 | -- | -- |
| 5 | 身份信息無效 | 1.身份信息不存在 2.身份信息不匹配 | 檢查身份信息 |
| 6 | 參數錯誤 | 身份信息格式不正確 | 檢查身份信息 |
| 7 | 系統錯誤 | 系統錯誤或服務異常 | -- |
| A | 穿網調用超時 | 內部接口穿網調用超時 | -- |
| E | 接口調用異常 | 內部接口接口調用異常 | -- |
| T | 接口調用超時 | 內部接口接口調用超時 | -- |
| X | 未執行 | 未執行 | -- |
| 其他代碼 | 其他 | 其他 | -- |
第二字節說明
| 返回代碼 | 代碼說明 | 可能出現原因 | 下一步建議 |
|---|---|---|---|
| 0 | 同一人 | -- | -- |
| 1 | 非同一人 | 1.照片為本人，但是照片可能有角度、光線過暗、臉部區域有亮斑；2.照片為本人，但是該照片尺寸太小 | 1.重新拍照； 2.傳入合格圖片 |
| 2 | 疑似為本人 | 1.照片為本人，但是照片可能有角度、光線過暗、臉部區域有亮斑；2.照片為本人，但是該照片尺寸太小；3.兩人長相類似 | 1.重新拍照；2.傳入合格圖片 |
| A | 數據庫操作錯誤 | 人像比對數據庫操作異常 | -- |
| B | 人像比對異常 | 人像比對系統異常 | -- |
| C | 參數錯誤 | 身份證號為空或長度不是 18 位 | -- |
| D | 無人像信息 | 數據庫中無該人像信息 | 檢查該人身份信息是否正確 |
| E | 圖像格式不正式 | 非JPEG格式圖像 | 檢查傳入的圖像數據是否為JPEG格式 |
| F | 待比對圖像建模失敗 | 1.照片可能有角度，光線過暗，臉部區域有亮斑，模糊；2.照片尺寸太小 | 1.重新拍照；2.傳入合格圖片 |
| G | 現場照片質量不合格 | 上傳照片質量不合格 | 自檢上傳照片質量 |
| J | 現場照片小于5K字節 | 現場照片小于5K字節 | 檢查圖像原始大小（非BASE64編碼）是否小于5K字節，重新拍照 |
| K | 照片質量不佳 | 庫內照片質量不佳 | 系統人像信息異常或者未錄入認證系統 |
| T | 人像引擎超時 | 人像服務所有比對引擎同時超時或一個引擎超時，另一個引擎故障 | 重試 |
| W | 系統其他錯誤 | 認證超時 | 重試 |
| X | 未執行 | 未執行 | 重試或者聯系運維人員 |
| 其他代碼 | 其他 | 其他 | -- |
返回值示例
1.請求成功返回值示例
{
"certToken": "d182ca85-xxxx-xxxx-xxxx-868cb258ceab",
"resStr": "00XX",
"statusCode": 0,
"retMessage": "成功"
}
2.請求失敗返回值示例
{
"statusCode": 1,
"retMessage": "接口調用失敗"
"error":"AI_OP_4101"
}
狀態碼
| http狀態碼 | 描述 |
|---|---|
| 200 | 表示接口調用成功。 |
錯誤碼說明
| 錯誤碼 | 錯誤信息 | 錯誤描述 |
|---|---|---|
| AI_OP_1 | 接口調用失敗 | 接口調用失敗 |
| AI_OP_2 | 服務器錯誤 | 服務器錯誤 |
| AI_OP_4002 | 參數錯誤，見retMessage | 如 portrait字段需為圖片轉換的base64字符串、portrait字段過長、不是有效的身份號碼 等 |
| AI_OP_4010 | 認證接口并發已到上限 | QPS達到上限 |
| AI_OP_4101 | 身份認證未通過 | 身份認證未通過 |
| AI_OP_4103 | 身份認證服務異常 | 身份認證服務異常 |
| AI_OP_4104 | 認證接口調用超時 | 認證接口調用超時 |
| AI_OP_4109 | 非庫內人員 | 非庫內人員，該人員身份信息未收錄或姓名與身份證號不匹配 |
base64 編碼規則：使用常規的 safe base64 編碼方式
- python 中推薦使用
base64.urlsafe_b64encode()函數進行編碼。 - java 中推薦使用
BASE64.getUrlEncoder().encodeToString()函數進行編碼。
