全部產品
Search

搜尋本產品

    ID Verification：FACE_COMPARE

    文件中心

    ID Verification：FACE_COMPARE

    更新時間：Nov 04, 2025

    本文介紹通過純服務端（API）接入FaceCompare的方案。

    介面說明

    • 介面名：FaceCompare

    • 要求方法：HTTPS POST

    • 介面說明：通過服務端介面傳入圖片資料等資訊進行人臉比對。

    • QPS限量：API獨享QPS限量，詳情請參見ID Verification服務端API QPS限量說明。

    • 服務地址：

      說明

      內網指的是阿里雲同地區產品之間的內部通訊網路，如果您的商務服務器部署在阿里雲的對應地區，可以通過內網網域名稱訪問 ID Verification 服務，以獲得更安全、穩定的網路通訊品質。

      中國香港

      • 公網：cloudauth-intl.cn-hongkong.aliyuncs.com

      • 內網：cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

      印尼

      • 公網：cloudauth-intl.ap-southeast-5.aliyuncs.com

      • 內網：cloudauth-intl-vpc.ap-southeast-5.aliyuncs.com

    線上調試和整合

    說明

    在調試和整合前，請確保您已完整閱讀使用OpenAPI調試和整合服務端API文檔，充分瞭解API介面在OpenAPI平台的調用方式和SDK及其代碼的擷取方式。

    您可以在OpenAPI Explorer中直接運行本介面進行調試，並產生本介面的SDK程式碼範例。

    傳入圖片格式要求

    • 圖片格式：JPG、JPEG、PNG。

    • 圖片大小：推薦50~100 KB，最大不超過1 MB。

    • 圖片解析度：不超過1920*1080（高*寬），至少為640*480（高*寬），推薦短邊縮放到720像素，壓縮率大於0.9。照片高大於寬，如果傳入的照片寬大於高，可能會影響檢測效果。

      說明

      圖片轉base64格式後，通常會導致資料體積增加。如您需要使用base64格式傳參，請保證原始圖片的體積不超過0.6MB，以滿足1MB的最巨量資料傳輸限制。

    • 圖片品質建議：

      • 人臉面部需要完整清晰無遮擋，正對網路攝影機，推薦通過自拍採集的人臉圖片。

      • 人臉大小佔比圖片中面積需要>60%，若人臉較小會影響檢測的準確性。

      • 若圖片中存在多個人臉，演算法預設截取較大的人臉，建議避免傳入多人臉圖片。

    請求參數

    名稱

    類型

    是否必選

    描述

    樣本值

    MerchantBizId

    String

    是

    自訂的業務唯一標識，用於後續定位排查問題使用。支援長度為32位的字母和數位組合，請確保唯一。

    e0c34a77f5ac40a5aa5e6ed20c35****

    SourceFacePicture

    String

    是

    人像照片Base64編碼。

    說明

    如果您選擇該方式傳入證件圖片，請檢查照片大小，不要傳入過大的照片。

    base64編碼

    SourceFacePictureUrl

    String

    否

    人像圖片地址，公網可訪問的HTTP、HTTPS連結。

    說明

    SourceFacePicture與SourceFacePictureUrl二選一。

    https://***

    TargetFacePicture

    String

    否

    底庫照片Base64編碼。

    說明

    如果您選擇該方式傳入證件圖片，請檢查照片大小，不要傳入過大的照片。

    base64編碼

    TargetFacePictureUrl

    String

    否

    底庫人像圖片地址，公網可訪問的HTTP、HTTPS連結。

    說明

    TargetFacePicture與TargetFacePictureUrl二選一。

    https://***

    返回資料

    名稱

    類型

    描述

    樣本值

    HTTP Status Code

    Integer

    HTTP狀態代碼。

    200

    HTTP Body

    RequestId

    String

    請求ID。

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

    Code

    String

    返回Code。

    Success

    Message

    String

    返回Code的詳細描述。

    success

    Result.TransactionId

    String

    認證請求的唯一標識。

    08573be80f944d95ac812e019e36****

    Result.Passed

    String

    認證最終結果，取值：

    • Y：通過

    • N：不通過

    Y

    Result.FaceComparisonScore

    String

    人臉比對分：取值範圍0～100。

    52.57

    返回Code

    HTTP Status Code

    Code

    描述

    200

    Success

    請求成功。

    400

    MissingParameter

    參數不可為空。

    400

    InvalidParameter

    非法參數。

    401

    NoFaceDetected

    自訂比對源的圖片人臉特徵提取失敗，建議更換圖片上傳。

    401

    UnqualifiedPhoto

    傳入的圖片不可讀，或圖片解析度不符合要求，建議更換圖片。需確保照片清晰、曝光正常，完整無遮擋，角度無太大偏差。

    401

    ToolargeImage

    圖片尺寸過大，建議壓縮圖片或更換圖片上傳方式。

    401

    DataDuplication

    同時傳入SourceFacePicture和SourceFacePictureUrl, 或者同時傳入TargetFacePicture和TargetFacePictureUrl。

    401

    DownloadTimeout

    URL圖片下載逾時。

    403

    Forbidden.RAMUserAccessDenied

    需要給RAM使用者授予AliyunAntCloudAuthFullAccess的操作許可權。更多資訊，請參見授權RAM使用者訪問服務。

    403

    Forbidden.AccountAccessDenied

    確保您開通了ID verification，並且保證賬戶未欠費。

    403

    Throttling.Api

    API限流攔截。

    500

    InternalError

    系統內部錯誤，請反饋工程師排查。