Facebox
Facial recognition with one-shot teaching

Additional documentation

Learn more about Healthz, Readyz, and other Box specific APIs

Read about what you can do with this box on the Machine Box Blog

Do you 💙 this box?

We rely on developers like you spreading the word about us, so please tell your friends and followers

Facebox is successfully running, check the status to the left and use the table of contents to the right to learn more about the services you just installed.

Facebox lets you recognize specific faces in images. You first teach Facebox which faces of the people you want it to recognize by submitting example images. After a 5 second cooldown period, Facebox will then be ready to detect faces in any new images you submit.

Teach faces

Before Facebox can recognize faces, you must first teach it which faces to look for.

/facebox/teach endpoint

Use the /facebox/teach endpoint to teach Facebox a face:

POST /facebox/teach
  • name - (required string) The name of the person (ensure this value is exactly the same for multiple examples from the same person)
  • id - (optional string) Unique ID for each teaching example (typically use the filename)

The face may be provided by submitting an image file, or by specifying the Faceprint.

  • The image you use to teach Facebox must contain only a single detectable face, an error will be returned if Facebox cannot detect a face, or if it detects multiple faces
  • Facebox supports one-shot teaching, but providing more examples of each person will improve its accuracy
Learn about the different ways to submit a file

You can submit a file to Facebox in a number of ways:

Direct HTTP post

You can post a file using an HTML multipart form POST request:

POST /facebox/teach
file={file}
  • file - (binary) The file to post
  • Set the Content-Type header to "multipart/form-data; charset=utf-8"

The following is an example HTML form:

<form method='post' action='/facebox/teach' enctype='multipart/form-data'>
<input type='file' name='file' required='required' placeholder='Select file' />
<button>POST</button>
</form>

If you're using cURL, you can run the following in a terminal shell:

curl -X POST -F 'file=@/path/to/file' /facebox/teach
URL via JSON payload

If you submit a URL, Facebox will download that file and use it as though you posted it.

POST /facebox/teach
{
url: "{url}"
}
  • url - (string) The absolute URL of the file to download
  • Set the Content-Type header to "application/json; charset=utf-8"
URL via query parameters

If you submit a URL, Facebox will download that file and use it as though you posted it.

POST /facebox/teach?url={url}
  • url - (string) The absolute URL of the file to download
  • Set the Content-Type header to "application/x-www-form-urlencoded; charset=utf-8"
URL via form post

If you submit a URL, Facebox will download that file and use it as though you posted it.

POST /facebox/teach
url={url}
  • url - (string) The absolute URL of the file to download
  • Set the Content-Type header to "application/x-www-form-urlencoded; charset=utf-8"
Base64 encoded string via POST body

If you have a file that is Base64 encoded you can post the string directly.

POST /facebox/teach
base64={base64}
  • base64 - (string) The Base64 encoded string of the file
  • Set the Content-Type header to "application/x-www-form-urlencoded; charset=utf-8"
Base64 encoded string via JSON

You may submit a Base64 encoded string in a JSON payload.

POST /facebox/teach
{
"base64": "{base64}"
}
  • base64 - (string) The Base64 encoded string of the file
  • Set the Content-Type header to "application/json; charset=utf-8"

You can submit the URL for an image to be analyzed in a JSON payload. Facebox will download the image and perform the analysis. Images are not cached.

POST http://cryptoconference.by/facebox/teach
{
	"url": "https://machinebox.io/samples/faces/john.jpg",
	"id": "john.jpg",
	"name": "John Lennon"
}
  • url - (string) Absolute URL of the image containing the face to learn
  • Set both the Accept and Content-Type headers to "application/json; charset=utf-8"
Try it now
cURL

In a terminal, make the following cURL request:

curl -H 'Content-Type: application/json' -d '{"url":"https://machinebox.io/samples/faces/john.jpg","name":"John Lennon","id":"john.jpg"}' http://cryptoconference.by/facebox/teach

You can post a file to the /facebox/teach endpoint.

POST http://cryptoconference.by/facebox/teach?name=John+Lennon&id=john.jpg
file={file}
  • file - (binary) The image file containing the face
  • Set the Accept header to "application/json; charset=utf-8"
  • Set the Content-Type header to "multipart/form-data; charset=utf-8"
