Face retrieval lets you build a searchable face library and match faces in query images against people stored in that library. You are responsible for maintaining the mapping between images in your face library and the corresponding person records.
This page covers the end-to-end workflow for getting started, how to move a person between groups, and which operations are billed.
Get started
Follow these steps the first time you use face retrieval.
Add a person. See API operation for adding a person. If the target group does not exist, this operation creates it automatically. If the group already exists, the person is added to it.
Add faces. See API operation for adding faces. Submit face images as HTTP or HTTPS URLs (recommended), or upload a local image file. For local file examples, see the SDK documentation.
Search for a face. See Custom face search. Each request targets a single group. To search across multiple groups, call this operation once per group with a different group ID each time.
(Optional) Set person information. See API operation for setting person information. Add supplementary metadata to a person. When a retrieval operation matches that person, the metadata is included in the response.
Limits
| Limit | Default value |
|---|---|
| Maximum faces per query image (face retrieval in M:N mode) | 20 |
| Person IDs returned per matched face | 5 (use the highest-scoring ID as the result) |
Retrieval responses do not include face images. Maintain the mapping between your face library images and person records on your end.
Move a person to a different group
To change which group a person belongs to:
Remove the person from the current group. See API operation for deleting a person from a group. Removing a person from a group does not delete their face images.
Add the person to the new group. See API operation for adding a person to a group. The target group must already exist. If it does not exist, the operation returns an error.
Billing
| Operation | Charged |
|---|---|
| Custom face search | Yes |
| Add faces | Yes |
| Add a person | No |
| Set person information | No |
| Delete a person from a group | No |
| Add a person to a group | No |
For pricing details, see the billing documentation.