For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Send one or more images, each as a `file` part, and, to change the defaults, settings as a JSON `config` part. The response holds one result per image, in the order the parts were sent. An image with no faces is a normal result with an empty `faces` array.
## Detection and measurement
The server detects the faces in each image and lists them in `faces`. It measures the largest of them, up to the limit below, and lists those first, largest first.
- A face is skipped, and is not listed, if its detection confidence is below `face.threshold` or its bounding box is under `face.min_size` pixels on its shorter side.
- Each measured face carries its bounding box, its detection confidence, a `face_id`, and two sets of scores: `expressions` for emotional expressions such as amusement or interest, and `descriptions` for visible facial actions such as a smile or a jaw drop.
- The faces that were not measured follow, most confident first, up to 32 faces in all. Each carries its bounding box and detection confidence, with `face_id`, `expressions` and `descriptions` null.
- `face_id` tracks a face across the images of one request. A face normally keeps its ID while it is measured, and can get it back after it leaves the view or is no longer among the largest faces. IDs do not identify a person.
- **Across requests:** IDs start again from 0 in every request. To keep them consistent, set `return_face_state` and pass the returned `face_state` as `face_state` in the next request.
## Limits
| Limit | Value |
|---|---|
| Request size | 25MB, the whole multipart body |
| Image size | 2MB |
| Pixels per image | 8,294,400 (the area of a 3840x2160 image) |
| Faces measured per image | 2 by default, the largest; contact support to raise it |
| Faces listed per image | 32 |
Every image is checked before any is measured. One bad image fails the whole request, which then returns no results:
- **Not a JPEG:** rejected with `unsupported_media_type`.
- **Over the image size or pixel limit:** rejected with `image_too_large`.
- **Cannot be decoded:** rejected with `image_decode_failed`, possibly after earlier images were measured.
Authentication
X-Hume-Api-Keystring
API Key authentication via header
Request
This endpoint expects a multipart form with multiple files.
configobjectOptional
Settings for a video request, sent as the JSON config part.
faceobjectOptional
Face detection settings.
face_statestringOptional
The face_state from an earlier response, so face_id continues from the faces that request saw. A state is accepted for 24 hours after it was issued. One that has expired, was altered, or was issued to another organization is ignored, and numbering starts again from 0.
filefilesRequired
The images, one JPEG per file part. Results are numbered by the order of the parts.
Response
One result per image, in the order sent.
request_idstring
Identifies this request in Hume's records. Quote it when contacting support.
run_idstringformat: "uuid"
Identifies the run this request was recorded as. Pass it to the run endpoints to look the run up.
receivedobject
What the server took from the request.
framesinteger>=0
The number of images measured.
measurementslist of objects
One result per image, in the order the file parts were sent. An image with no faces still has a result, with faces empty.
frame_idinteger>=0
Identifies the image within the run, counting from 0. A file request numbers its images by the order of the file parts; a realtime session numbers only the frames it answered with a measurement.
faceslist of objects
The faces detected in the image: the measured faces first, largest first, then the faces that were not measured, in descending order of confidence.
face_statestringOptional
Present when return_face_state was set. Pass it unchanged as face_state in a later request, within 24 hours, to continue face_id numbering.
Errors
400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
405
Method Not Allowed Error
413
Content Too Large Error
415
Unsupported Media Type Error
500
Internal Server Error
503
Service Unavailable Error
Send one or more images, each as a file part, and, to change the defaults, settings as a JSON config part. The response holds one result per image, in the order the parts were sent. An image with no faces is a normal result with an empty faces array.
Detection and measurement
The server detects the faces in each image and lists them in faces. It measures the largest of them, up to the limit below, and lists those first, largest first.
A face is skipped, and is not listed, if its detection confidence is below face.threshold or its bounding box is under face.min_size pixels on its shorter side.
Each measured face carries its bounding box, its detection confidence, a face_id, and two sets of scores: expressions for emotional expressions such as amusement or interest, and descriptions for visible facial actions such as a smile or a jaw drop.
The faces that were not measured follow, most confident first, up to 32 faces in all. Each carries its bounding box and detection confidence, with face_id, expressions and descriptions null.
face_id tracks a face across the images of one request. A face normally keeps its ID while it is measured, and can get it back after it leaves the view or is no longer among the largest faces. IDs do not identify a person.
Across requests: IDs start again from 0 in every request. To keep them consistent, set return_face_state and pass the returned face_state as face_state in the next request.
Limits
Limit
Value
Request size
25MB, the whole multipart body
Image size
2MB
Pixels per image
8,294,400 (the area of a 3840x2160 image)
Faces measured per image
2 by default, the largest; contact support to raise it
Faces listed per image
32
Every image is checked before any is measured. One bad image fails the whole request, which then returns no results:
Not a JPEG: rejected with unsupported_media_type.
Over the image size or pixel limit: rejected with image_too_large.
Cannot be decoded: rejected with image_decode_failed, possibly after earlier images were measured.