Try it now
cURL

In a terminal, make the following cURL request:

curl -X POST -F 'file=@/path/to/image.jpg' http://cryptoconference.by/facebox/teach?name=John+Lennon&id=john.jpg
  • /path/to/john.jpg - (string) The relative path to the file to POST to Facebox

If you have the Faceprint string for a face, you can teach it directly without submitting an image.

POST http://cryptoconference.by/facebox/teach
{
	"faceprint": "F/+DAgEBCVtdZmxvYXQ2NAH/hAABCAAA/gLv/4QA/4D7IP...",
	"id": "john.jpg",
	"name": "John Lennon"
}
  • faceprint - (string) The Faceprint of the face to teach

Response

Once the teaching is complete, you will receive a successful response:

200 OK
{
	"success": true
}
Learn more about response errors

Response errors

If something goes wrong, you will get a non-200 response with a body like this:

{
	"success": false,
	"error": "Something went wrong"
}
  • success - (boolean) false indicating all is not well
  • error - (string) Error message

Identify faces

Once Facebox has learned some faces, you can ask it to identify them in images.

Open live demo

/facebox/check endpoint

Use the /facebox/check endpoint to ask Facebox to identify faces that appear within an image.

POST /facebox/check
Learn about the different ways to submit a file

You can submit a file to Facebox in a number of ways:

Direct HTTP post

You can post a file using an HTML multipart form POST request:

POST /facebox/check
file={file}
  • file - (binary) The file to post
  • Set the Content-Type header to "multipart/form-data; charset=utf-8"

The following is an example HTML form:

<form method='post' action='/facebox/check' enctype='multipart/form-data'>
<input type='file' name='file' required='required' placeholder='Select file' />
<button>POST</button>
</form>

If you're using cURL, you can run the following in a terminal shell:

curl -X POST -F 'file=@/path/to/file' /facebox/check
URL via JSON payload

If you submit a URL, Facebox will download that file and use it as though you posted it.

POST /facebox/check
{
url: "{url}"
}
  • url - (string) The absolute URL of the file to download
  • Set the Content-Type header to "application/json; charset=utf-8"
URL via query parameters

If you submit a URL, Facebox will download that file and use it as though you posted it.

POST /facebox/check?url={url}
  • url - (string) The absolute URL of the file to download
  • Set the Content-Type header to "application/x-www-form-urlencoded; charset=utf-8"
URL via form post

If you submit a URL, Facebox will download that file and use it as though you posted it.

POST /facebox/check
url={url}
  • url - (string) The absolute URL of the file to download
  • Set the Content-Type header to "application/x-www-form-urlencoded; charset=utf-8"
Base64 encoded string via POST body

If you have a file that is Base64 encoded you can post the string directly.

POST /facebox/check
base64={base64}
  • base64 - (string) The Base64 encoded string of the file
  • Set the Content-Type header to "application/x-www-form-urlencoded; charset=utf-8"
Base64 encoded string via JSON

You may submit a Base64 encoded string in a JSON payload.

POST /facebox/check
{
"base64": "{base64}"
}
  • base64 - (string) The Base64 encoded string of the file
  • Set the Content-Type header to "application/json; charset=utf-8"

You can submit the URL for an image to be analyzed in a JSON payload. Facebox will download the image and perform the analysis. Images are not cached.

POST http://cryptoconference.by/facebox/check
{
	"url": "https://machinebox.io/samples/faces/thebeatles.jpg",
	"faceprint": false
}
  • url - (string) Absolute URL of the image containing the face to learn
  • faceprint - (boolean) If true will return the Faceprint with each face
  • Set both the Accept and Content-Type headers to "application/json; charset=utf-8"
Try it now
cURL

In a terminal, make the following cURL request:

curl -H 'Content-Type: application/json' -d '{"url":"https://machinebox.io/samples/faces/thebeatles.jpg"}' http://cryptoconference.by/facebox/check

You can post a file to the /facebox/check endpoint.

