Skip to main content
POST
/
api
/
faces
Create a face
curl --request POST \
  --url https://api.example.com/api/faces \
  --header 'Content-Type: application/json' \
  --data '
{
  "asset_id": "<string>",
  "bounding_box": {
    "x": 1,
    "y": 1,
    "w": 2,
    "h": 2
  },
  "person_id": "<string>",
  "library_id": "<string>"
}
'
{
  "id": "<string>",
  "asset_id": "<string>",
  "bounding_box": {},
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "person_id": "<string>",
  "confidence": 123,
  "timestamp_ms": 123,
  "asset_urls": {},
  "cluster_assignment": {
    "distance_to_person": 123,
    "candidates": [
      {
        "person_id": "<string>",
        "distance": 123,
        "name": "<string>"
      }
    ]
  }
}

Body

application/json
​
asset_id
string
required

ID of the asset (with asset_ prefix) to draw the face box on. Get IDs from list_assets / search_assets. 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. Get IDs from list_people; 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 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)

​
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

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

​
cluster_assignment
ClusterAssignmentResponse · object

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.