음식 인식 API 호출 가이드

페이지 이동경로

음식 인식 API Reference

카카오 i 클라우드의 음식 인식 API를 활용하면 입력한 이미지에 포함된 음식 종류와 영양 성분 정보 등을 조회할 수 있습니다. 음식 인식 API를 호출할 때 필요한 개발 정보는 다음과 같습니다.

안내
음식 인식률을 높이기 위해서는 권장 사양에 맞는 이미지를 입력해야 합니다.
- 권장 해상도: 800x800(px) 이상
- 이미지당 권장 음식 개수: 50개 이하

Request

Request Syntax

코드 예제 Request Syntax

curl -v -X POST '{API Endpoint URL}' \
 -H 'x-api-key: {API Key}' \
 -H 'Content-Type: multipart/form-data' \
 -F 'image=@{이미지 파일}'

API 호출 방식

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

Request Header

Request Header

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

Request Elements

Request Elements

파라미터 타입 필수여부 설명
image Binary 필수 이미지 파일의 바이너리
- 지원하는 파일 확장자: jpg, jpeg, png
- 1개의 이미지 파일만 적용

예제 이미지 입력 이미지 예시

Response

Response Syntax

코드 예제 Response Syntax

{
  "status": 200,
  "version": "1.0.4",
  "proc_secs": 0.1872,
  "result": [
    {
      "x": 42,
      "y": 63,
      "w": 416,
      "h": 253,
      "class_info": [
        {
          "rank": 1,
          "food_name": "짜장면",
          "prob": 0.9681,
          "food_nutrients": {
            "1회제공량당_영양성분": {
              "1회제공량(g/ml)": "600.0",
              "단위(g/ml)": "g",
              "열량(kcal)": "529.0",
              "탄수화물": {
                "총량(g)": "86.2",
                "당류(g)": "36.4",
                "식이섬유(g)": "8.2"
              },
              "단백질(g)": "16.2",
              "지방": {
                "총량(g)": "13.3",
                "트랜스지방(g)": "0",
                "포화지방(g)": "2.3"
              },
              "콜레스테롤(mg)": "12.28",
              "나트륨(mg)": "1843.68"
            },
            "100g당_영양성분": {
              "열량(kcal)": "88.17",
              "탄수화물": {
                "총량(g)": "14.37",
                "당류(g)": "6.07",
                "식이섬유(g)": "1.37"
              },
              "단백질(g)": "2.7",
              "지방": {
                "총량(g)": "2.22",
                "트랜스지방(g)": "0",
                "포화지방(g)": "0.38"
              },
              "콜레스테롤(mg)": "2.05",
              "나트륨(mg)": "307.28"
            }
          }
        },
        {
          "rank": 2,
          "food_name": "짜장밥",
          "prob": 0.026,
          "food_nutrients": {
            "1회제공량당_영양성분": {
              "1회제공량(g/ml)": "470.0",
              "단위(g/ml)": "g",
              "열량(kcal)": "572.0",
              "탄수화물": {
                "총량(g)": "73.2",
                "당류(g)": "0.2",
                "식이섬유(g)": "9.8"
              },
              "단백질(g)": "20.1",
              "지방": {
                "총량(g)": "22.2",
                "트랜스지방(g)": "0.1",
                "포화지방(g)": "2.7"
              },
              "콜레스테롤(mg)": "27.01",
              "나트륨(mg)": "1109.91"
            },
            "100g당_영양성분": {
              "열량(kcal)": "121.7",
              "탄수화물": {
                "총량(g)": "15.57",
                "당류(g)": "0.04",
                "식이섬유(g)": "2.09"
              },
              "단백질(g)": "4.28",
              "지방": {
                "총량(g)": "4.72",
                "트랜스지방(g)": "0.02",
                "포화지방(g)": "0.57"
              },
              "콜레스테롤(mg)": "5.75",
              "나트륨(mg)": "236.15"
            }
          }
        },
        {
          "rank": 3,
          "food_name": "유니짜장",
          "prob": 0.0031,
          "food_nutrients": {
            "1회제공량당_영양성분": {
              "1회제공량(g/ml)": "360.0",
              "단위(g/ml)": "g",
              "열량(kcal)": "415.0",
              "탄수화물": {
                "총량(g)": "83",
                "당류(g)": "9",
                "식이섬유(g)": "-"
              },
              "단백질(g)": "15",
              "지방": {
                "총량(g)": "2.4",
                "트랜스지방(g)": "-",
                "포화지방(g)": "1.8"
              },
              "콜레스테롤(mg)": "5",
              "나트륨(mg)": "1260"
            },
            "100g당_영양성분": {
              "열량(kcal)": "115.28",
              "탄수화물": {
                "총량(g)": "23.06",
                "당류(g)": "2.5",
                "식이섬유(g)": "-"
              },
              "단백질(g)": "4.17",
              "지방": {
                "총량(g)": "0.67",
                "트랜스지방(g)": "-",
                "포화지방(g)": "0.5"
              },
              "콜레스테롤(mg)": "1.39",
              "나트륨(mg)": "350"
            }
          }
        },
        {
          "rank": 4,
          "food_name": "쟁반짜장",
          "prob": 0.0024,
          "food_nutrients": {
            "1회제공량당_영양성분": {
              "1회제공량(g/ml)": "300.0",
              "단위(g/ml)": "g",
              "열량(kcal)": "494.0",
              "탄수화물": {
                "총량(g)": "81.12",
                "당류(g)": "2.09",
                "식이섬유(g)": "8.7"
              },
              "단백질(g)": "16.05",
              "지방": {
                "총량(g)": "13.91",
                "트랜스지방(g)": "-",
                "포화지방(g)": "3.909"
              },
              "콜레스테롤(mg)": "11",
              "나트륨(mg)": "376"
            },
            "100g당_영양성분": {
              "열량(kcal)": "164.67",
              "탄수화물": {
                "총량(g)": "27.04",
                "당류(g)": "0.7",
                "식이섬유(g)": "2.9"
              },
              "단백질(g)": "5.35",
              "지방": {
                "총량(g)": "4.64",
                "트랜스지방(g)": "-",
                "포화지방(g)": "1.3"
              },
              "콜레스테롤(mg)": "3.67",
              "나트륨(mg)": "125.33"
            }
          }
        },
        {
          "rank": 5,
          "food_name": "메밀국수",
          "prob": 0.0001,
          "food_nutrients": {
            "1회제공량당_영양성분": {
              "1회제공량(g/ml)": "350.0",
              "단위(g/ml)": "g",
              "열량(kcal)": "221.0",
              "탄수화물": {
                "총량(g)": "42.2",
                "당류(g)": "0",
                "식이섬유(g)": "2.8"
              },
              "단백질(g)": "11",
              "지방": {
                "총량(g)": "1",
                "트랜스지방(g)": "0",
                "포화지방(g)": "0.4"
              },
              "콜레스테롤(mg)": "0",
              "나트륨(mg)": "679.36"
            },
            "100g당_영양성분": {
              "열량(kcal)": "63.14",
              "탄수화물": {
                "총량(g)": "12.06",
                "당류(g)": "0",
                "식이섬유(g)": "0.8"
              },
              "단백질(g)": "3.14",
              "지방": {
                "총량(g)": "0.29",
                "트랜스지방(g)": "0",
                "포화지방(g)": "0.11"
              },
              "콜레스테롤(mg)": "0",
              "나트륨(mg)": "194.1"
            }
          }
        }
      ]
    },
    {
      "x": 460,
      "y": 249,
      "w": 174,
      "h": 148,
      "class_info": [
        {
          "rank": 1,
          "food_name": "단무지",
          "prob": 0.9888,
          "food_nutrients": {
            "1회제공량당_영양성분": {
              "1회제공량(g/ml)": "30.0",
              "단위(g/ml)": "g",
              "열량(kcal)": "3.0",
              "탄수화물": {
                "총량(g)": "0.7",
                "당류(g)": "0.1",
                "식이섬유(g)": "0.4"
              },
              "단백질(g)": "0.1",
              "지방": {
                "총량(g)": "0.1",
                "트랜스지방(g)": "0",
                "포화지방(g)": "0"
              },
              "콜레스테롤(mg)": "0",
              "나트륨(mg)": "165.55"
            },
            "100g당_영양성분": {
              "열량(kcal)": "10.0",
              "탄수화물": {
                "총량(g)": "2.33",
                "당류(g)": "0.33",
                "식이섬유(g)": "1.33"
              },
              "단백질(g)": "0.33",
              "지방": {
                "총량(g)": "0.33",
                "트랜스지방(g)": "0",
                "포화지방(g)": "0"
              },
              "콜레스테롤(mg)": "0",
              "나트륨(mg)": "551.83"
            }
          }
        },
        {
          "rank": 2,
          "food_name": "머스타드소스",
          "prob": 0.0009,
          "food_nutrients": {
            "1회제공량당_영양성분": {
              "1회제공량(g/ml)": "40.0",
              "단위(g/ml)": "g",
              "열량(kcal)": "80.0",
              "탄수화물": {
                "총량(g)": "-",
                "당류(g)": "9",
                "식이섬유(g)": "-"
              },
              "단백질(g)": "1",
              "지방": {
                "총량(g)": "-",
                "트랜스지방(g)": "-",
                "포화지방(g)": "1.1"
              },
              "콜레스테롤(mg)": "-",
              "나트륨(mg)": "280"
            },
            "100g당_영양성분": {
              "열량(kcal)": "200.0",
              "탄수화물": {
                "총량(g)": "-",
                "당류(g)": "22.5",
                "식이섬유(g)": "-"
              },
              "단백질(g)": "2.5",
              "지방": {
                "총량(g)": "-",
                "트랜스지방(g)": "-",
                "포화지방(g)": "2.75"
              },
              "콜레스테롤(mg)": "-",
              "나트륨(mg)": "700"
            }
          }
        },
        {
          "rank": 3,
          "food_name": "단무지무침",
          "prob": 0.0007,
          "food_nutrients": {
            "1회제공량당_영양성분": {
              "1회제공량(g/ml)": "50.0",
              "단위(g/ml)": "g",
              "열량(kcal)": "20.0",
              "탄수화물": {
                "총량(g)": "2.8",
                "당류(g)": "0.7",
                "식이섬유(g)": "1.6"
              },
              "단백질(g)": "0.5",
              "지방": {
                "총량(g)": "0.8",
                "트랜스지방(g)": "0",
                "포화지방(g)": "0.1"
              },
              "콜레스테롤(mg)": "0",
              "나트륨(mg)": "428.92"
            },
            "100g당_영양성분": {
              "열량(kcal)": "40.0",
              "탄수화물": {
                "총량(g)": "5.6",
                "당류(g)": "1.4",
                "식이섬유(g)": "3.2"
              },
              "단백질(g)": "1",
              "지방": {
                "총량(g)": "1.6",
                "트랜스지방(g)": "0",
                "포화지방(g)": "0.2"
              },
              "콜레스테롤(mg)": "0",
              "나트륨(mg)": "857.84"
            }
          }
        },
        {
          "rank": 4,
          "food_name": "쌈무(초절임)",
          "prob": 0.0007,
          "food_nutrients": {
            "1회제공량당_영양성분": {
              "1회제공량(g/ml)": "100.0",
              "단위(g/ml)": "g",
              "열량(kcal)": "15.0",
              "탄수화물": {
                "총량(g)": "3.1",
                "당류(g)": "1.48",
                "식이섬유(g)": "2.3"
              },
              "단백질(g)": "0.54",
              "지방": {
                "총량(g)": "0.03",
                "트랜스지방(g)": "0",
                "포화지방(g)": "0.01"
              },
              "콜레스테롤(mg)": "0",
              "나트륨(mg)": "400"
            },
            "100g당_영양성분": {
              "열량(kcal)": "15.0",
              "탄수화물": {
                "총량(g)": "3.1",
                "당류(g)": "1.48",
                "식이섬유(g)": "2.3"
              },
              "단백질(g)": "0.54",
              "지방": {
                "총량(g)": "0.03",
                "트랜스지방(g)": "0",
                "포화지방(g)": "0.01"
              },
              "콜레스테롤(mg)": "0",
              "나트륨(mg)": "400"
            }
          }
        },
        {
          "rank": 5,
          "food_name": "물",
          "prob": 0.0007,
          "food_nutrients": {
            "1회제공량당_영양성분": {
              "1회제공량(g/ml)": "100.0",
              "단위(g/ml)": "ml",
              "열량(kcal)": "0.0",
              "탄수화물": {
                "총량(g)": "0",
                "당류(g)": "0",
                "식이섬유(g)": "0"
              },
              "단백질(g)": "0",
              "지방": {
                "총량(g)": "0",
                "트랜스지방(g)": "0",
                "포화지방(g)": "0"
              },
              "콜레스테롤(mg)": "0",
              "나트륨(mg)": "2"
            },
            "100g당_영양성분": {
              "열량(kcal)": "0.0",
              "탄수화물": {
                "총량(g)": "0",
                "당류(g)": "0",
                "식이섬유(g)": "0"
              },
              "단백질(g)": "0",
              "지방": {
                "총량(g)": "0",
                "트랜스지방(g)": "0",
                "포화지방(g)": "0"
              },
              "콜레스테롤(mg)": "0",
              "나트륨(mg)": "2"
            }
          }
        }
      ]
    }
  ]
}

