페이지 이동경로
  • 문서>
  • Karlo>
  • REST API

Karlo

REST API

이 문서는 Karlo REST API 사용 방법을 안내합니다.

버전 업그레이드

2023년 7월 6일부터 Karlo API에 사용되는 Karlo 모델 버전이 1.4에서 2.0으로, 2023년 11월 10일부터 이미지 편집 관련 기능이 추가된 모델 버전 2.0.4.0으로 상향되었습니다. 새로운 버전은 기존 버전보다 다양하고 향상된 기능을 제공합니다. 기존 버전 정보는 별도 문서에서 확인할 수 있습니다.

시작하기 전에

이미지 파일 규격

Karlo API 요청 시 사용할 이미지는 다음 규격을 준수해야 합니다.

  • 파일 크기: 2MB 이하
  • 이미지 크기: 가로 및 세로 2048 픽셀 이하 권장
  • 비율: 가로와 세로 길이가 1:1 비율인 이미지 사용 권장
    • 이 외 비율의 이미지는 요청 처리 시 1:1 비율로 조정(Resizing)됨
  • 파일 형식: JPG, PNG, webp 권장

이미지 인코딩 및 디코딩

Karlo API는 요청과 응답의 이미지 파일을 Base64 인코딩한 문자열 값으로 처리합니다.

  • 요청: image 파라미터에 이미지 파일 Base64 인코딩한 값 전달
  • 응답: image 값을 Base64 디코딩 후 .PNG 파일로 저장해 사용

아래는 이미지 Base64 인코딩 및 디코딩의 Python 예제입니다.

import io
import base64
from PIL import Image

# Base64 인코딩 함수
def imageToString(img):
    img_byte_arr = io.BytesIO()
    img.save(img_byte_arr, format='PNG')
    my_encoded_img = base64.encodebytes(img_byte_arr.getvalue()).decode('ascii')
    return my_encoded_img

# Base64 디코딩 및 이미지 변환 함수
def stringToImage(base64_string, mode='RGBA'):
    imgdata = base64.b64decode(str(base64_string))
    img = Image.open(io.BytesIO(imgdata)).convert(mode)
    return img

# 이미지 파일 불러오기
img = Image.open('my_image.png')

# 이미지를 Base64 인코딩하기
img_base64 = imageToString(img)

# Base64 인코딩된 값을 디코딩해 이미지로 변환하기
image = stringToImage(img_base64, mode='RGB')

이미지 생성하기

기본 정보
메서드 URL 인증 방식
POST https://api.kakaobrain.com/v2/inference/karlo/t2i REST API 키
권한 사전 설정 카카오 로그인 사용자 동의
- - - -

주어진 제시어에 따라 이미지를 생성합니다. 가로세로 최대 640 픽셀(Pixel) 크기의 이미지를 생성할 수 있으며, 파라미터를 사용해 가로세로 최대 2048 픽셀 크기까지 확대할 수 있습니다.

REST API 키를 헤더에 담아 POST로 요청합니다. 생성할 이미지를 묘사하는 제시어prompt로 전달해야 합니다. 활용 가이드를 참고해 선택 파라미터를 사용하면 보다 정확하고 효율적인 이미지 생성 요청이 가능합니다.

Karlo가 요청을 성공적으로 처리하면 생성된 이미지를 응답 본문의 JSON 객체에 담아 반환합니다. images 필드는 각각의 생성된 이미지 정보를 JSON 배열로 포함합니다.

요청 실패 시 응답 코드로 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
Content-Type Content-Type: application/json
요청 데이터 타입
O
본문
이름 타입 설명 필수
prompt String 이미지를 묘사하는 제시어, 영문만 지원
(최대: 2048자)
O
negative_prompt String 이미지 생성 시 제외할 요소를 묘사하는 부정 제시어, 영문만 지원
(최대: 2048자)
X
width Integer 이미지 가로 크기, 8의 배수여야 함
(단위: 픽셀, 기본값: 512, 최소: 384, 최대 640)
X
height Integer 이미지 세로 크기, 8의 배수여야 함
(단위: 픽셀, 기본값: 512, 최소: 384, 최대 640)
X
upscale Boolean 이미지 크기 확대 여부
true: 확대
false: 확대하지 않음
X
scale Integer 확대 배율, 2 또는 4 중 하나
(기본값: 2)

