클라우드 가이드 센터 User Guide

유사 상품 검색 API 호출 가이드

페이지 이동경로

유사 상품 검색 API Reference

유사 상품 검색 API로 다양한 카테고리의 상품에 대해 속성 또는 카테고리를 인식하고 이미지 기반으로 다양한 카테고리의 유사한 상품을 검색할 수 있습니다.

최초 색인 설정

도메인을 생성하면 별도 설정 없이 곧바로 오토태깅(/classify)을 사용해 보실 수 있습니다.

그 외 유사 상품 검색 API의 모든 기능을 사용하기 위해서는 최초 색인을 위한 설정이 필요합니다. 최초 색인 설정은 헬프데스크에서 기술 문의 유형으로 문의하시기 바랍니다.

안내
최초 색인 DB는 json 또는 URL 규약으로 전달해야 합니다.
json 파일의 형식은 /update 항목의 Update file 예제를 참고하시기 바랍니다.

API Endpoint URL

카카오 i 클라우드 콘솔 > Vision > 도메인 탭의 [인증 정보] 버튼을 클릭해 API Endpoint URL을 조회 및 복사할 수 있습니다.

복사한 API Endpoint URL은 아래와 같이 구성되어 있습니다. API 호출 시 {signature}를 포함한 전체 주소에 요청합니다.
사용하고자 하는 기능에 따라, {API Endpoint URL} 과 {signature} 사이의 경로를 수정해서 사용합니다.

코드 예제 유사 상품 검색 API Endpoint URL

{API Endpoint URL}/classify/{signature}

표 기능 목록

기능 경로 설명
오토 태깅 /classify 다양한 상품의 속성 및 카테고리 인식
이미지 검색 /search_by_image 요청받은 이미지를 분석 후 이미지를 기반으로 대표 상품의 유사 상품을 검색
ID 검색 /search_by_id 요청받은 상품 ID의 유사 상품을 검색
색인 업데이트 /update 유사 상품 검색을 위한 색인 데이터 업데이트
색인 업데이트 요청 상태 조회 /status 색인 업데이트(/update)의 요청 상태 조회

공통 Request Header

표 Request Header

파라미터 타입 필수여부 설명
x-api-key String 필수 {API Key}: API 호출 시 필요한 인증키
- 카카오 i 클라우드 콘솔 > Conversation > 도메인 탭의 [인증 정보] 버튼 클릭해 조회
Content-Type String 필수 다음의 방식을 지원
- multipart/form-data
- /status 호출하는 경우 불필요

/classify

다양한 상품의 속성 및 카테고리를 인식합니다.

Request

Request Syntax

예제 코드 /classify Request Syntax 

curl -X 'POST' '{API Endpoint URL}/classify/{signature}' \
     -H 'x-api-key: {API KEY}' \
     -H 'Content-Type: multipart/form-data' \
     -F 'limit=3' \
     -F 'image=@{이미지 파일};type=image/jpeg'

API 호출 방식

표 API 호출 방식

메서드 요청 URL
POST {API Endpoint URL}/classify/{signature}
- API 호출 시 필요한 Endpoint 경로
- 카카오 i 클라우드 콘솔 > Vision > 도메인 탭의 [인증 정보] 버튼 클릭해 조회 후 수정

Request Elements

표 Request Elements

파라미터 타입 필수 여부 설명
image Binary 선택* 이미지 파일의 바이너리
- 지원하는 파일 확장자: jpg, jpeg, png
* image 또는 image_url 값 중 하나는 반드시 유효한 값을 가져야 함. 둘 다 입력한 경우 image_url 우선
image_url String 선택* 인식하고자 하는 이미지 URL
* image 또는 image_url 값 중 하나는 반드시 유효한 값을 가져야 함. 둘 다 입력한 경우 image_url 우선
limit Integer 선택 인식하고자 하는 최대 속성수
- 범위: 1 - 136
- 기본값: 3

Response

Response Syntax

예제 코드 /classify Response Syntax 

