Face Detection
Finds the faces in an image: their boxes, the model's confidence and their landmarks.#
/lmkit/v1/image-face-detectionRuns the configured face detection model on the image and answers every face found, the most confident first: its box in whole pixels from the top-left corner, the model's confidence from 0 to 1, and the landmarks the model places on it (eyes, nose tip, mouth, ears; right and left are the person's own). The image is read in its stored pixels (an EXIF orientation is not applied), the frame lmkit/v1/image-redact reads its areas in with 'apply_orientation' false: a face's box passed there as an 'ellipse' area covers that face. Small faces (a group photo, a crowd) are found down to 'min_face_size' by reading the image in overlapping tiles; 'min_confidence', 'overlap_threshold' and 'max_faces' tune what is reported. No language model is involved. Use 'page_index' to pick a page of a multi-page TIFF. A payload that is not a decodable image is refused with 422 and error 'invalid_image'; a model that is not available or does not detect faces with 503 and error 'model_unavailable'. If processing exceeds the configured timeout, returns 202 Accepted with a job_id. Poll GET /lmkit/v1/jobs/ for status and results.
Request body
application/json ·
| Property | Type | Description |
|---|---|---|
inputrequired | string | The input image. When input_format is 'Base64EncodedFile', provide a base64-encoded image payload. When 'FileIdentifier', provide the file ID previously returned by the lmkit/v1/files/upload endpoint. |
input_format | How the input is provided. Accepted values: 'Base64EncodedFile' or 'FileIdentifier'. Defaults to 'Base64EncodedFile'. | |
page_index | object (int32) | Zero-based page of a multi-page image (a TIFF scan) to read. Default: 0. An index past the last page is refused with 400. |
model | string | Optional face detection model identifier. Defaults to the server's configured face detection model. |
min_confidence | object (float) | The confidence (0-1) below which a detection is not reported as a face. Omit it for the value the model states. Lower it to miss fewer faces at the cost of more false detections, for instance before a person reviews them. |
min_face_size | object (double) | The smallest face to find, as a fraction (0-1) of the image's shorter side. Omit it for 0.02 (a face 20 pixels wide on a 1000 pixel tall photo). Smaller faces are found by reading the image in finer tiles, which takes longer; 0 reads the whole image alone, the fastest. |
overlap_threshold | object (float) | The overlap (intersection over union, greater than 0 and at most 1) above which two detections are one face and merge. Omit it for the value the model states. Raise it to keep overlapping faces of a dense crowd apart. |
max_faces | object (int32) | The most faces to return, the most confident first. Default: 0, every face found. |
Responses
| Status | Type | Description |
|---|---|---|
| 200 | OK | |
| 202 | Accepted | |
| 400 | Bad Request | |
| 422 | Unprocessable Entity | |
| 500 | application/json | Internal Server Error |
| 503 | Service Unavailable |
curl -X POST "$LMKIT_ONE_URL/lmkit/v1/image-face-detection" \
-H "Authorization: Bearer $LMKIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": "",
"input_format": "Base64EncodedFile",
"page_index": 0,
"model": "",
"min_confidence": "string"
}'