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

来源:互联网 发布:大疆无人机 知乎 编辑:程序博客网 时间:2024/03/29 02:25

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


在图片中发现人脸并返回人脸所在位置,和可选的 人脸ID(faceIds),坐标(landmarks) 和 属性(attributes)。

可选的参数包括返回的人脸ID(faceId),坐标(landmarks)和属性(attributes)。属性包括年龄,性别,是否微笑,须发,头部姿势和是否带眼镜。faceId 是提供给其他 APIs 来用的,包括 Face - Identitify,Face - Verify 和 Face - Find Similar。faceId 会在人脸被发现24小时后过期。

  • 支持 JPEG,PNG,GIF(第一帧)和BMP。图片文件的大小应该大于或等于 1KB 小于 4MB。
  • 被发现的人脸尺寸从 36x36 到 4096x4096 像素。人脸在这个尺寸范围之外不会被识别。
  • 一张图片中最多可以返回 64 张脸。返回的人脸会按照人脸矩形的尺寸降续排列。
  • 一些人脸可能会因为技术原因无法返回,例如非常大的人脸角度(头部姿势)或者 large occlusion。正面的或者接近正面的人脸最容易被识别。
  • 属性(年龄,性别,头部姿势,笑容,须发和眼镜)目前还处于实验阶段,可能会不准确。头部姿势的倾斜度(pitch)值是一个保留字段并且永远都会返回0。

Http 方法

POST

请求 URL

https://api.projectoxford.ai/face/v1.0/detect[?returnFaceId][&returnFaceLandmarks][&returnFaceAttributes]

请求参数

returnFaceId(可选)boolean是否返回发现的人脸的 faceIds。默认为 truereturnFaceLandmarks(可选)boolean是否返回发现的人脸的坐标信息。默认为 falsereturnFaceAttributes(可选)string分析并返回一个或多个特定的人脸属性,以逗号为分隔符,就像“returnFaceAttributes=age,gender”。支持的人脸属性包括年龄,性别,头部姿势,笑容,须发和眼镜。注意:每一个人脸属性的分析会有计算上的和时间上的消耗。

请求头部信息

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


请求 body

在一个 URL(或者 binary 数据)所指定的图片中发现人脸。
请求 body 中的 JSON 字段:
字段类型描述urlString输入图片的 URL
application/json
{    "url":"http://example.com/1.jpg"}

application/octet-stream
[binary data]

返回值 200

一个成功的调用会返回人脸的数组,该数组是按照人脸尺寸降续排列的。一个空的返回值表示没有发现人脸。一个人脸的信息根据输入的参数可能包括以下的信息:
字段类型描述faceIdString被发现的人脸的唯一标识,由 API 创建并且在人脸被发现24小时后过期。要返回该值,需要将“returnFaceId”参数设置为 true。faceRectangleObject人脸在图片中的位置的矩形区域faceLandmarksObject一个 27点 的人脸坐标数组,指定了人脸部件重要位置。要返回该值,需要将“returnFaceLandmarks”参数设置为 truefaceAttributesObject人脸属性:
  • age:以年为单位的年龄数值
  • gender:男(male) 或者 女(female)
  • smile:微笑意图,值在 0 和 1 之间
  • facialHair:包含了三个须发区域的长度:小胡子(moustache,鼻子下边嘴上边的胡须),络腮胡(beard,下巴上的胡须)和鬓角胡子(sideburns)。
  • 头部姿势:对于面部方向的 3D roll/yew/pitch 角度值。Pitch 值是一个保留字段并且永远返回0。
  • 眼镜:眼镜类型。可能的值包括没带眼镜(noGlasses),阅读眼镜(readingGlasses),太阳镜(sunglasses)和游泳镜(swimmingGoggles)。

