비전

이미지를 분석해서 콘텐츠 형태와 의미를 이해하고, 이미지를 활용할 수 있게 도와주는 API입니다.

현재 제공되는 API는 다음과 같습니다.

공통사항

API 호출 시 공통적으로 다음과 같은 사항을 준수해야 합니다.

  • 서버에서 호출하는 경우 REST API 키를 사용해 POST로 호출합니다.
  • 모든 API는 file 또는 image_url 중 하나의 값을 지정해야 합니다. 단, 문자 영역 감지 API와 문자 인식 API는 file만 지원합니다.
  • file에 업로드되는 이미지와 image_url에 지정되는 이미지는 png 또는 jpg 포맷만 지원합니다.
  • file을 업로드하는 경우는 Content-Type을 "multipart/form-data"로 요청해야 합니다.
  • image_url로 호출하는 경우는 Content-Type을 "application/x-www-form-urlencoded"로 POST 되어야 합니다.

OCR API의 공통사항

문자 영역 감지 API와 문자 인식 API를 호출 시 공통적으로 다음과 같은 사항을 준수해야 합니다.

  • 업로드 가능한 이미지 최대 용량은 2MB입니다.
  • file에 업로드되는 이미지는 bmp, dib, jpeg, jpg, jpe, jp2, png, webp, pbm, pgm, ppm, sr, ras, tiff, tif 포맷을 지원합니다.
  • 이미지 file 업로드를 위해 Content-Type을 "multipart/form-data"로 요청해야 합니다.

얼굴 검출

얼굴 검출 API는 이미지 내의 얼굴을 찾아내고, 얼굴의 위치, 특징점, 각도, 성별, 나이 등을 추정해서 반환합니다.

얼굴 검출 데모를 바로 확인해 보세요! 데모 보러 가기

[Request]

POST /v1/vision/face/detect HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {rest_app_key}

호출 파라미터에 대한 공통 설명은 공통사항을 참고하세요.

  • 앱키를 헤더에 담아 POST로 요청합니다.
  • file과 image_url 중 하나는 필수로 지정해야 합니다.
  • threshold는 검출된 얼굴이 오검출인지를 판단하기 위해 사용하는 기준값입니다.
  • 0 ~ 1.0 사이의 값이며, 얼굴검출의 기준값이 높으면 일부 인물은 검출하지 못할 수 있습니다.
  • 반대로 기준값이 낮으면 인물이 아닌 영역도 얼굴로 오검출할 수 있습니다.
설명 필수 타입
file 이미지 파일 O Binary
image_url 이미지 URL O String
threshold 얼굴 판정의 기준값. 0 ~ 1.0 사이의 값. 기본값 0.7 X Float

요청 예제

curl -v -X POST "https://kapi.kakao.com/v1/vision/face/detect" \
-d "image_url=https://t1.daumcdn.net/alvolo/_vision/openapi/r2/images/01.jpg" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"
curl -v -X POST "https://kapi.kakao.com/v1/vision/face/detect" \
-F "file=@sample_face.jpg" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"