{
  "reqid": "6abb590e9e5e470db6fde4356916072b",
    "result": [
      {
        "objects": [
          {
            "tags": [
              {"name": "[의류] 패턴-무지", "score": 0.977256, "category": ["의류", "패턴", "무지"]},
              {"name": "[의류] 색상-흰색", "score": 0.953949, "category": ["의류", "색상", "흰색"]},
              {"name": "[의류] 카테고리-원피스", "score": 0.91058, "category": ["의류", "카테고리", "원피스"]}
            ],
            "box": [242, 46, 729, 1176],
          }
        ],
        "tag_group": "fashion_attributes",
      }
    ],
  "version": "v1.0.1",
}

Response Elements

표 Response Elements

필드 타입 설명
version String 버전
- 형식: v{MAJOR}.{MINOR}.{PATCH}
- ex. v1.0.1
reqid String 요청마다 고유하게 부여되는 UUID
- 90일 간 유지 후 삭제
result ▼ Array 입력된 이미지에서 검출된 상품 정보
- 하위에 objects와 tag_group을 포함
- objects ▼ Array 각 상품에 대해 인식된 속성과 위치 정보
- 하위에 검출된 상품의 개수만큼의 tags, box를 포함
— tags ▼ Array 속성 인식 결과 리스트
- 하위에 name, score, category를 포함
—— name String 인식된 속성 이름
- ex. [의류] 패턴-무지
—— score Float 확률값
- 범위: 0.0 ~ 1.0
—— category Array 각 상품에 대해 인식된 속성(name)을 파싱한 결과
- ex. “의류”, “패턴”, “무지”
— box Array 검출된 박스 좌표
- [좌상단 x 좌표, 좌상단 y 좌표, 우하단 x 좌표, 우하단 y 좌표]
- tag_group String 검출 및 인식된 속성이 포함된 그룹명
- ex. fashion_attributes

/search_by_image

요청받은 이미지를 분석 후 이미지를 기반으로 대표 상품의 유사 상품을 검색합니다.

Request

Request Syntax

예제 코드 /search_by_image Request Syntax 

curl -X 'POST' '{API Endpoint URL}/search_by_image/{signature}’ \
     -H 'x-api-key: {API KEY}' \
     -H 'Content-Type: multipart/form-data' \
     -F 'image_url={image URL}' \
     -F 'request_id=' \
     -F 'no_page=1' \
     -F 'score_max=1' \
     -F 'image=' \
     -F 'limit=2' \
     -F 'with_classify=false' \
     -F 'with_meta=true'

API 호출 방식

표 API 호출 방식

메서드 요청 URL
POST {API Endpoint URL}/search_by_image/{signature}

Request Elements

표 Request Elements

파라미터 타입 필수 여부 설명
request_id String 선택* 기존 인식했던 이미지에 대해서 빠르게 결과를 가져오기 위한 고유 아이디
* product_id, request_id 둘 중 하나는 유효한 값을 가져야 함. 모두 입력되었을 경우 request_id를 우선 처리
image Binary 선택* 이미지 파일의 바이너리
- 지원하는 파일 확장자: jpg, jpeg, png
* request_id, image 또는 image_url 값 중 하나는 반드시 유효한 값을 가져야 함. 둘 이상 입력한 경우 request_id, image_url, image 순으로 우선 처리
image_url String 선택* 인식하고자 하는 이미지 URL 
- request_id, image 또는 image_url 값 중 하나는 반드시 유효한 값을 가져야 함. 둘 이상 입력한 경우 request_id, image_url, image 순으로 우선 처리
limit Int 선택 페이지에 노출될 최대 유사 상품 수
- 범위: 1 - 100
- 기본값: 10
no_page Int 선택 검색 결과 페이징 적용 시 노출할 페이지 번호
- 전체 유사상품 검색 결과 건수(total) 를 limit 로 나눈 수를 올림한 값보다 작거나 같은 수에 한해 정상 동작함
- 기본값: 1 - 11 이상의 값을 입력할 수 없음
score_max Float 선택 검색 결과로 노출되는 유사도의 최대값
- 범위: 0.0 ~ 1.0
- 기본값: 1 (모든 검색 결과를 노출)
- ex. ‘score_max=0.8’ 로 요청시 검색 결과에 노출되는 유사도의 최대값이 0.8로 설정됨
with_meta Bool 선택 색인된 메타데이터 포함 여부
- true(기본값): 메타데이터 포함
- false: 메타데이터 미포함
with_classify Bool 선택 속성 인식 결과 포함 여부
- false(기본값): 속성 인식 결과 미포함
- true: 속성 인식 결과 포함

