全部產品
Search

搜尋本產品

    ID Verification：添加人臉圖片到指定人臉庫

    文件中心

    ID Verification：添加人臉圖片到指定人臉庫

    更新時間：Apr 02, 2026

    FACE_IDU 支援人臉檢索模式。您可通過 ID Verification 控制台建立人臉庫並添加人臉圖片，也可通過本介面實現人臉圖片的添加。

    介面資訊

    • 介面名：AddFaceRecord

    • 要求方法：POST

    • 傳輸協議：HTTPS

    • QPS 限制：該 API 對單個租戶的請求速率上限為 50 QPS。

    • 服務地址：

      說明

      • 內網指的是阿里雲同地區產品之間的內部通訊網路，如果您的商務服務器部署在阿里雲的對應地區，可以通過內網網域名稱訪問 ID Verification 服務，以獲得更安全、穩定的網路通訊品質。

      • ID Verification不同產品方案支援的Region不同，資料之間相互隔離，您需要選擇資料所在Reigon下的介面網域名稱，才能成功訪問資料。

      新加坡

      • 公網：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文檔，充分瞭解API介面在OpenAPI平台的調用方式和SDK及其代碼的擷取方式。

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

    圖片上傳要求

    • 圖片格式：JPG，JPEG。

    • 圖片大小：推薦50~100 KB，最大不超過10 MB（建議超過1MB的圖片可以通過URL或檔案流的方式上傳）。

    • 圖片解析度：建議640*480（高*寬），不超過1920*1080（高*寬），且保持照片的高大於寬。推薦短邊縮放到720像素，壓縮率0.8。

    • 圖片品質：照片清晰、曝光正常，臉部無過黑、過亮、光暈等情況。

    • 圖片人臉：當圖片出現多個人臉時，系統將預設檢測圖中面積最大的人臉。

    請求參數

    說明

    上傳註冊人臉圖片時，FacePicture、FacePictureUrl、FacePictureFileObject三種方式任選其一即可。

    名稱

    類型

    描述

    是否必填

    樣本值

    ProductCode

    string

    產品代碼。固定值：FACE_ENROLL

    是

    FACE_ENROLL

    FaceGroupCode

    string

    人臉庫編碼。

    是

    sgl****7uc

    MerchantUserId

    string

    自訂的使用者唯一ID，不能超過32位。

    • 若傳入則優先以該userID註冊；

    • 若未傳入則選擇預設圖片名。

    否

    130A2C10B9EE4D8488E35384FF03hst

    FacePicture

    string

    人臉圖片的base64編碼。

    否

    base64

    FacePictureUrl

    string

    人臉圖片的URL。

    否

    https://example.com/test.jpg

    FacePictureFileObject

    InputStream

    人臉圖片的本地檔案流。

    使用此方式上傳時，需通過雲產品提供的 Advance 介面進行調用，並傳入有效 InputStream 對象。具體實現，請參見特殊情境：檔案上傳 Advance 介面配置。

    否

    圖⽚的InputStream對象

    FaceQualityCheck

    string

    是否檢測人臉圖片品質。

    • Y：開啟 

    • N：關閉（預設）

    說明

    儲備功能，暫不支援。

    否

    N

    返回參數

    名稱

    類型

    描述

    樣本值

    HTTP Status Code

    integer

    HTTP狀態代碼。

    200

    HTTP Body

    RequestId

    string

    請求ID。

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

    Code

    string

    返回Code。

    Success

    Message

    string

    返回Code的詳細描述。

    請求成功

    Result.Passed

    string

    註冊結果。

    • Y：註冊成功

    • N：註冊失敗

    Y

    Result.ExtFaceInfo

    string

    註冊相關結果資訊，關於JSON格式，請參見右側樣本。

    更多資訊，請參見ExtFaceInfo。

    {
  "faceQuality": "HIGH"
}

    ExtFaceInfo

    名稱

    類型

    描述

    樣本值

    faceQuality

    string

    映像品質。

    • HIGH：品質正常

    • LOW：品質不佳

    HIGH

    返回碼

    HTTP狀態代碼

    Code

    Message描述

    200

    Success

    請求成功。

    400

    MissingParameter

    參數不可為空。

    InvalidParameter

    非法參數。

    403

    Forbidden.RAMUserAccessDenied

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

    Forbidden.AccountAccessDenied

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

    Throttling.Api

    API限流攔截。

    500

    InternalError

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

    503

    ServiceUnavailable

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