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

Karlo

REST API

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

버전 업그레이드

2024년 2월 22일부터 Karlo API에 사용되는 Karlo 모델 이 이미지 생성 품질이 강화된 버전 2.1로 상향되었습니다. 이 문서는 모델 버전 2.0에 해당하는 내용을 안내합니다.

이미지 생성하기

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

입력된 텍스트에 따라 이미지를 생성합니다.

REST API 키를 헤더에 담아 POST로 요청합니다. 요청 시 Content-Typeapplication/json으로 설정해야 합니다. prompt 파라미터 하위의 text에 생성할 이미지를 묘사하는 제시어를 전달해야 합니다. 생성할 이미지 수는 batch_size 값으로 설정할 수 있습니다.

Karlo가 요청을 성공적으로 처리하면 생성한 이미지 정보를 응답 본문의 JSON 객체로 반환합니다. images 배열에서 각 이미지를 Base64 인코딩한 값을 확인할 수 있습니다. 요청 실패 시 응답 코드로 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
본문
이름 타입 설명 필수
prompt Prompt 프롬프트, 생성할 이미지에 대한 입력 정보 O
Prompt
이름 타입 설명 필수
text String 생성할 이미지를 묘사하는 제시어, 영문만 지원(최대: 256자)

참고: 활용 가이드
O
batch_size Integer 생성할 이미지 수(기본값: 1, 최대: 8) X

응답

본문
이름 타입 설명
id String 개별 처리 작업 식별자
model_version String 요청을 처리한 Karlo 모델 버전
images Image[] 생성된 이미지 배열
Image
이름 타입 설명
id String 개별 이미지 식별자
image String 생성된 이미지를 Base64 인코딩한 값(포맷: PNG, 크기: 1024*1024 pixel)

참고: 이미지 인코딩 및 디코딩
nsfw Boolean NSFW(Not Safe For Work) 여부
생성된 이미지에 폭력적이거나 성적인 요소가 있는지 판별한 결과를 참고용으로 제공

예제

요청
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 t2i(text, batch_size=1):
    r = requests.post(
        'https://api.kakaobrain.com/v1/inference/karlo/t2i',
        json = {
            'prompt': {
                'text': text,
                'batch_size': batch_size
            }
        },
        headers = {
            'Authorization': f'KakaoAK {REST_API_KEY}',
            'Content-Type': 'application/json'
        }
    )
    # 응답 JSON 형식으로 변환
    response = json.loads(r.content)
    return response

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

# 프롬프트에 사용할 제시어
text = "A lake, alpine, vivid"

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

# 응답의 첫 번째 이미지 생성 결과 출력하기
result = stringToImage(response.get("images")[0].get("image"), mode='RGB')
result.show()
curl -X POST https://api.kakaobrain.com/v1/inference/karlo/t2i \
    -H "Authorization: KakaoAK ${REST_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
        "prompt": {
            "text": "A lake, alpine, vivid", 
            "batch_size": 1
        }
    }'
응답
HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "a03ae776-0659-41bd-ada3-6cabd5fe0d34", 
    "model_version": "v1.3.2-rev1.prod", 
    "images": [
        {
            "id": "a03ae776-0659-41bd-ada3-6cabd5fe0d34_0", 
            "image": "UklGRtxwAABXRUJQVlA4INBwAABwFgOdA...",
            "nsfw": false
        }
    ]
}

이미지 변환하기

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

입력된 이미지의 내용을 이해하여 새로운 이미지를 생성합니다.

REST API 키를 헤더에 담아 POST로 요청합니다. 요청 시 Content-Typeapplication/json으로 설정해야 합니다. prompt 파라미터 하위의 image에 원본 이미지를 Base64 인코딩한 값을 전달해야 합니다. 생성할 이미지 수는 batch_size 값으로 설정할 수 있습니다.

Karlo가 요청을 성공적으로 처리하면 생성한 이미지 정보를 응답 본문의 JSON 객체로 반환합니다. images 배열에서 Base64 인코딩된 이미지를 확인할 수 있습니다. 요청 실패 시 응답 코드로 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
본문
이름 타입 설명 필수
prompt Prompt 프롬프트, 생성할 이미지에 대한 입력 정보 O
Prompt
이름 타입 설명 필수
image String 변환할 원본 이미지를 Base64 인코딩한 값

참고: 이미지 파일 규격, 이미지 인코딩 및 디코딩
O
batch_size Integer 생성할 이미지 수(기본값: 1, 최대: 8) X

응답

본문
이름 타입 설명
id String 개별 처리 작업 식별자
model_version String 요청을 처리한 Karlo 모델 버전
images Image[] 생성된 이미지 배열

예제

