이 문서는 Karlo REST API 사용 방법을 안내합니다.
Karlo API 요청 시 사용할 이미지는 다음 규격을 준수해야 합니다.
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/v1/inference/karlo/t2i |
REST API 키 |
권한 | 사전 설정 | 카카오 로그인 | 사용자 동의 |
---|---|---|---|
필요 | - | - | - |
입력된 텍스트에 따라 이미지를 생성합니다.
REST API 키를 헤더에 담아 POST
로 요청합니다. 요청 시 Content-Type
을 application/json
으로 설정해야 합니다. prompt
파라미터 하위의 text
에 생성할 이미지를 묘사하는 제시어를 전달해야 합니다. 생성할 이미지 수는 batch_size
값으로 설정할 수 있습니다.
Karlo가 요청을 성공적으로 처리하면 생성한 이미지 정보를 응답 본문의 JSON
객체로 반환합니다. images
배열에서 각 이미지를 Base64 인코딩한 값을 확인할 수 있습니다. 요청 실패 시 응답 코드로 원인을 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: KakaoAK ${REST_API_KEY} 인증 방식, REST API 키로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
prompt | Prompt |
프롬프트, 생성할 이미지에 대한 입력 정보 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
text | String |
생성할 이미지를 묘사하는 제시어, 영문만 지원(최대: 256자) 참고: 활용 가이드 |
O |
batch_size | Integer |
생성할 이미지 수(기본값: 1, 최대: 8) | X |
이름 | 타입 | 설명 |
---|---|---|
id | String |
개별 처리 작업 식별자 |
model_version | String |
요청을 처리한 Karlo 모델 버전 |
images | Image[] |
생성된 이미지 배열 |
이름 | 타입 | 설명 |
---|---|---|
id | String |
개별 이미지 식별자 |
image | String |
생성된 이미지를 Base64 인코딩한 값(포맷: PNG , 크기: 1024*1024 pixel)참고: 이미지 인코딩 및 디코딩 |
nsfw | Boolean |
NSFW(Not Safe For Work) 여부 생성된 이미지에 폭력적이거나 성적인 요소가 있는지 판별한 결과를 참고용으로 제공 |
# 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-Type
을 application/json
으로 설정해야 합니다. prompt
파라미터 하위의 image
에 원본 이미지를 Base64 인코딩한 값을 전달해야 합니다. 생성할 이미지 수는 batch_size
값으로 설정할 수 있습니다.
Karlo가 요청을 성공적으로 처리하면 생성한 이미지 정보를 응답 본문의 JSON
객체로 반환합니다. images
배열에서 Base64 인코딩된 이미지를 확인할 수 있습니다. 요청 실패 시 응답 코드로 원인을 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: KakaoAK ${REST_API_KEY} 인증 방식, REST API 키로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
prompt | Prompt |
프롬프트, 생성할 이미지에 대한 입력 정보 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
image | String |
변환할 원본 이미지를 Base64 인코딩한 값 참고: 이미지 파일 규격, 이미지 인코딩 및 디코딩 |
O |
batch_size | Integer |
생성할 이미지 수(기본값: 1, 최대: 8) | X |
이름 | 타입 | 설명 |
---|---|---|
id | String |
개별 처리 작업 식별자 |
model_version | String |
요청을 처리한 Karlo 모델 버전 |
images | Image[] |
생성된 이미지 배열 |
# 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-Type
을 application/json
으로 설정해야 합니다. prompt
파라미터 하위의 image
에 원본 이미지, mask
에 편집할 부분을 표시한 원본 이미지를 각각 Base64 인코딩한 값으로 전달해야 합니다. 편집해 넣을 이미지를 묘사하는 제시어는 text
, 생성할 이미지 수는 batch_size
값으로 설정할 수 있습니다.
Karlo가 요청을 성공적으로 처리하면 생성한 이미지 정보를 응답 본문의 JSON
객체로 반환합니다. images
배열에서 Base64 인코딩된 이미지를 확인할 수 있습니다. 요청 실패 시 응답 코드로 원인을 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: KakaoAK ${REST_API_KEY} 인증 방식, REST API 키로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
prompt | Prompt |
프롬프트, 생성할 이미지에 대한 입력 정보 | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
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[] |
생성된 이미지 배열 |
# 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
}
]
}