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." } } ~~~