Skip to content

Robbie RW-Identity™

Info

For Authentication documentation, please refer to Authentication

The base URL for the API is: https://rw-identity.robbieapis.com

Quickstart

We will register a template image, then we are going to match it to another image.

Info

For v1 version register|match is single-face, so sending an image with multiple faces will return just one, the response attribute box helps to guess the face by position.

Image format

Supported image formats are:

  • webp
  • PNG
  • WEBP (beta)

Maximum image size allowed: 10 Megabytes.

Register

This endpoint provides identity registration, meaning a picture that is not yet registered. The endpoint allows attaching free data (in JSON format) to the identity.

Info

In case it was already registered then the already registered is returned, overriding the current metadata and the same ID.

For checking if your token is correct, call the register endpoint:

  • Path: /v1/register/
  • Method: POST
  • Headers:
    • Authorization
  • Content Type: application/json
  • Body:
Field Type Required Default Description
image string[base64] true N/A Image to register
metadata object false {} Free meta data attached
antiSpoofing boolean false false Enable anti-spoofing detection

Calling the register endpoint with a template image:

Dani G1

1
2
3
4
5
6
7
cat docs/images/register.webp | base64 | tee register.b64
API_KEY=7dae9cfd1b40454dad3cdf15b073370fcfa7f09a97c743e081459ad28b1e18df
http POST https://rw-identity.robbieapis.com/v1/register/ \
    "Authorization: ApiKey-v1 ${API_KEY}" \
    image=@register.b64 \
    metadata:='{"some": "metadata", "label": "Dani G"}' \
    antiSpoofing:=false
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import base64
import requests
import json
API_KEY="7dae9cfd1b40454dad3cdf15b073370fcfa7f09a97c743e081459ad28b1e18df"

with open("docs/images/register.webp", "rb") as f:
    base64_image = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://rw-identity.robbieapis.com/v1/register/",
    json={
        "metadata": {"some": "metadata", "label": "Dani G"},
        "image": base64_image,
        "antiSpoofing": False,
    },
    headers={
        "Authorization": "ApiKey-v1 {}".format(API_KEY),
    },
)
assert response.status_code == 200
print("{}".format(json.dumps(response.get_json(), indent=4)))

Expected Response

Field Type Description
biometrics object Age, Ethnicity & gender
metadata object Free meta data attached
box array[int] Coordinates(x,y,w,h) of the face
id long integer Unique ID of the identity
image string[URL] A 1-hour duration valid signed URL for the face

Warning

image URL is in WEBP format only, and it is expired after one hour, so the URL cannot be used anymore nor the image can be downloaded. It is expected to be useful for short-term front-end interactions, if you happen to use it after the expiration, it will fail, so keeping/storing the URL itself is useless. If a copy of a downloaded image is made on your party, or cached or stored in any way, you are automatically subject to any compliance with personal data protection. If used in an HTML page somehow, we encourage you to give a version to the asset so it is not cached.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Alt-Svc: clear
Content-Length: 246
Content-Security-Policy: default-src 'self'
Content-Type: application/json
Date: Mon, 24 Jun 2019 19:06:50 GMT
Referrer-Policy: strict-origin-when-cross-origin
Server: gunicorn/19.9.0
Strict-Transport-Security: max-age=31556926; includeSubDomains
Via: 1.1 google
X-Content-Security-Policy: default-src 'self'
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block