Response Elements

Response Elements

필드 타입 필수 여부 설명
status String 필수 - 200 : 정상
- 400 : 입력 이미지가 누락되었거나, 타입이 잘못된 경우 (자세한 설명은 “message” 참고)
- 500 : 예상치 못한 내부 오류가 발생한 경우 (자세한 설명은 “message”참고)
version String 필수 API 버전
request_id String 필수 각 요청마다 고유하게 부여되는 UUID
created String 필수 요청 시간 (ISO 8601)
proc_secs Float 필수 이미지 처리와 분류하는데 걸린 총 시간(초)
result ▼ Array 필수 검출된 음식의 위치, 크기와 각각에 대한 음식 분류 결과 및 영양 성분 정보를 포함한 결과
- 검출된 음식이 하나도 없으면 빈 리스트를 반환
   x Float 필수 검출된 박스 좌측의 x 좌표
   y Float 필수 검출된 박스 상단의 y 좌표
   w Float 필수 검출된 박스의 가로 길이(px)
   h Float 필수 검출된 박스의 세로 길이(px)
   class_info ▼ Array 필수 박스의 음식 분류 결과 Top 5의 리스트
- 확률값에 의한 내림 차순으로 정렬됨
     rank Int 필수 인식 결과를 확률값이 높은 순으로 정렬 했을 때의 순위 (1~5)
     food_name String 필수 음식 이름
     prob Float 필수 확률값(0.0 ~ 1.0)
     food_nutrients Dictionary 필수 음식 영양 성분 정보