비고: scale 값을 4로 지정하더라도 가로세로 최대 2048 픽셀 크기까지만 확대 가능
X
image_format String 이미지 파일 형식, 다음 중 하나
webp
jpeg
png
(기본값: webp)
X
image_quality Integer 이미지 저장 품질
(기본값: 70, 최소: 1, 최대: 100)
X
samples Integer 생성할 이미지 수
(기본값: 1, 최소: 1, 최대 8)
X
return_type String 응답의 이미지 파일 반환 형식, 다음 중 하나
base64_string: 이미지 파일을 Base64 인코딩한 값
url: 이미지 파일 URL
(기본값: url)
X
prior_num_inference_steps Integer 이미지 생성 과정의 노이즈 제거 단계 수
(기본값: 25, 최소: 10, 최대 100)
X
prior_guidance_scale Double 이미지 생성 과정의 노이즈 제거 척도
(기본값: 5.0, 최소: 1.0, 최대: 20.0)
X
num_inference_steps Integer 디코더를 통한 노이즈 제거 단계 수
(기본값: 50, 최소: 10, 최대: 100)
X
guidance_scale Double 디코더를 통한 노이즈 제거 척도
(기본값: 5.0, 최소: 1.0, 최대: 20.0)
X
scheduler String 디코더를 통한 노이즈 제거 단계에서 사용할 스케줄러(Scheduler), 다음 중 하나
decoder_ddim_v_prediction
decoder_ddpm_v_prediction
(기본값: decoder_ddim_v_prediction)
X
seed Integer[] 각 이미지 생성 작업에 사용할 시드(Seed) 값
생성할 이미지 수와 같은 길이의 배열이어야 함
0 이상 4,294,967,295 이하 숫자로 구성
파라미터 미사용 시 무작위(Random) 시드 값으로 이미지 생성
(기본값: null)

비고: seed를 포함한 모든 파라미터가 동일할 경우, 항상 같은 이미지 생성
X
nsfw_checker Boolean 생성할 이미지에 대한 NSFW 검사하기 수행 여부
true: 수행
false 수행하지 않음
(기본값: false)
X
face_refiner FaceRefiner 얼굴 형태 조정 기능 설정 파라미터 X
FaceRefiner
이름 타입 설명 필수
bbox_size_threshold Double 얼굴 형태 조정 기능을 적용할 전체 이미지 대비 얼굴 영역의 비율, 실제 얼굴 영역이 설정 크기 이하인 경우만 기능 적용
(기본값: 1, 최소: 0(0%), 최대: 1(100%))
X
bbox_filter_threshold Double 이미지가 사람의 얼굴인지 여부를 판단하는 임계값, 0인 경우 기능 적용 안함
(기본값: 1, 최소: 0, 최대: 1)
X
restoration_repeats Double 얼굴 형태 조정 기능 적용 횟수
(기본값: 2, 최소: 1, 최대: 10)
X
weight_sft Double 원본 이미지 반영 가중치, 높을수록 원본 이미지 유지 수준 높음
(기본값: 0.5, 최소: 0, 최대 1)
X

응답

본문
이름 타입 설명 필수
id String 요청 처리 작업 ID O
model_version String 요청 처리 시 사용된 Karlo 버전 O
images Image[] 생성된 이미지 정보를 담은 배열 O
Image
이름 타입 설명 필수
id String 이미지 ID O
seed Integer 이미지 생성 시 사용된 시드 값
재요청을 통해 같은 콘텐츠의 이미지를 다시 생성하는 데 사용
O
image String 이미지 파일
return_type 파라미터 값에 따라 이미지 파일을 Base64 인코딩한 값, 또는 이미지 파일 URL 제공
이미지 파일 URL은 응답 시각으로부터 10분간 유효
O
nsfw_content_detected Boolean 이미지의 NSFW 콘텐츠 포함 여부
true: 포함
false: 포함하지 않음

비고: 미사용 시 null 반환
X
nsfw_score Double 이미지의 NSFW 콘텐츠 포함 확률

비고: 미사용 시 null 반환
X

예제

요청
Python
curl
# REST API 호출, 이미지 파일 처리에 필요한 라이브러리
import requests
import json
import urllib
from PIL import Image

# [내 애플리케이션] > [앱 키] 에서 확인한 REST API 키 값 입력
REST_API_KEY = '${REST_API_KEY}'

# 이미지 생성하기 요청
def t2i(prompt, negative_prompt):
    r = requests.post(
        'https://api.kakaobrain.com/v2/inference/karlo/t2i',
        json = {
            'prompt': prompt,
            'negative_prompt': negative_prompt
        },
        headers = {
            'Authorization': f'KakaoAK {REST_API_KEY}',
            'Content-Type': 'application/json'
        }
    )
    # 응답 JSON 형식으로 변환
    response = json.loads(r.content)
    return response