{
    "biometrics": {
        "age": 30.38529603869331,
        "ethnicity": "LATINO",
        "gender": "M"
    },
    "box": [
        2256,
        1117,
        478,
        478
    ],
    "id": 5413685439686021138,
    "metadata": {
        "label": "Dani G",
        "public-api": true,
        "some": "metadata"
    },
    "image": "https://storage.googleapis.com/878e3274c08e986246b96b088d.identity.images.dev.storage.robbieapis.com/00000000/04215236337134144221/1561/486/560/56037428.webp?Expires=1561490216&GoogleAccessId=aws-workers%40robbie-ai-us.iam.gserviceaccount.com&Signature=ZGJaFL3L9xgHH9rxjjxETTx1pbeJylI76V%2FtYagQnHQgKzzuqrqQ2aTRAwzxlkFOba5olRk8zf1oYpNKkGuvx2ylrta%2BOnbz7jWgmxEBkdHC1zhH%2Fc%2BXupq5YXPrP%2BT20N2FZRHiMIgGw5pURe1Wl8kfP5Jh3QLccsxzGAajhyzF%2FDH7vSOHQXQl0GYo0SA8dFxBbWwpTewLBpjcrKc6xg%2B0qvzdZmkZlawFZWkzRgC9osrcm9PQ%2F%2F%2BUxNrA7FNj0cIyAGLv5ouCnH2Qf1oKtbQ03q03CnZARDOA6uPnZkVqVKH1aLMni%2F3%2F%2FaEyyVuH8KetXWQsTcLpKVQ0xnHTwQ%3D%3D",
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
    "biometrics": {
        "age": 30.38529603869331,
        "ethnicity": "LATINO",
        "gender": "M"
    },
    "box": [
        2256,
        1117,
        478,
        478
    ],
    "id": 5413685439686021138,
    "metadata": {
        "label": "Dani G",
        "public-api": True,
        "some": "metadata"
    },
    "image": "https://storage.googleapis.com/878e3274c08e986246b96b088d.identity.images.dev.storage.robbieapis.com/00000000/04215236337134144221/1561/486/560/56037428.webp?Expires=1561490216&GoogleAccessId=aws-workers%40robbie-ai-us.iam.gserviceaccount.com&Signature=ZGJaFL3L9xgHH9rxjjxETTx1pbeJylI76V%2FtYagQnHQgKzzuqrqQ2aTRAwzxlkFOba5olRk8zf1oYpNKkGuvx2ylrta%2BOnbz7jWgmxEBkdHC1zhH%2Fc%2BXupq5YXPrP%2BT20N2FZRHiMIgGw5pURe1Wl8kfP5Jh3QLccsxzGAajhyzF%2FDH7vSOHQXQl0GYo0SA8dFxBbWwpTewLBpjcrKc6xg%2B0qvzdZmkZlawFZWkzRgC9osrcm9PQ%2F%2F%2BUxNrA7FNj0cIyAGLv5ouCnH2Qf1oKtbQ03q03CnZARDOA6uPnZkVqVKH1aLMni%2F3%2F%2FaEyyVuH8KetXWQsTcLpKVQ0xnHTwQ%3D%3D",
}

Match

This endpoint provides identity matching, with a previous ID from the endpoint register, meaning a picture that is not yet registered.

For checking if your token is correct, call the match endpoint:

  • Path: /v1/match/{id}/
  • Method: POST
  • Headers:
    • Authorization
  • Content Type: application/json
  • Body:
Field Type Required Default Description
image string[base64] true N/A Image to register
antiSpoofing boolean false false Enable anti-spoofing detection

Calling the match endpoint with a target image:

Dani G1

1
2
3
4
5
6
7
cat docs/images/match.webp | base64 | tee match.b64
API_KEY=7dae9cfd1b40454dad3cdf15b073370fcfa7f09a97c743e081459ad28b1e18df
ID=5413685439686021138
http POST https://rw-identity.robbieapis.com/v1/match/${ID}/ \
    "Authorization: ApiKey-v1 ${API_KEY}" \
    image=@register.b64 \
    antiSpoofing:=false
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import base64
import requests
import json
API_KEY="7dae9cfd1b40454dad3cdf15b073370fcfa7f09a97c743e081459ad28b1e18df"
ID=5413685439686021138

with open("docs/images/match.webp", "rb") as f:
    base64_image = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://rw-identity.robbieapis.com/v1/match/{}/".format(ID),
    json={
        "image": base64_image,
        "antiSpoofing": False,
    },
    headers={
        "Authorization": "ApiKey-v1 {}".format(API_KEY),
    },
)
assert response.status_code == 200
print("{}".format(json.dumps(response.get_json(), indent=4)))

Expected Response

Field Type Description
match boolean Whether it was a match or not
metadata object Free meta data attached
box array[int] Coordinates (x,y,w,h) of the face
similarity float % of similarity
image string[URL] A 1-hour duration valid signed URL for the face
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Alt-Svc: clear
Content-Length: 143
Content-Security-Policy: default-src 'self'
Content-Type: application/json
Date: Mon, 24 Jun 2019 19:52:54 GMT
Referrer-Policy: strict-origin-when-cross-origin
Server: gunicorn/19.9.0
Strict-Transport-Security: max-age=31556926; includeSubDomains
Via: 1.1 google
X-Content-Security-Policy: default-src 'self'
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block

