全部產品
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.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

    線上調試和整合

    說明

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

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

    請求參數

    名稱

    類型

    是否必選

    描述

    樣本值

    ProductCode

    String

    是

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

    FACE_IDU

    SceneCode

    String

    否

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

    1234567890

    MetaInfo

    String

    是

    MetaInfo環境參數，需要通過用戶端 SDK 調用函數 getMetaInfo() 擷取，請參考對應平台的用戶端接入文檔，擷取MetaInfo。

    說明

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

    {
  "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"
}

    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

    VerifyModel

    String

    否

    驗證類型：

    • 0：檢索模式

      • 功能：傳入指定人臉庫，使用者完成用戶端刷臉動作時，系統自動檢索指定的人臉庫中是否已經存該人臉圖片。

      • 建議情境：真人註冊帳號且不允許重複註冊情境。

    • 1（預設）：驗證模式

      • 功能：傳入指定人臉圖片，使用者完成用戶端刷臉動作時，系統自動驗證是否與指定的人臉一致。

      • 建議情境：登入、帳號資訊修改等需要是否驗證是否本人操作的情境。

    • 2：綜合模式

      • 功能：同時傳入指定人臉庫與人臉圖片，使用者完成用戶端刷臉動作時，系統自動檢索指定的人臉庫中是否已經存該人臉圖片，是否指定人臉本人。

      • 建議情境：需要驗證是新增使用者且是本人操作環境。

    0

    FaceGroupCodes

    String

    否

    通過控制台建立的人臉庫編碼，最大支援同時查詢10個人臉庫。當傳入多個人臉庫編碼時，以逗號區分。

    說明

    當 VerifyModel = 1或2 時必傳。

    sg*****xta，s*****uk3j

    TargetFacePicture

    String

    否

    人像照片Base64編碼。

    指作為比對源可信人臉圖片，可選傳入。

    說明

    當 VerifyModel = 1或2 時必傳。

    -

    TargetFacePictureUrl

    String

    否

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

    -

    MerchantUserId

    String

    是

    您自訂的使用者唯一ID，或者其他可以識別特定使用者的標識，例如：手機號碼、郵箱地址等。

    說明

    強烈建議對該欄位的值進行預先脫敏，例如對值進行雜湊處理，並且保持唯一性。

    123456789

    AutoRegistration

    String

    否

    驗證通過時是否自動註冊到指定人臉庫：

    • 0：自動註冊

    • 1（預設）：不註冊

    0

    FaceRegisterGroupCode

    String

    否

    當開啟自動註冊人臉功能且存在多個人臉庫時，需要通過該參數傳入指定的人臉庫編碼。

    sg*****xta

    ReturnFaces

    String

    否

    指匹配閾值之上存在多個人臉時，可通過該參數自訂返回數量

    預設返回1 ，最大支援5。

    說明

    當VerifyModel = 1時，該參數不生效。

    1

    FaceVerifyThreshold

    String

    否

    人臉驗證閾值。

    說明

    預留欄位，暫未開放。

    0.4

    返回資料

    名稱

    類型

    描述

    樣本值

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

    返回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

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