# 프롬프트에 사용할 제시어
prompt = "A cat with white fur"
negative_prompt = "sleeping cat, dog, human, ugly face, cropped"

# 이미지 생성하기 REST API 호출
response = t2i(prompt, negative_prompt)

# 응답의 첫 번째 이미지 생성 결과 출력하기
result = Image.open(urllib.request.urlopen(response.get("images")[0].get("image")))
result.show()
curl -v -X POST "https://api.kakaobrain.com/v2/inference/karlo/t2i" \
    -H "Authorization: KakaoAK ${REST_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
        "prompt": "A cat with white fur",
        "negative_prompt": "sleeping cat, human, ugly face, cropped"
    }'
응답
HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "3d6fb820-9845-4b3e-8d6d-7cfd01db5649",
    "model_version": "${MODEL_VERSION}",
    "images": [
        {
            "id": "a80108f8-b9c6-4bf4-aa38-957a38ced4a8",
            "seed": 3878985944,
            "image": "https://mk.kakaocdn.net/dna/karlo/image/..."
        }
    ]
}

이미지 확대하기

기본 정보
메서드 URL 인증 방식
POST https://api.kakaobrain.com/v2/inference/karlo/upscale REST API 키
권한 사전 설정 카카오 로그인 사용자 동의
- - - -

이미지의 크기를 확대합니다. 가로세로 최대 2048 픽셀까지 확대 가능합니다.

REST API 키를 헤더에 담아 POST로 요청합니다. 확대할 이미지를 images 배열에 담아 전달해야 합니다. 확대 배율인 scale은 2배 또는 4배 중 선택할 수 있습니다.

Karlo가 요청을 성공적으로 처리하면 확대 결과 이미지를 응답 본문의 JSON 객체에 담아 반환합니다. images 배열에서 각각의 확대된 이미지 파일을 확인할 수 있습니다.

요청 실패 시 응답 코드로 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
Content-Type Content-Type: application/json
요청 데이터 타입
O
본문
이름 타입 설명 필수
images String[] 확대할 이미지 파일을 Base64 인코딩한 값, 이미지 인코딩 및 디코딩 참고
이미지 크기는 가로세로 최대 1024 픽셀 이하여야 함
webp, png, jpeg, heic 형식의 이미지 파일 지원
(최대: 8개)
O
scale Integer 확대 배율, 2 또는 4 중 하나
(기본값: 2)

비고: scale 값을 4로 지정하더라도 가로세로 최대 2048 픽셀 크기까지만 확대 가능
X
image_format String 이미지 파일 형식, 다음 중 하나
webp
jpeg
png
(기본값: webp)
X
image_quality Integer 이미지 저장 품질
(기본값: 70, 최소: 1, 최대: 100)
X
return_type String 응답의 이미지 파일 반환 형식, 다음 중 하나
base64_string: 이미지 파일을 Base64 인코딩한 값
url: 이미지 파일 URL
(기본값: url)
X

응답

본문
이름 타입 설명 필수
images String[] 확대 결과 이미지 파일을 담은 배열
return_type 파라미터 값에 따라 이미지 파일을 Base64 인코딩한 값, 또는 이미지 파일 URL 제공
이미지 파일 URL은 응답 시각으로부터 10분간 유효
O

예제

요청
Python
curl
# REST API 호출, 이미지 파일 처리에 필요한 라이브러리
import requests
import json
import io
import base64
import urllib
from PIL import Image

# [내 애플리케이션] > [앱 키] 에서 확인한 REST API 키 값 입력
REST_API_KEY = '${REST_API_KEY}'

# 이미지 확대하기
def upscale(images, scale=2):
    r = requests.post(
        'https://api.kakaobrain.com/v2/inference/karlo/upscale',
        json = {
            'images': images,
            'scale': scale
        },
        headers = {
            'Authorization': f'KakaoAK {REST_API_KEY}',
            'Content-Type': 'application/json'
        }
    )
    # 응답 JSON 형식으로 변환
    response = json.loads(r.content)
    return response

# Base64 인코딩
def imageToString(img):
    img_byte_arr = io.BytesIO()
    img.save(img_byte_arr, format='PNG')
    my_encoded_img = base64.encodebytes(img_byte_arr.getvalue()).decode('ascii')
    return my_encoded_img

# 이미지 파일 불러오기
img = Image.open('original.png')

