Compare person

Available in VPC

It recommends people registered in the workspace whose faces resemble the uploaded thumbnail image. You can use this feature to check whether the same person is already registered before adding a new person, or to review candidate profiles when assigning a name to an anonymous person.

Before making a request, upload the image to the URL obtained via Issue person thumbnail presigned URL, and use Get person thumbnail upload status to verify that the upload is complete.

Note

If the list of recommended persons is returned as an empty array, it means there are no registered persons that match the specified similarity threshold or higher. In this case, you can proceed with Register person.

Request

This section describes the request format. The method and URI are as follows:

Method	URI
POST	/api/v1/workspaces/{workspace_name}/persons/recommend-by-thumbnail

Request headers

For information about the request headers common to all Media Intelligence APIs, see Media Intelligence request headers.

Request path parameters

You can use the following path parameters with your request:

Field	Type	Required	Description
`workspace_name`	String	Required	Workspace name

Request body

You can include the following data in the body of your request:

Field	Type	Required	Description
`thumbnailKey`	String	Required	Key value of the uploaded thumbnail Key issued from Issue person thumbnail presigned URL. Expires 24 hours after upload. Example: `persons/thumbnails/hong.jpg`
`personCount`	Integer	Optional	Number of recommended people to query 1-10 (default: 3)
`scoreThreshold`	Integer	Optional	Similarity threshold for determining whether two individuals are similar 80-100 (default: 80)

Request example

The request example is as follows:

curl --location --request POST 'https://mi.apigw.ntruss.com/api/v1/workspaces/my-workspace/persons/recommend-by-thumbnail' \
--header 'x-ncp-apigw-timestamp: {Timestamp}' \
--header 'x-ncp-iam-access-key: {Access Key}' \
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}' \
--header 'Content-Type: application/json' \
--data '{
  "thumbnailKey": "persons/thumbnails/hong.jpg",
  "personCount": 3,
  "scoreThreshold": 80
}'

Response

This section describes the response format.

Response body

The response body includes the following data:

Field	Type	Required	Description
`code`	String	-	API processing result code
`message`	String	-	API processing result message
`result`	Object	-	Person comparison result
`result.thumbnailKey`	String	-	Thumbnail key used in the request
`result.recommendPersons`	Array	-	Recommended person list: recommendPersons Similarity in descending order. An empty array if no person meets the criteria.
`result.totalRecommendPersons`	Integer	-	Total number of candidate persons exceeding the threshold similarity

`recommendPersons`

The following describes recommendPersons.

Field	Type	Required	Description
`personId`	Integer	-	Person ID of recommended person
`name`	String	-	Name of recommended person Anonymous persons are displayed as null.
`score`	Number	-	Similarity to requested thumbnail 0-100
`assetCount`	Integer	-	Number of assets featuring the recommended person

Response status codes

For information about the response status codes common to all Media Intelligence APIs, see Media Intelligence response status codes.

Response example

The response example is as follows:

{
  "code": "0",
  "message": "success",
  "result": {
    "thumbnailKey": "persons/thumbnails/hong.jpg",
    "recommendPersons": [
      {
        "personId": 1001,
        "name": "Gildong Hong",
        "score": 93.42,
        "assetCount": 12
      }
    ],
    "totalRecommendPersons": 1
  }
}