Search the Face Index
Find the Orbit profiles whose photos show a picked face.
POST
/
v3
/
faces
/
index-search
Search the Face Index
curl --request POST \
--url https://api.orbitsearch.com/v3/faces/index-search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"image_url": "<string>",
"bbox": [
212,
140,
388,
356
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({image_url: '<string>', bbox: [212, 140, 388, 356]})
};
fetch('https://api.orbitsearch.com/v3/faces/index-search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.orbitsearch.com/v3/faces/index-search"
payload = {
"image_url": "<string>",
"bbox": [212, 140, 388, 356]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"status": "success",
"payload": {
"min_similarity": 123,
"face": {
"bbox": [
212,
140,
388,
356
]
},
"matches": [
{
"profile_id": "<string>",
"similarity": 0.5,
"image_url": "<string>"
}
]
}
}{
"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
}
}Search the face index compares a picked face with the faces on Orbit profiles. It is the free first step of face search: a match shows a known profile at once.
Several matches can be the same person on different profiles, or look-alikes. Show them to your user to choose. To search the web for the face, start a search with
curl -X POST "https://api.orbitsearch.com/v3/faces/index-search" \
-H "Authorization: Bearer $ORBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"image_url": "face-source:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08.jpg",
"bbox": [212, 140, 388, 356]
}'
Request Body
| Field | Type | Description |
|---|---|---|
image_url | string | The photo reference from Detect faces. |
bbox | array of 4 numbers | The picked face’s box from Detect faces. Required when the photo has more than one face. |
Response
{
"status": "success",
"payload": {
"min_similarity": 0.52,
"face": { "bbox": [212, 140, 388, 356] },
"matches": [
{
"profile_id": "profile_123",
"similarity": 0.81,
"image_url": "https://example.com/example-person.jpg"
}
]
}
}
| Field | Type | Description |
|---|---|---|
min_similarity | number | The lowest similarity a match can have. |
face.bbox | array of 4 integers | The face Orbit compared, as it found it in the photo. |
matches | array | Profiles whose photos show the same face, highest similarity first. The array is empty when the index has no match. |
matches[].profile_id | string | The Orbit profile ID. Pass it to Read a profile. |
matches[].similarity | number | How alike the two faces are, from 0 to 1. |
matches[].image_url | string | The profile photo that matched. |
signals.face_source.
Errors
| Status | Code | Meaning |
|---|---|---|
| 400 | developer_face_source_invalid | image_url is a reference other than one from Detect faces, or bbox has the wrong shape. |
| 422 | developer_v3_faces_source_face_not_found | The box matches none of the faces in the photo, or the photo has several faces and the request has no bbox. |
| 502 | developer_v3_faces_upstream_failed | Face matching is temporarily unavailable. Retry later. |
Authentication and Cost
This endpoint requiressearch:read. Searching the face index is free.Authorizations
Use an Orbit API key from the Developer Dashboard.
Body
application/json
A face from a photo stored by POST /v3/faces/detect. On POST /v3/search it searches for the people the face could be.
⌘I
Search the Face Index
curl --request POST \
--url https://api.orbitsearch.com/v3/faces/index-search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"image_url": "<string>",
"bbox": [
212,
140,
388,
356
]
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({image_url: '<string>', bbox: [212, 140, 388, 356]})
};
fetch('https://api.orbitsearch.com/v3/faces/index-search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.orbitsearch.com/v3/faces/index-search"
payload = {
"image_url": "<string>",
"bbox": [212, 140, 388, 356]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"status": "success",
"payload": {
"min_similarity": 123,
"face": {
"bbox": [
212,
140,
388,
356
]
},
"matches": [
{
"profile_id": "<string>",
"similarity": 0.5,
"image_url": "<string>"
}
]
}
}{
"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
}
}