안내
이미지 내 여러 상품이 포함된 경우, 모델에 의해 선택된 대표 상품에 대한 유사 상품 검색 결과가 반환됩니다.

Response

Response Syntax

예제 코드 /search_by_image Response Syntax 

{
  "request_id": "6b1acff7db3b433085460efc1c4917be",
  "no_page": 1,
  "limit": 2,
  "total": 100,
  "product_types": [
    {
      "box": [242, 46, 729, 1176],
      "tags": [
        {"name": "[의류] 패턴-무지", "score": 0.977256, "category": ["의류", "패턴", "무지"]},
        {"name": "[의류] 색상-흰색", "score": 0.953949, "category": ["의류", "색상", "흰색"]},
        {"name": "[의류] 카테고리-원피스", "score": 0.91058, "category": ["의류", "카테고리", "원피스"]},
        {"name": "[의류] 소매길이-반팔", "score": 0.889285, "category": ["의류", "소매길이", "반팔"]},
        {"name": "[의류] 네크라인-라운드/유넥", "score": 0.839502, "category": ["의류", "네크라인", "라운드/유넥"]},
        {"name": "[의류] 상의 스타일-끈/벨트/허리", "score": 0.812361, "category": ["의류", "상의 스타일", "끈/벨트/허리"]},
        {"name": "[의류] 하의 스타일(치마)-플레어", "score": 0.782024, "category": ["의류", "하의 스타일(치마)", "플레어"]},
        {"name": "[의류] 소재-면", "score": 0.660514, "cstegory": ["의류", "소재", "면"]},
        {"name": "[의류] 상의 길이-무릎 아래", "score": 0.646213, "category": ["의류", "상의 길이", "무릎 아래"]},
        {"name": "[의류] 핏-기본핏", "score": 0.591068, "category": ["의류", "핏", "기본핏"]},
      ],
    }
  ],
  "result": [
    {
      "product_id": "{Search Result Product ID}",
      "score": 0.255393,
      "value_map": {
        "image_url": "{Search Result Image URL}"
      },
    },
    {
      "product_id": "{Search Result Product ID}",
      "score": 0.232565,
      "value_map": {
        "image_url": "{Search Result Image URL}"
      },
    },
  ],
  "version": "v1.0.1",
}

Response Elements

표 Response Elements

필드 타입 설명
version String 버전
- 형식: v{MAJOR}.{MINOR}.{PATCH}
- ex. v1.0.1
request_id String 요청 이미지마다 고유하게 부여되는 이미지 ID
no_page Int 요청받은 페이지 넘버
limit Int 페이지 내 유사 상품 수
total Int 전체 유사 상품 수
- 최대 100개까지 검색
product_types ▼ Array 검색 대상이 되는 대표 상품의 속성 정보
- tags, box 포함
- with_classify를 false로 요청한 경우 empty array를 반환함
- box Array 대표 상품의 박스 좌표
- [좌상단 x 좌표, 좌상단 y 좌표, 우하단 x 좌표, 우하단 y 좌표]
- tags ▼ Array 속성 인식 결과 리스트
- 하위에 name, score, category 를 포함
—- name String 인식된 속성 이름
- ex. [의류] 패턴-무지
—- score Float 속성 인식 확률값
- 범위: 0.0 ~ 1.0
—- category Array 각 상품에 대해 인식된 속성(name)을 파싱한 결과
- ex. “의류”, “패턴”, “무지”
result ▼ Array 검색된 유사 상품 리스트
- product_id, score, value_map으로 구성됨
- product_id String 상품 ID
- score Float 예측된 유사도
- 범위: 0.0 ~ 1.0
- value_map Object 색인에 포함된 메타 데이터의 키, 밸류를 동일한 이름의 키를 사용하여 전달
- with_meta를 false로 요청한 경우는 제외

