Face API - v1.0
This API is currently available in:
- Australia East - australiaeast.api.cognitive.microsoft.com
- Brazil South - brazilsouth.api.cognitive.microsoft.com
- Canada Central - canadacentral.api.cognitive.microsoft.com
- Central India - centralindia.api.cognitive.microsoft.com
- Central US - centralus.api.cognitive.microsoft.com
- East Asia - eastasia.api.cognitive.microsoft.com
- East US - eastus.api.cognitive.microsoft.com
- East US 2 - eastus2.api.cognitive.microsoft.com
- France Central - francecentral.api.cognitive.microsoft.com
- Japan East - japaneast.api.cognitive.microsoft.com
- Japan West - japanwest.api.cognitive.microsoft.com
- Korea Central - koreacentral.api.cognitive.microsoft.com
- North Central US - northcentralus.api.cognitive.microsoft.com
- North Europe - northeurope.api.cognitive.microsoft.com
- South Africa North - southafricanorth.api.cognitive.microsoft.com
- South Central US - southcentralus.api.cognitive.microsoft.com
- Southeast Asia - southeastasia.api.cognitive.microsoft.com
- UK South - uksouth.api.cognitive.microsoft.com
- West Central US - westcentralus.api.cognitive.microsoft.com
- West Europe - westeurope.api.cognitive.microsoft.com
- West US - westus.api.cognitive.microsoft.com
- West US 2 - westus2.api.cognitive.microsoft.com
- UAE North - uaenorth.api.cognitive.microsoft.com
Face - Identify
1-to-many identification to find the closest matches of the specific query person face from a person group or large person group.
For each face in the faceIds array, Face Identify will compute similarities between the query face and all the faces in
the person group (given by personGroupId) or large person group (given by largePersonGroupId), and return candidate person(s)
for that face ranked by similarity confidence. The person group/large person group should be trained to make it ready for
identification. See more in
PersonGroup - Train and
LargePersonGroup - Train.
Remarks:
- The algorithm allows more than one face to be identified independently at the same request, but no more than 10 faces.
- Each person in the person group/large person group could have more than one face, but no more than 248 faces.
- Higher face image quality means better identification precision. Please consider high-quality faces: frontal, clear, and face size is 200x200 pixels (100 pixels between eyes) or bigger.
- Number of candidates returned is restricted by maxNumOfCandidatesReturned and confidenceThreshold. If no person is identified, the returned candidates will be an empty array.
- Try Face - Find Similar when you need to find similar faces from a face list/large face list instead of a person group/large person group.
- The 'recognitionModel' associated with the query faces' faceIds should be the same as the 'recognitionModel' used by the target person group or large person group.
Http Method
POSTSelect the testing console in the region where you created your resource:
West US West US 2 East US East US 2 West Central US South Central US West Europe North Europe Southeast Asia East Asia Australia East Brazil South Canada Central Central India UK South Japan East Central US France Central Korea Central Japan West North Central US South Africa North UAE North Norway East West US 3 Jio India WestRequest URL
Request headers
Request body
JSON fields in request body:
Fields | Type | Description |
---|---|---|
faceIds | Array | Array of query faces faceIds, created by the Face - Detect. Each of the faces are identified independently. The valid number of faceIds is between [1, 10]. |
personGroupId | String | personGroupId of the target person group, created by PersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. |
largePersonGroupId | String | largePersonGroupId of the target large person group, created by LargePersonGroup - Create. Parameter personGroupId and largePersonGroupId should not be provided at the same time. |
maxNumOfCandidatesReturned (optional) | Number | The range of maxNumOfCandidatesReturned is between 1 and 100 (default is 10). |
confidenceThreshold (optional) | Number | Optional parameter.
Customized identification confidence threshold, in the range of [0, 1]. Advanced user can tweak this value to override default internal threshold for better precision on their scenario data. Note there is no guarantee of this threshold value working on other data and after algorithm updates. |
{
"largePersonGroupId": "sample_group",
"faceIds": [
"c5c24a82-6845-4031-9d5d-978df9175426",
"65d083d4-9447-47d1-af30-b626144bf0fb"
],
"maxNumOfCandidatesReturned": 1,
"confidenceThreshold": 0.5
}
Response 200
A successful call returns the identified candidate person(s) for each query face.
JSON fields in response body:
Fields | Type | Description |
---|---|---|
faceId | String | faceId of the query face. |
candidates | Array | Identified person candidates for that face (ranked by confidence). Array size should be no larger than input maxNumOfCandidatesReturned. If no person is identified, will return an empty array. |
personId | String | personId of candidate person. |
confidence | Number | A float number between 0.0 and 1.0. |
[
{
"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
}
]
}
]
Response 400
Error code and message returned in JSON:
Error Code | Error Message Description |
---|---|
BadArgument | Invalid request body. |
BadArgument | The argument maxNumOfCandidatesReturned is not valid. Range is [1,5] |
BadArgument | The argument confidenceThreshold is not valid. Range is [0, 1] |
BadArgument | Face ID is invalid. |
BadArgument | Person group ID is invalid. Valid format should be a string composed by numbers, English letters in lower case, '-', '_', and no longer than 64 characters. |
BadArgument | Large person group ID is invalid. Valid format should be a string composed by numbers, English letters in lower case, '-', '_', and no longer than 64 characters. |
BadArgument | 'recognitionModel' is incompatible. |
PersonGroupIdAndLargePersonGroupIdBothNotNull | Large person group ID and person group ID are both not null. |
PersonGroupIdAndLargePersonGroupIdBothNull | Large person group ID and person group ID are both null. |
PersonGroupNotFound | Person group is not found. |
LargePersonGroupNotFound | Large person group is not found. |
FaceNotFound | Face is not found. |
PersonGroupNotTrained | Person group not trained. |
LargePersonGroupNotTrained | Large person group not trained. |
PersonGroupTrainingNotFinished | Person group is under training. |
LargePersonGroupTrainingNotFinished | Large person group is under training. |
{
"error": {
"code": "BadArgument",
"message": "Large Person group is invalid."
}
}
Response 401
Error code and message returned in JSON:
Error Code | Error Message Description |
---|---|
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 days."
}
}
Response 409
Training process is conflict with identify. Try identify again when training is finished.
{
"error": {
"code": "LargePersonGroupTrainingNotFinished",
"message": "Large person group is under training."
}
}
Response 415
Unsupported media type error. Only "application/json" is valid for this API.
{
"error": {
"code": "BadArgument",
"message": "Invalid Media Type."
}
}
Response 429
{
"error": {
"statusCode": 429,
"message": "Rate limit is exceeded. Try again in 26 seconds."
}
}
Code samples
@ECHO OFF
curl -v -X POST "https://centralindia.api.cognitive.microsoft.com/face/v1.0/identify"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: {subscription key}"
--data-ascii "{body}"
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://centralindia.api.cognitive.microsoft.com/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);
}
}
}
}
// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;
public class JavaSample
{
public static void main(String[] args)
{
HttpClient httpclient = HttpClients.createDefault();
try
{
URIBuilder builder = new URIBuilder("https://centralindia.api.cognitive.microsoft.com/face/v1.0/identify");
URI uri = builder.build();
HttpPost request = new HttpPost(uri);
request.setHeader("Content-Type", "application/json");
request.setHeader("Ocp-Apim-Subscription-Key", "{subscription key}");
// Request body
StringEntity reqEntity = new StringEntity("{body}");
request.setEntity(reqEntity);
HttpResponse response = httpclient.execute(request);
HttpEntity entity = response.getEntity();
if (entity != null)
{
System.out.println(EntityUtils.toString(entity));
}
}
catch (Exception e)
{
System.out.println(e.getMessage());
}
}
}
<!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://centralindia.api.cognitive.microsoft.com/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>
#import <Foundation/Foundation.h>
int main(int argc, const char * argv[])
{
NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
NSString* path = @"https://centralindia.api.cognitive.microsoft.com/face/v1.0/identify";
NSArray* array = @[
// Request parameters
@"entities=true",
];
NSString* string = [array componentsJoinedByString:@"&"];
path = [path stringByAppendingFormat:@"?%@", string];
NSLog(@"%@", path);
NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
[_request setHTTPMethod:@"POST"];
// Request headers
[_request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
[_request setValue:@"{subscription key}" forHTTPHeaderField:@"Ocp-Apim-Subscription-Key"];
// Request body
[_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
NSURLResponse *response = nil;
NSError *error = nil;
NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];
if (nil != error)
{
NSLog(@"Error: %@", error);
}
else
{
NSError* error = nil;
NSMutableDictionary* json = nil;
NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
NSLog(@"%@", dataString);
if (nil != _connectionData)
{
json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
}
if (error || !json)
{
NSLog(@"Could not parse loaded json with error:%@", error);
}
NSLog(@"%@", json);
_connectionData = nil;
}
[pool drain];
return 0;
}
<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';
$request = new Http_Request2('https://centralindia.api.cognitive.microsoft.com/face/v1.0/identify');
$url = $request->getUrl();
$headers = array(
// Request headers
'Content-Type' => 'application/json',
'Ocp-Apim-Subscription-Key' => '{subscription key}',
);
$request->setHeader($headers);
$parameters = array(
// Request parameters
);
$url->setQueryVariables($parameters);
$request->setMethod(HTTP_Request2::METHOD_POST);
// Request body
$request->setBody("{body}");
try
{
$response = $request->send();
echo $response->getBody();
}
catch (HttpException $ex)
{
echo $ex;
}
?>
########### Python 2.7 #############
import httplib, urllib, base64
headers = {
# Request headers
'Content-Type': 'application/json',
'Ocp-Apim-Subscription-Key': '{subscription key}',
}
params = urllib.urlencode({
})
try:
conn = httplib.HTTPSConnection('centralindia.api.cognitive.microsoft.com')
conn.request("POST", "/face/v1.0/identify?%s" % params, "{body}", headers)
response = conn.getresponse()
data = response.read()
print(data)
conn.close()
except Exception as e:
print("[Errno {0}] {1}".format(e.errno, e.strerror))
####################################
########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64
headers = {
# Request headers
'Content-Type': 'application/json',
'Ocp-Apim-Subscription-Key': '{subscription key}',
}
params = urllib.parse.urlencode({
})
try:
conn = http.client.HTTPSConnection('centralindia.api.cognitive.microsoft.com')
conn.request("POST", "/face/v1.0/identify?%s" % params, "{body}", headers)
response = conn.getresponse()
data = response.read()
print(data)
conn.close()
except Exception as e:
print("[Errno {0}] {1}".format(e.errno, e.strerror))
####################################
require 'net/http'
uri = URI('https://centralindia.api.cognitive.microsoft.com/face/v1.0/identify')
uri.query = URI.encode_www_form({
})
request = Net::HTTP::Post.new(uri.request_uri)
# Request headers
request['Content-Type'] = 'application/json'
# Request headers
request['Ocp-Apim-Subscription-Key'] = '{subscription key}'
# Request body
request.body = "{body}"
response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
http.request(request)
end
puts response.body