微软认知服务 人脸识别 API 之 查找相似

原文地址： https://dev.projectoxford.ai/docs/services/563879b61984550e40cbbe8d/operations/563879b61984550f30395237

给定查询人脸的 faceId，从一个 faceId 数组或一个 faceListId 中查找到外表相似的人脸。faceId 数组包括了由 Face - Detect 创建的人脸，会在创建24小时后过期。但 faceListId 是由 Face List - Create a Face List 创建的，包括了永远不会过期的 persistedFaceIds。基于输入的信息，返回的类似的人脸包括 faceIds 或者 persistedFaceIds，根据相似度排序。

发现类似人脸有两个工作模式： matchPerson 和 matchFace。matchPerson 是默认的模式，它会通过使用内部的同一人的阈值（thresholds）来尝试尽可能地找到同一个人。这种模式可以用于查找一个已知的人的其他照片。请注意，如果没有任何满足阈值的人脸，那么一个空的列表将会返回。 matchFace 模式会忽略同一人的阈值而返回指定的相似的人脸，即使相似度很低。这个模式可以用于查找长得像名人的人脸。

Http 方法

POST

请求 URL

https://api.projectoxford.ai/face/v1.0/findsimilars

请求头部信息

Content-Type（可选）string发送给 API 的 body 的媒体类型（Media type）Ocp-Apim-Subscription-Keystring提供访问该 API 的订阅 key。查找你的订阅

请求 body

请求 body 中的 JSON 字段：

字段类型描述faceIdString查询人脸的 faceId。用户需要首先调用 Face - Detect 以获得一个正确的 faceId。请注意，这个 faceId 不是永久的，会在调用发现人脸服务24小时后过期。 faceListIdString一个已经存在的用户指定的唯一的候选人脸列表，在 Face List - Create a Fae List 中创建。人脸列表包括了一套永远不会过期的 persistedFaceIds。参数 faceListId 和 faceIds 不应该同事被传入。faceIdsArray候选 faceIds 数组。他们全部都由 Face - Detect 创建，并且 faceIds 会在调用发现人脸服务24小时后过期。faceIds 的数量不得超过1000。参数 faceListId 和 faceIds 不应该同时被传入。maxNumOfCandidatesReturned（可选）Number可选参数。最多返回多少个相似的人脸。正确的范围在 1 到 1000 之间，默认是20。mode（可选）String可选参数。相似人脸查询模式。可以为 matchPerson 或者 matchFace。默认为 matchPerson。
application/json

{        "faceId":"c5c24a82-6845-4031-9d5d-978df9175426",    "faceListId":"sample_list",      "maxNumOfCandidatesReturned":10,    "mode": "matchPerson"}

返回值 200

一个成功的调用会返回最相似的人脸的数组，如果传入的参数是 faceIds 那么会使用 faceId，如果传入的参数是 faceListId 那么会使用 persistedFaceId。

返回 body 中的 JSON 字段：

字段类型描述persistedFaceIdString当通过 faceListId 查询的时候，是候选人脸的 persistedFaceId。人脸列表中的 persistedFaceId 是永久的，永远不会过期。像下边的 response 中展示的那样。faceIdString当通过 faceIds 查询的时候，是候选人脸的 faceId。faceId 是由 Face - Detect 创建的而且会在调用 detection 24小时后过期。confidenceNumber对于候选人脸的相似自信度。相似自信度越高就越相似。范围在 0 到1 之间。
application/json

[    {        "persistedFaceId" : "015839fb-fbd9-4f79-ace9-7675fc2f1dd9",            "confidence" : 0.82    },    ...]

返回值 400

JSON 中返回的错误代码和信息：

错误代码错误信息描述BadArgument不正确的请求 body.BadArgument模式不正确BadArgumentmaxNumofCandidatesReturned 在1 到1000 之外BadArgumentfaceIds 的长度在 1 到 1000 之外BadArgumentfaceListId 和 faceIds 没有被提供BadArgument参数 faceListId 和 faceIds 不能被同时提供BadArgumentFace list ID 不正确FaceNotFound查询的人脸没有被找到FaceListNotFoundFace list 没有被找到FaceListNotReadyFace list 是空的

application/json

{        "error":{            "code":"BadArgument",            "message":"Request body is invalid."    }}

返回值 401

JSON 中返回的错误代码和信息：

错误代码错误信息描述Unspecified错误的订阅 Key 或者用户/计划被封

application/json

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

返回值 403

application/json

{    "error":{        "statusCode": 403,        "message": "Out of call volume quota. Quota will be replenished in 2.12 days."     }}

返回值 415

不支持的媒体类型错误。该 API 只支持“application/json”。

application/json

{    "error":{        "code":"BadArgument",        "message":"Invalid Media Type"     }}

返回值 429

application/json

{    "error":{        "statusCode": 429,        "message": "Rate limit is exceeded. Try again in 26 seconds."     }}

示例代码

C#

using System;using System.Net.Http.Headers;using System.Text;using System.Net.Http;using System.Web;namespace CSHttpClientSample{    static class Program    {        static void Main()        {            MakeRequest();            Console.WriteLine("Hit ENTER to exit...");            Console.ReadLine();        }                static async void MakeRequest()        {            var client = new HttpClient();            var queryString = HttpUtility.ParseQueryString(string.Empty);            // Request headers            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");            var uri = "https://api.projectoxford.ai/face/v1.0/findsimilars?" + queryString;            HttpResponseMessage response;            // Request body            byte[] byteData = Encoding.UTF8.GetBytes("{body}");            using (var content = new ByteArrayContent(byteData))            {               content.Headers.ContentType = new MediaTypeHeaderValue("< your content type, i.e. application/json >");               response = await client.PostAsync(uri, content);            }        }    }}

Javascript

<!DOCTYPE html><html><head>    <title>JSSample</title>    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script></head><body><script type="text/javascript">    $(function() {        var params = {            // Request parameters        };              $.ajax({            url: "https://api.projectoxford.ai/face/v1.0/findsimilars?" + $.param(params),            beforeSend: function(xhrObj){                // Request headers                xhrObj.setRequestHeader("Content-Type","application/json");                xhrObj.setRequestHeader("Ocp-Apim-Subscription-Key","{subscription key}");            },            type: "POST",            // Request body            data: "{body}",        })        .done(function(data) {            alert("success");        })        .fail(function() {            alert("error");        });    });</script></body></html>