POST http://cryptoconference.by/facebox/check
file={file}
  • file - (binary) The image file containing the face
  • faceprint - (boolean) If true will return the Faceprint with each face
  • Set the Accept header to "application/json; charset=utf-8"
  • Set the Content-Type header to "multipart/form-data; charset=utf-8"
Try it now
cURL

In a terminal, make the following cURL request:

curl -X POST -F 'file=@/path/to/image.jpg' http://cryptoconference.by/facebox/check
  • /path/to/john.jpg - (string) The relative path to the file to POST to Facebox

Response

Facebox will return an array of faces that it detected, along with their position within the image, and the name and id if the face matched.

{
	"success": true,
	"facesCount": 3,
	"faces": [
		{
			"rect": { "top": 0, "left": 0, "width": 120, "height": 120 },
			"id": "file1.jpg",
			"name": "John Lennon",
			"matched": true,
			"confidence": 0.624,
			"faceprint": "F/+DAgEBCVtdZmxvYXQ2NAH/hAABCAAA/gLv/4QA/4D7IP..."
		},
		{
			"rect": { "top": 200, "left": 200, "width": 100, "height": 100 },
			"id": "file6.jpg",
			"name": "Ringo Starr",
			"matched": true,
			"confidence": 0.72,
			"faceprint": "F/+DAgEBCVtdZmxvYXQ2NAH/hAABCAAA/gLv/4QA/4D7IP..."
		},
		{
			"rect": { "top": 50, "left": 50, "width": 100, "height": 100 },
			"matched": false,
			"confidence": 0,
			"faceprint": "F/+DAgEBCVtdZmxvYXQ2NAH/hAABCAAA/gLv/4QA/4D7IP..."
		}
	]
}
  • success - (bool) true indicating success
  • facesCount - (int) number of faces found
  • faces - (array) All the detected faces in the image
  • faces[].rect - (object) The position of the face in the image
  • faces[].id - (string) Unique ID of the closest matched image
  • faces[].name - (string) Name of the person who owns the face
  • faces[].matched - (bool) true if known faces found (taught via teaching)
  • faces[].confidence - (probability number) How confident facebox is about this match
  • faces[].faceprint - (string) A Faceprint string that describes the face (only included if faceprint=true in the request)

Facebox will detect all the faces and attempt to provide a decision based on which face it recognises.

If the matched bool is false, it means Facebox detected a face but could not tell who it was. In this case, more teaching might be in order.

Learn more about response errors

Response errors

If something goes wrong, you will get a non-200 response with a body like this:

{
	"success": false,
	"error": "Something went wrong"
}
  • success - (boolean) false indicating all is not well
  • error - (string) Error message

Similar faces

You can ask Facebox to find similar faces to one provided in an image, or by its unique identifier. This endpoint can be used to group or discover unknown people, or collect all id values for the same person.

Similar faces by ID

If you want to get similar faces to a face that Facebox has learned, and you know the id you used during teaching, you can make the following GET request:

GET /facebox/similar?id={id}&limit={limit}
  • id - (string) The unique identifier of the similar face
  • limit - (integer) Optional maximum number of faces to return (default is 5)
Try it now

Similar faces by image

If you want to get similar faces to a new or unknown face, you can make a POST request submitting the image containing the face to check:

POST /facebox/similars
Learn about the different ways to submit a file

You can submit a file to Facebox in a number of ways:

Direct HTTP post

You can post a file using an HTML multipart form POST request:

POST /facebox/similars
file={file}
  • file - (binary) The file to post
  • Set the Content-Type header to "multipart/form-data; charset=utf-8"

The following is an example HTML form:

<form method='post' action='/facebox/similars' enctype='multipart/form-data'>
<input type='file' name='file' required='required' placeholder='Select file' />
<button>POST</button>
</form>

If you're using cURL, you can run the following in a terminal shell:

curl -X POST -F 'file=@/path/to/file' /facebox/similars
URL via JSON payload

If you submit a URL, Facebox will download that file and use it as though you posted it.

POST /facebox/similars
{
url: "{url}"
}
  • url - (string) The absolute URL of the file to download
  • Set the Content-Type header to "application/json; charset=utf-8"
URL via query parameters

