Camera Search API 가이드

개요

Camera Search API는 고객이 요청한 이미지를 기준으로 유사한 상품을 추천하여 전달합니다.

Endpoint

현재 지원되고 있는 Lens API Version은 두가지가 있습니다

Version 1.1:

https://api.omnious.com/lens/v1.1/searchapi.omnious.com

Version 1.2: 신규로 Lens를 사용하시는 경우 해당 Version 사용하시는 것을 추천드립니다

https://api.omnious.com/lens/v1.2/searchapi.omnious.com

POST /

요청 형식

Header

Name	Description
Content-Type	application/json
x-api-key	{omnious 로 부터 발급 받은 API Key} [Required]

Body

Name	Type	Required	Description
image	object	O	요청할 이미지에 대한 타입과 해당 타입의 정보를 가지는 객체
image.type	String	O	요청 이미지에 대한 타입 (url 또는 base64)
image.content	String	O	요청 이미지의 타입별 정보 url 타입 : 요청 이미지의 URL 정보 base64 타입 : 요청 이미지의 base 64로 인코딩한 스트링 base64 호출 시 prefix 필요. 내용은 차트 아래 호출 방법 참조
limit	Integer	X	(Optional) 검색할 항목의 최대 수량 기본값: 10 최대값: 100
weightColorFeature	String	X	(Optional) 검색에 색상을 얼마나 반영할지 여부 기본값: MEDIUM 다음 값 중에서 선택가능 LOW MEDIUM HIGH
showContext	Bool	X	(Optional) Context 정보를 표시할지 여부 기본값: false
showImageInfo	Bool	X	(Optional) Image 정보를 표시할지 여부 기본값: false

image.type `base64` format에 대해

• base64 사용 시 "data:image/{image ext};base64," prefix가 있어야 합니다.

base64 python code 예시

encoded = base64.b64encode(image_data).decode('ascii')
img2str'data:image/png;base64,{}'.format(encoded)

요청 Example

Example1. Base64 Image로 검색 (최소한의 Field 만 요청)

{
  "image": {
    "type": "base64",
    "content": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQYV2Poi5b8DwAEfwICWoNPegAAAABJRU5ErkJggg=="
  }
}

Example2. Image URL 로 검색 (최소한의 Field 만 요청)

{
  "image": {
    "type": "url",
    "content": "http://imageserver.net/some/image.jpeg"
  }
}

Example3. Base64 Image로 검색 (Context 정보, Image 정보와 함께 요청)

{
  "image": {
    "type": "base64",
    "content": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVQYV2Poi5b8DwAEfwICWoNPegAAAABJRU5ErkJggg=="
  },
  "limit": 10,
  "weightColorFeature": "MEDIUM",
  "showContext": true,
  "showImageInfo": true
}

응답형식

검색된 상품을 유사도 순으로 반환합니다.

HTTP Status Code

Code	Description
403	API KEY 인증과 관련된 오류
400	입력 값 Validation 진행중 발생한 오류
200	성공적으로 추천 결과를 리턴하였지만 추천된 상품 정보가 없는 경우
201	성공적으로 추천 결과를 리턴하였고 추천된 상품 정보가 있는 경우
500	서버 오류

Response Body

Name	Type	Description
status	String	성공인 경우 "ok"
error	Object	Error가 없는 경우 null 반환. Error가 있는 경우 아래와 같은 형식으로 반환 error.code: 오류코드 에 정의된 오류코드 error.message: 오류 Message
data	Object	아래의 Response Data 항목 참조

Response Data

