Search a collection

Find the enrolled faces that match a query photo.

POST /v1/face-search/query1 operation per search, however large the collection

Request

multipart/form-data, with your key as a bearer token.

Field	Type	Default	Description
imagerequired	file	—	A photo containing the face to look for.
model	string	arcface	Embedding model.
threshold	number	0.85	Minimum match score 0–1. Raise it to cut false positives.
top_k	integer	10	Maximum matches to return.
collection	string	—	Restrict the search to one collection. Omit to search all of them.

Example

curl -X POST https://api.quantilence.com/v1/face-search/query \
  -H "Authorization: Bearer $QUANTILENCE_API_KEY" \
  -F "image=@photo.jpg" \
  -F "model=arcface" \
  -F "threshold=0.85" \
  -F "top_k=10" \
  -F "collection=staff"

Response

200 OK with this shape. Values below are illustrative; the keys and types are not.

{
  "success": true,
  "query_faces": 1,
  "matches": [
    {
      "ml_face_id": 4127,
      "collection": "staff",
      "sim_score": 91.6,
      "det_score": 0.938
    },
    {
      "ml_face_id": 3980,
      "collection": "staff",
      "sim_score": 86.2,
      "det_score": 0.902
    }
  ],
  "threshold": 0.85,
  "model": "arcface",
  "detail": {}
}

Field	Type	Description
success	boolean	Always true on a 200.
query_faces	integer	Faces found in the query image.
matches	Match[]	Best matches, highest score first.
matches[].ml_face_id	integer	The enrolled face's id.
matches[].collection	string	Collection it lives in.
matches[].sim_score	float	0–100, not 0–1.
matches[].det_score	float \| null	Detector score at enrolment.
threshold	float	Threshold applied, 0–1.
model	string	Model used.
detail	object	Diagnostic strings; do not parse.

Worth knowing

An empty `matches` array is a successful search that found nobody — not an error.
`sim_score` is 0–100 while `threshold` is 0–1, the same as Compare faces.