/search_by_id

요청받은 상품 ID의 유사 상품을 검색합니다.

Request

Request Syntax

예제 코드 /search_by_id Request Syntax 

curl -X 'POST' '{API Endpoint URL}/search_by_id/{signature}’ \
     -H 'x-api-key: {API KEY}' \
     -H 'Content-Type: multipart/form-data' \
     -F 'request_id=' \
     -F 'no_page=1' \
     -F 'score_max=1' \
     -F 'image=' \
     -F 'limit=10' \
     -F 'with_classify=false' \
     -F 'with_meta=true'

API 호출 방식

표 API 호출 방식

메서드 요청 URL
POST {API Endpoint URL}/search_by_id/{signature}

Request Elements

표 Request Elements

파라미터 타입 필수 여부 설명
product_id String 선택* 상품 고유 아이디
* product_id, request_id 둘 중 하나는 유효한 값을 가져야 함. 모두 입력되었을 경우 request_id를 우선적으로 처리
request_id String 선택* 기존 인식했던 이미지에 대해서 빠르게 결과를 가져오기 위한 고유 아이디
* product_id, request_id 둘 중 하나는 유효한 값을 가져야 함. 모두 입력되었을 경우 request_id를 우선적으로 처리
limit Int 선택 페이지에 노출될 최대 유사 상품 수
- 범위: 1 - 100
- 기본값: 10
no_page Int 선택 검색 결과 페이징 적용 시 노출할 페이지 번호
- 전체 유사상품 검색 결과 건수(total) 를 limit 로 나눈 수를 올림한 값보다 작거나 같은 수에 한해 정상 동작함
- 기본값: 1 - 11 이상의 값을 입력할 수 없음
score_max Float 선택 검색 결과로 노출되는 유사도의 최대값
- 범위: 0.0 ~ 1.0
- 기본값: 1 (모든 검색 결과를 노출)
- ex. ‘score_max=0.8’ 로 요청시 검색 결과에 노출되는 유사도의 최대값이 0.8로 설정됨
with_meta Bool 선택 색인된 메타데이터 포함 여부
- true(기본값): 메타데이터 포함
- false: 메타데이터 미포함
with_classify Bool 선택 속성 인식 결과 포함 여부
- false(기본값): 속성 인식 결과 미포함
- true: 속성 인식 결과 포함

Response

/search_by_image와 동일합니다.

/update

유사 상품 검색을 위한 색인 데이터를 업데이트합니다. 마지막 데이터 업데이트 과정 중 실패 없이 업데이트된 상품 리스트와 비교하여 색인을 업데이트합니다. 상세 로직은 아래와 같습니다.

  1. 리스트에 없는 상품의 경우 추가를 시도합니다.
  2. 마지막 업데이트된 상품 중 신규 리스트에 없는 상품은 삭제를 시도합니다.
  3. callback_url로 결과를 받는 경우, update file 구조와 동일한 결과를 전달합니다.
    • with_classify가 true인 경우, callback url을 이용하여 update file 구조와 동일한 구조로 결과를 전달합니다.

중복 아이템이 있는 경우

업데이트 요청 데이터에 중복 아이템이 있는 경우 아래와 같이 처리합니다.

  • 중복 product_id: 리스트의 첫 번째 항목만 색인하고, 나머지는 무시합니다.
  • 상이한 product_id에 포함된 중복 이미지: 따로 처리하지 않고 모두 색인합니다.

