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

Karlo

REST API

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

시작하기 전에

이미지 파일 규격

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

  • 파일 용량 2MB 이하
  • 가로 및 세로 2048 pixel 이하 권장
  • 가로와 세로 길이가 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')

이미지 생성하기

기본 정보

POST /v1/inference/karlo/t2i
Host: api.kakaobrain.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json

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

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

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

Request

Parameter
Name Type Description Required
prompt Prompt 프롬프트, 생성할 이미지에 대한 입력 정보 O
Prompt
Name Type Description Required
text String 생성할 이미지를 묘사하는 제시어, 영문만 지원(최대: 256자)

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

Response

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

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

Sample

Request
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
        }
    }'
Response: 성공
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
        }
    ]
}

이미지 변환하기

기본 정보

POST /v1/inference/karlo/variations
Host: api.kakaobrain.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json

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

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

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

Request

Parameter
Name Type Description Required
prompt Prompt 프롬프트, 생성할 이미지에 대한 입력 정보 O
Prompt
Name Type Description Required
image String 변환할 원본 이미지를 Base64 인코딩한 값

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

Response

Name Type Description
id String 개별 처리 작업 식별자
model_version String 요청을 처리한 Karlo 모델 버전
images Image[] 생성된 이미지 배열

Sample

Request
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
        }
    }'
Response: 성공
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
        }
    ]
}

이미지 편집하기

기본 정보

POST /v1/inference/karlo/inpainting
Host: api.kakaobrain.com
Authorization: KakaoAK ${REST_API_KEY}
Content-Type: application/json

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

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

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

Request

Parameter
Name Type Description Required
prompt Prompt 프롬프트, 생성할 이미지에 대한 입력 정보 O
Prompt
Name Type Description Required
image String 원본 이미지를 Base64 인코딩한 값

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

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

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

Response

Name Type Description
id String 개별 처리 작업 식별자
model_version String 요청을 처리한 Karlo 모델 버전
images Image[] 생성된 이미지 배열

Sample

Request
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
        }
    }'
Response: 성공
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
        }
    ]
}