# 이미지를 Base64 인코딩하기
img_base64 = imageToString(img)

# 이미지를 Base64 인코딩한 값의 배열
img_arr = []
img_arr.append(img_base64)

# 이미지 변환하기 REST API 호출
response = upscale(img_arr, 2)

# 응답의 첫 번째 이미지 생성 결과 출력하기
result = Image.open(urllib.request.urlopen(response.get("images")[0]))
result.show()
curl -v -X POST "https://api.kakaobrain.com/v2/inference/karlo/upscale" \
    -H "Authorization: KakaoAK ${REST_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
        "images": [
            "iVBORw0KGgoAAAANSUhEUgA..."
        ]
    }'
응답
HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "ca2fff9c-83ae-4def-86b9-efdf107cdb96", 
    "model_version": "${MODEL_VERSION}", 
    "images": [
        "https://mk.kakaocdn.net/dna/karlo/image/..."
    ]
}

이미지 변환하기

기본 정보
메서드 URL 인증 방식
POST https://api.kakaobrain.com/v2/inference/karlo/variations REST API 키
권한 사전 설정 카카오 로그인 사용자 동의
- - - -

주어진 이미지의 내용을 이해하여 새로운 이미지를 생성합니다.

REST API 키를 헤더에 담아 POST로 요청합니다. 활용 가이드를 참고해 선택 파라미터를 사용하면 보다 정확하고 효율적인 이미지 생성 요청이 가능합니다.

Karlo가 요청을 성공적으로 처리하면 생성된 이미지를 응답 본문의 JSON 객체에 담아 반환합니다. images 필드는 각각의 생성된 이미지 정보를 JSON 객체로 포함합니다.

요청 실패 시 응답 코드로 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
Content-Type Content-Type: application/json
요청 데이터 타입
O
본문
이름 타입 설명 필수
image String 원본 이미지 파일을 Base64 인코딩한 값 O
width Integer 이미지 가로 크기, 8의 배수여야 함
(단위: 픽셀, 기본값: 512, 최소: 384, 최대 640)
X
height Integer 이미지 세로 크기, 8의 배수여야 함
(단위: 픽셀, 기본값: 512, 최소: 384, 최대 640)
X
upscale Boolean 이미지 크기 확대 여부
true: 확대
false: 확대하지 않음
X
scale Integer 확대 배율, 2 또는 4 중 하나
(기본값: 2)

비고: scale 값을 4로 지정하더라도 가로세로 최대 2048 픽셀 크기까지만 확대 가능
X
image_format String 이미지 파일 형식, 다음 중 하나
webp
jpeg
png
(기본값: webp)
X
image_quality Integer 이미지 저장 품질
(기본값: 70, 최소: 1, 최대: 100)
X
samples Integer 생성할 이미지 수
(기본값: 1, 최소: 1, 최대 8)
X
return_type String 응답의 이미지 파일 반환 형식, 다음 중 하나
base64_string: 이미지 파일을 Base64 인코딩한 값
url: 이미지 파일 URL
(기본값: url)
X
num_inference_steps Integer 디코더를 통한 노이즈 제거 단계 수
(기본값: 50, 최소: 10, 최대: 100)
X
guidance_scale Double 디코더를 통한 노이즈 제거 척도
(기본값: 5.0, 최소: 1.0, 최대: 20.0)
X
scheduler String 디코더를 통한 노이즈 제거 단계에서 사용할 스케줄러(Scheduler), 다음 중 하나
decoder_ddim_v_prediction
decoder_ddpm_v_prediction
(기본값: decoder_ddim_v_prediction)
X
seed Integer[] 각 이미지 생성 작업에 사용할 시드(Seed) 값
생성할 이미지 수와 같은 길이의 배열이어야 함
0 이상 4,294,967,295 이하 숫자로 구성
파라미터 미사용 시 무작위(Random) 시드 값으로 이미지 생성
(기본값: null)

비고: seed를 포함한 모든 파라미터가 동일할 경우, 항상 같은 이미지 생성
X
nsfw_checker Boolean 생성할 이미지에 대한 NSFW 검사하기 수행 여부
true: 수행
false 수행하지 않음
(기본값: false)
X
face_refiner FaceRefiner 얼굴 형태 조정 기능 설정 파라미터 X

응답

본문
이름 타입 설명 필수
id String 요청 처리 작업 ID O
model_version String 요청 처리 시 사용된 Karlo 버전 O
images Image[] 생성된 이미지 정보를 담은 배열 O

예제

