API usage

You can communicate with this API from any platform, any OS that allow you to send and receive HTTP messages. Each message you will send or receive contains in its body plain text formatted as an XML or JSON. In this documentation you will find list of available functions, requests templates and possible responses.

Use following credentials for FREE API subscription plan:
api_key: d45fd466-51e2-4701-8da8-04351c872236
api_secret: 171e8465-f548-401d-b63b-caf0dc28df5f

Typical workflow usually looks like this: You start by transferring your image (either as binary file or as URL) using image upload functions. Image will be put in processing queue and you will get corresponding image ID immediately. With this image ID you should poll API function GetImageInfo (for example every second) until you get response that the image is processed. Once the image is processed GetImageInfo function will return complete metadata for this image – detected faces and their properties including classification, points coordinates and other measurements. Each face information returned will contain unique face ID. Once you have your face IDs you can:

  • assign persons name to one or more faces (function Faces_SetPerson)
  • retrieve cropped face images (function GetFaceImage)
  • try to recognize person on the image or just find out how similar it is comparing to another faces (function Faces_Recognize)
  • apply different geometrical transformations to face image or make average face image from a group of faces (function Transform_Faces)

API provides auto-generated help pages with all functions and request/response examples for all API endpoints (HHTP and HTTPS/SSL):

Help page (XML responses)

Help page (JSON responses)

Help page (XML responses, SSL)

Help page (JSON responses, SSL)

Sending requests

To communicate with API you have to transfer properly formed text request with required HTTP method GET or POST and parse text result. Requests and results are structured as XML. Function names, urls, required HTTP method and auto-generated examples of requests/responses you will find at webservice generated help page (open it with Internet Explorer or with any XML viewer). You will also find complete request/response examples in the next section.

Betaface API now supports JSON formatted requests and responses. Just replace “service.svc” with “service_json.svc” in all URLs and use another generated JSON help page

Betaface API now also supports HTML FORM requests. Try to call API using Betaface API forms test page (JSON responses) or Betaface API forms test page (XML responses)

Important notice regarding XML requests: all HTTP requests sent to API should contain Content-Type: application/xml HTTP header, and body of the message should contain XML tag at the beginning , otherwise your request will not be recognized. Remember to form the rest of XML request exactly as it is specified in API help page, including XML namespaces. Order of the variables in request is also important.

We recommend to install HTTP debugger, such as Fiddler to see exact messages you send and compare them to messages sent by API demo.

Couple of requests examples and corresponding responses (XML):

Uploading images

UploadNewImage_File and UploadNewImage_Url
Use those functions to queue your image for processing

In case of UploadNewImage_Url you have to provide full URL of publicly accessible image.
In case of UploadNewImage_File function you transfer image file in common image format (JPEG, PNG, several others) in base64Binary encoding format. Encode complete file and insert it in corresponding place in XML request.

