Sign in
faces

Get a face detection

Fetches one face's details by ID (bounding box, assigned person, timestamps, thumbnail). Use when you already have a face_id.

get/api/faces/{face_id}

Path parameters

face_idstring required

Face ID (with face_ prefix) to fetch. Carried by the entries of an asset's faces field (returned with include=faces).

Face ID (with face_ prefix) to fetch. Carried by the entries of an asset's faces field (returned with include=faces).

Query parameters

library_idstring nullable

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

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

includestring[] nullable

Opt-in expansion fields. See list_faces for supported values. Accepts multiple include= query params or a single comma-delimited value.

Opt-in expansion fields. See list_faces for supported values. Accepts multiple include= query params or a single comma-delimited value.

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

Changed in 4 of the 79 revisions of this API.37

  • 815e0302a98811See the full diff
    • ▲

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

      response-property-list-of-types-widened

    • ○

      the response property detail became required for the status 422

      response-property-became-required

  • c3e15c78f2da4See the full diff
    • ○

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

      response-media-type-added

    • ○

      added the non-success response with the status 401

      response-non-success-status-added

    • ○

      added the non-success response with the status 403

      response-non-success-status-added

    • ○

      added the non-success response with the status 429

      response-non-success-status-added

  • 0af8aaa9fea32See the full diff
    • ○

      added the optional property confidence to the response with the 200 status

      response-optional-property-added

    • ○

      added the required property source to the response with the 200 status

      response-required-property-added

  • adbb9fcd30662See the full diff
    • ▲

      query request parameter include list-of-types was narrowed by removing types string

      request-parameter-list-of-types-narrowed

    • ▲

      for the query request parameter include, the type/format of property anyOf[subschema #1]/ was specialized from string/ to array/

      request-parameter-property-type-specialized