全部產品
Search

搜尋本產品

    ID Verification：FACE_LIVENESS_MIN_PRO

    文件中心

    ID Verification：FACE_LIVENESS_MIN_PRO

    更新時間：Jul 14, 2026

    FACE_LIVENESS_MIN_PRO是一項通過API介面調用的真實臉部偵測服務。該服務接收預先擷取的人臉映像作為輸入，並依託Qwen-VL大模型深度分析偽造風險，以精準判定是否為真人。鑒於App或Web SDK模式具備更高的安全性，若您的業務對真實人臉核驗的安全等級要求較高，建議整合這兩種模式。

    介面說明

    • 介面名：FaceLivenessV2

    • 要求方法：HTTPS POST

    • 介面說明：調用FaceLivenessV2介面對人臉圖片進行活體檢測。

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

    • 服務地址：

      說明

      • 內網訪問優勢：內網指阿里雲同一地區內各產品間的私人通訊網路。若您的商務服務器部署於阿里雲對應地區，請使用內網網域名稱訪問 ID Verification 服務，以獲得更安全、穩定的通訊品質。 

      • 海外訪問最佳化建議：海外網路環境複雜，建議參考服務端網路耗時最佳化，最佳化整合方案，降低網路延遲及請求失敗機率。

      新加坡

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

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

      印尼

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

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

      中國香港

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

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

      馬來西亞（吉隆坡）

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

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

    線上調試和整合

    說明

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

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

    傳入人臉圖片格式要求

    • 人像圖片傳入提供三種方式，任選其一即可。

      • Base64模式：FacePictureBase64

      • URL模式：FacePictureUrl

      • 檔案流模式：FacePictureFile

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

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

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

      說明

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

    • 圖片品質建議：

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

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

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

    請求參數

    名稱

    類型

    是否必選

    描述

    樣本值

    ProductCode

    String

    是

    接入的產品方案。取值FACE_LIVENESS_MIN_PRO

    FACE_LIVENESS_MIN_PRO

    MerchantBizId

    String

    是

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

    說明

    阿里雲伺服器不會對該欄位的值進行唯一性檢查。為了更好地跟蹤，強烈建議保證欄位唯一性。

    e0c34a77f5ac40a5aa5e6ed20c35****

    MerchantUserId

    String

    是

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

    123456789

    FacePictureBase64

    String

    否

    照片Base64編碼。如果您選擇FacePictureBase64（照片Base64編碼）方式傳入人臉照片，請注意檢查照片大小，不要傳入過大的照片。

    base64

    FacePictureUrl

    String

    否

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

    https://***

    FacePictureFile

    InputStream

    否

    人像地址，檔案流傳輸。

    人像圖⽚的InputStream對象

    FaceQualityCheck

    String

    否

    人臉品質檢查功能，預設不開啟，取值：

    • N：不開啟。

    • Y：開啟。

    開啟後，系統將自動攔截模糊、遮擋等低品質的人臉照片，阻止其進入後續比對等環節。建議在對識別精度要求較高或需減少無效請求的情境下開啟。攔截返回401（UnqualifiedPhoto）。

    N

    FaceAttributeCheck

    String

    否

    是否需要返回額外的人臉屬性欄位。

    • N：關閉（預設）。

    • Y：開啟，在ExtFaceInfo的faceAttributeInfo欄位中以字串形式返回。

    N

    返回資料

    名稱

    類型

    描述

    樣本值

    HTTP Status Code

    Integer

    HTTP狀態代碼。

    200

    HTTP Body

    RequestId

    String

    請求ID。

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

    Result.TransactionId

    String

    整個認證流程的唯一標識。

    hksb7ba1b28130d24e015d694361****

    Code

    String

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

    Success

    Message

    String

    返回Code的詳細描述。

    Success

    Result.Passed

    String

    認證結果，取值：

    • Y：通過

    • N：不通過

    Y

    Result.SubCode

    String

    認證結果描述。更多資訊，請參見ResultObject.SubCode錯誤碼說明。

    200

    Result.ExtFaceInfo

    Object

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

    {
  "FaceQualityScore": 76.69,
  "OcclusionResult": "N",
  "FaceAttack": "Y",
  "SharpnessScore": 60.78,
  "KaOcclusionScore": 100,
  "FaceGender": "M",
  "OcclusionScore": 99.99,
  "FaceAge": 28,
  "IlluminationScore": 97.43
}

    ResultObject.SubCode錯誤碼說明

    錯誤碼

    是否計費

    描述和原因建議

    200

    是

    認證通過。

    205

    是

    活體檢測存在風險。

    ExtFaceInfo

    名稱

    類型

    描述

    樣本值

    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

    FaceAttack

    String

    採集人臉是否涉及活體攻擊。

    • Y：涉及攻擊。

    • N：不涉及攻擊。

    N

    FaceAttributeInfo

    String

    檢測傳入圖片中的主體人臉（離鏡頭最近、面部面積最大且清晰的人臉）的相關面部屬性。檢測結果以字串形式返回，據此決策消費內容。

    返回欄位定義如下：

    • gender：主體人物性別。1 代表男性，0 代表女性。

    • glasses：主體人物是否攜帶眼鏡。1 代表檢測到對應資訊，0 代表未檢測到。

    • hat：主體人物是否頭頂戴帽子（包含頭巾/頭紗情境）。1 代表檢測到對應資訊，0 代表未檢測到。

    • mask：主體人物是否戴口罩。1 代表檢測到對應資訊，0 代表未檢測到。

    • tattoo：主體人物是否有可見紋身。1 代表檢測到對應資訊，0 代表未檢測到。

    • smoking：主體人物是否在抽煙。1 代表檢測到對應資訊，0 代表未檢測到。

    • others：除主體外是否還有其他人物出現。1 代表檢測到對應資訊，0 代表未檢測到。

    • env：主體人物所在的環境，例如辦公室、工廠、醫院、車內等。目前支援返回 office / hospital / factory / vehical / other。

    • expression：主體人物是否為誇張表情（指人物面部出現明顯異於自然/平靜狀態的強烈表情）。1 代表檢測到誇張表情，0 代表未檢測到。

    • age：主體人物對應的真實年齡（周歲）。對應真實年齡。

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