요청
Python
curl
# REST API 호출, 이미지 파일 처리에 필요한 라이브러리
import requests
import json
import io
import base64
import urllib
from PIL import Image

# [내 애플리케이션] > [앱 키] 에서 확인한 REST API 키 값 입력
REST_API_KEY = '${REST_API_KEY}'

# 이미지 변환하기
def variations(image):
    r = requests.post(
        'https://api.kakaobrain.com/v2/inference/karlo/variations',
        json = {
            'image': image
        },
        headers = {
            'Authorization': f'KakaoAK {REST_API_KEY}',
            'Content-Type': 'application/json'
        }
    )
    # 응답 JSON 형식으로 변환
    response = json.loads(r.content)
    return response

# Base64 인코딩
def imageToString(img):
    img_byte_arr = io.BytesIO()
    img.save(img_byte_arr, format='PNG')
    my_encoded_img = base64.encodebytes(img_byte_arr.getvalue()).decode('ascii')
    return my_encoded_img

# 이미지 파일 불러오기
img = Image.open('original.png')

# 이미지를 Base64 인코딩하기
img_base64 = imageToString(img)

# 이미지 변환하기 REST API 호출
response = variations(img_base64)
print(response)

# 응답의 첫 번째 이미지 생성 결과 출력하기
result = Image.open(urllib.request.urlopen(response.get("images")[0].get("image")))
result.show()
curl -v -X POST "https://api.kakaobrain.com/v2/inference/karlo/variations" \
    -H "Authorization: KakaoAK ${REST_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
        "image": "iVBORw0KGgoAAAANSUhEUgA..."
    }'
응답
HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "6c0db22f-ecba-4d84-a817-b06e06a207da", 
    "model_version": "${MODEL_VERSION}", 
    "images": [
        {
            "id": "812702f0-3627-4a32-91cc-eaec50910156", 
            "image": "https://mk.kakaocdn.net/dna/karlo/image/...", 
            "seed": 2639508875
        }
    ]
}

이미지 편집하기

기본 정보
메서드 URL 인증 방식
POST https://api.kakaobrain.com/v2/inference/karlo/inpainting REST API 키
권한 사전 설정 카카오 로그인 사용자 동의
- - - -

이미지의 선택 영역을 재구성하거나, 이미지 경계 밖으로 연속된 이미지를 생성합니다.

REST API 키를 헤더에 담아 POST로 요청합니다. 편집할 이미지 파일, 편집할 영역이 표시된 이미지 파일, 편집할 이미지를 묘사하는 제시어를 파라미터로 전달해야 합니다. 활용 가이드를 참고해 선택 파라미터를 사용하면 보다 정확하고 효율적인 이미지 편집 요청이 가능합니다.

Karlo가 요청을 성공적으로 처리하면 생성된 이미지를 응답 본문의 JSON 객체에 담아 반환합니다. images 필드는 각각의 편집된 이미지 정보를 JSON 배열로 포함합니다.

요청 실패 시 응답 코드로 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
Content-Type Content-Type: application/json
요청 데이터 타입
O
본문
이름 타입 설명 필수
prompt String 이미지를 묘사하는 제시어, 영문만 지원
(최대: 2048자)
O
negative_prompt String 이미지 생성 시 제외할 요소를 묘사하는 부정 제시어, 영문만 지원
(최대: 2048자)
X
image String 편집할 이미지 파일을 Base64 인코딩한 값, 이미지 인코딩 및 디코딩 참고
이미지 크기는 가로세로 최대 1024 픽셀 이하여야 함
webp, png, jpeg, heic 형식의 이미지 파일 지원
O
mask String 편집할 영역을 검정(RGB 또는 Grayscale 값 0)으로 표시한 이미지를 Base64 인코딩한 값, 이미지 인코딩 및 디코딩 참고 O
reference_image String 편집 영역 보정 시 참고할 이미지를 Base64 인코딩한 값, 이미지 크기는 가로세로 최대 1024 픽셀 이하여야 함
webp, png, jpeg, heic 형식의 이미지 파일 지원
X
upscale Boolean 이미지 크기 확대 여부
true: 확대
false: 확대하지 않음
X
scale Integer 확대 배율, 2 또는 4 중 하나
(기본값: 2)