Here is an example of a request (in further examples we skip the headers and URLs, URL of each function you can see in webservice help page:

HTTP message

URL: http://www.betafaceapi.com/service.svc/UploadNewImage_File
Method: POST


Content-Length: 94998
Content-Type: application/xml
Cache-Control: no-cache(optional)
Pragma: no-cache(optional)

Message Body:

<?xml version="1.0" encoding="utf-8"?>
<ImageRequestBinary xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
<imagefile_data>/9j/4AAQS..here goes Base64binary encoded image file..grVZWUk6f/2Q==</imagefile_data>

You should get back response like this:

<BetafaceImageResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance">


Default value for this parameter is an empty string – .

You can use different binary flags to enable/disable different image processing features to make sure your images are processed as fast as possible and the time is not spent generating information you dont need. Some of the flags are always enabled, even if not supplied, others may trigger other flags On state (for example enabling extended measurements will enable Pro facial points detection). You can combine multiple flags in a single string using any delimiter or just by concatenating all flags in one string.

Note: With current version of webservice when image is processed, resulting image info (with whichever processing was enabled for this image) is cached and will be returned regardless of the future detection_flags supplied for that particular image. We will alter this behaviour with next update, so that image is re-processed if you change detection_flags.

Supported flags:
(empty string) - default processing, equivalent to enabling "propoints,classifiers" flags
"bestface" - return only one detected face per image with highest detection score
"propoints" - enable 86 Pro facial points detection
"classifiers" - enable classifiers (gender, ethicity, age, etc.)
"extended" - extended set of measurements, including colors retured in tags collection. 
             See GetImageInfo documentation. Warning - processing time will increase significantly.

For example, if you use webservice only for face recognition (similarity measurement, search/identification, verification) and expect only one face per image, in your requests to UploadNewImage_File or UploadNewImage_Url functions specify:


Reading image metadata

GetImageInfo and GetImageFileInfo

Use those functions to read processed image information

GetImageFileInfo function is similar to GetImageInfo with only difference that GetImageInfo accept image ID as a parameter and GetImageFileInfo allow you to use image file SHA-256 hash (checksum) instead.
If image is not yet processed GetImageInfo will return integer result = 1, which means image is still in the queue. If image was processed integer result will be 0 (ok) and you can parse the rest of the response.

Your request should look like this:

<?xml version="1.0" encoding="utf-8"?>
<ImageInfoRequestUid xmlns:xsd="http://www.w3.org/2001/XMLSchema" 

if the image is not yet processed you response will look like this:

<BetafaceImageInfoResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <string_response>Request is in the queue</string_response>
  <checksum i:nil="true"/>
  <faces i:nil="true"/>

if there is an error you will have negative number in int_response and error description in string_response

if image processing is finished you will get complete image information described below:

Example of successful image upload and processing

<BetafaceImageInfoResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
         <PointInfo><name>basic eye left</name><type>512</type><x>314.08</x><y>48.76</y></PointInfo>
         <PointInfo><name>basic eye right</name><type>768</type><x>345.37</x><y>47.23</y></PointInfo>
         ... rest of points
         ... rest of the tags
      <user_points i:nil="true"/>

Point type value and/or name tells you which exactly point it is. Name string can potentially change, therefore it is recommended to use type id when accessing specific point programmatically. Here is the full list of Basic and Pro points names and type ids:

         basic eye left - 512
         basic eye right - 768
         basic eye left outer - 1024
         basic eye right outer - 1280
         basic eye left inner - 1536
         basic eye right inner - 1792
         basic mouth left - 2048
         basic mouth right - 2304

detection_flag option "propoints"

         chin ear left - 65536
         chin left 1 - 131072
         chin left 2 - 196608
         chin left 3 - 262144
         chin left 4 - 327680
         chin left 5 - 393216
         chin bottom - 458752
         chin right 5 - 524288
         chin right 4 - 589824
         chin right 3 - 655360
         chin right 2 - 720896
         chin right 1 - 786432
         chin ear right - 851968
         temple right 4 - 917504
         temple right 3 - 983040
         temple right 2 - 1048576
         temple right 1 - 1114112
         temple right - 1179648
         forehead right - 1245184
         forehead 4 - 1310720
         forehead 3 - 1376256
         forehead middle - 1441792
         forehead 2 - 1507328
         forehead 1 - 1572864
         forehead left - 1638400
         temple left - 1703936
         temple left 1 - 1769472
         temple left 2 - 1835008
         temple left 3 - 1900544
         temple left 4 - 1966080
         eye right outer - 2031616
         eye right bottom outer - 2097152
         eye right bottom - 2162688
         eye right bottom inner - 2228224
         eye right inner - 2293760
         eye right top inner - 2359296
         eye right top - 2424832
         eye right top outer - 2490368
         eye left outer - 2555904
         eye left top outer - 2621440
         eye left top - 2686976
         eye left top inner - 2752512
         eye left inner - 2818048
         eye left bottom inner - 2883584
         eye left bottom - 2949120
         eye left bottom outer - 3014656
         eyebrow right inner - 3080192
         eyebrow right top inner - 3145728
         eyebrow right top - 3211264
         eyebrow right top outer - 3276800
         eyebrow right outer - 3342336
         eyebrow right bottom outer - 3407872
         eyebrow right botom - 3473408
         eyebrow rigth bottom inner - 3538944
         eyebrow left inner - 3604480
         eyebrow left top inner - 3670016
         eyebrow left top - 3735552
         eyebrow left top outer - 3801088
         eyebrow left outer - 3866624
         eyebrow left bottom outer - 3932160
         eyebrow left bottom - 3997696
         eyebrow left bottom inner - 4063232
         mouth left - 4128768
         mouth left top - 4194304
         mouth top - 4259840
         mouth right top - 4325376
         mouth right - 4390912
         mouth right bottom - 4456448
         mouth bottom - 4521984
         mouth left bottom - 4587520
         nose left top - 4653056
         nose left top inner - 4718592
         nose left top outer - 4784128
         nose left bottom outer - 4849664
         nose left bottom inner - 4915200
         nose bottom - 4980736
         nose right bottom inner - 5046272
         nose right bottom outer - 5111808
         nose right top outer - 5177344
         nose right top inner - 5242880
         nose right top - 5308416
         eye right iris - 5373952
         eye left iris - 5439488
         nose tip - 5505024
         cheekbone left - 5570560
         cheekbone right - 5636096


Notice that the set of tags you will get together with the face depends on the detection_flags you specified in UploadNewImage_File or UploadNewImage_Url functions. Processing time will increase significantly when extended measurements are enabled. You will find more information about detection_flags above in UploadNewImage_File and UploadNewImage_Url section. Each tag contains confidence value. Tags with no confidence information have a value 1.0. Negative confidence value indicates that the measurement or classification did not produce any significant result and the value shows what was the closest of the choices.

Here is the list of tags, possible values and which detection_flags you have to enable to generate them.

detection_flags option - "classifiers"

         age - approximate age value
         beard - yes, no
         gender - male, female
         glasses - yes, no
         mustache - yes, no
         race - asian-middle-eastern, asian, african-american, hispanic, white, middle eastern, other
         smile - yes, no

detection_flags option - "extended", 
works only for color images and for the single face per image (with highest detection score)

         chin size - extra large, large, average, small, extra small
         color background - RGB hex color value, for example 4f3530
         color clothes middle - RGB hex color value
         color clothes sides - RGB hex color value
         color eyes - RGB hex color value
         color hair - RGB hex color value
         color mustache - RGB hex color value
         color skin - RGB hex color value
         eyebrows corners - extra low, low, average, raised, extra raised
         eyebrows position - extra low, low, average, high, extra high
         eyebrows size - extra thick, thick, average, thin, extra thin
         eyes corners - extra low, low, average, raised, extra raised
         eyes distance - extra far, far, average, close, extra close
         eyes position - extra low, low, average, high, extra high
         eyes shape - extra round, round, average, thin, extra thin
         glasses rim - yes, no
         hair beard - none, short, thick
         hair color type - black, blond, red, brown, brown light, not natural light, not natural
         hair forehead - yes, no
         hair length - none, very short, short, average, long, very long
         hair mustache - none, short, thick
         hair sides - very thin, thin, average, thick
         hair top - very short, short, average, thick, very thick
         head shape - extra heart, heart, average, rect, extra rect
         head width - extra narrow, narrow, average, wide, extra wide
         mouth corners - extra low, low, average, raised, extra raised
         mouth height - extra thick, thick, average, thin, extra thin
         mouth width - extra wide, wide, average, small, extra small
         nose shape - extra straight, straight, average, triangle, extra triangle
         nose width - extra wide, wide, average, narrow, extra narrow
         teeth visible - yes, no

Faces recognition (identification, verification)

Faces_SetPerson function
This function allow you to group multiple face images under one person name and optionally assign this person to specific namespace. Later you can instead of comparing new face image with selected face images from database, compare new face image with selected persons from database, or with all persons within specific namespace.

Person names and namespace names should contain only letters, spaces, numbers and symbol ‘.’. Symbol ‘@’ should separate person name from namespace. When you assign person to namespace, if namespace does not exists, it will be created. If no namespace is provided, face will be assigned to default namespace with an empty name. Person with the same name but different namespace considered to be different person. Each face (unique face ID) can have only one person assigned to it. To remove specific face from person faces collection simply assign it again to a different person or assign it to an empty string.

This function is a main entry to execute similar persons search, identification and verification tasks. As with faces detection, you first place recognition request with Faces_Recognize function in the queue, and then keep polling GetRecognizeResult function until you get the result. Function accept two arrays: first list – array of faces (face IDs) you wish to analyze (compare with other faces, identify person, verify is it a specific person). Usually you have one Face ID in this array. second list – array of targets which should be used for comparison. Targets can be individual face IDs, full person names (personname@namespace) or complete namespaces (all@namespace).

Example 1: Compare one face with 5 other faces

<?xml version="1.0" encoding="utf-8"?>
<FacesRecognizeRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
   <guid xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
   <string xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
   <string xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
   <string xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
   <string xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
   <string xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">

Example 2: Compare one face with all persons in ‘celebrities.betaface.com’ namespace.

<?xml version="1.0" encoding="utf-8"?>
<FacesRecognizeRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
   <guid xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
   <string xmlns="http://schemas.microsoft.com/2003/10/Serialization/Arrays">

in the response of Faces_Recognize function you will get recognize_uid, which you can use to retrieve recognition result with GetRecognizeResult function.

<BetafaceRecognizeRequestResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

Use this function to read recognition result

As with GetImageInfo function, if recognition request is not yet processed GetRecognizeResult will return integer result = 1, which means request is still in the queue. Keep calling GetRecognizeResult every 0.5-1 seconds until you get integer result not equal 1. If request was processed, integer result will be 0 (ok) and you can parse the rest of the response.

In the result you will get separate FaceRecognizeInfo structure for each face ID you specified in the first list in Faces_Recognize function.

Response for Example 1 request (person name will be empty if match is an individual face, not a person):

<BetafaceRecognizeResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance">

Response for Example 2 request (function will return 10 closest matches in the namespace, sorted by similarity):

<BetafaceRecognizeResponse xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <person_name>Dudley Moore@celebrities.betaface.com</person_name>
        <person_name>Woody Harrelson@celebrities.betaface.com</person_name>
        <person_name>Tansu Ciller@celebrities.betaface.com</person_name>
        <person_name>Ladislas I@celebrities.betaface.com</person_name>
        <person_name>Kenneth Branagh@celebrities.betaface.com</person_name>
        <person_name>Curtis Sliwa@celebrities.betaface.com</person_name>
        <person_name>Camilla Parker Bowles@celebrities.betaface.com</person_name>
        <person_name>Roscoe H. Hillenkoetter@celebrities.betaface.com</person_name>
        <person_name>Bertha von Suttner@celebrities.betaface.com</person_name>
        <person_name>Pierre-Daniel Huet@celebrities.betaface.com</person_name>

More samples