---
title: "Compare person"
slug: "mi-recommend-persons-by-thumbnail"
updated: 2026-10-08T04:13:08Z
published: 2026-10-08T04:13:08Z
canonical: "api.ncloud-docs.com/mi-recommend-persons-by-thumbnail"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/docs/en/maiu-upload-person-thumbnail-url), and use [Get person thumbnail upload status](/docs/en/maiu-upload-person-thumbnail-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](/docs/en/maiu-create-persons).

## 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](/docs/en/maiu-overview#%EC%9A%94%EC%B2%AD%ED%97%A4%EB%8D%94).

### 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](/docs/en/maiu-upload-person-thumbnail-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](/docs/en/maiu-overview#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C) |
| `message` | String | - | [API processing result message](/docs/en/maiu-overview#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C) |
| `result` | Object | - | Person comparison result |
| `result.thumbnailKey` | String | - | Thumbnail key used in the request |
| `result.recommendPersons` | Array | - | Recommended person list: [recommendPersons](/docs/en/mi-recommend-persons-by-thumbnail#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](/docs/en/maiu-overview#%EC%9D%91%EB%8B%B5%EC%83%81%ED%83%9C%EC%BD%94%EB%93%9C).

### 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
  }
}
```