[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래 값을 포함합니다

필드 설명 타입
result 얼굴 검출 결과를 담는 객체 Object

result (객체)

필드 설명 타입
width 요청 이미지의 가로 길이 Integer
height 요청 이미지의 세로 높이 Integer
faces 검출된 얼굴 정보를 담은 객체의 배열 Array

faces (배열)

필드 설명 타입
facial_attributes 얼굴의 성별, 나이를 담은 객체 Object
facial_points 검출된 얼굴의 특징점들을 담은 객체. 총 68개의 특징점이 영역별로 x,y 배열에 담겨있음 Object
score 검출된 얼굴의 판별 점수. threshold에서 지정한 값 이상만 검출 결과에 나옴. 0 ~ 1.0 사이의 값 Float
class_idx 판별된 객체의 검출 값이며, 현재는 0만 반환함. Integer
x 얼굴의 x좌표. 이미지의 가로 크기에 비례하는 0 ~ 1.0 사이의 값 Float
y 얼굴의 y좌표. 이미지의 가로 크기에 비례하는 0 ~ 1.0 사이의 값 Float
w 얼굴의 가로 크기. 이미지의 가로 크기에 비례하는 0 ~ 1.0 사이의 값 Float
h 얼굴의 세로 크기. 이미지의 가로 크기에 비례하는 0 ~ 1.0 사이의 값 Float
pitch 얼굴의 x축 각도. 얼굴의 상하 움직임 각도를 표현 Radian
yaw 얼굴의 y축 각도. 얼굴의 좌우 움직임 각도를 표현 Radian
roll 얼굴의 z축 각도. 얼굴의 회전 각도를 표현. Radian
얼굴의 각도를 나타내는 값들인 pitch, yaw, roll의 정의는 아래 그림과 같습니다
이미지 출처 : Enhanced real-time head pose estimation system for mobile device

facial_attributes ( 객체 )

필드 설명 타입
gender 검출된 얼굴의 추정 성별 객체
age 검출된 인물의 추정나이 Float

gender ( 객체 ) : male과 female 중 더 높은 성별을 사용하면 됩니다.

필드 설명 타입
male 검출된 얼굴의 남성 추정 값. 0 ~ 1.0 사이의 값 Float
female 검출된 인물의 여성 추정 값. 0 ~ 1.0 사이의 값 Float

facial_points ( 객체 )

모든 좌표는 왼쪽부터 아래로 정렬되어 있습니다.

필드 설명 타입
jaw 검출된 턱선의 17개의 죄표 배열. 0 ~ 1.0 사이의 (x,y) 값의 배열 배열
right_eyebrow 검출된 오른쪽 눈썹의 5개의 죄표 배열. 0 ~ 1.0 사이의 (x,y) 값의 배열 배열
left_eyebrow 검출된 왼쪽 눈썹의 5개의 죄표 배열. 0 ~ 1.0 사이의 (x,y) 값의 배열 배열
nose 검출된 코의 9개의 죄표 배열. 0 ~ 1.0 사이의 (x,y) 값의 배열 배열
right_eye 검출된 오른쪽 눈의 6개의 죄표 배열. 0 ~ 1.0 사이의 (x,y) 값의 배열 배열
left_eye 검출된 왼쪽 눈의 6개의 죄표 배열. 0 ~ 1.0 사이의 (x,y) 값의 배열 배열
lip 검출된 입술의 20개의 죄표 배열. 0 ~ 1.0 사이의 (x,y) 값의 배열 배열

상품 검출

상품 검출 API는 이미지 내에 존재하는 상품의 위치와 종류를 반환합니다. 패션 상품, 가방, 신발 등 을 검출할 수 있습니다.

상품 검출 데모를 바로 확인해 보세요! 데모 보러 가기

[Request]

POST /v1/vision/product/detect HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {rest_app_key}

호출 파라미터에 대한 공통 설명은 공통사항을 참고하세요.

  • 앱키를 헤더에 담아 POST로 요청합니다.
  • file과 image_url 중 하나는 필수로 지정해야 합니다.
  • threshold는 검출된 상품이 오검출인지를 판단하기 위해 사용하는 기준값입니다.
  • 0 ~ 1.0 사이의 값이며, 상품 검출의 기준값이 높으면 일부 상품은 검출하지 못할 수 있습니다.
  • 반대로 기준값이 낮으면 상품이 아닌 영역도 상품으로 오검출할 수 있습니다.
설명 필수 타입
file 이미지 파일 O Binary
image_url 이미지 URL O String
threshold 검출 기준값. . 0 ~ 1.0 사이의 값. 기본값 0.8 X Float

요청 예제

curl -v -X POST "https://kapi.kakao.com/v1/vision/product/detect" \
-d "image_url=https://t1.daumcdn.net/alvolo/_vision/openapi/r2/images/06.jpg" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"
curl -v -X POST "https://kapi.kakao.com/v1/vision/product/detect" \
-F "file=@sample_product.jpg" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"


[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래 값을 포함합니다

필드 설명 타입
result 상품 검출 결과를 담는 객체 Object

result ( 객체 )

필드 설명 타입
width 요청 이미지의 가로 크기 Integer
height 요청 이미지의 세로 크기 Integer
objects 검출된 상 정보를 담은 객체의 배열 Array

objects ( 배열 )

필드 설명 타입
x1 검출된 상품영역 박스의 좌상단 x좌표. 이미지의 가로 크기에 비례하는 0 ~ 1.0 사이의 값 Float
y1 검출된 상품영역 박스의 좌상단 y좌표. 이미지의 가로 크기에 비례하는 0 ~ 1.0 사이의 값 Float
x2 검출된 상품영역 박스의 우하단 x좌표. 이미지의 가로 크기에 비례하는 0 ~ 1.0 사이의 값 Float
y2 검출된 상품영역 박스의 우하단 y좌표. 이미지의 가로 크기에 비례하는 0 ~ 1.0 사이의 값 Float
class 상품의 이름 String

썸네일 생성

썸네일 생성 API는 이미지 내의 콘텐츠를 바탕으로 중요한 부분을 썸네일로 생성해주는 API입니다. 요청한 width, height 비율에 따라 이미지를 잘라내어 반환합니다.

썸네일 생성 데모를 바로 확인해 보세요! 데모 보러 가기

[Request]

POST /v1/vision/thumbnail/crop HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {rest_app_key}

호출 파라미터에 대한 공통 설명은 공통사항을 참고하세요.

앱키를 헤더에 담아 POST로 요청합니다. file과 image_url 중 하나는 필수로 지정해야 합니다.

설명 필수 타입
file 이미지 파일 O Binary
image_url 이미지 URL O String
width 이미지 가로 크기 O Integer
height 이미지 세로 크기 O Integer

요청 예제

curl -v -X POST "https://kapi.kakao.com/v1/vision/thumbnail/crop" \
-d "image_url=https://t1.daumcdn.net/alvolo/_vision/openapi/r2/images/07.jpg"
-d "width=200" \
-d "height=200" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"
curl -v -X POST "https://kapi.kakao.com/v1/vision/thumbnail/crop" \
-F "file=@sample_thumbnail.jpg" \
-F "width=200" \
-F "height=200" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래 값을 포함합니다

필드 설명 타입
thumbnail_image_url crop한 썸네일 이미지 url String

썸네일 검출

썸네일 검출 API는 이미지 내의 콘텐츠를 바탕으로 중요한 부분을 썸네일로 생성할 수 있게 도와주는 API입니다. 요청한 width, height 비율에 맞춰 이미지에서 잘라낼 수 있는 제안 영역을 반환합니다.

썸네일 검출 데모를 바로 확인해 보세요! 데모 보러 가기

[Request]

POST /v1/vision/thumbnail/detect HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {rest_app_key}

호출 파라미터에 대한 공통 설명은 공통사항을 참고하세요.

앱키를 헤더에 담아 POST로 요청합니다. file과 image_url 중 하나는 필수로 지정해야 합니다.

설명 필수 타입
file 이미지 파일 O Binary
image_url 이미지 URL O String
width 이미지 가로 크기 O Integer
height 이미지 세로 크기 O Integer

요청 예제

curl -v -X POST "https://kapi.kakao.com/v1/vision/thumbnail/detect" \
-d "image_url=https://t1.daumcdn.net/alvolo/_vision/openapi/r2/images/07.jpg" \
-d "width=200" \
-d "height=20" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"
curl -v -X POST "https://kapi.kakao.com/v1/vision/thumbnail/detect" \
-F "file=@sample_thumbnail.jpg" \
-F "width=200" \
-F "height=200" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래 값을 포함합니다

필드 설명 타입
result 이미지 검출 결과를 담는 객체 Object

result ( 객체 )

필드 설명 타입
width 요청 이미지의 가로 크기 Integer
height 요청 이미지의 세로 크기 Integer
thumbnail 제안하는 영역의 좌표를 담은 객체 Object

thumbnail ( 객체 )

필드 설명 타입
x 썸네일 가로 시작 좌표 Intger
y 썸네일 세로 시작 좌표 Intger
width 썸네일의 가로 크기 Intger
height 썸네일의 세로 크기 Intger

제안된 썸네일은 요청된 가로x세로의 비율에 해당하는 이미지의 영역입니다. 실제 썸네일을 생성할 경우는 제안 영역으로 자른 뒤에 원하는 크기로 리사이즈해야 합니다.

멀티태그 생성

멀티태그 API는 이미지 내의 콘텐츠에 대한 태그를 생성하는 API입니다. 이미지의 카테고리를 분류할 수 있도록 도움을 줍니다.

멀티태그 데모를 바로 확인해 보세요! 데모 보러 가기

[Request]

POST /v1/vision/multitag/generate HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {rest_app_key}

호출 파라미터에 대한 공통 설명은 공통사항 을 참고하세요.

앱키를 헤더에 담아 POST로 요청합니다. file과 image_url 중 하나는 필수로 지정해야 합니다.

설명 필수 타입
file 이미지 파일 O Binary
image_url 이미지 URL O String

요청 예제

curl -v -X POST "https://kapi.kakao.com/v1/vision/multitag/generate" \
-d "image_url=https://t1.daumcdn.net/alvolo/_vision/openapi/r2/images/08.jpg" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"
curl -v -X POST "https://kapi.kakao.com/v1/vision/multitag/generate" \
-F "file=@sample_tag.jpg" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래 값을 포함합니다

필드 설명 타입
result 태그 생성 결과를 담는 객체 Object

result ( 객체 )

필드 설명 타입
label 검출된 태그의 영문 목록 StringArray
label_kr 검출된 태그의 한글 목로 StringArray

성인 이미지 판별

성인 이미지 판별 API는 이미지가 성인물에 해당하는지를 판별한 결과를 알려줍니다. 스팸 이미지를 필터링하는 데 사용할 수 있습니다.
결과값은 ( normal, soft, adult )의 점수를 반환합니다. soft나 adult의 점수가 높으면 성인 이미지일 가능성이 높습니다. 모든 카테고리의 점수의 합은 1.0이 됩니다. ( normal + soft + adult = 1.0 )

성인 이미지 판별 데모를 바로 확인해 보세요! 데모 보러 가기

[Request]

POST /v1/vision/adult/detect HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {rest_app_key}

호출 파라미터에 대한 공통 설명은 공통사항 을 참고하세요.

앱키를 헤더에 담아 POST로 요청합니다. file과 image_url 중 하나는 필수로 지정해야 합니다.

설명 필수 타입
file 이미지 파일 O Binary
image_url 이미지 URL O String

요청 예제

curl -v -X POST "https://kapi.kakao.com/v1/vision/adult/detect" \
-d "image_url=https://t1.daumcdn.net/alvolo/_vision/openapi/r2/images/09.jpg" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"
curl -v -X POST "https://kapi.kakao.com/v1/vision/adult/detect" \
-F "file=@sample_adult.jpg" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래 값을 포함합니다

필드 설명 타입
result 성인 이미지 결과를 담는 객체 Object

result ( 객체 )

필드 설명 타입
normal 이미지가 정상일 확률. 0 ~ 1.0 사이의 값 Float
soft 이미지에 약간의 노출이 있을 확률. 주로 수영복 사진일 경우 해당. 0 ~ 1.0 사이의 값 Float
adult 이미지가 노출이 많은 성인 이미지일 경우. 주로 음란물일 경우 해당. 0 ~ 1.0 사이의 값 Float

OCR

문자 영역 감지

문자 영역 감지 API는 주어진 이미지에서 문자 영역을 사각형 형태로 감지합니다. 사각형에는 개행되지 않은 단일 라인의 문자가 들어갑니다. 이미지 내에서 글자가 어떤 영역에 얼마나 분포되어 있는지 확인할 수 있도록 도와줍니다.

문자 영역 감지 데모를 바로 확인해 보세요! 데모 보러 가기

[Request]

POST /v1/vision/text/detect HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {rest_app_key}
Content-Type: multipart/form-data

호출 파라미터에 대한 공통설명은 공통사항OCR API의 공통사항 을 참고하세요.

앱키를 헤더에 담아 POST로 요청합니다. 이미지업로드를 위해 Content-Type을 multipart/form-data 로 요청해야 합니다.

설명 필수 타입
file 이미지 파일 O Binary

요청 예제

curl -v -X POST "https://kapi.kakao.com/v1/vision/text/detect" \
-F "file=@sample.jpg" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk" \
-H "Content-Type: multipart/form-data"

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래 값을 포함합니다

필드 설명 타입
result 추출한 문자 영역에 대한 좌표 정보 Object

result ( 객체 )

필드 설명 타입
boxes 추출한 문자영역에 대한 x,y 좌표 정보 Array

하나의 box에서 꼭지점은 [[좌상단x, 좌상단y], [우상단x, 우상단y], [우하단x, 우하단y], [좌하단x, 좌하단y]] 순입니다. 여기서 상단/하단은 모니터의 위아래를 가리킵니다. x 좌표는 왼쪽에서 오른쪽으로 갈수록 증가하며, y 좌표는 위에서 아래로 갈수록 증가합니다.

문자 인식

문자 인식 API는 주어진 이미지에서 특정 영역의 글자를 추출합니다. 문자 영역 감지API 로 얻은 영역 정보를 파라미터로 이용합니다. 사각형에는 한 줄의 문자열만 들어가야 합니다. 단일 라인이라면, 여러 사각형을 하나의 사각형으로 합쳐서 입력해도 무방합니다.

문자인식 데모를 바로 확인해 보세요! 데모 보러 가기

다음은 문자인식 API를 사용하는 데 주의사항입니다.

  1. 문자 영역 감지 API에 사용된 것과 같은 이미지여야 합니다.
  2. 한번에 호출 가능한 box의 갯수는 최대 160 개 입니다.
  3. box의 갯수가 기준을 초과 할 경우, 아래와 같은 방법이 가능합니다.
    • 임의로 box를 merge할 수 있습니다. merge 는 한줄의 문장일때만 사용이 가능하며, 너무 긴 문자열이나 많은 box를 merge 할 경우 성능이 저하될 수 있습니다.
    • box를 일정 기준치로 나누어 API를 병렬로 호출할 수 있습니다.

[Request]

POST /v1/vision/text/recognize HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {rest_app_key}
Content-Type: multipart/form-data

호출 파라미터에 대한 공통설명은 공통사항OCR API의 공통사항 을 참고하세요.

앱키를 헤더에 담아 POST로 요청합니다. 이미지업로드를 위해 Content-Type을 multipart/form-data 로 요청해야 합니다.

설명 필수 타입
file 이미지 파일 O Binary
boxes 문자의 box 영역의 좌표 값. 문자 영역 감지API 응답의 boxes 값을 그대로 넣어줘야 합니다. O Array

요청 예제

curl -v -X POST "https://kapi.kakao.com/v1/vision/text/recognize?boxes=%5B%5B%5B362%2C478%5D%2C%5B571%2C488%5D%2C%5B569%2C538%5D%2C%5B360%2C528%5D%5D%2C%5B%5B370%2C595%5D%2C%5B514%2C611%5D%2C%5B509%2C664%5D%2C%5B364%2C648%5D%5D%2C%5B%5B359%2C540%5D%2C%5B467%2C548%5D%2C%5B465%2C594%5D%2C%5B357%2C587%5D%5D%5D" \
-F "file=@sample.jpg" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk" \
-H "Content-Type: multipart/form-data"

[Response]

요청이 성공하면 응답 바디에 JSON객체로 아래 값을 포함합니다.

필드 설명 타입
result 추출한 글자 정보 Object

result ( 객체 )

필드 설명 타입
recognition_words 추출한 글자 정보. box 순으로 정렬 String Array

OCR API 사용시나리오

OCR(Optical Character Recognition) 은 이미지 안에 있는 문자를 인지하여, text 형식으로 추출해 주는 기능입니다.
OCR을 위해 저희는 두 가지 API를 제공합니다.

첫 번째는 사용할 API는 Text Detection입니다.
문자-영역 감지 API는 이미지에서 문자라고 판단되는 부분을 사각형(BOX)의 영역으로 구분하여, 원본 이미지 기준 픽셀좌표를 전달해줍니다.

이 API를 호출하면, 문자 영역에 대해 4개의 꼭짓점을 가진 사각형(BOX)을 얻을 수 있습니다.
하나의 box에서 꼭짓점은 [[좌상단 x, 좌상단 y], [우상단 x, 우상단 y], [우하단 x, 우하단 y], [좌하단 x, 좌하단 y]] 순입니다.
여기서 상단/하단은 모니터의 위아래를 가리킵니다. x 좌표는 왼쪽에서 오른쪽으로 갈수록 증가하며, y 좌표는 위에서 아래로 갈수록 증가합니다.

{
  "result": {
    "boxes": [
      [
        [340, 456], 
        [533, 467], 
        [530, 514], 
        [337, 503]
      ], 
      [
        [349, 570], 
        [478, 586], 
        [473, 631], 
        [343, 615]
      ], 
      [
        [343, 516],
        [436, 524], 
        [433, 566], 
        [340, 559]
      ]
    ]
  }
}


팁)
"문자가 무엇이건 간에 이미지에서 문자가 차지하는 비율" 만을 원하신다면, Recognition API를 호출할 필요 없이, Text Detection API의 결과에서 나온 BOX의 넓이와 이미지의 넓이를 비교하여 원하는 정보를 얻을 수 있습니다.


두 번째는 Text Recognition API입니다.
문자 인식 API는 이미지 중 문자열이 존재하는 특정 영역을 지정해 그에 대한 Text 정보로 변환시켜 주는 API입니다.
좌표를 특별히 수정하지 않았다면, 문자 영역 감지 API의 boxes정보를 그대로 입력해야 순서에 맞는 결과를 얻을 수 있습니다

이 API를 호출하면 다음과 같은 문자열 정보를 얻을 수 있습니다.

{
 "result": {
  "recognition_words": [
   "Under",
   "Step",
   "the"
  ]
 }
}

팁)
프로그램으로 얻은 이미지나 어떠한 사유로 인해, 문자의 위치정보가 항상 같다면, Text Detection API 없이 바로 알고 있는 좌표를 이용해 Text Recognition API를 사용하실 수 있습니다.

