Person-Add a Person Face 添加一張具有代表性的人臉給一個人用于識別。輸入作為人臉的圖片需要具有目標人臉的矩形區域，API返回一個代表該人臉的persistedFaceId參數，該persistedFaceId永遠不會過期。注意 persistedFaceId不同于faceId，faceId表示在 Face-Detec API檢測到的人臉。 ? 人物的 persistedFaceId在Person - Delete a Person Face中被用來刪除該人的這張人臉數據。 ? 每個人最多有可以存儲248張人臉數據。 ? 圖片支持JPEG, PNG, GIF(第一幀), 和 BMP格式。圖片文件大小要求在1KB和4MB之間（包括1KB和4MB）。 ? 可檢測的臉的大小在36x36至4096x4096像素之間。超出這個范圍的臉不會被檢測到。 ? 由targetFace指定的矩形（圖片）應該只包含一個臉。沒有或有多張臉時會被視為錯誤。大小超出可檢測的范圍，大的頭部姿勢或非常大的遮擋（陰影）也將導致無法添加人臉數據。 ? 給定的矩形（圖片）同時指定了臉部位置和臉的大小。如果您使用的是不是從Face - Detect返回的矩形（圖片），則不能保證結果的正確性。 面對不同的人進行添加或刪除時支持并發。對同一個人進行操作時則按順序進行。 Request URL https://api.cognitive.azure.cn/face/v1.0/persongroups/{personGroupId}/persons/{personId}/persistedFaces[?userData][&targetFace] Request parameters | personGroupId |string|指定包含目標人物的人物組參數 | | --- | --- | --- | | personId|string|被添加人臉的目標人物參數| |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 | 臉部圖片URL。有效的圖像大小在1KB到4MB。每個臉只能一個圖片 | ~~~ { "url":"http://example.com/1.jpg" } ~~~ Response 200 成功請求返回新的persistedFaceId | Fields |Type |Description | | --- | --- | --- | | persistedFaceId | string | 新增的臉的persistedFaceId一直存在，不會過期。與被Face - Detect創建的faceId不同，faceId會在檢測后24小時內過期 | ~~~ { "persistedFaceId": "B8D802CF-DD8F-4E61-B15C-9E6C5844CCBA" } ~~~ Response 400 Error code and message returned in JSON | Error Code | Error Message Description | | --- | --- | | BadArgument | 'userData'過長 | | BadArgument |無效的請求主體 | | BadArgument |參數targetFace超出范圍，targetFace是有效的，但它與整個圖片的交集是空的 | | BadArgument |無效的參數targetFace。由無效的字符串格式或無效的left/top/height/width的值引起 | | InvalidImage |解碼錯誤，圖片格式不支持 | | InvalidImage |在圖像中或在指定的targetFace中未檢測到人臉 | | InvalidImage |圖像中或指定的targetFace上有多張face | | InvalidImageSize |圖像尺寸太小或太大 | | InvalidURL |無效的圖片URL | | InvalidURL |無法從目標服務器下載。遠程服務器錯誤返回 | ~~~ { "error":{ "code":"BadArgument", "message":"Request body is invalid." } } ~~~ 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數量達到極限，最多為每人248張 ~~~ { "error":{ "code": "QuotaExceeded", "message": "Persisted face number reached limit." } } ~~~ Response 404 | Error Code | Error Message Description | | --- | --- | | PersonGroupNotFound |person groupID無效。有效的格式應該是由數字組成的字符串，英文字母小寫，' - '，'_'，且不超過64個字符 | | PersonGroupNotFound |找不到person group | PersonNotFound |Person ID無效| PersonNotFound |找不到Person| Response 408 運算超時 ~~~ { "error":{ "code":"OperationTimeOut", "message":"Request Timeout." } } ~~~ Response 409 Error code and message returned in JSON | Error Code |Error Message Description | | --- | --- | | PersonGroupTrainingNotFinished |該人物組仍在接受培訓。訓練完成后重試 | | ConcurrentOperationConflict | 資源并發操作沖突 | ~~~ { "error":{ "code":"PersonGroupTrainingNotFinished", "message":"Person group 'sample_group' is under training." } } ~~~ Response 415 不支持的媒體類型錯誤。Content-Type不在允許的類型中 1. 對于一個URL，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." } } ~~~