全部產品
Search

搜尋本產品

    ID Verification：Initialize

    文件中心

    ID Verification：Initialize

    更新時間：Jan 31, 2026

    本文介紹如何通過調用Initialize介面發起活體人臉驗證方案請求。

    發起認證請求

    • 介面名：Initialize

    • 要求方法：HTTPS POST

    • 介面說明：每次開始認證流程前，通過本介面擷取transactionId，用來串聯認證請求中的各個介面。

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

    • 服務地址：

      說明

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

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

      中國香港

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

      • 內網：cloudauth-intl-vpc.cn-hongkong.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%，若人臉較小會影響檢測的準確性。

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

    請求參數

    名稱

    類型

    是否必選

    描述

    樣本值

    ProductCode

    String

    是

    要接入的產品方案。唯一取值：FACE_VERIFY。

    FACE_VERIFY

    SceneCode

    String

    否

    您自訂的認證情境ID，用於後續控制台輸入此情境ID查詢相關記錄使用。支援長度為10位的字母、數字或底線的組合。

    1234567890

    MerchantBizId

    String

    是

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

    說明

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

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    是

    MetaInfo環境參數，需要通過用戶端SDK擷取，詳情請參見Android接入。

    說明

    無須修改傳回值，直接透傳即可。

    		 
    {
    "appVersion": "1",
    "bioMetaInfo": "4.1.0:1150****,0",
    "appName": "com.aliyun.antcloudauth",
    "deviceType": "ios",
    "osVersion": "iOS 10.3.2",
    "apdidToken": "",
    "deviceModel": "iPhone9,1"
}

    MerchantUserId

    String

    是

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

    123456789

    FacePictureBase64

    String

    否

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

    /9j/4AAQSkZJRgABAQAASASBC****

    FacePictureUrl

    String

    否

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

    說明

    當產品方案是FACE_VERIFY時，請確保FacePictureBase64 或FacePictureUrl兩者至少傳入其中一個。

    https://cn-shanghai-aliyun-cloudauth-****.oss-cn-shanghai.aliyuncs.com/verify/****.jpeg

    SecurityLevel

    String

    否

    代表認證流程不同安全水位的模式，可選值：

    • 01：普通模式，僅適用低風險且對裝置資訊採集限制的情境。

    • 02：安全模式，相對嚴格的模式（預設）。

      說明

      • 安全模式通過 SDK 新增的裝置助手模組，基於裝置資訊識別刷臉環境的安全性，有效提升對注入攻擊的攔截能力。建議啟用此模式。

      • 在開發測試階段，測試裝置的環境特徵可能導致裝置安全助手判定存在風險，從而觸發認證失敗（Subcode 206）。建議在測試期間將模式手動設定為“01 普通模式”，以提升測試效率；正式上線時切換為“02 安全模式”，以增強認證安全性。

    02

    Model

    String

    否

    要進行活體檢測的類型：

    • LIVENESS：眨眼動作活體檢測（預設）。

    • PHOTINUS_LIVENESS：眨眼動作活體檢測和炫彩活體（PC端不支援）檢測。

    說明

    支援整合的SDK版本，請參見SDK發布記錄。

    PHOTINUS_LIVENESS

    DocVideo

    String

    否

    是否需要存證視頻。

    • N：不需要（預設）。

    • Y：認證過程中會同時採集使用者的刷臉過程視頻（1~2s視頻檔案），並通過查詢介面返回。

    說明

    因為視頻檔案較大，當網路不穩定時系統會丟棄視頻檔案，優先保障認證必要圖片傳輸。

    N

    CallbackUrl

    String

    否

    認證結果的回調通知地址，回調請求方式預設為GET，回調地址必須以https開頭。平台在完成認證後會回調該地址，並自動添加以下欄位：

    • transactionId

    • passed

    • subcode

    警告

    • 此值的傳入會在調用介面前做可訪問校正，如果傳入的地址不能在公網訪問，會返回400。

    • 回調會在認證完成後立即執行，但可能會因為網路等原因延遲，建議您優先接收用戶端側的認證完成通知，再請求查詢介面擷取認證詳情。

    https://www.aliyun.com?callbackToken=100000****&transactionId=shaxxxx&passed=Y&subCode=200

    CallbackToken

    String

    否

    安全Token，由您自行產生，用於防重複、防篡改校正。

    如果設定了此值，將會在CallbackUrl回調時攜帶CallbackToken欄位。

    NMjvQanQgplBSaEI0sL86WnQplB

    AppQualityCheck

    String

    否

    是否開啟人臉嚴格品質檢測。

    • Y：開啟（預設）

    • N：不開啟

    重要

    • 此配置需要用戶端SDK的支援，如果設定開啟，但用戶端SDK沒有整合人臉品質檢測模組，則此配置視同不開啟。

    • 用戶端SDK版本需要1.2.5及以上版本。

    N

    返回資料

    名稱

    類型

    描述

    樣本值

    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

    整個認證流程的唯一標識。該欄位為計費統計字段，並用於發起CheckResult介面請求。

    重要

    • 當請求過程中出現錯誤時，例如參數無效，則不會返回TransactionId。

    • 建議將TransactionId與您本次商務程序的業務ID綁定並儲存在服務端，在CheckResult時從您服務端儲存提取該認證ID，發起結果查詢。

    • 擷取TransectionId或TransactionUrl成功後，需要在30分鐘內完成認證，超過時間將自動失效無法再認證。

    hksb7ba1b28130d24e015d6********

    Result.Protocol

    String

    認證標準加密協議。

    建議擷取該參數並傳遞給用戶端 SDK。用戶端 SDK 將基於此參數減少網路互動，並支援動態網路切換，以提升使用者體驗。

    hksb7ba1b28130d24e015d*********

    返回Code

    HTTP Status Code

    Code

    描述

    200

    Success

    請求成功。

    400

    MissingParameter

    參數不可為空。

    400

    InvalidParameter

    非法參數。

    401

    NoFaceDetected

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

    401

    UnqualifiedPhoto

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

    401

    ToolargeImage

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

    401

    DataDuplication

    同時通過Base64方式與連結方式傳入圖片。

    401

    DownloadTimeout

    URL圖片下載逾時。

    403

    Forbidden.RAMUserAccessDenied

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

    403

    Forbidden.AccountAccessDenied

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

    403

    Throttling.Api

    API限流攔截。

    500

    InternalError

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