Skip to navigation
Expression Measurement APIVideo

Upload images

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

LimitValue
Request size25MB, the whole multipart body
Image size2MB
Pixels per image8,294,400 (the area of a 3840x2160 image)
Faces measured per image2 by default, the largest; contact support to raise it
Faces listed per image32

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