비고: scale 값을 4로 지정하더라도 가로세로 최대 2048 픽셀 크기까지만 확대 가능
X
image_format String 이미지 파일 형식, 다음 중 하나
webp
jpeg
png
(기본값: webp)
X
image_quality Integer 이미지 저장 품질
(기본값: 70, 최소: 1, 최대: 100)
X
samples Integer 생성할 이미지 수
(기본값: 1, 최소: 1, 최대 8)
X
return_type String 응답의 이미지 파일 반환 형식, 다음 중 하나
base64_string: 이미지 파일을 Base64 인코딩한 값
url: 이미지 파일 URL
(기본값: url)
X
prior_num_inference_steps Integer 이미지 생성 과정의 노이즈 제거 단계 수
(기본값: 25, 최소: 10, 최대 100)
X
prior_guidance_scale Double 이미지 생성 과정의 노이즈 제거 척도
(기본값: 5.0, 최소: 1.0, 최대: 20.0)
X
num_inference_steps Integer 디코더를 통한 노이즈 제거 단계 수
(기본값: 50, 최소: 10, 최대: 100)
X
guidance_scale Double 디코더를 통한 노이즈 제거 척도
(기본값: 5.0, 최소: 1.0, 최대: 20.0)
X
seed Integer[] 각 이미지 생성 작업에 사용할 시드(Seed) 값
생성할 이미지 수와 같은 길이의 배열이어야 함
0 이상 4,294,967,295 이하 숫자로 구성
파라미터 미사용 시 무작위(Random) 시드 값으로 이미지 생성
(기본값: null)

비고: seed를 포함한 모든 파라미터가 동일할 경우, 항상 같은 이미지 생성
X
nsfw_checker Boolean 생성할 이미지에 대한 NSFW 검사하기 수행 여부
true: 수행
false 수행하지 않음
(기본값: false)
X
face_refiner FaceRefiner 얼굴 형태 조정 기능 설정 파라미터 X

응답

본문
이름 타입 설명 필수
id String 요청 처리 작업 ID O
model_version String 요청 처리 시 사용된 Karlo 버전 O
images Image[] 생성된 이미지 정보를 담은 배열 O

예제

요청
Python
curl
# REST API 호출, 이미지 파일 처리에 필요한 라이브러리
import requests
import json
import io
import base64
import urllib
from PIL import Image

# [내 애플리케이션] > [앱 키] 에서 확인한 REST API 키 값 입력
REST_API_KEY = '${REST_API_KEY}'

# 이미지 변환하기
def inpainting(image, mask):
    r = requests.post(
        'https://api.kakaobrain.com/v2/inference/karlo/inpainting',
        json = {
            'image': image,
            'mask': mask
        },
        headers = {
            'Authorization': f'KakaoAK {REST_API_KEY}',
            'Content-Type': 'application/json'
        }
    )
    # 응답 JSON 형식으로 변환
    response = json.loads(r.content)
    return response

# Base64 인코딩
def imageToString(img):
    img_byte_arr = io.BytesIO()
    img.save(img_byte_arr, format='PNG')
    my_encoded_img = base64.encodebytes(img_byte_arr.getvalue()).decode('ascii')
    return my_encoded_img

# 이미지 파일 불러오기
img = Image.open('image.png')
mask = Image.open('mask.png')

# 이미지를 Base64 인코딩하기
img_base64 = imageToString(img)
mask_base64 = imageToString(mask)

# 이미지 변환하기 REST API 호출
response = inpainting(img_base64,mask_base64)
print(response)

# 응답의 첫 번째 이미지 생성 결과 출력하기
result = Image.open(urllib.request.urlopen(response.get("images")[0].get("image")))
result.show()
curl -v -X POST "https://api.kakaobrain.com/v2/inference/karlo/variations" \
    -H "Authorization: KakaoAK ${REST_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
        "prompt": "tiger",
        "image": "https://mk.kakaocdn.net/dn/karlo-dev/...",
        "mask": "https://mk.kakaocdn.net/dn/karlo-dev/...",
        "negative_prompt": "dog, human",
        "samples": 1,
        "prior_num_inference_steps": 25,
        "prior_guidance_scale": 5,
        "num_inference_steps": 50,
        "guidance_scale": 5,
        "seed": [0],
        "nsfw_checker": true,
        "upscale": false,
        "scale": 2,
        "face_refiner": {
            "bbox_size_threshold": 1,
            "bbox_filter_threshold": 0.5,
            "restoration_repeats": 2,
            "weight_sft": 0.5
        },
        "image_format": "webp",
        "image_quality": 70
    }'
응답
HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "3d6fb820-9845-4b3e-8d6d-7cfd01db5649",
    "model_version": "${MODEL_VERSION}",
    "images": [
        {
            "id": "a80108f8-b9c6-4bf4-aa38-957a38ced4a8",
            "seed": 3878985944,
            "image": "https://mk.kakaocdn.net/dna/karlo/image/..."
        }
    ]
}