{
    "match": true,
    "metadata": {
        "label": "Dani G",
        "public-api": true,
        "some": "metadata"
    },
    "similarity": 0.153,
    "image": "https://storage.googleapis.com/878e3274c08e986246b96b088d.identity.images.dev.storage.robbieapis.com/00000000/04215236337134144221/1561/486/560/56037428.webp?Expires=1561490216&GoogleAccessId=aws-workers%40robbie-ai-us.iam.gserviceaccount.com&Signature=ZGJaFL3L9xgHH9rxjjxETTx1pbeJylI76V%2FtYagQnHQgKzzuqrqQ2aTRAwzxlkFOba5olRk8zf1oYpNKkGuvx2ylrta%2BOnbz7jWgmxEBkdHC1zhH%2Fc%2BXupq5YXPrP%2BT20N2FZRHiMIgGw5pURe1Wl8kfP5Jh3QLccsxzGAajhyzF%2FDH7vSOHQXQl0GYo0SA8dFxBbWwpTewLBpjcrKc6xg%2B0qvzdZmkZlawFZWkzRgC9osrcm9PQ%2F%2F%2BUxNrA7FNj0cIyAGLv5ouCnH2Qf1oKtbQ03q03CnZARDOA6uPnZkVqVKH1aLMni%2F3%2F%2FaEyyVuH8KetXWQsTcLpKVQ0xnHTwQ%3D%3D",
}
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
    "match": True,
    "metadata": {
        "label": "Dani kG",
        "public-api": True,
        "some": "metadata"
    },
    "similarity": 0.153,
    "image": "https://storage.googleapis.com/878e3274c08e986246b96b088d.identity.images.dev.storage.robbieapis.com/00000000/04215236337134144221/1561/486/560/56037428.webp?Expires=1561490216&GoogleAccessId=aws-workers%40robbie-ai-us.iam.gserviceaccount.com&Signature=ZGJaFL3L9xgHH9rxjjxETTx1pbeJylI76V%2FtYagQnHQgKzzuqrqQ2aTRAwzxlkFOba5olRk8zf1oYpNKkGuvx2ylrta%2BOnbz7jWgmxEBkdHC1zhH%2Fc%2BXupq5YXPrP%2BT20N2FZRHiMIgGw5pURe1Wl8kfP5Jh3QLccsxzGAajhyzF%2FDH7vSOHQXQl0GYo0SA8dFxBbWwpTewLBpjcrKc6xg%2B0qvzdZmkZlawFZWkzRgC9osrcm9PQ%2F%2F%2BUxNrA7FNj0cIyAGLv5ouCnH2Qf1oKtbQ03q03CnZARDOA6uPnZkVqVKH1aLMni%2F3%2F%2FaEyyVuH8KetXWQsTcLpKVQ0xnHTwQ%3D%3D",
}

Tip

Note that similarity is not a matching attribute, meaning it gives only information about how different is the same identity from one picture to the other. For instance, if you provide a register picture with a very different look, a long lapse of time in age or with distinct characteristics (glasses, beards, angles, etc.).

Anti-Spoofing

Anti-Spoofing feature can be enabled by passing to the endpoints antiSpoofing: true.

No Detection of faces

Robbie RW-Identity™ API provides anti-spoofing measures, first let's try with a masked face, a invalid human face:

Dani G1

1
2
3
4
5
6
7
cat docs/images/spoof.webp | base64 | tee spoof.b64
API_KEY=7dae9cfd1b40454dad3cdf15b073370fcfa7f09a97c743e081459ad28b1e18df
ID=5413685439686021138
http POST https://rw-identity.robbieapis.com/v1/register/ \
    "Authorization: ApiKey-v1 ${API_KEY}" \
    image=@spoof.b64 \
    antiSpoofing:=true

