Detect Faces
Upload a photo and find every face in it.
POST
/
v3
/
faces
/
detect
Detect Faces
curl --request POST \
--url https://api.orbitsearch.com/v3/faces/detect \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form image=@example-fileconst form = new FormData();
form.append('image', '<string>');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://api.orbitsearch.com/v3/faces/detect', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.orbitsearch.com/v3/faces/detect"
files = { "image": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, files=files, headers=headers)
print(response.text){
"status": "success",
"payload": {
"image_url": "<string>",
"image_width": 123,
"image_height": 123,
"faces": [
{
"index": 1,
"bbox": [
212,
140,
388,
356
],
"det_score": 0.5
}
]
}
}{
"status": "failed",
"error": {
"code": "<string>",
"message": "<string>",
"requiredCredits": 1,
"remainingCredits": 1
}
}{
"status": "failed",
"error": {
"code": "<string>",
"message": "<string>",
"requiredCredits": 1,
"remainingCredits": 1
}
}{
"status": "failed",
"error": {
"code": "<string>",
"message": "<string>",
"requiredCredits": 1,
"remainingCredits": 1
}
}{
"status": "failed",
"error": {
"code": "<string>",
"message": "<string>",
"requiredCredits": 1,
"remainingCredits": 1
}
}{
"status": "failed",
"error": {
"code": "<string>",
"message": "<string>",
"requiredCredits": 1,
"remainingCredits": 1
}
}{
"status": "failed",
"error": {
"code": "<string>",
"message": "<string>",
"requiredCredits": 1,
"remainingCredits": 1
}
}{
"status": "failed",
"error": {
"code": "<string>",
"message": "<string>",
"requiredCredits": 1,
"remainingCredits": 1
}
}Detect faces is the first step of face search. Orbit stores the photo privately and returns a reference to it with every face it finds, left to right.
Orbit keeps the photo for 7 days. Detect a photo again to search with it after that.
curl -X POST "https://api.orbitsearch.com/v3/faces/detect" \
-H "Authorization: Bearer $ORBIT_API_KEY" \
-F "image=@photo.jpg"
Request
Send the photo as the multipart fieldimage. Orbit accepts JPG, PNG, and WebP photos from 50 × 50 pixels up to 25 MB.
Response
{
"status": "success",
"payload": {
"image_url": "face-source:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08.jpg",
"image_width": 1280,
"image_height": 960,
"faces": [
{ "index": 0, "bbox": [212, 140, 388, 356], "det_score": 0.91 },
{ "index": 1, "bbox": [720, 180, 868, 372], "det_score": 0.87 }
]
}
}
| Field | Type | Description |
|---|---|---|
image_url | string | The reference to the stored photo. Pass it to Search the face index and to signals.face_source on Start a search. |
image_width | integer or null | The photo’s width in pixels. |
image_height | integer or null | The photo’s height in pixels. |
faces | array | Every face in the photo, left to right. The array is empty when the photo shows no usable face. |
faces[].index | integer | The face’s position in faces. |
faces[].bbox | array of 4 integers | The face box [x0, y0, x1, y1] in the pixels of the upright photo. |
faces[].det_score | number | How confident Orbit is that the box holds a face, from 0 to 1. |
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | developer_v3_faces_image_required | The request has no image field. |
| 413 | face_image_too_large | The photo is larger than 25 MB. |
| 422 | developer_v3_faces_image_unusable | The photo is smaller than 50 × 50 pixels or in another format. |
| 502 | developer_v3_faces_upstream_failed | Face detection is temporarily unavailable. Retry later. |
Authentication and Cost
This endpoint requiressearch:read. Detecting faces is free.Authorizations
Use an Orbit API key from the Developer Dashboard.
Body
multipart/form-data
A JPG, PNG, or WebP photo from 50 × 50 pixels up to 25 MB.
⌘I
Detect Faces
curl --request POST \
--url https://api.orbitsearch.com/v3/faces/detect \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--form image=@example-fileconst form = new FormData();
form.append('image', '<string>');
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
options.body = form;
fetch('https://api.orbitsearch.com/v3/faces/detect', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.orbitsearch.com/v3/faces/detect"
files = { "image": ("example-file", open("example-file", "rb")) }
headers = {"Authorization": "Bearer <token>"}
response = requests.post(url, files=files, headers=headers)
print(response.text){
"status": "success",
"payload": {
"image_url": "<string>",
"image_width": 123,
"image_height": 123,
"faces": [
{
"index": 1,
"bbox": [
212,
140,
388,
356
],
"det_score": 0.5
}
]
}
}{
"status": "failed",
"error": {
"code": "<string>",
"message": "<string>",
"requiredCredits": 1,
"remainingCredits": 1
}
}{
"status": "failed",
"error": {
"code": "<string>",
"message": "<string>",
"requiredCredits": 1,
"remainingCredits": 1
}
}{
"status": "failed",
"error": {
"code": "<string>",
"message": "<string>",
"requiredCredits": 1,
"remainingCredits": 1
}
}{
"status": "failed",
"error": {
"code": "<string>",
"message": "<string>",
"requiredCredits": 1,
"remainingCredits": 1
}
}{
"status": "failed",
"error": {
"code": "<string>",
"message": "<string>",
"requiredCredits": 1,
"remainingCredits": 1
}
}{
"status": "failed",
"error": {
"code": "<string>",
"message": "<string>",
"requiredCredits": 1,
"remainingCredits": 1
}
}{
"status": "failed",
"error": {
"code": "<string>",
"message": "<string>",
"requiredCredits": 1,
"remainingCredits": 1
}
}