The Faces Controller enables you to manage face recognition and person identification within your media assets. This powerful API allows you to automatically detect, organize, and associate faces with named individuals across your media library.
Key capabilities include:
- Person Management: Create and maintain a database of named individuals with multiple face sources
- Smart Suggestions: Get AI-powered recommendations for face identification based on similarity matching
- Face Association: Link detected faces to known persons or create new person entries
IAM permission
Requires managed policy 41 or IAM permission faces.suggest, faces.update, faces.destroy
Reference
Find faces/persons
Retrieve faces and persons from AdmiralCloud DAM, optionally filtered by mediaContainer.
| Field | Type | Required | Description |
|---|---|---|---|
| mediaContainerId | integer | ✗ | Return assigned faces/persons for the given mediaContainerId |
| Field | Type | Description |
|---|---|---|
| faceId | integer | ID of this face/person |
| id | integer | ID of this face/person |
| lastEditorId | integer | Id of the user who last edited this face/person |
| name | string | Name of this face/person |
| sources | array | |
| └ mediaContainerId | integer | ID of the mediaContainer used as source |
| └ identifier | string | Identifier of the face in the original media of the mediaContainer used as source |
| └ lastEditorId | integer | ID of the user who added this source |
| └ createdAt | integer | Timestamp when this source was added |
Create or update faces/persons
Create a new person or add a face source to an existing person in AdmiralCloud DAM.
| Field | Type | Required | Description |
|---|---|---|---|
| identifier | string | ✓ | Selects the a face in an image for this person. |
| mediaContainerId | integer | ✓ | Add mediaContainer to a face/person. Creates a new face/person if it does not exist yet. |
| name | string | ✓ | Name of this face/person |
| Field | Type | Description |
|---|---|---|
| faceId | integer | ID of this face/person |
| lastEditorId | integer | Id of the user who last edited this face/person |
| name | string | Name of this face/person |
| sources | array | |
| └ mediaContainerId | integer | ID of the mediaContainer used as source |
| └ identifier | string | Identifier of the face in the original media of the mediaContainer used as source |
| └ lastEditorId | integer | ID of the user who added this source |
| └ createdAt | integer | Timestamp when this source was added |
Suggest faces/persons
Get suggestions for unidentified faces in a mediaContainer based on similarity matching.
| Field | Type | Required | Description |
|---|---|---|---|
| mediaContainerId | integer | ✗ | Returns suggestions for faces/persons in the image of mediaContainer. |
| Field | Type | Description |
|---|---|---|
| faceId | integer | ID of this face/person |
| identifier | string | |
| name | string | Name of this face/person |
| similarity | float | Similarity of the face/person in the image/bounding box with the suggested face/person range: 0 to 1 |
Delete faces/persons
Mark a person/face as deleted. The name is anonymized and the entry flagged. The sources remain intact for auditing. Also by just marking them as deleted, we make sure that detected faces for that persons do not request assignment.
| Field | Type | Required | Description |
|---|---|---|---|
| faceId | integer | ✓ | ID of this face/person |
| Field | Type | Description |
|---|---|---|
| faceId | integer | ID of this face/person |
| id | integer | ID of this face/person |
| lastEditorId | integer | Id of the user who last edited this face/person |
| name | string | Name of this face/person |
| sources | array | |
| └ mediaContainerId | integer | ID of the mediaContainer used as source |
| └ identifier | string | Identifier of the face in the original media of the mediaContainer used as source |
| └ lastEditorId | integer | ID of the user who added this source |
| └ createdAt | integer | Timestamp when this source was added |