ID Verification：FACE_IDU_MIN

名稱

類型

是否必選

描述

樣本值

ProductCode

String

是

產品方案標識，固定取值：FACE_IDU_MIN。

FACE_IDU_MIN

MerchantBizId

String

是

商戶業務唯一標識，用於後續定位排查問題。支援32 位字母和數字組合。服務端不校正此ID唯一性，商戶應自行保證唯一。

e0c34a77f5ac40a5aa5e6ed20c35****

MerchantUserId

String

是

商戶自訂的使用者標識，或其他可識別使用者的標識，例如手機號碼、郵箱地址等。建議預先對該欄位進行脫敏或雜湊處理。

123456789

SourceFacePicture

String

三種上傳方式任選其一，用於傳入活體檢測的人像圖片。

【API方案傳入人臉映像】人像圖片 Base 64 編碼。

base64

SourceFacePictureUrl

String

【API方案傳入人臉映像】人像圖片地址，公網可訪問的 HTTP、HTTPS 連結。

https://***face1.jpeg

SourceFacePictureFile

String

【API方案傳入人臉映像】人像圖片檔案流

具體接入方式，請參見特殊情境：檔案上傳 Advance 介面配置。

FaceQualityCheck

String

否

N

FaceAttributeCheck

String

否

N

VerifyModel

String

是

【產品方案配置】核驗模式：

• 1驗證模式：1:1核驗（預設）

• 0檢索模式：1:N檢索

• 2綜合模式：1:1核驗+1:N檢索

0

TargetFacePicture

String

VerifyModel=1或2時必選，三種上傳方式任選其一。

【產品方案配置-1:1核驗】1:1 比對的可信目標人臉照片Base64編碼。

base64

TargetFacePictureUrl

String

【產品方案配置-1:1核驗】人像圖片地址，公網可訪問的HTTP、HTTPS連結。

https://***face2.jpeg

TargetFacePictureFile

String

【產品方案配置-1:1核驗】人像圖片檔案流。

具體接入方式，請參見特殊情境：檔案上傳 Advance 介面配置。

FaceGroupCodes

String

VerifyModel=0或2時必選

【產品方案配置-1:N檢索】1:N 檢索的人臉庫編碼。通過ID Verification產品控制台建立人臉庫時擷取對應編碼，最大支援同時查詢10個人臉庫。當傳入多個人臉庫編碼時，以逗號區分。

sg*****xta，s*****uk3j

ReturnFaces

String

VerifyModel=0或2時必選

【產品方案配置-1:N檢索】多張人臉超過匹配閾值時返回的匹配人臉數量，預設返回1，最大支援5。

1

AutoRegistration

String

VerifyModel=0或2時必選

【產品方案配置-1:N檢索】認證通過後是否自動註冊至人臉庫：

• 0：自動註冊

• 1：不註冊（預設）

0

FaceRegisterGroupCode

String

VerifyModel=0或2，且AutoRegistration=0時必選

【產品方案配置-1:N檢索】自動註冊入庫的目標人臉庫編碼。

sg*****xta

UpdateFaceIfUserExists

String

VerifyModel=0或2時必選

【產品方案配置-1:N檢索】自動註冊入庫時若 MerchantUserId 已存在，是否使用本次人臉覆蓋原有人臉：

• Y：覆蓋

• N：不覆蓋（預設），並返回 UserId 已存在

N

核驗模式

VerifyModel 值

核心邏輯

適用情境

關鍵輸入參數

觸發自動註冊入庫條件

驗證模式（預設）

1

活體檢測 + 1:1 核驗

登入、帳號找回、敏感操作確認

TargetFacePicture、TargetFacePictureUrl或 TargetFacePictureFile（三選一傳入目標人臉）

不適用

檢索模式

0

活體檢測 + 1:N 檢索

新使用者註冊防重、一人一號管控

FaceGroupCodes（指定檢索人臉庫）；
ReturnFaces（可選，配置匹配閾值以上的返回人臉數量）

活體檢測通過，且 1:N 檢索未命中

綜合模式

2

活體檢測 + 1:1 核驗 + 1:N 檢索