응용)
이미지에서 인식하길 원하는 문자 영역의 BOX가 특정 위치에 있는 경우, Detection에서 얻은 좌표를 이용해 필터링한 뒤, BOX 개수를 줄여서 Recognition API를 호출하면 더 빠른 속도로 결과를 얻을 수 있습니다.

구현 예제

간단하게 python을 이용해 vision api를 활용할 수 있는 예제를 선보입니다. python버전은 2.7 또는 3.6 이상을 권장합니다. 설치가 필요한 python module requirement는 아래와 같습니다.

requests==2.14.2
Pillow==5.0.0

[얼굴을 추출해 모자이크 처리하는 예제]

이미지에서 얼굴을 찾아내고, 찾아낸 얼굴의 사각형 영역에 모자이크 처리하는 예제

import sys
import argparse
import requests
from PIL import Image, ImageFilter

API_URL = 'https://kapi.kakao.com/v1/vision/face/detect'
MYAPP_KEY = 'YOUR_APP_KEY'

def detect_face(filename):
    headers = {'Authorization': 'KakaoAK {}'.format(MYAPP_KEY)}

    try:
        files = { 'file' : open(filename, 'rb')}
        resp = requests.post(API_URL, headers=headers, files=files)
        resp.raise_for_status()
        return resp.json()
    except Exception as e:
        print(str(e))
        sys.exit(0)