If you submit a URL, Facebox will download that file and use it as though you posted it.

POST /facebox/similars?url={url}
  • url - (string) The absolute URL of the file to download
  • Set the Content-Type header to "application/x-www-form-urlencoded; charset=utf-8"
URL via form post

If you submit a URL, Facebox will download that file and use it as though you posted it.

POST /facebox/similars
url={url}
  • url - (string) The absolute URL of the file to download
  • Set the Content-Type header to "application/x-www-form-urlencoded; charset=utf-8"
Base64 encoded string via POST body

If you have a file that is Base64 encoded you can post the string directly.

POST /facebox/similars
base64={base64}
  • base64 - (string) The Base64 encoded string of the file
  • Set the Content-Type header to "application/x-www-form-urlencoded; charset=utf-8"
Base64 encoded string via JSON

You may submit a Base64 encoded string in a JSON payload.

POST /facebox/similars
{
"base64": "{base64}"
}
  • base64 - (string) The Base64 encoded string of the file
  • Set the Content-Type header to "application/json; charset=utf-8"

You can submit the URL for an image to be analyzed in a JSON payload. Facebox will download the image and perform the analysis. Images are not cached.

POST http://cryptoconference.by/facebox/similars
{
	url: "https://machinebox.io/samples/faces/john.jpg"
}
  • url - (string) Absolute URL of the image containing the face to learn
  • limit - (integer) Optional maximum number of faces to return (default is 5)
  • Set both the Accept and Content-Type headers to "application/json; charset=utf-8"
Try it now
cURL

In a terminal, make the following cURL request:

curl -H 'Content-Type: application/json' -d '{"url":"https://machinebox.io/samples/faces/john.jpg"}' http://cryptoconference.by/facebox/similars

You can post a file to the /facebox/similars endpoint.

POST http://cryptoconference.by/facebox/similars
file={file}
  • file - (binary) The image file containing the face
  • Set the Accept header to "application/json; charset=utf-8"
  • Set the Content-Type header to "multipart/form-data; charset=utf-8"
Try it now
cURL

In a terminal, make the following cURL request:

curl -X POST -F 'file=@/path/to/image.jpg' http://cryptoconference.by/facebox/similars
  • /path/to/john.jpg - (string) The relative path to the file to POST to Facebox

Response

If successful, Facebox will return the following JSON:

{
	"success": true,
	"faces": [
		{
			"rect": { "top": 0, "left": 0, "width": 120, "height": 120 },
			"similar_faces": [
				{"id": "file8.jpg", "name": "George Harrison"},
				{"id": "file6.jpg", "name": "George Harrison"}
			]
		},
		{
			"rect": { "top": 0, "left": 0, "width": 120, "height": 120 },
			"similar_faces": [
				{"id": "file1.jpg", "name": "John Lennon"},
				{"id": "file2.jpg", "name": "John Lennon"}
			]
		},
		{
			"rect": { "top": 0, "left": 0, "width": 120, "height": 120 },
			"similar_faces": [
				{"id": "file4.jpg", "name": "Paul McCartney"},
				{"id": "file3.jpg", "name": "Paul McCartney"}
			]
		}
	]
}
  • success - (bool) true indicating success
  • faces - (array) List of faces
  • faces[].rect - (object) The position of the face in the image
  • faces[].similar_faces[].id - (string) Unique identifier of the face (usually the image filename used during teaching)
  • faces[].similar_faces[].name - (string) Name of the person who owns the face

similar_faces array is ordered by most similar faces first.

Learn more about response errors

Response errors

If something goes wrong, you will get a non-200 response with a body like this:

{
	"success": false,
	"error": "Something went wrong"
}
  • success - (boolean) false indicating all is not well
  • error - (string) Error message

Updating faces

Updating faces becomes useful when you learn more about that face, such as a manual process where a face is tagged as a known person.

There are two options to consider when it comes to changing names of faces in Facebox. If you want to change the name of an individual face, and you know the id, you can use the Rename faces by ID endpoint. If you want to change all faces with one name for another, use the Rename all endpoint.

Rename all

To rename all faces with a given name, make the following request:

