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