def mosaic(filename, detection_result):
    image = Image.open(filename)

    for face in detection_result['result']['faces']:
        x = int(face['x']*image.width)
        w = int(face['w']*image.width)
        y = int(face['y']*image.height)
        h = int(face['h']*image.height)
        box = image.crop((x,y,x+w, y+h))
        box = box.resize((20,20), Image.NEAREST).resize((w,h), Image.NEAREST)
        image.paste(box, (x,y,x+w, y+h))

    return image



if __name__ == "__main__":
    parser = argparse.ArgumentParser(description='Mosaic faces.')
    parser.add_argument('image_file', type=str, nargs='?', default="./images/05.jpg",
                        help='image file to hide faces')

    args = parser.parse_args()

    detection_result = detect_face(args.image_file)
    image = mosaic(args.image_file, detection_result)
    image.show()

[상품을 추출하는 예제]

이미지로부터 상품 영역을 검출해서, 사각형을 영역을 표시하고 검출된 상품 이름을 보여주는 예제

import sys
import argparse
import requests
from PIL import Image, ImageDraw, ImageFont
from io import BytesIO

API_URL = 'https://kapi.kakao.com/v1/vision/product/detect'
MYAPP_KEY = 'YOUR_APP_KEY'

def detect_product(image_url):
    headers = {'Authorization': 'KakaoAK {}'.format(MYAPP_KEY)}

    try:
        data = { 'image_url' : image_url}
        resp = requests.post(API_URL, headers=headers, data=data)
        resp.raise_for_status()
        return resp.json()
    except Exception as e:
        print(str(e))
        sys.exit(0)