Response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Alt-Svc: clear
Content-Length: 3
Content-Security-Policy: default-src 'self'
Content-Type: application/json
Date: Tue, 25 Jun 2019 16:52:23 GMT
Referrer-Policy: strict-origin-when-cross-origin
Server: gunicorn/19.9.0
Strict-Transport-Security: max-age=31556926; includeSubDomains
Via: 1.1 google
X-Content-Security-Policy: default-src 'self'
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block

{}

An empty response indicates no human face was detected/validated.

Abstract

Invalid faces are skipped always, no matter which antiSpoofing value is passed.

Spoofing faces

If antiSpoofing: true is set, then pictures with bad quality, edited or with some degree of artifacts/noise over the face, that can lead to an incorrect identification, are filtered:

1
2
3
4
5
API_KEY=7dae9cfd1b40454dad3cdf15b073370fcfa7f09a97c743e081459ad28b1e18df
http POST https://rw-identity.robbieapis.com/v1/register/ \ 
    "Authorization: ApiKey-v1 ${API_KEY}" \
    image=@spoof2.b64 \
    antiSpoofing:=true

The response will detect this face for identity as an spoof:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Alt-Svc: clear
Content-Length: 15
Content-Security-Policy: default-src 'self'
Content-Type: application/json
Date: Tue, 25 Jun 2019 19:18:20 GMT
Referrer-Policy: strict-origin-when-cross-origin
Server: gunicorn/19.9.0
Strict-Transport-Security: max-age=31556926; includeSubDomains
Via: 1.1 google
X-Content-Security-Policy: default-src 'self'
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block

{
    "spoof": true
}

Warning

If a multiple faces image is supplied and one of them is considered an spoof, all faces are discarded.

If we disable anti-spoofing, we will get normal results for the same picture:

1
2
3
4
5
API_KEY=7dae9cfd1b40454dad3cdf15b073370fcfa7f09a97c743e081459ad28b1e18df
http POST https://rw-identity.robbieapis.com/v1/register/ \ 
    "Authorization: ApiKey-v1 ${API_KEY}" \
    image=@spoof2.b64 \
    antiSpoofing:=false
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Alt-Svc: clear
Content-Length: 776
Content-Security-Policy: default-src 'self'
Content-Type: application/json
Date: Tue, 25 Jun 2019 18:16:56 GMT
Referrer-Policy: strict-origin-when-cross-origin
Server: gunicorn/19.9.0
Strict-Transport-Security: max-age=31556926; includeSubDomains
Via: 1.1 google
X-Content-Security-Policy: default-src 'self'
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block

{
    "biometrics": {
        "age": 35.0,
        "ethnicity": "BLACK",
        "gender": "F"
    },
    "box": [
        36,
        140,
        79,
        79
    ],
    "id": 4215236337134144221,
    "image": "https://storage.googleapis.com/878e3274c08e986246b96b088d.identity.images.dev.storage.robbieapis.com/00000000/04215236337134144221/1561/486/560/56037428.webp?Expires=1561490216&GoogleAccessId=aws-workers%40robbie-ai-us.iam.gserviceaccount.com&Signature=ZGJaFL3L9xgHH9rxjjxETTx1pbeJylI76V%2FtYagQnHQgKzzuqrqQ2aTRAwzxlkFOba5olRk8zf1oYpNKkGuvx2ylrta%2BOnbz7jWgmxEBkdHC1zhH%2Fc%2BXupq5YXPrP%2BT20N2FZRHiMIgGw5pURe1Wl8kfP5Jh3QLccsxzGAajhyzF%2FDH7vSOHQXQl0GYo0SA8dFxBbWwpTewLBpjcrKc6xg%2B0qvzdZmkZlawFZWkzRgC9osrcm9PQ%2F%2F%2BUxNrA7FNj0cIyAGLv5ouCnH2Qf1oKtbQ03q03CnZARDOA6uPnZkVqVKH1aLMni%2F3%2F%2FaEyyVuH8KetXWQsTcLpKVQ0xnHTwQ%3D%3D",
    "metadata": {
        "public-api": true
    }
}

Abstract

antiSpoofing: true is a security measure, to mainly avoid impersonation. It may lead to unwanted filtered images because the filter rather false positive spoofs (original images marked as spoof) than false negatives (that is, allowing a possible spoof), so use it when you have untrusted sources of identity, or a very high level of strict identification is required.


  1. CTO and co-founder of Robbie AI Inc.