Add a Face to a Face List 將人臉添加到人臉列表。輸入的face被指定為一個帶有targetFace矩形的圖像。它返回一個persistedFaceId代表添加的人臉，而persistedFaceId不會過期。注意Face - Detect檢測到的persistedFaceId與FaceId不同.。 * face list 的persistedFaceId用于刪除，移除face list中某個face，或者輸出face的json格式 查找類似值 * JPEG，PNG，GIF（第一幀）和BMP。圖像文件大小應該大于或等于1KB但不大于4MB。 * 可檢測的面部大小在36x36至4096x4096像素之間。超出這個范圍的面不會被檢測到 * 由targetFace指定的矩形應該只包含一個面。零個或多個面孔將被視為錯誤。超出可檢測的面部大小，大的頭部姿勢或非常大的遮擋也將導致無法添加人臉。 * 給定的矩形同時指定臉部位置和臉部大小。如果使用不是從面部檢測返回的矩形，則不能保證正確的結果 臉部列表是一組臉孔，這些臉部不會過期。臉部列表被用作Face - Find Similar的源臉部的參數 。當經常設置固定的臉部時，臉部列表非常有用，例如在名人，朋友或家庭成員的臉部列表中找到類似的臉部。 可以在不同的facelist同時進行新增或者刪除faces,如果在同一facelist則按順序執行。 face list最多可以有1000個faces。 Http Method `POST` Request URL `https://api.cognitive.azure.cn/face/v1.0/facelists/{faceListId}/persistedFaces[?userData][&targetFace]` Request parameters | 字段 |類型 |描述 | | --- | --- | --- | | faceListId | string | 有效字符是小寫或數字或“ - ”或“_”的字母，最大長度為64 | | userData(可選) | string | 用戶指定的有關任何用途的人臉列表數據。最大長度是1KB | | targetFace (可選) | string | 定要添加到臉部列表中的目標臉部的臉部矩形，格式為“targetFace = left，top，width，height”。例如“targetFace = 10,10,100,100”。如果圖像中有多個面，targetFace需要指定要添加的面。沒有targetFace意味著在整個圖像中只有一個臉部被檢測到。 | Request headers | 請求頭 |類型 |描述 | | --- | --- | --- | | Content-Type(可選) | string | Media type of the body sent to the API | | Ocp-Apim-Subscription-Key | string | Subscription key which provides access to this API. Found in your Cognitive Services accounts. | Request body | Fields | Type | Description | | --- | --- | --- | | url | String | 圖片路徑，圖片大小為1kb-4MB之間，每個face對應一個圖片 | ~~~ { "url":"http://example.com/1.jpg" } ~~~ Response 200 成功的調用返回一個新的persistedFaceId JSON fields in response body | Fields | Type | Description | | --- | --- | --- | | persistedFaceId | String | 添加的face的persistedFaceId，永不過期。與Face - Detect中創建的faceId，檢測后24小時內會過期。 | ~~~ { "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA" } ~~~ Response 400 Error code and message returned in JSON | Error Code | Error Message Description | | --- | --- | | BadArgument | 錯誤和未被解析出來的json主體 | | BadArgument | userData’過長 | | BadArgument | 參數targetFace超出范圍，targetFace是有效的，但它與整個圖像的交集是空的 | | BadArgument | 無效的參數targetFace。由無效的字符串格式或無效的左/頂/高/寬度值引起 | | InvalidURL | 無效的圖片網址 | | InvalidURL | 無法從目標服務器下載。遠程服務器錯誤返回 | | InvalidImage | 圖像中或指定的目標面上有多個面| | InvalidImage | 在圖像中或在指定的目標面部區域中未檢測到人臉 | | InvalidImage | 解碼錯誤，圖片格式不支持。 | | InvalidImageSize | 圖像尺寸太小或太大。 | ~~~ { "error":{ "code":"BadArgument", "message":"JSON parsing error." } } ~~~ Response 401 | Error Code | Error Message Description | | --- | --- | | Unspecified | 無效的subscription Key 或user/plan 被凍結 | ~~~ { "error":{ "code": "Unspecified", "message": "Access denied due to invalid subscription key. Make sure you are subscribed to an API you are trying to call and provide the right key." } } ~~~ Response 403 face數達到極限，每個face list最多1000個face ~~~ { "error":{ "code": "QuotaExceeded", "message": "Face number reached limit." } } ~~~ Response 404 Error code and message returned in JSON | Error Code | Error Message Description | | --- | --- | | FaceListNotFound | 未找到face list | | FaceListNotFound |臉部列表ID無效。有效格式應該是由數字組成的字符串，英文字母小寫，' - '，'_'，不超過64個字符。 | ~~~ { "error":{ "code":"FaceListNotFound", "message":"Face list 'sample_list' is not found." } } ~~~ Response 408 操作超過最大執行時間 ~~~ { "error":{ "code":"OperationTimeOut", "message":"Request Timeout." } } ~~~ Response 409 ~~~ { "error":{ "code": ConcurrentOperationConflict, "message": "There is a conflict operation on resource 'sample_group', please try later." } } ~~~ Response 415 不支持的媒體類型錯誤。Content-Type不在允許的類型中 1. 1對于圖片網址，Content-Type應該是application / json 2. 對于本地圖像，Content-Type應該是application / octet-stream ~~~ { "error":{ "code":"BadArgument", "message":"Invalid Media Type" } } ~~~ Response 429 ~~~ { "error":{ "statusCode": 429, "message": "Rate limit is exceeded. Try again in 26 seconds." } } ~~~