Skip to main content
Gumnut exposes two related resources for face workflows:
  • people for grouped identities such as everyone in a library
  • faces for individual face boxes on specific assets
Use the people endpoints when you want to browse or manage identities. Use the faces endpoints when you need to review a specific box, fix an assignment, or add a face that automatic detection missed.

​
When to use faces vs people

Choose the resource that matches the job:
  • Use people when you want the grouped identities in a library.
  • Use faces when you need one face box on one asset.
  • Use asset responses with include=faces when you want face boxes alongside the asset record you are already fetching.

​
Add a manual face box for a missed detection

Gumnut detects faces automatically, but you can also add a manual face box when someone in an asset was missed. When you create a manual face box:
  • Use the asset’s display-space pixel coordinates, matching the same width and height values the asset reports.
  • Pass a person_id if you already know who the face belongs to.
  • Create the person first if you need a brand-new identity, then attach the face to that person.
  • Leave the face unassigned if you want to review it later.
Manual face boxes stay where you put them. If you leave one unassigned, Gumnut will not automatically group or move it later, so plan to assign it explicitly when you are ready.

​
How faces appear in responses

Manual and automatic faces use the same response shape in asset expansions and in the faces endpoints. Use the source field to tell them apart:
  • automatic for detector-found faces
  • manual for user-drawn face boxes
A face row can also include person_id when the face is already assigned to a person.

​
Common face-management workflows

​
Review faces on an asset

Request include=faces when you want the face boxes alongside an asset. Use the faces endpoints directly when you need pagination, filtering, or per-face updates across many assets.

​
Fix a wrong assignment without deleting the box

Update the face’s person_id when you want to reassign it. Set person_id to null when you want to keep the face box but detach it from the current person.

​
Remove a bad face box entirely

Delete the face only when the box itself should be removed. This does not delete the underlying asset or the person it was assigned to.