全部產品
Search

搜尋本產品

    ID Verification：Initialize

    文件中心

    ID Verification：Initialize

    更新時間：Nov 08, 2025

    本文介紹如何通過調用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_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新增的裝置助手模組通過裝置資訊識別刷臉環境裝置的安全性，有效增強注入攻擊的攔截。強烈建議您選擇。

    02

    Model

    String

    否

    要進行活體檢測的類型：

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

    • PHOTINUS_LIVENESS：眨眼動作活體+炫彩活體雙重檢測。

    • PHOTINUS_FAR_NEAR_LIVENESS: 眨眼動作+遠近+炫彩活體檢測。

      （僅 APP SDK 或基於 APP SDK 封裝的 Flutter 接入方式支援）

    說明

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

    • PC端不支援炫彩活體雙重檢測。

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

    返回Code

    HTTP狀態代碼

    Code

    Message說明

    200

    Success

    請求成功。

    400

    MissingParameter

    參數不可為空。

    InvalidParameter

    非法參數。

    401

    UnqualifiedPhoto

    傳入的圖片不可讀，或圖片解析度不符合要求，建議更換圖片。

    需確保照片清晰、曝光正常，完整無遮擋，角度無太大偏差。

    DataDuplication

    同時傳入Base64編碼的圖片和Url圖片地址，此二參數任選其一即可。

    ToolargeImage

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

    DownloadTimeout

    URL圖片下載逾時。

    NoFaceDetected

    傳入圖片無人臉。

    403

    Forbidden.RAMUserAccessDenied

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

    Forbidden.AccountAccessDenied

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

    Throttling.Api

    API限流攔截。

    500

    InternalError

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