application.json
[    {        "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",        "faceRectangle": {            "width": 78,            "height": 78,            "left": 394,            "top": 54        },        "faceLandmarks": {            "pupilLeft": {                "x": 412.7,                "y": 78.4             },            "pupilRight": {                "x": 446.8,                "y": 74.2             },            "noseTip": {                "x": 437.7,                "y": 92.4             },            "mouthLeft": {                "x": 417.8,                "y": 114.4             },            "mouthRight": {                "x": 451.3,                "y": 109.3             },            "eyebrowLeftOuter": {                "x": 397.9,                "y": 78.5             },            "eyebrowLeftInner": {                "x": 425.4,                "y": 70.5             },            "eyeLeftOuter": {                "x": 406.7,                "y": 80.6             },            "eyeLeftTop": {                "x": 412.2,                "y": 76.2             },            "eyeLeftBottom": {                "x": 413.0,                "y": 80.1             },            "eyeLeftInner": {                "x": 418.9,                "y": 78.0             },            "eyebrowRightInner": {                "x": 4.8,                "y": 69.7             },            "eyebrowRightOuter": {                "x": 5.5,                "y": 68.5             },            "eyeRightInner": {                "x": 441.5,                "y": 75.0             },            "eyeRightTop": {                "x": 446.4,                "y": 71.7             },            "eyeRightBottom": {                "x": 447.0,                "y": 75.3             },            "eyeRightOuter": {                "x": 451.7,                "y": 73.4             },            "noseRootLeft": {                "x": 428.0,                "y": 77.1             },            "noseRootRight": {                "x": 435.8,                "y": 75.6             },            "noseLeftAlarTop": {                "x": 428.3,                "y": 89.7             },            "noseRightAlarTop": {                "x": 442.2,                "y": 87.0             },            "noseLeftAlarOutTip": {                "x": 424.3,                "y": 96.4             },            "noseRightAlarOutTip": {                "x": 446.6,                "y": 92.5             },            "upperLipTop": {                "x": 437.6,                "y": 105.9             },            "upperLipBottom": {                "x": 437.6,                "y": 108.2             },            "underLipTop": {                "x": 436.8,                "y": 111.4             },            "underLipBottom": {                "x": 437.3,                "y": 114.5             }        },        "faceAttributes": {            "age": 71.0,            "gender": "male",            "smile": 0.88,            "facialHair": {                "mustache": 0.8,                "beard": 0.1,                "sideburns": 0.02                }            },            "glasses": "sunglasses",            "headPose": {                "roll": 2.1,                "yaw": 3,                "pitch": 0            }        }    }]

返回值 400

在 JSON 里返回错误代码和信息:
错误代码错误信息描述BadArgumentJSON 解析错误。错误的或者不能被识别的请求 JSON body。BadArgument不正确的 returnFaceAttributes。支持的值包括:age,gender,headPose,smile,faciaHair,glasses,以逗号分隔InvalidURL不正确的图片格式或者 URL。支持的格式包括:JPEG,PNG,GIF(第一帧)和 BMP。InvalidURL从给定的 URL 下载图片失败。远程服务器返回错误。InvalidImage解码错误,图片格式不支持。InvalidImageSize图片大小太小或太大。正确的图片大小应该大于或等 1KB 并且小于 4MB。
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."     }}

返回值 408

操作超出最大执行时间

application/json
{    "error":{        "code":"OperationTimeOut",        "message":"Request Timeout."     }}

返回值 415

不支持的媒体类型错误。Content-Type 不在允许的类型里:
  1. 对于图片 URL,Content-Type 应该是 application/json
  2. 对于本地图片,Content-Type 应该是 application/octet-stream
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}");            // Request parameters            queryString["returnFaceId"] = "true";            queryString["returnFaceLandmarks"] = "false";            queryString["returnFaceAttributes"] = "{string}";            var uri = "https://api.projectoxford.ai/face/v1.0/detect?" + 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            "returnFaceId": "true",            "returnFaceLandmarks": "false",            "returnFaceAttributes": "{string}",        };              $.ajax({            url: "https://api.projectoxford.ai/face/v1.0/detect?" + $.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>
0 0
原创粉丝点击