def show_products(image_url, detection_result):
    try:
        image_resp = requests.get(image_url)
        image_resp.raise_for_status()
        file_jpgdata = BytesIO(image_resp.content)
        image = Image.open(file_jpgdata)
    except Exception as e:
        print(str(e))
        sys.exit(0)


    draw = ImageDraw.Draw(image)
    for obj in detection_result['result']['objects']:
        x1 = int(obj['x1']*image.width)
        y1 = int(obj['y1']*image.height)
        x2 = int(obj['x2']*image.width)
        y2 = int(obj['y2']*image.height)
        draw.rectangle([(x1,y1), (x2, y2)], fill=None, outline=(255,0,0,255))
        draw.text((x1+5,y1+5), obj['class'], (255,0,0))
    del draw

    return image

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description='Detect Products.')
    parser.add_argument('image_url', type=str, nargs='?',
        default="http://t1.daumcdn.net/alvolo/_vision/openapi/r2/images/06.jpg",
        help='image url to show product\'s rect')

    args = parser.parse_args()

    detection_result = detect_product(args.image_url)
    image = show_products(args.image_url, detection_result)
    image.show()

[이미지의 썸네일을 생성하는 예제]

이미지의 주요 부분을 선택해서 지정한 width, height의 비율에 맞도록 썸네일을 생성해서 보여주는 예제