POST /facebox/rename
{
	"from": "Current name",
	"to": "New name"
}
  • from - (string) The current name to match
  • to - (string) The new name to use instead
Try it now
cURL
curl -X POST -d '{"from": "Old name", "to": "New name"}' http://cryptoconference.by/facebox/rename

Rename faces by ID

To rename a face that has been previously taught, make the following request:

PATCH /facebox/teach/{id}
{
	"name": "New name"
}
  • id - (string) The unique identifier of the item to delete
  • name - (string) The name of the person
Try it now
cURL
curl -X PATCH -d '{"name": "New name"}' http://cryptoconference.by/facebox/teach/{id}

Remove faces

To get Facebox to forget a face, you can delete it.

Remove faces by ID

To remove a face that has been previously taught, make the following request:

DELETE /facebox/teach/{id}
  • id - (string) The unique identifier of the item to delete
Try it now
cURL
curl -X DELETE http://cryptoconference.by/facebox/teach/{id}

Faceprint

You can compare multiple faceprints and get back the confidence from the result of the comparsion, a high confidence would mean that the faceprint probably belongs to the same person.

Faceprint compare

To compare multiple faceprints with a target faceprint you can use the following request:

POST /facebox/faceprint/compare
{
    "faceprints": [
        "F/+DAgEBCVtdZmxvAABCAAA...", 
        "4D7IEUvv7/7QMIIkj/7wGMC...", 
        "tg+CS1P/uAx4N+P/dddsegg..."
    ],
	"target": "J/+ZDRTEBCVtdZmxY..."
}
  • faceprints - (array of string) The faceprints that you want to compare with the target
  • target - (string) The faceprint that is going to be compare with the rest

Response

If successful, Facebox will return the following JSON:

{
	"success": true,
	"confidences": [
        0.21287301029665473, 
        0.7309214023621301,
        0.820001
    ]
}
  • success - (bool) true indicating success
  • confidences - (array) List of confidences following the comparison operation. They are in the same order as the faceprints passed in the request.

Faceprint check

To check the identity using the faceprint, you can use the following request:

POST /facebox/faceprint/check
	{
		"faceprints": [
			"F/+DAgEBCVtdZmxvAABCAAA...", 
			"4D7IEUvv7/7QMIIkj/7wGMC..."
		]
	}
  • faceprints - (array of string) The faceprints that you want to check in facebox

Response

If successful, Facebox will return the following JSON:


{ 
	"success": true, 
	"faceprints": [ 
		{ "id": "j1", "name": "John Lennon", "matched": true, "confidence": 0.982 },
		{ "matched": false, "confidence": 0 } 
	]
}
  • success - (bool) true indicating success
  • faceprints - (array) All of check results in the same order of the request
  • faceprints[].id - (string) Unique ID of the closest matched image
  • faceprints[].name - (string) Name of the person who owns the face
  • faceprints[].matched - (bool) true if known faces found (taught via teaching)
  • faceprints[].confidence - (probability number) How confident facebox is about this match

Managing state

Facebox maintains internal state which is how it remembers faces. You can download the state into a binary file for backup, and upload the state on startup or at runtime. This is useful for production environments or for spreading the checking to multiple instances of Facebox.

Downloading state

To download the state from Facebox make the following GET request:

GET /facebox/state
  • A .facebox data file will be downloaded

Uploading state

To upload a .facebox file, make the following POST request:

POST /facebox/state

You can post the file directly, or specify a URL for Facebox to download.

Learn about the different ways to submit a file

You can submit a file to Facebox in a number of ways:

Direct HTTP post

You can post a file using an HTML multipart form POST request:

POST /facebox/state
file={file}
  • file - (binary) The file to post
  • Set the Content-Type header to "multipart/form-data; charset=utf-8"

The following is an example HTML form:

<form method='post' action='/facebox/state' enctype='multipart/form-data'>
<input type='file' name='file' required='required' placeholder='Select file' />
<button>POST</button>
</form>

If you're using cURL, you can run the following in a terminal shell:

curl -X POST -F 'file=@/path/to/file' /facebox/state
URL via JSON payload

If you submit a URL, Facebox will download that file and use it as though you posted it.

