NAV Navbar
shell

Introduction

Welcome to the Facest API!

The Facest Recognition API is a REST API, which accepts and returns JSON-encoded data, and uses standard HTTP response codes, authentication, and verbs.

REST API Base URL

We value security, so only HTTPS is supported. Calls made over plain HTTP will fail.

https://api.facest.io

Authentication

Send your API Key with the request.

curl -XPOST -H "Authorization: Bearer API_KEY" https://api.facest.io/v1/train

The Facest API uses API Keys to authenticate requests. You can view and manage your API Keys in the Facest Console.

Usage limit

Your Facest account determines daily/monthly usage limit.

Detect

Request with URL

curl -XPOST \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "url": "https://cdn.facest.io/samples/faces.jpg"
}' \
https://api.facest.io/v1/detect

Request with file upload

curl -XPOST \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: multipart/form-data" \
-F image=@face.jpg \
https://api.facest.io/v1/detect

Response

{
  "code": 200,
  "data": {
    "count": 2,
    "faces": [
      {
        "rectangle": {
          "top": 125,
          "left": 125,
          "width": 200,
          "height": 200
        }
      }
    ]
  }
}

Detect faces within a given image. This endpoint doesn't recognize faces yet, it's used to find faces only and returns their positions (rectangle coordinates).

You can submit the photo either as a publicly accessible URL or as a file upload.

Train

Request with URL

curl -XPOST \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "url": "https://cdn.facest.io/samples/face2.jpg",
  "face_id": "greg1001"
}' \
https://api.facest.io/v1/train

Request with file upload

curl -XPOST \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: multipart/form-data" \
-F image=@face.jpg \
-f face_id=greg1001 \
https://api.facest.io/v1/train

Response

{
  "code": 200,
  "message": "trained",
  "data": {
    "face_token": "1421e3b21110c10ce2e69c18f197d7d54c757ffa7e9b061c3cff2b49a259cd2c",
    "image_token": "304cef9f3b5ded94718db2db5414f974a153d9867e4c2cc0e87d4f54f8f887e0",
    "image_url": "https://cdn.facest.io/304cef9f3b5ded94718db2db5414f974a153d9867e4c2cc0e87d4f54f8f887e0.jpeg"
  }
}

Train the model by uploading face image and tagging it with something unique to your app (face_id).

You can submit the photo either as a publicly accessible URL or as a file upload.

This endpoint returns face_token which is our internal face identifier which you can use in other endpoints later.

Recognize

Request with URL

curl -XPOST \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{
  "url": "https://cdn.facest.io/samples/faces.jpg"
}' \
https://api.facest.io/v1/recognize

Request with file upload

curl -XPOST \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: multipart/form-data" \
-F image=@face.jpg \
https://api.facest.io/v1/recognize

Response

{
  "code": 200,
  "data": {
    "count": 2,
    "faces": [
      {
        "rectangle": {
          "top": 125,
          "left": 125,
          "width": 200,
          "height": 200
        },
        "confidence": 0.65,
        "face_id": "greg1001",
        "face_token": "66c4e85c28c9d5868df69b8c2f5cdc70e89a1b59",
        "image_url": "https://cdn.facest.io/304cef9f3b5ded94718db2db5414f974a153d9867e4c2cc0e87d4f54f8f887e0.jpeg"
      }
    ]
  }
}

Once you trained the model, you can submit a file and find matching faces.

You can submit the photo either as a publicly accessible URL or as a file upload.

As a result you will get an array of recognized faces with their face_id (the one you used during the training) and face_token (our internal face identifier, you may use it later for managing face data).

Get Faces

Request

curl -XGET \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
https://api.facest.io/v1/faces?limit=100&page=1

Response

{
    "code": 200,
    "message": "",
    "data": {
        "count": 100,
        "pages_count": 1,
        "faces": [
            {
                "face_token": "8264fd4ba88f2120717c86516840cd65fc8c635232112946fc1b06527bad4763",
                "face_id": "greg1001",
                "face_images": [
                    {
                        "image_token": "9ce892e6724e797123751b05cd116cb3a2bcdd057db8b3799d94d2d79e126fc4",
                        "image_url": "https://cdn.facest.io/9ce892e6724e797123751b05cd116cb3a2bcdd057db8b3799d94d2d79e126fc4.jpg",
                        "created_at": "2020-03-31T20:54:57Z"
                    }
                ],
                "created_at": "2020-03-31T20:54:57Z"
            }
        ]
    }
}

Get trained faces and their images. Faces are sorted in descending order by time they've been added. This endpoint supports pagination by sending limit and page.

Get Face

Request

curl -XGET \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
https://api.facest.io/v1/faces/:face_token

Response

{
    "code": 200,
    "data": {
        "face_token": "8264fd4ba88f2120717c86516840cd65fc8c635232112946fc1b06527bad4763",
        "face_id": "greg1001",
        "face_images": [
            {
                "image_token": "9ce892e6724e797123751b05cd116cb3a2bcdd057db8b3799d94d2d79e126fc4",
                "image_url": "https://cdn.facest.io/9ce892e6724e797123751b05cd116cb3a2bcdd057db8b3799d94d2d79e126fc4.jpg",
                "created_at": "2020-03-31T20:54:57Z"
            }
        ],
        "created_at": "2020-03-31T20:54:57Z"
    }
}

Get face object and its images.

Remove Face

Request

curl -XDELETE \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
https://api.facest.io/v1/faces/:face_token

Response

{
  "code": 200,
  "message": "face has been removed"
}

Remove face from the model and all its images.

Remove Face Image

Request

curl -XDELETE \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
https://api.facest.io/v1/images/:image_token

Response

{
  "code": 200,
  "message": "face image has been removed"
}

You can remove single face image from the model. If it's the last image of the face, face will be removed as well.

Errors

Error Response Format

{
    "code": 429,
    "message": "you exceeded daily usage limit"
}

Our API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided. Codes in the 5xx range indicate an error with Facest.io servers (these are rare).

The facest Recognition API uses the following error codes:

Error Code Meaning
400 Bad Request - Please check the API reference
401 Unauthorized - API Key is not valid
404 Not Found - The specified resource not found
429 Too Many Requests - You exceeded daily or monthly usage limit
500 Internal Server Error - We had a problem with our server. Try again later.

SDKs

Most Facest.io REST API endpoints are easy enough to implement using standard HTTP functions in your language, however you may find it useful to use one of the available SDKs: