Face - Find Similar 根据需要查的faceId在一组faceid数组或者faceListid中查找相似的面部数据，faceIds array 由detect方法创建，该数组创建24小时后销毁。faceIistId由Face List - Create a Face List 创建，包含persistedFaceIds，其永不过期。根据请求 返回包含faceIds 或者persistedFaceIds 根据相似度排序的相似面部数据排序。 查询相似的面部数据有两种模式："matchPerson" and "matchFace"。"matchPerson"是默认选择模式。matchPerson根据内部的same-person阀值找到关于一个人尽多的面部数据。用于找到已知人的其他照片。如果根据内部阀值没有找到数据则返回空列表。"matchFace"模式忽略same-person阀值，返回类似的图片，有时候图片的相似值很低。该方法可以用来搜索明星脸的情况下。 Http Method `POST` Request URL `https://api.cognitive.azure.cn/face/v1.0/findsimilars` Request headers | 请求头部 |类型 |描述 | | --- | --- | --- | | Content-Type (可选) | string | 发送到API的主体的媒体类型。 | | Ocp-Apim-Subscription-Key| string | Subscription key which provides access to this API. Found in your [Cognitive Services accounts](http://go.microsoft.com/fwlink/?LinkID=826555). 订阅Key是你访问该API服务的凭证,可以在你的认知服务账户中找到 | Request body JSON fields in request body | 字段名| 类型 |描述 | | --- | --- | --- | | faceId | String | 查询面的faceId。用户需要先调用Face - Detect来获取有效的FaceId。请注意，此faceId不会持续，并将在检测后24小时过期。| | faceListId | String | 现有的用户指定唯一候选人脸列表，在 Face List - Create a Face List创建。人脸列表包含一组persistedFaceIds，这些persistedFaceIds被保留并永远不会过期。不应该同时提供参数faceListId和faceIds。 | | faceIds | Array | 候选faceIds的数组。所有这些都是由Face - Detect创建的，faceIds将在检测生成后24小时过期。faceIds的数量限制为1000.不应该同时提供参数faceListId和faceIds。 | | maxNumOfCandidatesReturned (可选) | 数字|可选参数。返回最相似面的数量。有效范围是[1，1000]。默认为20。 | | mode(可选) | 字符串 | 查询类似的脸部搜索模式。它可以是“matchPerson”或“matchFace”。它默认为“matchPerson”。 | ~~~ { "faceId":"c5c24a82-6845-4031-9d5d-978df9175426", "faceListId":"sample_list", "maxNumOfCandidatesReturned":10, "mode": "matchPerson" } ~~~ Response 200 请求成功返回值为一个数组，如果请求参数为faceIds 返回是faceId ，如果请求参数为faceListId则返回persistedFaceId JSON fields in response body | 参数 |类型 |值描述 | | --- | --- | --- | | persistedFaceId | String | 通过faceListId查找候选人脸的persistedFaceId。在face列表中的persistedFaceId不会过期 | | faceId | String | 通过faceIds查找候选人脸的faceId。faceId是通过Face - Detect创建的，在检测呼叫后24小时过期 | | Confidence | Number | 候选人面孔的相似度。相似度越高，越匹配。范围在[0,1]之间 | ~~~ [ { "persistedFaceId" : "015839fb-fbd9-4f79-ace9-7675fc2f1dd9", "confidence" : 0.82 }, ... ] ~~~ 返回值400 Error code and message returned in JSON: | 错误代码 |错误信息描述 | | --- | --- | | BadArgument| 无效的请求主体 | | BadArgument | 无效模式 | | BadArgument | maxNumOfCandidatesReturned超出[1,1000范围] | | BadArgument | faceIds的长度不在[1,1000]范围内 | | BadArgument | faceListId and faceIds均未提供 | | BadArgument | 同时提供 faceListId and faceIds两个参数 | | BadArgument | 无效的 face list id| | FaceNotFound | 需要查询face 未定义| | FaceListNotFound | 未定义 face list| | FaceListNotReady |face list 为空 | ~~~ { "error":{ "code":"BadArgument", "message":"Request body is invalid." } } ~~~ Response 401 Error code and message returned in JSON | 错误码 |错误信息 | | --- | --- | | Unspecified | Invalid subscription Key or user/plan is blocked | ~~~ { "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 ~~~ { "error":{ "statusCode": 403, "message": "Out of call volume quota. Quota will be replenished in 2.12 days." } } ~~~ Response 415 Unsupported media type error. Only "application/json" is valid for this API 不支持的媒体类型错误。该API支持“application / json” ~~~ { "error":{ "code":"BadArgument", "message":"Invalid Media Type" } } ~~~ Response 429 • application/json { "error":{ "statusCode": 429, "message": "Rate limit is exceeded. Try again in 26 seconds." } }