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 | MEDIUM | HIGH]

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

PreviousRecommendation API 가이드Next오류 정보

Last updated

Was this helpful?