faces

Create a face

Changed on

Adds a user-drawn face box to an asset, for a face the detector missed. To remove a face detection instead, use delete_face; to introduce a brand-new identity first, use create_person.

post/api/faces

Request

  • Base URL: https://api.gumnut.ai
  • URL: https://api.gumnut.ai/api/faces
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Request body

asset_idstring required

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

person_idstring nullable

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_idstring nullable

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

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

Changes

  • 815e0302a988Revision changes
    • breaking

      response property detail list-of-types was widened by adding types string to media type application/json of response 422

    • info

      the response property became required for the status

  • c3e15c78f2daRevision changes
    • info

      added the media type application/json for the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status