Skip to main content

Face Search

POST 
/api/v1/ml/people/facesearch

Search for faces in an image. The method requires the image parameter to perform the search. The limit_per_page parameter is optional and defaults to 30 if not provided. The method returns a list of assets that match the search criteria.

Face Search Filters​

The filters option provides the ability to filter face search results with the metadata fields associated with the Asset. This is useful when you want to search for faces with specific metadata fields such as location set to london and age set to 30.

Notes:

  • filters option is only available when FR Addon Settings has been updated for event hooks with appropriate event criteria
  • filters JSON should be passed as a string in the multipart form data: 
    curl --request POST \
      --url <<API_HOST>>/api/v1/ml/people/facesearch \
      --header 'X-FileSpin-Api-Key: UPDATE_ME' \
      --header 'content-type: multipart/form-data' \
      --form image=@face.jpg \
      --form 'filters=\{"field1": "y"\}'
  • filters support string, number, boolean and date fields
  • Asset Metadata fields that end with Date are treated as date fields. Date ranges can be passed as {"createdDate": ["2021-01-01T01:01:01Z", "2022-02-02T02:02:02Z"]} (ISO 8601, inclusive)
  • Fields passed in filters are case-sensitive and ANDed together
  • A field value may contain multiple space-separated values which are ORed together, e.g. {"location": "earth mars"}

Response​

A successful POST request returns a list of assets that match the search criteria. If extended_result is true, response includes Asset Data for all assets in the page.

{
    "data": {
        "matches": ["asset_id1", "asset_id2", "asset_id3"],
        "extended_result": {
            "asset_id1": {"Asset Data JSON"},
            "asset_id2": {"Asset Data JSON"}
        }
    },
    "page": 1,
    "search_id": "eed4c602a80a4920a4a9e56b5d3ea161",
    "limit_per_page": 30,
    "hits": 3
}
ParameterTypeDescription
dataJSONA dictionary with matches that contains a list of asset ids that are direct matches. If include groups is set to true in request, group_matches will be returned with the list of asset ids that the algorithm has determined to be in the same group.
extended_resultJSONA dictionary containing the current data for each file id returned in result. Data for each file follows Asset Data Format JSON. If extended_result is false or not set, response will not contain this JSON.
pageintegerIndex of the page from the result pages. Index is calculated using limit_per_page.
search_idstringReturned if save_search was set to true in the request.
limit_per_pageintegerAs specified in the request or the default.
hitsintegerTotal number of hits for this search. Pagination can be done using this and limit_per_page.

Request​

Responses​

Successful operation