全部產品
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程式碼範例。

    請求參數

    名稱

    類型

    是否必選

    描述

    樣本值

    ProductCode

    String

    是

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

    FACE_LIVENESS

    SceneCode

    String

    否

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

    1234567890

    MerchantBizId

    String

    是

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

    說明

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

    e0c34a77f5ac40a5aa5e6ed20c35****

    MetaInfo

    String

    是

    MetaInfo環境參數，實際環境需要通過JS檔案，調用函數getMetaInfo()擷取，詳情請參見Android接入。

    說明

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

    		 
    {
  "zimVer": "3.0.0",
  "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

    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-5384FF03****

    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狀態代碼

    Code

    Message描述

    200

    Success

    請求成功。

    400

    MissingParameter

    參數不可為空。

    InvalidParameter

    非法參數。

    401

    Forbidden.ExceptionRepeatedInvoke

    異常重複調用次數超限。

    403

    Forbidden.RAMUserAccessDenied

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

    Forbidden.AccountAccessDenied

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

    Throttling.Api

    API限流攔截。

    500

    InternalError

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

    503

    ServiceUnavailable

    服務不可用，請反饋工程師排查。