기본 API 가이드

기본 API 는 이미지를 하나씩 요청하는 방식입니다. 요청에 대한 응답으로 태깅 결과를 즉시 받을 수 있습니다. 상품 등록에 대해서 빠르게 반영하고자 하는 경우 기본 API 를 사용하시면 됩니다. (SYNCHRONOUS 방식)

기본정보

TAGGER API의 요청 URI 및 요청에 필요한 헤더 정보는 다음과 같습니다.

메서드	요청 URI	필요 헤더
POST	https://api.omnious.com/tagger/v2.12/tags	x-api-key : 인증을 위한 API Key [Required] accept-language : 언어 선택 en : English (Default) ko: Korean zh: Chinese ja: Japanese

요청

[HTTP Request Header]

POST /tagger/v2/tags HTTP/1.1 Host : api.omnious.com Content-Type: application/json x-api-key : {omnious로부터 발급받은 API Key} accept-language : {언어 선택}

[HTTP Request Body]

필드 이름	데이터 타입	설명	필수
image	object	요청할 이미지에 대한 타입과 해당 타입의 정보를 가지는 객체	O
image.type	string	요청 이미지에 대한 타입 (url 또는 base64)	O
image.content	string	요청 이미지의 타입별 정보 url 타입 : 요청 이미지의 URL 정보 base64 타입 : 요청 이미지의 base 64로 인코딩한 스트링 base64 호출 시 prefix 필요. 내용은 차트 아래 호출 방법 참조	O
context	object	추가적인 정보를 가지는 객체	X
context.id	string	고객사에서 관리하는 상품에 대한 ID	X
context.detection	string array	value : TOP, BOTTOM, WHOLEBODY, SWIMWEAR, SHOES, BAG, HAT, JEWELRY, ACCESSORY 의류 만 태깅을 원할 때 (default) detection: 정의하지 않음. 의류의 경우 TOP, BOTTOM, WHOLEBODY, SWIMWEAR 로 detection이 세분화 되어 있음. 따라서 의류만 태깅하고자 할 경우, 위 전체 세분화 되어 있는 부분을 모두 입력하는 번거로움 없이 정의하지 않으면 default 사항으로 인지하여 의류만 태깅하여 전달함. 잡화만 태깅을 원할 때 detection : ["ACCESSORY"] 잡화는 일정 기간 동안 Beta 서비스로 제공 주얼리만 태깅을 원할 때 detection: [“JEWELRY”] 주얼리는 일정 기간 동안 Beta 서비스로 제공 모자 만 태깅을 원할 때 detection :["HAT"] 모자는 일정 기간 동안 Beta 서비스로 제공 가방 만 태깅을 원할 때 detection:["BAG"] 신발 만 태깅을 원할 때 detection:["SHOES"] 의류의 치마와 바지 종류만 태깅을 원할 때 detection: ["BOTTOM"] 의류 전체와 신발을 태깅하기 원할 detection: ["TOP", "BOTTOM", "WHOLEBODY", "SWIMWEAR", "SHOES"] 의류 상의와 신발을 태깅하기 원할 detection: ["TOP", "SHOES"] 모든 상품 (의류 전체와 모자, 가방, 신발)을 태깅하기 원할 detection: ["TOP", "BOTTOM", "WHOLEBODY", "SWIMWEAR", "SHOES", "HAT", "BAG", "JEWELRY", "ACCESSORY"]	X
context.gender	string	상품에 대한 gender 정보 예시) 남성, 여성, 유니섹스	X
context.brand	string	상품의 브랜드 명	X
context.currency	string	통화 단위 (KRW) 예시) KRW 또는 USD	X
context.price	string	상품에 대한 가격	X
context.age	string	상품에 대한 주 구매 고객사의 연령대 예시) 10대, 20대초, 20대중후, 30대초, 30대중후, 40대, 50대이상	X
context.keywords	string	상품에 대한 키워드 예시) 여름 원피스, 원피스	X
context.productContentName	string	요청 이미지의 상품명	X
context.season	string	상품의 시즌 정보 예시) 19SS, 19FW, 20SS, 20FW	X

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)

