REST API

This document describes how to integrate Karlo APIs into your service with a REST API.

Before you begin

Applicable model version for each API

Each API of Karlo has different applicable model versions. You can select the model version to apply with version. We recommend using version 2.1, which has enhanced image generation quality. Version 2.1 can generate images up to 1280 pixels in both width and height, while version 2.0 can generate images up to 640 pixels in size.

Refer to the list of applicable model versions for each API below.

• Generate image: v2.1, v2.0
• Make variation: v2.1, v2.0
• Modify image: v2.0

Image file specification

The original image must comply with the specifications below.

• File size: 2 MB or less
• Image size: 2048 pixels or less for width and height (Recommended)
• Ratio: 1:1 (Recommended)
  • Images of other ratios will be resized to a 1:1 ratio.
• File format: JPG, PNG, webp (Recommended)

Image encoding and decoding

Karlo API handles the image file for the request and the response as a Base64 encoded string value.

• Request: Pass a Base64 encoded string value of the image file through the image parameter.
• Response: Base64 decode the value of the image field and save it as a PNG image file.

Below is a sample for Base64 encoding and decoding.

import io
import base64
from PIL import Image

# Base64 encoding
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 decoding and saving as a PNG file
def stringToImage(base64_string, mode='RGBA'):
    imgdata = base64.b64decode(str(base64_string))
    img = Image.open(io.BytesIO(imgdata)).convert(mode)
    return img

# Image loading
img = Image.open('my_image.png')

# Base64 encoding
img_base64 = imageToString(img)

# Decoding and saving
image = stringToImage(img_base64, mode='RGB')

Generate image

Basic information

Create new images based on the given text prompt.

Include the REST API key in the request header, and send a POST request. You must specify the prompt in the request body. Refer to How to use to request more efficiently with optional parameters.

If failed, refer to Error code to figure out the reason.

Request

Header

Body

FaceRefiner

Response

Body

Image

Sample

Request

# Libraries for REST API requests and image processing
import requests
import json
import urllib
from PIL import Image

# Input the REST API key in [My Application] > [App keys]
REST_API_KEY = '${REST_API_KEY}'

# Generate image
def t2i(prompt, negative_prompt):
    r = requests.post(
        'https://api.kakaobrain.com/v2/inference/karlo/t2i',
        json = {
            "version": "v2.1", 
            "prompt": prompt,
            "negative_prompt": negative_prompt, 
            "height": 1024,
            "width": 1024
        },
        headers = {
            'Authorization': f'KakaoAK {REST_API_KEY}',
            'Content-Type': 'application/json'
        }
    )
    # Convert the response to JSON
    response = json.loads(r.content)
    return response

# Prompt
prompt = "A photo of a cute tiny monster on the beach, daylight."
negative_prompt = ""

# Call the API
response = t2i(prompt, negative_prompt)

# Show the first image of the 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/t2i" \
    -H "Authorization: KakaoAK ${REST_API_KEY}" \
    -H "Content-Type: application/json" \
    -d '{
        "version": "v2.1",
        "prompt": "A photo of a cute tiny monster on the beach, daylight.",
        "height": 1024,
        "width": 1024
    }'

Response

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/..."
        }
    ]
}

Make variation

Basic information

Create variations of the given image.

Include the REST API key in the request header, and send a POST request. Refer to How to use to request more efficiently with optional parameters.

If failed, refer to Error code to figure out the reason.

Request

Header

Body

Response

Body

Sample

Request

# Libraries for REST API requests and image processing
import requests
import json
import io
import base64
import urllib
from PIL import Image

# Input the REST API key in [My Application] > [App keys]
REST_API_KEY = '${REST_API_KEY}'

# Make variation
def variations(image):
    r = requests.post(
        'https://api.kakaobrain.com/v2/inference/karlo/variations',
        json = {
            'version': 'v2.1',
            'image': image,
            'height': 1024,
            'width': 1024
        },
        headers = {
            'Authorization': f'KakaoAK {REST_API_KEY}',
            'Content-Type': 'application/json'
        }
    )
    # Convert the response to JSON
    response = json.loads(r.content)
    return response

# Base64 encoding
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

# Loading image
img = Image.open('original.png')

# Base64 encoding
img_base64 = imageToString(img)

# Call the API
response = variations(img_base64)
print(response)

# Show the first image of the 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 '{
        "version": "v2.1",
        "image": "iVBORw0KGgoAAAANSUhEUgA...",
        "height": 1024,
        "width": 1024
    }'

Response

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
        }
    ]
}

Modify image

Basic information

Creates a connected image based on the given image.

Include the REST API key in the request header, and send a POST request. Refer to How to use to request more efficiently with optional parameters.

If failed, refer to Error code to figure out the reason.

Request

Header

Body

Response

Body

Sample

Request

# Libraries for REST API requests and image processing
import requests
import json
import io
import base64
import urllib
from PIL import Image

# Input the REST API key in [My Application] > [App keys]
REST_API_KEY = '${REST_API_KEY}'

# Modify image
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'
        }
    )
    # Convert the response to JSON
    response = json.loads(r.content)
    return response

# Base64 encoding
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

# Loading image
img = Image.open('image.png')
mask = Image.open('mask.png')

# Base64 encoding
img_base64 = imageToString(img)
mask_base64 = imageToString(mask)

# Call the API
response = inpainting(img_base64,mask_base64)
print(response)

# Show the first image of the 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
    }'

Response

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/..."
        }
    ]
}