- 1회 제공량 당 영양성분
- 100g 당 영양성분
- 영양 성분 값이 존재하지 않는 항목은 -로 표기

Status Code

Status Code

응답 코드 응답 내용 설명
200 - API 호출 성공
400 Bad Request 요청 주소가 잘못된 경우
  INVALID_SIGNATURE 요청 Endpoint 주소의 signature가 잘못된 경우
  Image is Required 필수 파라미터(image)가 누락됨
  Unsupported image format 지원하지 않는 타입의 이미지(jpg, jpeg, png 이외의 파일)가 입력됨
  Exceed image size limit 입력 이미지의 크기가 8MB 이상으로, 지원 한도를 초과함
  RatioError 입력 이미지의 장축이 단축보다 3배 이상 김
  ResolutionError 입력 이미지의 가로/세로 길이가 모두 300px 미만
  - API를 HEAD로 호출함
401 Authentication failed x-api-key 헤더가 없거나 값이 잘못된 경우
404 NOT FOUND 지원하지 않는 Method로 요청을 보낸 경우
405 Method Not Allowed 지원하지 않는 Method로 요청을 보낸 경우
413 Request Entity Too Large 요청의 크기가 제한보다 큰 경우
415 Unsupported content type Content Type 헤더가 없거나 규격에 맞지 않는 경우
425 Domain not found 요청한 도메인이 삭제되어 없을 경우
  Domain not deployed 요청한 도메인이 아직 배포되지 않은 경우
429 Too many Requests 설정한 한도를 초과해서 요청한 경우
503 INTERNAL ERROR 예상하지 못한 서버 오류가 발생한 경우

코드 예제 에러 코드 응답

{
    "code": 400,
    "msg": "unsupported content-type. only support 'Content-Type: application/json'",
    "result": {},
    "elapsed_time": "0.000010",
    "version": "1.2.7"
}

API 성능

카카오 i 클라우드 음식 인식 API는 대락 7개의 음식이 포함된 1개의 이미지 파일 요청을 1건이라고 할 때, 초당 7건의 요청(7 TPS)을 처리할 수 있으며, 1건당 평균 처리 시간은 약 0.3초입니다.

API 성능

구분 설명
초당 처리 성능 음식이 7개인 이미지 파일(180Kb, 1280*720px) 기준 초당 7건의 요청(7 TPS)을 처리
평균 처리 시간 0.3초

안내
제시된 음식 인식 API 성능보다 더 높은 성능이 필요한 경우에는 헬프데스크 > 기술문의 또는 상담 및 도입 문의 신청으로 문의하시기 바랍니다.