新增使用者註冊（需同時確認本人身份並查重）

需同時傳入驗證模式（值為 1）與檢索模式（值為 0）所需的全部關鍵參數

活體檢測通過、1:1 核驗通過，且 1:N 檢索未命中

名稱

類型

描述

樣本值

HTTP Status Code

Integer

HTTP狀態代碼。

200

HTTP Body

RequestId

String

請求ID。

130A2C10-B9EE-4D84-88E3-5384FF0****

Code

String

返回Code，具體資訊請參見服務端返回HTTP狀態代碼說明。

Success

Message

String

返回Code的詳細描述。

success

Result.TransactionId

String

認證請求的唯一標識。

4ab0b***cbde97

Result.SubCode

String

認證結果描述。請參考Result.SubCode認證結果子碼說明。

200

Result.FacePassed

String

認證最終結果，取值：

• Y：通過

• N：不通過

Y

Result.FaceAttack

String

是否檢測到活體攻擊：

• Y：是

• N：否

N

Result.FaceAttributeInfo

String

{
        gender: 1
        glasses: 0
        hat: 1
        mask: 1
        tattoo: 0
        smoking: 0
        others: 1
        env：office
        expression：1
        age：16
}

Result.ExtFaceInfo

Object

活體檢測相關結果資訊。關於JSON格式，請參見右側樣本。更多資訊，請參見Result.ExtFaceInfo。

{
  "FaceQualityScore": 66.3,
  "OcclusionScore": 100,
  "SharpnessScore": 70.3,
  "KaOcclusionScore": 80,
  "IlluminationScore": 90.79
}

Result.FaceComparisonScore

Double

【VerifyModel=1/2時返回】人臉比對結果，比對分範圍 0~100；系統預設閾值為 90，也可以基於自身業務需求自訂決策。

98

Result.DuplicateFace

String

【VerifyModel=0/2時返回】重複人臉檢索結果；檢索到相似人臉時返回。

返回欄位定義如下：

• faceGroupCode：相似人臉的人臉庫編碼

• faceId：相似人臉的人臉 ID

• merchantUserId：相似人臉的使用者唯一ID

• score：相似人臉的分數

[
  {
    "faceGroupCode": "sg7****uzt",
    "faceId": "f5a921*******9e792ec84c8f0ca592a"
    "merchantUserId":"face0005",
    "score":93.26
  }
]

Result.FaceRegistrationResult

Integer

【VerifyModel=0/2時返回】人臉庫註冊結果：

• 0：註冊失敗，人臉圖片原因導致

• 1：註冊成功

• 2：註冊失敗，自動註冊入庫條件未滿足

• 3：註冊失敗，使用者已存在

• 4：註冊成功，人臉圖片更新成功（符合自動註冊入庫條件，但MerchantUserId重複，且UpdateFaceIfUserExists=Y）

1

Result.FaceRegistrationId

String

【VerifyModel=0/2且AutoRegistration=0 並註冊成功時返回】人臉註冊ID。

9e792******a592a

名稱

類型

描述

樣本值

FaceQualityScore

Double

活體人臉品質分數。取值範圍0～100，數值越大品質越高。

88.62

OcclusionScore

Double

品質判斷子維度，遮擋的演算法分數，取值範圍0～100，數值越大品質越高。

99.99

KaOcclusionScore

Double

品質判斷子維度，關鍵地區遮擋的演算法分數，取值範圍0～100，數值越大品質越高。

100

IlluminationScore

Double

品質判斷子維度，光照的演算法分數，取值範圍0～100，數值越大品質越高。

97.43

SharpnessScore

Double

品質判斷子維度，圖片清晰度分數，取值範圍0～100，數值越大品質越高。

60.78

錯誤碼

認證記錄是否計費

描述和原因建議

200

是

認證通過。

204

是

【1:1驗證結果】人臉比對不一致，可能不是同一人或活體照片品質較低。

205

是

【活體攻擊】活體檢測存在風險。

233

是

【1:N檢索結果】檢測到相似人臉。應結合 Result.ExtFaceInfo.duplicateFace 資訊處理重複註冊或身份冒用風險。