요청
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 variations(image, batch_size=1):
    r = requests.post(
        'https://api.kakaobrain.com/v1/inference/karlo/variations',
        json = {
            'prompt': {
                'image': image,
                'batch_size': batch_size
            }
        },
        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

# 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('original.jpg')

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

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

# 응답의 첫 번째 이미지 생성 결과 출력하기
result = stringToImage(response.get("images")[0].get("image"), mode='RGB')
result.show()
# prompt.image 값이 길 경우, 예제가 정상 동작하지 않을 수 있음
curl -X POST https://api.kakaobrain.com/v1/inference/karlo/variations \
    -H "Authorization: KakaoAK ${REST_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
        "prompt": {
            "image": "iVBORw0KGgoAAAANSUhEUgA...", 
            "batch_size": 1
        }
    }'
응답
HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "a03ae776-0659-41bd-ada3-6cabd5fe0d34", 
    "model_version": "v1.3.2-rev1.prod", 
    "images": [
        {
            "id": "a03ae776-0659-41bd-ada3-6cabd5fe0d34_0", 
            "image": "UklGRtxwAABXRUJQVlA4INBwAABwFgOdA...",
            "nsfw": false
        }
    ]
}

이미지 편집하기

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

Karlo가 입력된 텍스트에 따라 이미지의 일부 영역을 사용자 의도에 맞게 편집합니다.

REST API 키를 헤더에 담아 POST로 요청합니다. 요청 시 Content-Typeapplication/json으로 설정해야 합니다. prompt 파라미터 하위의 image에 원본 이미지, mask에 편집할 부분을 표시한 원본 이미지를 각각 Base64 인코딩한 값으로 전달해야 합니다. 편집해 넣을 이미지를 묘사하는 제시어는 text, 생성할 이미지 수는 batch_size 값으로 설정할 수 있습니다.

Karlo가 요청을 성공적으로 처리하면 생성한 이미지 정보를 응답 본문의 JSON 객체로 반환합니다. images 배열에서 Base64 인코딩된 이미지를 확인할 수 있습니다. 요청 실패 시 응답 코드로 원인을 확인합니다.

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
본문
이름 타입 설명 필수
prompt Prompt 프롬프트, 생성할 이미지에 대한 입력 정보 O
Prompt
이름 타입 설명 필수
image String 원본 이미지를 Base64 인코딩한 값

참고: 이미지 파일 규격, 이미지 인코딩 및 디코딩
O
mask String 편집할 부분을 표시한 원본 이미지를 Base64 인코딩한 값
편집할 부분을 검은색(Grayscale, RGB 기준 0)으로 가려서 표시
이미지의 여러 곳 마스킹 가능

참고: 이미지 파일 규격, 이미지 인코딩 및 디코딩
O
text String 편집해 넣을 이미지를 묘사하는 제시어, 영문만 지원(최대: 256자)
text 값이 설정되지 않으면 편집할 부분의 주변과 어울리도록 사물을 삭제하거나 대체함
(기본값: "", 빈 문자열)

참고: 활용 가이드
X
batch_size Integer 생성할 이미지 수(기본값: 1, 최대: 8) X

응답

본문
이름 타입 설명
id String 개별 처리 작업 식별자
model_version String 요청을 처리한 Karlo 모델 버전
images Image[] 생성된 이미지 배열

예제

요청
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 inpaint(image, mask, text="", batch_size=1):
    r = requests.post(
        'https://api.kakaobrain.com/v1/inference/karlo/inpainting',
        json = {
            'prompt': {
                'image': image,
                'mask': mask,
                'text': text,
                'batch_size': batch_size
            }
        },
        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

# 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('original.png')
mask = Image.open('mask.png')

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

# 프롬프트에 사용할 제시어
text = "Flowers"

# 이미지 변환하기 REST API 호출
response = inpaint(image=img_base64, mask=mask_base64, text=text, batch_size=1)

# 응답의 첫 번째 이미지 생성 결과 출력하기
result = stringToImage(response.get("images")[0].get("image"), mode='RGB')
result.show()
# prompt.image 값이 길 경우, 예제가 정상 동작하지 않을 수 있음
curl -X POST https://api.kakaobrain.com/v1/inference/karlo/inpainting \
    -H "Authorization: KakaoAK ${REST_API_KEY}" \
    -H 'Content-Type: application/json' \
    -d '{
        "prompt": {
            "image": "iVBORw0KGgoAAAANSUhEUgA...", 
            "mask": "iVBORw0KGgoAAAANSUhEUgA...", 
            "text": "Flowers", 
            "batch_size": 1
        }
    }'
응답
HTTP/1.1 200 OK
Content-Type: application/json
{
    "id": "6ae484d7-bf46-46f2-8b59-97067850850a", 
    "model_version": "v1.3.2-rev1.prod", 
    "images": [
        {
            "id": "6ae484d7-bf46-46f2-8b59-97067850850a_0", 
            "image": "UklGRmCKAABXRUJQVlA4IFSKAACwAAWdASoABAAEPp1Kn0ulq7...", 
            "nsfw": false
        }
    ]
}