요청 예

{
  "image": {
    "type": "url",
    "content": "분석할 이미지의 URL"
  },
  "context": {
    "id": "A111",
    "detection": [
      "TOP",
      "BOTTOM",
      "WHOLEBODY",
      "SWIMWEAR",
      "SHOES",
      "BAG",
      "HAT",
      "JEWELRY"
    ],
    "gender": "남",
    "brand": "NIKE",
    "currency": "KRW",
    "price": 30000,
    "age": "20대초",
    "keywords": "블링블링, 테스트",
    "productContentName": "원피스",
    "season": "19SS"
  }
}

응답

Tagger API의 분석한 결과를 JSON 형식의 데이터로 반환합니다. JSON 응답의 각 필드에 대한 설명은 다음과 같습니다.

필드 이름	데이터 타입	설명
status	string	입력된 이미지의 분석에 대한 성공 실패 여부
data	object	입력된 이미지의 분석 결과를 가지는 객체
data.imageinfo[]	object array	입력된 이미지에 대한 정보를 가진 객체 배열
data.imageinfo[].id	string	이미지 정보의 아이디
data.imageinfo[].name	string	이미지 정보 내용
data.genderInfo	object	요청 이미지에 모델이 있는 경우 젠더 정보를 가지는 객체
data.genderInfo.id	string	젠더 정보의 고유 아이디 (예:T0001)
data.genderInfo.name	string	젠더 정보 내용 : “male”, “female”, “unknown”. male : 이미지 내에 모든 모델이 남성인 경우 female : 이미지 내에 모든 모델이 여성인 경우 unknown : 이미지 내에 여성 / 남성 모델이 함께 있는 경우, 이미지 내의 모델 성별을 알 수 없는 경우, 모델 인식이 안된 경우
data.objects[]	object array	입력된 이미지의 detected 된 수만큼 속성 정보를 가지고 있는 객체 배열
data.objects[].type	string	“CLOTHING”, “SHOES”, "BAGS", "HATS", "JEWELRIES", "ACCESSORIES", "no detected product" 중 하나로 정의
data.objects[].tags[]	object array	하나의 이미지에서 detected 된 count 를 의미하는 객체 배열 해당하는 type 별로 검출된 bounding box의 수에 따라 아래 형식의 data가 나옴 해당하는 값이 없으면 비어 있는 array
data.objects[].tags[].info[]	object array	product에 대한 정보
data.objects[].tags[].info[].id	string	product에 대한 정보의 고유 ID
data.objects[].tags[].info[].name	string	product에 대한 정보의 고유 name (예: product-folded)
data.objects[].tags[].category	object	카테고리 항목의 정보를 가지는 객체
data.objects[].tags[].category.id	string	카테고리 항목의 ID (예:T0001)
data.objects[].tags[].category.name	string	카테고리 항목의 이름 (예 :dress)
data.objects[].tags[].position	object	bounding box의 중심 좌표 정보를 가지는 객체
data.objects[].tags[].position.x	number	bounding box의 중심 x 좌표 (이미지 크기의 비율로 표기)
data.objects[].tags[].position.y	number	bounding box의 중심 y 좌표 (이미지 크기의 비율로 표기)
data.objects[].tags[].pairIndex	number	data.objects[].type이 "SHOES"인 경우에 제공 동일 상품 여부를 나타내는 index (신발에만 제공) 한 이미지 안에 여러 신발이 존재하는 경우, 각 신발은 0 ~ 100 사이의 “pairIndex”를 제공 합니다. Tagger가 동일 신발로 인지한 경우, 같은 “pairIndex” 값을 가집니다.
data.objects[].tags[].colors[]	object array	컬러 정보를 가지는 객체 배열 현재 제공하는 18 색상을 모델의 결과로 전달 top1, top2, top3의 모델 결과 전달
data.objects[].tags[].colors[].id	string	컬러의 고유 ID
data.objects[].tags[].colors[].name	string	컬러 이름
data.objects[].tags[].colors[].confidence	number	모델이 예측한 컬러에 대한 confidence 값 1에 가까울수록 높은 확신을 나타냅니다.
data.objects[].tags[].colorDetails[]	object array	세부컬러 정보를 가지는 객체 배열 2,000여 가지 이상의 palette 색상을 전
data.objects[].tags[].colorDetails[].code	string	세부컬러 헥사 코드 (RGB)
data.objects[].tags[].colorDetails[].name	string	세부컬러 이름
data.objects[].tags[].colorDetails[].pixelFraction	number	세부컬러의 pixelFraction
data.objects[].tags[].item	object	item 정보를 가지는 객체
data.objects[].tags[].item.id	string	item 의 고유 ID
data.objects[].tags[].item.name	string	item 의 이름
data.objects[].tags[].item.confidence	number	모델이 예측한 item에 대한 confidence 값 1에 가까울수록 높은 확신을 나타냅니다.
data.objects[].tags[].details[]	object array	detail 정보를 가지는 객체 배열
data.objects[].tags[].details[].id	string	detail의 고유 ID
data.objects[].tags[].details[].name	string	detail의 이름
data.objects[].tags[].details[].confidence	number	모델이 예측한 detail에 대한 confidence 값 1에 가까울수록 높은 확신을 나타냅니다.
data.objects[].tags[].prints[]	object array	print 정보를 가지는 객체 배열
data.objects[].tags[].prints[].id	string	print의 고유 ID
data.objects[].tags[].prints[].name	string	print의 이름
data.objects[].tags[].prints[].confidence	number	모델이 예측한 print에 대한 confidence 값 1에 가까울수록 높은 확신을 나타냅니다.
data.objects[].tags[].textures[]	object array	texture 정보를 가지는 객체 배열
data.objects[].tags[].textures[].id	string	texture의 고유 ID
data.objects[].tags[].textures[].name	string	texture의 이름
data.objects[].tags[].textures[].confidence	number	모델이 예측한 texture에 대한 confidence 값 1에 가까울수록 높은 확신을 나타냅니다.
data.objects[].tags[].looks[]	object array	look 정보를 가지는 객체 배열
data.objects[].tags[].looks[].id	string	look의 고유 ID
data.objects[].tags[].looks[].name	string	look의 이름
data.objects[].tags[].looks[].confidence	number	모델이 예측한 look에 대한 confidence 값 1에 가까울수록 높은 확신을 나타냅니다.
data.objects[].tags[].length	object	length 정보를 가지는 객체
data.objects[].tags[].length.id	string	length의 고유 ID
data.objects[].tags[].length.name	string	length의 이름
data.objects[].tags[].length.confidence	number	모델이 예측한 length에 대한 confidence 값 1에 가까울수록 높은 확신을 나타냅니다.
data.objects[].tags[].sleeveLength	object	sleeve length의 정보를 가지는 객체
data.objects[].tags[].sleeveLength.id	string	sleeve length의 고유 ID
data.objects[].tags[].sleeveLength.name	string	sleeve length의 이름
data.objects[].tags[].neckLine	object	neckline 정보를 가지는 객체
data.objects[].tags[].neckLine.id	string	neck line의 고유 ID
data.objects[].tags[].neckLine.name	string	neck line의 이름
data.objects[].tags[].neckLine.confidence	number	모델이 예측한 neck line에 대한 confidence 값 1에 가까울수록 높은 확신을 나타냅니다.
data.objects[].tags[].fit	object	fit 정보를 가지는 객체
data.objects[].tags[].fit.id	string	fit의 고유 ID
data.objects[].tags[].fit.name	string	fit의 이름
data.objects[].tags[].fit.confidence	number	모델이 예측한 fit에 대한 confidence 값 1에 가까울수록 높은 확신을 나타냅니다.
data.objects[].tags[].shape	object	shape 정보를 가지는 객체
data.objects[].tags[].shape.id	string	shape의 고유 ID
data.objects[].tags[].shape.name	string	shape의 이름
data.objects[].tags[].shape.confidence	number	모델이 예측한 shape에 대한 confidence 값 1에 가까울수록 높은 확신을 나타냅니다.
data.objects[].tags[].heelHeight	object	shoes의 heelheight 정보를 가지는 객체
data.objects[].tags[].heelHeight.id	string	shoes의 heelheight의 고유 ID
data.objects[].tags[].heelHeight.name	string	shoes의 heelheight의 이름
data.objects[].tags[].heelHeight.confidence	number	모델이 예측한 shoes의 heelheight 에 대한 confidence 값 1에 가까울 수록 높은 확신을 나타냅니다.
data.objects[].tags[].toeType	object	shoes의 toetype 정보를 가지는 객체
data.objects[].tags[].toeType.id	string	shoes의 toetype의 고유 ID
data.objects[].tags[].toeType.name	string	shoes의 toetype의 이름
data.objects[].tags[].toeType.confidence	number	모델이 예측한 shoes의 toetype 에 대한 confidence 값 1에 가까울 수록 높은 확신을 나타냅 니다.
data.objects[].tags[].heelShape	object	shoes의 heelshape 정보를 가지는 객체
data.objects[].tags[].heelShape.id	string	shoes의 heelShape 의 고유 ID
data.objects[].tags[].heelShape.name	string	shoes의 heelShape의 이름
data.objects[].tags[].heelShape.confidence	number	모델이 예측한 shoes의 heelShape 에 대한 confidence 값 1에 가까울 수록 높은 확신을 나타냅 니다.
data.objects[].tags[].soleType	object	shoes의 soletype 정보를 가지는 객체
data.objects[].tags[].soleType.id	string	shoes의 soleType 의 고유 ID
data.objects[].tags[].soleType.name	string	shoes의 soleType의 이름
data.objects[].tags[].soleType.confidence	number	모델이 예측한 shoes의 soleType에 대한 confidence 값 1에 가까울 수록 높은 확신을 나타냅 니다.
data.objects[].tags[].mainMaterials[]	object array	main material 정보를 가지는 객체 배열
data.objects[].tags[].mainMaterials[].id	string	main material 항목의 ID (예:T0001)
data.objects[].tags[].mainMaterials[].name	string	main material 항목의 이름 (예 : beads)
data.objects[].tags[].mainMaterials[].confidence	number	모델이 예측한 main material 에 대한 confidence 값. 1에 가까울수록 높은 확신을 나타냅니다.
data.objects[].tags[].subMaterials[]	object array	sub material 정보를 가지는 객체 배열
data.objects[].tags[].subMaterials[].id	string	sub material 항목의 ID (예:T0001)
data.objects[].tags[].subMaterials[].name	string	sub material 항목의 이름 (예 : beads)
data.objects[].tags[].subMaterials[].confidence	number	모델이 예측한 sub material 에 대한 confidence 값. 1에 가까울수록 높은 확신을 나타냅니다.
data.notmatchedobjects[]	object array	context.detection 을 TOP, BOTTOM, WHOLEBODY, SWIMWEAR 로 요청한 경우, 요청과 다른 아이템의 정보를 가지고 있는 객체 배열. 고객의 요청과는 다르나 추가로 “인식되어진 상품”의 태깅 정보를 전달.
error	object	에러가 있는 경우 정보를 가지는 객체
error.code	number	(에러가 난 경우에 한해) 오류 코드
error.message	string	(에러가 난 경우에 한해) 오류 메시지