얼굴 형태 조정하기

기본 정보
메서드 URL 인증 방식
POST https://api.kakaobrain.com/v2/inference/karlo/face_refiner REST API 키
권한 사전 설정 카카오 로그인 사용자 동의
- - - -

이미지의 얼굴 형태 왜곡을 교정해 자연스럽게 만듭니다.

참고

이미지 생성하기, 이미지 변환하기, 이미지 편집하기는 얼굴 형태 조정하기를 함께 요청할 수 있습니다.

REST API 키를 헤더에 담아 POST로 요청합니다. 조정할 이미지 파일을 images 배열에 담아 전달해야 합니다. 활용 가이드를 참고해 선택 파라미터를 사용하면 보다 정확하고 효율적인 요청이 가능합니다.

Karlo가 요청을 성공적으로 처리하면 생성된 이미지를 응답 본문의 JSON 객체에 담아 반환합니다. images 필드는 각각의 조정된 이미지 정보를 JSON 배열로 포함합니다.

요청 실패 시 응답 코드로 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
Content-Type Content-Type: application/json
요청 데이터 타입
O
본문
이름 타입 설명 필수
images String[] 이미지 파일을 Base64 인코딩한 값의 배열(최대: 8개), 이미지 인코딩 및 디코딩 참고
이미지 크기는 가로세로 최대 1024 픽셀 이하여야 함
webp, png, jpeg, heic 형식의 이미지 파일 지원
O
image_format String 이미지 파일 형식, 다음 중 하나
webp
jpeg
png
(기본값: webp)
X
image_quality Integer 이미지 저장 품질
(기본값: 70, 최소: 1, 최대: 100)
X
return_type String 응답의 이미지 파일 반환 형식, 다음 중 하나
base64_string: 이미지 파일을 Base64 인코딩한 값
url: 이미지 파일 URL
(기본값: url)
X
bbox_size_threshold Double 얼굴 형태 조정 기능을 적용할 전체 이미지 대비 얼굴 영역의 비율, 실제 얼굴 영역이 설정 크기 이하인 경우만 기능 적용
(기본값: 1, 최소: 0(0%), 최대: 1(100%))
X
bbox_filter_threshold Double 이미지가 사람의 얼굴인지 여부를 판단하는 임계값, 0인 경우 기능 적용 안함
(기본값: 1, 최소: 0, 최대: 1)
X
restoration_repeats Double 얼굴 형태 조정 기능 적용 횟수
(기본값: 2, 최소: 1, 최대: 10)
X
weight_sft Double 원본 이미지 반영 가중치, 높을수록 원본 이미지 유지 수준 높음
(기본값: 0.5, 최소: 0, 최대 1)
X

응답

본문
이름 타입 설명 필수
id String 요청 처리 작업 ID O
model_version String 요청 처리 시 사용된 Karlo 버전 O
images Image[] 생성된 이미지 정보를 담은 배열 O

예제

요청
Python
curl
# REST API 호출, 이미지 파일 처리에 필요한 라이브러리
import requests
import json
import io
import base64
import urllib
from PIL import Image

# [내 애플리케이션] > [앱 키] 에서 확인한 REST API 키 값 입력
REST_API_KEY = '${REST_API_KEY}'

# 이미지 변환하기
def faceRefiner(image):
    r = requests.post(
        'https://api.kakaobrain.com/v2/inference/karlo/face_refiner',
        json = {
            'images': [image]
        },
        headers = {
            'Authorization': f'KakaoAK {REST_API_KEY}',
            'Content-Type': 'application/json'
        }
    )
    # 응답 JSON 형식으로 변환
    response = json.loads(r.content)
    return response

# Base64 인코딩
def imageToString(img):
    img_byte_arr = io.BytesIO()
    img.save(img_byte_arr, format='PNG')
    my_encoded_img = base64.encodebytes(img_byte_arr.getvalue()).decode('ascii')
    return my_encoded_img

# 이미지 파일 불러오기
img = Image.open('original.png')

# 이미지를 Base64 인코딩하기
img_base64 = imageToString(img)

# 얼굴 형태 조정하기 REST API 호출
response = faceRefiner(img_base64)
print(response)

