Update a face

Assigns a face to a specific person, or detaches it from its current person (set person_id to null). This is the right tool for 'this face is Alice' or 'this face isn't Bob after all'.

Currently only the person_id field is mutable. To create a brand-new identity first, call create_person; to delete the face detection entirely, use delete_face.

face_idstring required

Face ID (with face_ prefix) of the face detection to update.

library_idstring nullable

Library the face belongs to. Optional if the user has a single library; required when they have multiple.

Request body

person_idstring nullable

Target person ID (with person_ prefix) to assign this face to. Pass null to detach the face from its current person without deleting either. Use create_person first if the target identity doesn't exist yet.

Response

Successful Response

idstring required

Unique face identifier with 'face_' prefix

asset_idstring required

ID of the asset containing this face

person_idstring nullable

ID of the person this face belongs to (if identified)

bounding_boxobject required

Face location as {x, y, w, h} coordinates in pixels

confidencenumber nullable

Detector confidence on a 0-1 scale; higher is more confident among faces detected under the same configuration (values are not comparable across detector generations). Null on legacy faces without a stored score and on manually added faces.

source'automatic' | 'manual' required

How this face was added: 'automatic' for detector-found faces, 'manual' for user-drawn face boxes.

timestamp_msinteger nullable

For video files, timestamp in milliseconds when face appears

asset_urlsobject nullable

Asset variants for this face: 'thumbnail' with face crop

created_atstring date-time required

When this face was detected and recorded

updated_atstring date-time required

When this face record was last updated

v64

Update a face

Path parameters

Query parameters

Request body

Response