안내
- 색인 업데이트 요청의 권장 처리량은 num_add_item 기준 15,000건입니다.
- 업데이트 요청은 중복으로 보낼 수 없습니다. 중복 요청 시에는 기존 요청의 상태를 반환합니다.

주의
업데이트 요청을 1초 내에 연속으로 보낼 경우, 색인 서버가 비정상적으로 동작할 수 있습니다.

Request

Request Syntax

예제 코드 /update Request Syntax 

curl -X POST 'http://{API Endpoint URL}/update/{signature}' \
     -H 'x-api-key: {API KEY}' \
     -H 'Content-Type: multipart/form-data' \
     -F 'file=@{Product List File};type=application/json' \
     -F 'url=' \
     -F 'callback_url=' \
     -F 'with_classify=false'

API 호출 방식

표 API 호출 방식

메서드 요청 URL
POST {API Endpoint URL}/update/{signature}

Request Elements

표 Request Elements

파라미터 타입 필수 여부 설명
file Bytes 선택* 업데이트 대상이 되는 상품 목록 리스트를 포함하는 파일
- 지원 파일 형식: json
* file 또는 url 중 하나는 반드시 유효한 값을 가져야 함, 둘 다 입력된 경우는 url 우선
url String 선택* 업데이트 대상이 되는 상품 목록 리스트를 포함하는 파일의 URL
* file 또는 url 중 하나는 반드시 유효한 값을 가져야 함, 둘 다 입력된 경우는 url 우선
callback_url String 선택 결과를 callback 함수로 받고자 하는 경우, 결과를 받기 위한 URL
- ex. Webhook URL
with_classify Bool 선택 속성 인식 결과 포함 여부
- false(기본값): 속성 인식 결과 미포함
- true: 속성 인식 결과 포함

Update file

예제 코드 Update File Syntax 

[
  {
    "product_id":"{product ID}",
    "image_url":"{Image URL}",
    "meta":{
      "title1":"{Product Title}",
      "title2":"{Product Title}"
    }
  },
  {
    "product_id":"{product ID}",
    "image_url":"{Image URL}",
    "meta":{
      "title1":"{Product Title}",
      "title2":"{Product Title}"
    }
  },
  {
    "product_id":"{product ID}",
    "image_url":"{Image URL}",
    "meta":{
      "title1":"{Product Title}",
      "title2":"{Product Title}"
    }
  },
  {
    "product_id":"{product ID}",
    "image_url":"{Image URL}",
    "meta":{
      "title1":"{Product Title}",
      "title2":"{Product Title}"
    }
  }
]

Update file Elements

표 Update file Elements

필드 타입 필수 여부 설명
- Array 필수  
product_id String 필수 쇼핑몰 데이터베이스 내 고유 상품 ID
image_url String 필수 쇼핑몰 데이터베이스 내 이미지 URL
meta Array 선택 쇼핑몰 데이터베이스 내 상품과 관련된 메타 정보
- search_by_image 또는 search_by_id의 with_meta 옵션이 true인 경우 해당 값이 리턴 됨

Response

이미지 디코딩이나 다운로드의 실패 등의 사유로 색인 업데이트 요청 건수(num_add_item)와 실제 색인에 성공한 아이템 수 (num_success_items) 간에는 차이가 있을 수 있습니다. 과금은 num_success_items를 기준으로 부과됩니다.

Response Syntax

예제 코드 /update Response Syntax 

{
  "status": "ready",
  "start_time": "2022-10-13T23:43:36.152106 KST",
  "finish_time": "2022-10-13T23:43:36.152106 KST",
  "num_total_items": 0,
  "num_add_items": 0,
  "num_delete_items": 0,
  "num_fail_items": 0,
  "num_indexing_items": 0,
  "num_success_items": 0,
  "callback_url": null,
  "version": "v1.0.1",
  "updated": "2022-10-13T23:43:36.248695 KST"
}

Response Elements

표 Response Elementds

