微软认知服务人脸识别 API 之识别

来源：互联网发布：windows怎么切换显卡编辑：程序博客网时间：2024/04/29 02:42

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

从一组人中识别出位置的面孔。

对于 faceIds 数组中的每一个人脸，Face Identify 将会计算所查询的人脸和这组人的人脸（通过提供 personGroupId 来提供）的相似度，然后会返回在一定相似度之内的可选的人脸。Person group 应该被训练来让它可以被识别。查看 Person Group - Train Person Group 获得更多信息。

备注：

算法允许在同一个请求中，多于一张的人脸能够被独立地识别出来，但是最多不能超过10张脸
Person group 中的每一个人可以有多于一张的脸，但是最多不能多于248张脸
识别对于正脸或者接近正脸的面孔识别的最好
能够返回的可选人脸数是由 maxNumOfCandidatesReturned 和 confidenceThreshold 来限制的。如果没有人被识别出来，将不会返回任何的可选人脸。
当你想要从一个人脸列表而不是从人的列表中识别出相似人脸的话，请尝试 Face - Find Similar。

Http Method

POST

Request URL

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

Request headers

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

Request body

请求 body 中的 JSON 字段：

字段类型描述faceIdsArray查询人脸 faceIds 的数组，由 Face - Detect 创建。每一个人脸会被独立地识别出来。faceIds 的正确的数量应该在 1 到 10 之间。 personGroupIdString目标 person group 的 personGroupId，由 Person Group - Create a Person Group 创建。maxNumOfCandidatesReturned（可选）NumbermaxNumOfCandidatesReturned 范围应该在 1 到 5 之间（默认为1）。confidenceThreshold（可选）Number可选参数。识别的信息临界值，用来判断一个面孔是否属于一个人。confidenceThreshold 范围是在 0 到 1 之间（默认值由算法来指定）。

application/json

{        "personGroupId":"sample_group",    "faceIds":[        "c5c24a82-6845-4031-9d5d-978df9175426",        "65d083d4-9447-47d1-af30-b626144bf0fb"    ],    "maxNumOfCandidatesReturned":1,    "confidenceThreshold": 0.5}

返回值 200

成功的调用会返回针对每一个查询面孔的识别出来的可选面孔。

Response body 中的 JSON 字段：

字段类型描述faceIdString查询人脸的 faceIdcandidatesArray对于查询的人脸所识别出来的候选人（根据信心值排序）。数组的大小不应该比输入的 maxNumOfCandidatesReturned 多。如果没有人被识别出来，将会返回空的数组。personIdString候选人的 personIdconfidenceNumber一个在 0.0 到 1.0 之间的浮点数

application/json

{    [        {            "faceId":"c5c24a82-6845-4031-9d5d-978df9175426",            "candidates":[                {                    "personId":"25985303-c537-4467-b41d-bdb45cd95ca1",                    "confidence":0.92                }            ]        },        {            "faceId":"65d083d4-9447-47d1-af30-b626144bf0fb",            "candidates":[                {                    "personId":"2ae4935b-9659-44c3-977f-61fac20d0538",                    "confidence":0.89                }            ]        }    ]}

返回值 400

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

错误代码错误信息描述BadArgument

Invalid request body.
不正确的请求 body.

BadArgumentThe argument maxNumOfCandidatesReturned is not valid. Range is [1,5]
参数 maxNumOfCandidatesReturned 不正确。范围应该是 [1,5]BadArgumentThe argument confidenceThreshold is not valid. Range is [0, 1]
参数 confidenceThreshold 不正确。范围应该是 [0,1]BadArgumentFace ID is invalid.
Face ID 不正确BadArgumentPerson group ID is invalid. Valid format should be a string composed by numbers, English letters in lower case, '-', '_', and no longer than 64 characters.
Person group ID 不正确。正确的格式应该是由数字，小写英文字母，“-”，“_” 组成的字符串，并且不应该多于64个字符。PersonGroupNotFoundPerson group is not found.
Person group 没有找到FaceNotFoundFace is not found.
人脸没有找到PersonGroupNotTrainedPerson group 'sample_group' not trained.
Person group 'sample_group' 没有被训练

application/json

{    "error":{        "code":"BadArgument",        "message":"Person group 'sample_group' 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."    }}

返回值 409

训练的过程跟识别冲突。尝试当训练完成后重新识别一次。

application/json

{    "error":{        "code":"PersonGroupTrainingNotFinished",        "message":"Person group 'sample_group' is under training."    }}

返回值 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/identify?" + 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/identify?" + $.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>