Skip to main content
POST
Create a face

Authorizations

Authorization
string
header
required

Gumnut API key (apikey_...) sent as a Bearer token in the Authorization header. Create and manage keys in the Gumnut app, or with the API key endpoints while signed in to it.

Body

application/json
asset_id
string
required

ID of the asset (with asset_ prefix) to draw the face box on. The asset must belong to the target library.

bounding_box
BoundingBoxInput · object
required

Where the face is, as a box in display-space pixels matching the asset's reported width/height. The box must fit inside those dimensions.

person_id
string | null

Optional person ID (with person_ prefix) to assign this face to at creation. Omit to leave it unassigned; assign it later via update_face. Use create_person first if the identity doesn't exist yet.

library_id
string | null

Library to create the face in. Optional if the user has a single live (non-trashed) library; required when they have multiple.

Response

Successful Response

Represents a detected face in an asset with facial recognition data.

id
string
required

Unique face identifier with 'face_' prefix

asset_id
string
required

ID of the asset containing this face

bounding_box
Bounding Box · object
required

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

source
enum<string>
required

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

Available options:
automatic,
manual
created_at
string<date-time>
required

When this face was detected and recorded

updated_at
string<date-time>
required

When this face record was last updated

person_id
string | null

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

assignment_source
enum<string> | null

How the current person assignment was set: 'assigned' at ingest, 'clustered' by clustering, 'auto_merged' by automatic person merge, or 'manual' by an explicit client assignment, confirmation, or manual person merge. Manual does not imply individual human review. Null when unassigned or when provenance is unknown. Separate from source, which describes how the face box was created.

Available options:
assigned,
clustered,
auto_merged,
manual
confidence
number | null

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.

timestamp_ms
integer | null

For video files, timestamp in milliseconds when face appears

asset_urls
Asset Urls · object | null

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

cluster_assignment
ClusterAssignmentResponse · object | null

Cluster-assignment diagnostics for this face. Populated only when include=cluster_assignment is requested on the faces endpoint; null otherwise. See ClusterAssignmentResponse for the shape.