인물 비교

VPC 환경에서 이용 가능합니다.

업로드한 썸네일 이미지를 기준으로 워크스페이스에 등록된 인물 중 얼굴이 유사한 인물을 추천합니다. 인물을 신규 등록하기 전 동일 인물이 이미 등록되어 있는지 확인하거나, 익명 인물에 이름을 지정할 때 후보 인물을 확인하는 용도로 활용할 수 있습니다.

요청 전 인물 썸네일 Presigned URL 발급으로 발급받은 URL에 이미지를 업로드하고, 인물 썸네일 업로드 상태 조회로 업로드 완료 여부를 확인해 주십시오.

참고

추천 인물 목록이 빈 배열로 반환되면 기준 유사도 이상으로 일치하는 등록 인물이 없다는 의미이며, 인물 등록을 진행할 수 있습니다.

요청

요청 형식을 설명합니다. 요청 형식은 다음과 같습니다.

메서드	URI
POST	/api/v1/workspaces/{workspace_name}/persons/recommend-by-thumbnail

요청 헤더

Media Intelligence API에서 공통으로 사용하는 헤더에 대한 정보는 Media Intelligence 요청 헤더를 참조해 주십시오.

요청 경로 파라미터

요청 경로 파라미터에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`workspace_name`	String	Required	워크스페이스 이름

요청 바디

요청 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`thumbnailKey`	String	Required	업로드된 썸네일의 키 값 인물 썸네일 Presigned URL 발급으로 발급받은 키 업로드 후 24시간이 지나면 만료 <예시> `persons/thumbnails/hong.jpg`
`personCount`	Integer	Optional	조회할 추천 인물 수 1~10 (기본값: 3)
`scoreThreshold`	Integer	Optional	유사 인물로 판단할 기준 유사도 80~100 (기본값: 80)

요청 예시

요청 예시는 다음과 같습니다.

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
}'

응답

응답 형식을 설명합니다.

응답 바디

응답 바디에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`code`	String	-	API 처리 결과 코드
`message`	String	-	API 처리 결과 메시지
`result`	Object	-	인물 비교 결과
`result.thumbnailKey`	String	-	요청에 사용한 썸네일 키
`result.recommendPersons`	Array	-	추천 인물 목록: recommendPersons 유사도 내림차순 조건에 해당하는 인물이 없는 경우 빈 배열
`result.totalRecommendPersons`	Integer	-	기준 유사도 이상인 전체 후보 인물 수

`recommendPersons`

recommendPersons에 대한 설명은 다음과 같습니다.

필드	타입	필수 여부	설명
`personId`	Integer	-	추천 인물의 인물 ID
`name`	String	-	추천 인물의 이름 익명 인물은 null로 표시
`score`	Number	-	요청 썸네일과의 유사도 0~100
`assetCount`	Integer	-	추천 인물이 등장하는 에셋 수

응답 상태 코드

Media Intelligence API에서 공통으로 사용하는 응답 상태 코드에 대한 정보는 Media Intelligence 응답 상태 코드를 참조해 주십시오.

응답 예시

응답 예시는 다음과 같습니다.

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