import sys
import argparse
import requests
from PIL import Image, ImageFilter

API_URL = 'https://kapi.kakao.com/v1/vision/thumbnail/detect'
MYAPP_KEY = 'YOUR_APP_KEY'

def detect_thumbnail(filename, width, height):
    headers = {'Authorization': 'KakaoAK {}'.format(MYAPP_KEY)}

    try:
        files = { 'file' : open(filename, 'rb')}
        params = {'width': width, 'height': height}
        resp = requests.post(API_URL, headers=headers, data=params, files=files)
        resp.raise_for_status()
        return resp.json()
    except Exception as e:
        print(str(e))
        sys.exit(0)

def show_thumbnail(filename, detection_result, width, height):
    image = Image.open(filename)
    rect = detection_result['result']['thumbnail']
    thumbnail = image.crop((rect['x'], rect['y'], rect['x'] + rect['width'], rect['y'] + rect['height']))
    thumbnail = thumbnail.resize((width, height))

    return thumbnail


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description='Make a thumbnail.')
    parser.add_argument('image_file', type=str, nargs='?', default="./images/07.jpg",
                        help='image file to make a thumbnail')
    parser.add_argument('width', type=int, nargs='?', default=150,
                        help='thumbnail width')
    parser.add_argument('height', type=int, nargs='?', default=200,
                        help='thumbnail height')

    args = parser.parse_args()

    detection_result = detect_thumbnail(args.image_file, args.width, args.height)
    image = show_thumbnail(args.image_file, detection_result, args.width, args.height)
    image.show()