POST /facebox/state
{
url: "{url}"
}
  • url - (string) The absolute URL of the file to download
  • Set the Content-Type header to "application/json; charset=utf-8"
URL via query parameters

If you submit a URL, Facebox will download that file and use it as though you posted it.

POST /facebox/state?url={url}
  • url - (string) The absolute URL of the file to download
  • Set the Content-Type header to "application/x-www-form-urlencoded; charset=utf-8"
URL via form post

If you submit a URL, Facebox will download that file and use it as though you posted it.

POST /facebox/state
url={url}
  • url - (string) The absolute URL of the file to download
  • Set the Content-Type header to "application/x-www-form-urlencoded; charset=utf-8"
Base64 encoded string via POST body

If you have a file that is Base64 encoded you can post the string directly.

POST /facebox/state
base64={base64}
  • base64 - (string) The Base64 encoded string of the file
  • Set the Content-Type header to "application/x-www-form-urlencoded; charset=utf-8"
Base64 encoded string via JSON

You may submit a Base64 encoded string in a JSON payload.

POST /facebox/state
{
"base64": "{base64}"
}
  • base64 - (string) The Base64 encoded string of the file
  • Set the Content-Type header to "application/json; charset=utf-8"

You can submit a URL and Facebox will download the .facebox file.

POST /facebox/state
{
	"url": "https://machinebox.io/path/to/file"
}
  • url - (string) The absolute URL of the .facebox file
Try it now
cURL

In a terminal, make the following cURL request:

curl -H 'Content-Type: application/json' -d '{"url":"https://machinebox.io/samples/faces/john.jpg"}' http://cryptoconference.by/facebox/state

You can post the .facebox state file directly to the endpoint.

POST /facebox/state
file={state-file}
  • state-file - (binary) The .facebox state file to upload
  • Set the Accept header to "application/json; charset=utf-8"
  • Set the Content-Type header to "multipart/form-data; charset=utf-8"
Try it now
cURL

In a terminal, make the following cURL request:

curl -X POST -F 'file=@/path/to/state.facebox' http://cryptoconference.by/facebox/state
  • /path/to/state.facebox - (string) The relative path to the .facebox file to POST to Facebox

Environment variables

You can use environment variables to control how Facebox behaves.

  • MB_WORKERS - (integer) Defaults to 4 - The number of workers to run inside the box. More workers means the box can handle more concurrent requests, but each worker takes more RAM. The recommended way to scale is horizontally, by adding more instances of Facebox.
  • MB_FACEBOX_STATE_URL - (string) URL to a .facebox state file to initialize the box with. Useful for spinning up many instances of Facebox with the same state.
  • MB_FACEBOX_STATE_POLL_SECONDS - (integer) Default to 0 (No polling). If this variable is set, Facebox would poll the MB_FACEBOX_STATE_URL for changes on the file, based on the ETag or Last-Modified http headers. If the file changes Facebox will download the new file and update the state of the teaching. This variable is useful for updating multiple running instances of Facebox.
  • MB_FACEBOX_READ_ONLY - (bool) Defaults to false - If true Facebox will be read only. Teaching and updating state will be disabled. Be sure to provide MB_FACEBOX_STATE_URL to set the initial state, otherwise the box will be useless.
  • MB_FACEBOX_INDEX_REFRESH_SECONDS - (integer) Defaults to 2 - Number of seconds that Facebox will wait to update the index for new data, or changes in the data. Facebox will accumulate changes to perform an update on the search index, because changes are an expensive operation, with this variable you can adjust the time interval for that operation.
  • MB_FACEBOX_DISABLE_RECOGNITION - (bool) Defaults to false - If you only need face detection, the recognition algorithms can be disabled by setting this variable to true, saving resources. If you disable recognition, the teaching endpoinds would be disabled as well.
  • MB_DISABLE_CORS - (bool) Defaults to false - If true will turn off CORS support for the box.
  • MB_BASICAUTH_USER and MB_BASICAUTH_PASS - (string) The Basic Authentication username and password that every request must use. Recommended for sitautions where the boxes are publicly accessible. Read more about Basic Authentication.