# 응답의 첫 번째 이미지 생성 결과 출력하기
result = Image.open(urllib.request.urlopen(response.get("images")[0]))
result.show()
curl -v -X POST "https://api.kakaobrain.com/v2/inference/karlo/face_refiner" \
    -H "Authorization: KakaoAK ${REST_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
        "images": [
            "iVBORw0KGgoAAAANSUhEUgA...",
            "aVZCT1J3MEtHZ29BQUFBTNV..."
        ],
        "image_format": "webp",
        "image_quality": 70,
        "bbox_size_threshold": 1,
        "bbox_filter_threshold": 0.5,
        "restoration_repeats": 2,
        "weight_sft": 0.5
    }'
응답
HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "ca2fff9c-83ae-4def-86b9-efdf107cdb96", 
    "model_version": "${MODEL_VERSION}", 
    "images": [
        "https://mk.kakaocdn.net/dna/karlo/image/...",
        "https://mk.kakaocdn.net/dna/karlo/image/..."
    ]
}

NSFW 검사하기

기본 정보
메서드 URL 인증 방식
POST https://api.kakaobrain.com/v2/inference/karlo/nsfw_checker REST API 키
권한 사전 설정 카카오 로그인 사용자 동의
- - - -

NSFW(Not Safe For Work, 폭력적이거나 선정적임) 콘텐츠를 포함한 이미지인지 검사합니다. 이 API는 이미 보유하고 있는 이미지에 대해 NSFW 콘텐츠를 검사하는 데 사용합니다.

참고

이미지 생성하기, 이미지 확대하기, 이미지 변환하기, 이미지 편집하기는 NSFW 검사하기를 함께 요청할 수 있습니다.

REST API 키를 헤더에 담아 POST로 요청합니다. 검사 대상 이미지를 images 배열로 전달합니다.

Karlo가 요청을 성공적으로 처리하면 생성된 이미지를 응답 본문의 JSON 객체에 담아 반환합니다. images 필드는 각각의 생성된 이미지 정보를 JSON 객체로 포함합니다.

요청 실패 시 응답 코드로 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
Content-Type Content-Type: application/json
요청 데이터 타입
O
본문
이름 타입 설명 필수
images String[] 검사 대상 이미지 파일을 Base64 인코딩한 값의 배열
(최대: 8개)
O

응답

본문
이름 타입 설명 필수
id String 요청 처리 작업 ID O
model_version String 요청 처리 시 사용된 Karlo 버전 O
results Result[] NSFW 검사하기 결과 O
Result
이름 타입 설명 필수
nsfw_content_detected Boolean 이미지의 NSFW 콘텐츠 포함 여부
true: 포함
false: 포함하지 않음
X
nsfw_score Double 이미지의 NSFW 콘텐츠 포함 확률 X

예제

요청
Python
curl
# REST API 호출, 이미지 파일 처리에 필요한 라이브러리
import requests
import json
import io
import base64
from PIL import Image

# [내 애플리케이션] > [앱 키] 에서 확인한 REST API 키 값 입력
REST_API_KEY = '${REST_API_KEY}'

# 이미지 변환하기
def nsfw(images):
    r = requests.post(
        'https://api.kakaobrain.com/v2/inference/karlo/nsfw_checker',
        json = {
            'images': images
        },
        headers = {
            'Authorization': f'KakaoAK {REST_API_KEY}',
            'Content-Type': 'application/json'
        }
    )
    # 응답 JSON 형식으로 변환
    response = json.loads(r.content)
    return response

# Base64 인코딩
def imageToString(img):
    img_byte_arr = io.BytesIO()
    img.save(img_byte_arr, format='PNG')
    my_encoded_img = base64.encodebytes(img_byte_arr.getvalue()).decode('ascii')
    return my_encoded_img

# 이미지 파일 불러오기
img = Image.open('target.png')

# 이미지를 Base64 인코딩하기
img_base64 = imageToString(img)

# 이미지를 Base64 인코딩한 값의 배열
img_arr = []
img_arr.append(img_base64)

# 이미지 변환하기 REST API 호출
response = nsfw(img_arr)

# NSFW 검사하기 결과 확인
print(response)
curl -v -X POST "https://api.kakaobrain.com/v2/inference/karlo/nsfw_checker" \
    -H "Authorization: KakaoAK ${REST_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
        "images": [
            "iVBORw0KGgoAAAANSUhEUgA..."
        ]
    }'
응답
HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "31aed005-9d31-4248-8a5e-3d086f1eae0e", 
    "model_version": "${MODEL_VERSION}", 
    "results": [
        {
            "nsfw_content_detected": false, 
            "nsfw_score": 0.20849609375
        }
    ]
}