[이미지에서 적절한 태그를 추출하는 예제]

이미지를 대표하는 태그를 추출해서 출력하는 예제

import sys
import argparse
import requests
from PIL import Image, ImageDraw, ImageFont
from io import BytesIO

API_URL = 'https://kapi.kakao.com/v1/vision/multitag/generate'
MYAPP_KEY = 'YOUR_APP_KEY'

def generate_tag(image_url):
    headers = {'Authorization': 'KakaoAK {}'.format(MYAPP_KEY)}

    try:
        data = { 'image_url' : image_url}
        resp = requests.post(API_URL, headers=headers, data=data)
        resp.raise_for_status()
        result = resp.json()['result']
        if len(result['label_kr']) > 0:
            if type(result['label_kr'][0]) != str:
                result['label_kr'] = map(lambda x: str(x.encode("utf-8")), result['label_kr'])
            print("이미지를 대표하는 태그는 \"{}\"입니다.".format(','.join(result['label_kr'])))
        else:
            print("이미지로부터 태그를 생성하지 못했습니다.")

    except Exception as e:
        print(str(e))
        sys.exit(0)

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description='Classify Tags')
    parser.add_argument('image_url', type=str, nargs='?',
        default="http://t1.daumcdn.net/alvolo/_vision/openapi/r2/images/08.jpg",
        help='image url to classify')

    args = parser.parse_args()

    generate_tag(args.image_url)

[성인 이미지, 노출 이미지를 판단하는 예제]

성인 이미지, 노출 포함 여부를 점수로 보여주는 예제

import sys
import argparse
import requests
from PIL import Image, ImageDraw, ImageFont
from io import BytesIO

API_URL = 'https://kapi.kakao.com/v1/vision/adult/detect'
MYAPP_KEY = 'YOUR_APP_KEY'