필드 타입 설명
version String 버전
- 형식: v{MAJOR}.{MINOR}.{PATCH}
- ex. v1.0.1
status String update 상태
- 상태 변경: ready → indexing → complete
- error 발생 시: fail (헬프데스크를 통해 문의)
start_time String 요청받은 시간 (KST)
finish_time String 요청 건 처리 완료 시간 (KST)
num_total_item Int 요청받은 아이템 수
num_add_item Int 추가 희망 아이템 수
- 이미지 디코딩, 다운로드 실패 등의 사유로 실제 색인된 아이템 수와 다를 수 있음
num_delete_items Int 삭제 대상 아이템 수
num_fail_items Int 처리 실패한 아이템 수
num_indexing_items Int 색인 되는 전체 아이템 수
num_success_items Int num_add_items의 대상 중 색인에 성공한 아이템 수
- 미터링 카운트 기준
callback_url String 요청받은 콜백 URL
updated String 상태 변경이 일어난 시간 (KST)

안내
status가 fail로 확인되는 경우 헬프데스크에 기술 문의 유형으로 문의를 작성하시기 바랍니다.

/status

/update로 색인 업데이트를 요청한 경우 상태를 확인합니다.

안내
색인 업데이트 요청 상태 조회(/status) 기능은 무료로 사용할 수 있습니다.

Request

Request Syntax

예제 코드 /status Request Syntax 

curl -X GET '{API Endpoint URL}/status/{signature}' \
     -H 'x-api-key: {API KEY}'

API 호출 방식

표 API 호출 방식

메서드 요청 URL
GET {API Endpoint URL}/status/{signature}

Response

/update와 동일합니다.

Status Code

표 Status Code

응답 코드 응답 내용 설명
400 BAD_REQUEST 요청 Method가 표준이 아닐 경우
400 EXPIRED_REQUEST_ID 잘못되었거나, 기간이 만료된 request ID로 요청한 경우
- request ID는 90일 간 유지
400 INVALID_PARAMETER_VALUE 잘못된 파라미터 타입 혹은 값을 사용하여 호출한 경우
400 INVALID_SIGNATURE 요청 Endpoint 주소의 signature가 잘못된 경우
400 UNKNOWN_DOMAIN_ID 설정된 색인 서버가 존재하지 않는 경우
- 헬프 데스크를 통해 요청
400 INVALID_IMAGE_URL 잘못된 Image URL인 경우
400 INVALID_CALLBACK_URL 잘못된 Callback URL 인 경우
400 INVALID_JSON_FILE 잘못된 JSON 파일을 사용하는 경우
401 Authentication failed x-api-key 값이 잘못된 경우
403 Forbidden x-api-key 헤더가 없는 경우
404 NOT_FOUND - API가 지원하지 않는 Method로 요청한 경우
- API Endpoint URL이 올바르지 않은 경우
405 Method Not Allowed 카카오 i 클라우드가 지원하지 않는 Method로 요청한 경우
413 Request Entity Too Large 요청의 크기가 8MB 이상인 경우
413 IMAGE_SIZE_ERROR 아래의 케이스와 같이, 비정상 이미지 크기로 요청한 경우
   1. 이미지의 단축이 32픽셀 미만
   2. 이미지 장축이 4000 초과 (이미지 바이너리 업로드에만 해당)
   3. 이미지 단축/이미지 장축의 비율이 0.3 미만
415 UNSUPPORTED_CONTENT_TYPE - multipart/form-data가 아닌 다른 타입으로 요청한 경우
- 헤더에 Content-Type이 누락된 경우 등
415 UNSUPPORTED_IMAGE_FORMAT 이미지 디코딩에 실패한 경우
425 DOMAIN_NOT_FOUND 요청한 도메인이 이미 삭제되어 없는 경우
425 DOMAIN_NOT_DEPLOYED 요청한 도메인이 아직 배포되지 않은 경우
429 Too many Requests 한도를 초과하여 요청한 경우
503 INTERNAL_SERVER_ERROR 내부 동작 중 에러가 발생한 경우