Name	Type	Description
image	Object	입력한 Image 정보를 반환
image.type	String	입력한 Image의 Type (base64 또는 url)
image.content	String	입력한 Image 정보 type=url인 경우: image url type=base64인 경우: null
limit	Int	추천할 항목의 최대 수량
weightColorFeature	String	추천에 색상을 얼마나 반영할지 여부 [LOW
showContext	Bool	Context 정보를 표시할지 여부
showImageInfo	Bool	Image 정보를 표시할지 여부
detection	Array	(Reserved) 현재는 무조건 null 반환
results	Array of Object	인식된 상품 별 검색 결과

Response Data > Results

Name	Type	Description
id	String	인식된 상품을 나타내는 ID. 순서대로 부여됨
category	String	인식된 상품의 카테고리 정보
bbox	Array[4]	인식된 상품의 영역 정보. 0~1 사이의 값을 가지며 순서대로 아래와 같음. [top, left, width, height]
recommendation	Array of Object	아래의 Recommendation 항목 참조

인식된 상품의 카테고리 정보

ield	Description
SHOES	신발
BAGS	가방
HATS	모자
GLASSES	안경, 선글라스류
BELTS	벨트
WATCHES	손목시계
TOPS	상의 (블라우스, 셔츠, 니트웨어 등)
OUTWEARS	코트, 자켓, 점퍼, 패딩 등
SKIRTS	스커트
PANTS	바지류
WHOLEBODIES	드레스, 점프슈트 등
JEWELRIES	쥬얼리 (반지, 목걸이 등)
ACCESSORIES	악세서리

Response Data > Results > Recommendation

Name	Type	Description
id	String	추천할 상품 code
url	String	추천할 상품 정보 url
context	Object	Data Management API 에서 입력했던 context 정보
imageInfo	Object	Data Management API 에서 입력했던 image 정보 (Detection 정보, Image URL) showImageInfo 가 false 인 경우 null
imageInfo.detection	String	해당 상품의 Detection 정보
imageInfo.content	String	분석에 사용된 상품 Image의 url

응답 Example

Example1. Image URL만 입력으로 하여 검색한 결과

• context, imageInfo 미포함

• limit은 기본값 (10) 으로 설정

{
  "data": {
    "image": {
      "type": "url",
      "content": "http://imageserver.com/query/image.jpg"
    },
    "limit": 10,
    "detection": null,
    "weightColorFeature": "MEDIUM",
    "showContext": null,
    "showImageInfo": null,
    "results": [
      {
        "id": "0",
        "category": "TOPS",
        "bbox": [
          0.21605325,
          0.2837942,
          0.50699013,
          0.75328624
        ],
        "recommendation": [
          {
            "id": "MYzlj9KPsyQBtchdmIUa",
            "url": "http://shop.net/product/MYzlj9KPsyQBtchdmIUa",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "MwTO7mcvtNgpAD32n0yq",
            "url": "http://shop.net/product/MwTO7mcvtNgpAD32n0yq",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "YqTfcdOGZi90aP7Rk3oL",
            "url": "http://shop.net/product/YqTfcdOGZi90aP7Rk3oL",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "BatjlcFOLvoz4q81Dhpm",
            "url": "http://shop.net/product/BatjlcFOLvoz4q81Dhpm",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "w3lmJryV0nF8NSQxivBU",
            "url": "http://shop.net/product/w3lmJryV0nF8NSQxivBU",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "hQM0yBHtA3LNFczsVCub",
            "url": "http://shop.net/product/hQM0yBHtA3LNFczsVCub",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "bzKYuEjSMe94WDxXoT1I",
            "url": "http://shop.net/product/bzKYuEjSMe94WDxXoT1I",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "xsoGLOj9HZUfrdlzpiCw",
            "url": "http://shop.net/product/xsoGLOj9HZUfrdlzpiCw",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "fzZTe8qG4PbprYksw7uv",
            "url": "http://shop.net/product/fzZTe8qG4PbprYksw7uv",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "VoTsF4iyvdPZaQK87nJl",
            "url": "http://shop.net/product/VoTsF4iyvdPZaQK87nJl",
            "context": null,
            "imageInfo": null
          }
        ]
      },
      {
        "id": "1",
        "category": "HATS",
        "bbox": [
          0.0036665350000000003,
          0.24149363000000001,
          0.42002466,
          0.35420066
        ],
        "recommendation": [
          {
            "id": "TF4q0gXPejJnMi1vWGyR",
            "url": "http://shop.net/product/TF4q0gXPejJnMi1vWGyR",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "nk6LVh5aDq8tCN2BxcFu",
            "url": "http://shop.net/product/nk6LVh5aDq8tCN2BxcFu",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "OB3pmA7xuzyrWktFUjML",
            "url": "http://shop.net/product/OB3pmA7xuzyrWktFUjML",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "VQJcPAFB2asZODr9qyx8",
            "url": "http://shop.net/product/VQJcPAFB2asZODr9qyx8",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "jQ0nX5dIZsTAKikWv7zL",
            "url": "http://shop.net/product/jQ0nX5dIZsTAKikWv7zL",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "4ZlM2HQ3YDo7cBUAbd5W",
            "url": "http://shop.net/product/4ZlM2HQ3YDo7cBUAbd5W",
            "context": null,
            "imageInfo": null
          }
        ]
      }
    ]
  },
  "error": null,
  "status": "ok"
}

Example2. Base64 형식의 Image 를 입력으로 검색한 결과

• context, imageInfo 미포함

• limit은 기본값 (10) 으로 설정

{
  "data": {
    "image": {
      "type": "base64",
      "content": null
    },
    "limit": 10,
    "detection": null,
    "weightColorFeature": "MEDIUM",
    "showContext": null,
    "showImageInfo": null,
    "results": [
      {
        "id": "0",
        "category": "TOPS",
        "bbox": [
          0.21605325,
          0.2837942,
          0.50699013,
          0.75328624
        ],
        "recommendation": [
          {
            "id": "MYzlj9KPsyQBtchdmIUa",
            "url": "http://shop.net/product/MYzlj9KPsyQBtchdmIUa",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "MwTO7mcvtNgpAD32n0yq",
            "url": "http://shop.net/product/MwTO7mcvtNgpAD32n0yq",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "YqTfcdOGZi90aP7Rk3oL",
            "url": "http://shop.net/product/YqTfcdOGZi90aP7Rk3oL",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "BatjlcFOLvoz4q81Dhpm",
            "url": "http://shop.net/product/BatjlcFOLvoz4q81Dhpm",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "w3lmJryV0nF8NSQxivBU",
            "url": "http://shop.net/product/w3lmJryV0nF8NSQxivBU",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "hQM0yBHtA3LNFczsVCub",
            "url": "http://shop.net/product/hQM0yBHtA3LNFczsVCub",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "bzKYuEjSMe94WDxXoT1I",
            "url": "http://shop.net/product/bzKYuEjSMe94WDxXoT1I",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "xsoGLOj9HZUfrdlzpiCw",
            "url": "http://shop.net/product/xsoGLOj9HZUfrdlzpiCw",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "fzZTe8qG4PbprYksw7uv",
            "url": "http://shop.net/product/fzZTe8qG4PbprYksw7uv",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "VoTsF4iyvdPZaQK87nJl",
            "url": "http://shop.net/product/VoTsF4iyvdPZaQK87nJl",
            "context": null,
            "imageInfo": null
          }
        ]
      },
      {
        "id": "1",
        "category": "HATS",
        "bbox": [
          0.0036665350000000003,
          0.24149363000000001,
          0.42002466,
          0.35420066
        ],
        "recommendation": [
          {
            "id": "TF4q0gXPejJnMi1vWGyR",
            "url": "http://shop.net/product/TF4q0gXPejJnMi1vWGyR",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "nk6LVh5aDq8tCN2BxcFu",
            "url": "http://shop.net/product/nk6LVh5aDq8tCN2BxcFu",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "OB3pmA7xuzyrWktFUjML",
            "url": "http://shop.net/product/OB3pmA7xuzyrWktFUjML",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "VQJcPAFB2asZODr9qyx8",
            "url": "http://shop.net/product/VQJcPAFB2asZODr9qyx8",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "jQ0nX5dIZsTAKikWv7zL",
            "url": "http://shop.net/product/jQ0nX5dIZsTAKikWv7zL",
            "context": null,
            "imageInfo": null
          },
          {
            "id": "4ZlM2HQ3YDo7cBUAbd5W",
            "url": "http://shop.net/product/4ZlM2HQ3YDo7cBUAbd5W",
            "context": null,
            "imageInfo": null
          }
        ]
      }
    ]
  },
  "error": null,
  "status": "ok"
}