def detect_adult(image_url):
    headers = {'Authorization': 'KakaoAK {}'.format(MYAPP_KEY)}

    try:
        data = { 'image_url' : image_url}
        resp = requests.post(API_URL, headers=headers, data=data)
        resp.raise_for_status()
        result = resp.json()['result']
        if result['adult'] > result['normal'] and result['adult'] > result['soft']:
            print("성인 이미지일 확률이 {}% 입니다.".format(result['adult']*100))
        elif result['soft'] > result['normal'] and result['soft'] > result['adult']:
            print("노출이 포함된 이미지일 확률이 {}% 입니다.".format(result['soft']*100))
        else :
            print("일반적인 이미지일 확률이 {}% 입니다.".format(result['normal']*100))

    except Exception as e:
        print(str(e))
        sys.exit(0)

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description='Classify adult image.')
    parser.add_argument('image_url', type=str, nargs='?',
        default="http://t1.daumcdn.net/alvolo/_vision/openapi/r2/images/10.jpg",
        help='image url to classify')

    args = parser.parse_args()

    detect_adult(args.image_url)

[이미지에서 문자 영역을 감지하고 문자를 추출하는 예제]

이미지에서 문자 영역을 감지하고 문자를 추출하는 예제

import json

import cv2
import requests
import sys

LIMIT_PX = 1024
LIMIT_BYTE = 1024*1024  # 1MB
LIMIT_BOX = 40


def kakao_ocr_resize(image_path: str):
    """
    ocr detect/recognize api helper
    ocr api의 제약사항이 넘어서는 이미지는 요청 이전에 전처리가 필요.

    pixel 제약사항 초과: resize
    용량 제약사항 초과  : 다른 포맷으로 압축, 이미지 분할 등의 처리 필요. (예제에서 제공하지 않음)

    :param image_path: 이미지파일 경로
    :return:
    """
    image = cv2.imread(image_path)
    height, width, _ = image.shape

    if LIMIT_PX < height or LIMIT_PX < width:
        ratio = float(LIMIT_PX) / max(height, width)
        image = cv2.resize(image, None, fx=ratio, fy=ratio)
        height, width, _ = height, width, _ = image.shape

        # api 사용전에 이미지가 resize된 경우, recognize시 resize된 결과를 사용해야함.
        image_path = "{}_resized.jpg".format(image_path)
        cv2.imwrite(image_path, image)

        return image_path
    return None


def kakao_ocr_detect(image_path: str, appkey: str):
    """
    detect api request example
    :param image_path: 이미지파일 경로
    :param appkey: 카카오 앱 REST API 키
    """
    API_URL = 'https://kapi.kakao.com/v1/vision/text/detect'

    headers = {'Authorization': 'KakaoAK {}'.format(appkey)}

    image = cv2.imread(image_path)
    jpeg_image = cv2.imencode(".jpg", image)[1]
    data = jpeg_image.tobytes()

    return requests.post(API_URL, headers=headers, files={"file": data})


def kakao_ocr_recognize(image_path: str, boxes: list, appkey: str):
    """
    recognize api request example
    :param boxes: 감지된 영역 리스트. Canvas 좌표계: 좌상단이 (0,0) / 우상단이 (limit,0)
                    감지된 영역중 좌상단 점을 기준으로 시계방향 순서, 좌상->우상->우하->좌하
                    ex) [[[0,0],[1,0],[1,1],[0,1]], [[1,1],[2,1],[2,2],[1,2]], ...]
    :param image_path: 이미지 파일 경로
    :param appkey: 카카오 앱 REST API 키
    """
    API_URL = 'https://kapi.kakao.com/v1/vision/text/recognize'

    headers = {'Authorization': 'KakaoAK {}'.format(appkey)}

    image = cv2.imread(image_path)
    jpeg_image = cv2.imencode(".jpg", image)[1]
    data = jpeg_image.tobytes()

    return requests.post(API_URL, headers=headers, files={"file": data}, data={"boxes": json.dumps(boxes)})


def main():
    if len(sys.argv) != 3:
        print("Please run with args: $ python example.py /path/to/image appkey")
    image_path, appkey = sys.argv[1], sys.argv[2]

    resize_impath = kakao_ocr_resize(image_path)
    if resize_impath is not None:
        image_path = resize_impath
        print("원본 대신 리사이즈된 이미지를 사용합니다.")

    output = kakao_ocr_detect(image_path, appkey).json()
    print("[detect] output:\n{}\n".format(output))

    boxes = output["result"]["boxes"]
    boxes = boxes[:min(len(boxes), LIMIT_BOX)]
    output = kakao_ocr_recognize(image_path, boxes, appkey).json()
    print("[recognize] output:\n{}\n".format(json.dumps(output, sort_keys=True, indent=2)))


if __name__ == "__main__":
    main()

Last Modified : 2019-07-23