응답 예

입력 이미지에서 패션 이미지에 대해 분석한 경우

{
  "data": {
    "imageInfo": [
      {
        "id": "T0449",
        "name": "nonFashion"
      }
    ],
    "genderInfo": {
      "id": "T0418",
      "name": "male"
    },
    "objects": [
      {
        "type": "CLOTHING",
        "tags": [
          {
            "category": {
              "id": "T0363",
              "name": "shirts"
            },
            "position": {
              "x": 0.5033992828,
              "y": 0.5039257706
            },
            "info": {
              "id": "T1740",
              "name": "product-folded"
            },
            "item": {
              "id": "T0273",
              "name": "y-shirts",
              "confidence": 0.7787289023
            },
            "colors": [
              {
                "id": "T0326",
                "name": "beige",
                "confidence": 0.8287289023
              }
            ],
            "colorDetails": [
              {
                "code": "#e5ccaf",
                "name": "gray-sand",
                "pixelFraction": 1.0
              }
            ],
            "prints": [
              {
                "id": "T0198",
                "name": "solid",
                "confidence": 0.9973957539
              }
            ],
            "looks": [
              {
                "id": "T0141",
                "name": "casual",
                "confidence": 0.8063992262
              }
            ],
            "textures": [
              {
                "id": "T0220",
                "name": "synthetic/polyester",
                "confidence": 0.659104526
              }
            ],
            "details": [
              {
                "id": "T0097",
                "name": "buttoned",
                "confidence": 0.89336586
              }
            ],
            "length": {
              "id": "T0468",
              "name": "half",
              "confidence": 0.5978361964
            },
            "sleeveLength": {
              "id": "T0082",
              "name": "long-sleeve",
              "confidence": 0.9963954091
            },
            "neckLine": {
              "id": "T0342",
              "name": "hood",
              "confidence": 0.6770937443
            },
            "fit": {
              "id": "T0480",
              "name": "skinny",
              "confidence": 0.5594306588
            },
            "shape": {
              "id": "T0493",
              "name": "tapered",
              "confidence": 0.9758504033
            }
          }
        ]
      },
      {
        "type": "SHOES",
        "tags": [
          {
            "category": {
              "id": "T0495",
              "name": "boots"
            },
            "position": {
              "x": 0.3587198853,
              "y": 0.8293977976
            },
            "item": {
              "id": "T0503",
              "name": "ankle-boots",
              "confidence": 0.3421388268
            },
            "colors": [
              
            ],
            "heelHeight": {
              "id": "T0536",
              "name": "high(7~)",
              "confidence": 0.609870851
            },
            "toeType": {
              "id": "T0537",
              "name": "round-toe",
              "confidence": 0.5348223448
            },
            "heelShape": {
              "id": "T0539",
              "name": "stiletto",
              "confidence": 0.7321234598
            },
            "soleType": {
              "id": "T0542",
              "name": "platform",
              "confidence": 0.6345823217
            }
          }
        ]
      },
      {
        "type": "BAGS",
        "tags": [
          {
            "category": {
              "id": "T0700",
              "name": "가방"
            },
            "position": {
              "x": 0.5,
              "y": 0.5991468
            },
            "item": {
              "id": "T0709",
              "name": "서류가방",
              "confidence": 0.80419564
            },
            "colors": [
              {
                "id": "T0324",
                "name": "블랙",
                "confidence": 0.99993014
              },
              {
                "id": "T0327",
                "name": "브라운",
                "confidence": 0.0000517389
              },
              {
                "id": "T0333",
                "name": "네이비",
                "confidence": 0.0000137481
              }
            ],
            "colorDetail": [
              {
                "code": "#211f20",
                "name": "real-black31",
                "pixelFraction": 1.0
              }
            ],
            "prints": [
              {
                "id": "T0714",
                "name": "무지",
                "confidence": 0.9950991
              }
            ],
            "textures": [
              {
                "id": "T0731",
                "name": "합성섬유",
                "confidence": 0.9647524
              }
            ],
            "details": [
              {
                "id": "T0776",
                "name": "포켓",
                "confidence": 0.89414203
              }
            ]
          }
        ]
      }
    ],
    "notMatchedObject": [
      {
        "type": "CLOTHING",
        "tags": [
          {
            "category": {
              "id": "T0360",
              "name": "jacket"
            },
            "position": {
              "x": 0.5033992828,
              "y": 0.5039257706
            },
            "item": {
              "id": "T0345",
              "name": "balmacaan-jacket",
              "confidence": 0.7787289023
            },
            "colors": [
              {
                "id": "T0326",
                "name": "beige",
                "confidence": 0.8287289023
              }
            ],
            "colorDetails": [
              {
                "code": "#e5ccaf",
                "name": "gray-sand",
                "pixelFraction": 1.0
              }
            ],
            "prints": [
              {
                "id": "T0198",
                "name": "solid",
                "confidence": 0.9973957539
              }
            ],
            "looks": [
              {
                "id": "T0141",
                "name": "casual",
                "confidence": 0.8063992262
              }
            ],
            "textures": [
              {
                "id": "T0220",
                "name": "synthetic/polyester",
                "confidence": 0.659104526
              }
            ],
            "details": [
              {
                "id": "T0097",
                "name": "buttoned",
                "confidence": 0.89336586
              }
            ],
            "length": {
              "id": "T0468",
              "name": "half",
              "confidence": 0.5978361964
            },
            "sleeveLength": {
              "id": "T0082",
              "name": "long-sleeve",
              "confidence": 0.9963954091
            },
            "neckLine": {
              "id": "T0342",
              "name": "hood",
              "confidence": 0.6770937443
            },
            "fit": {
              "id": "T0480",
              "name": "skinny",
              "confidence": 0.5594306588
            },
            "shape": {
              "id": "T0493",
              "name": "tapered",
              "confidence": 0.9758504033
            }
          }
        ]
      },
      {
        "type": "SHOES",
        "tags": [
          {
            "category": {
              "id": "T0495",
              "name": "boots"
            },
            "position": {
              "x": 0.3587198853,
              "y": 0.8293977976
            },
            "item": {
              "id": "T0503",
              "name": "ankle-boots",
              "confidence": 0.3421388268
            },
            "colors": [
              
            ],
            "heelHeight": {
              "id": "T0536",
              "name": "high(7~)",
              "confidence": 0.609870851
            },
            "toeType": {
              "id": "T0537",
              "name": "round-toe",
              "confidence": 0.5348223448
            },
            "heelShape": {
              "id": "T0540",
              "name": "ball",
              "confidence": 0.6543234342
            },
            "soleType": {
              "id": "T0543",
              "name": "chunky-sneaker",
              "confidence": 0.5677854423
            }
          }
        ]
      }
    ]
  },
  "error": null,
  "status": "ok"
}

입력 이미지에서 분석 대상을 찾지 못한 경우

{
    "data": {
        "imageInfo": [],
        "genderInfo": {},
        "objects": [
            {
                "type": "no detected product",
                "tags": []
            }
        ]
    },
    "error": null,
    "status": "ok"
}

에러 발생 경우

{
   "data": {},
   "status": "fail",
   "error": {
       "code": 803,
       "message": "Fail to prove image from url."
   }
}

옴니어스 태거는 의류와 신발, 가(베타)의 모든 속성(item, detail, look, print, texture, length 등)의 예측값에 confidence 값을 함께 제공하고 있습니다 (data.objects[].tags[].*.confidence).

confidence 값은 모델의 예측에 대한 “확신”의 정도를 나타내며 1에 가까울수록 모델의 예측값이 맞을 확률이 큽니다. Tagger 2.7.0 버전에서는 보다 정확한 태그값을 제공하기 위해 아이템 이외의 모든 속성에 대해 모델 예측의 confidence 값이 0.2 이상인 경우 태그값을 제공하고 있습니다.