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

KoGPT

REST API

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

KoGPT에게 요청하기

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

KoGPT에게 제시어를 전달해 과제 수행을 요청하고 결과를 받습니다.

REST API 앱 키를 헤더(Header)에 담아 POST 로 요청합니다. 요청 시 Content-Type을 application/json으로 설정해야 합니다. KoGPT가 수행해야 할 과제에 대한 설명과 예시, 입력을 prompt 파라미터로 전달해야 합니다. 개념 및 용어와 구현 예제를 참고해 선택 파라미터의 값을 조정하면 요구사항에 더 잘 부합하는 결과를 유도할 수 있습니다.

KoGPT가 요청을 성공적으로 처리하면 처리 결과를 응답 본문의 JSON 객체로 반환합니다. KoGPT가 생성한 결과 문장은 generations 하위의 text에서 확인할 수 있습니다.

usage 하위의 토큰 사용량 정보를 참고해 결과 개선에 활용할 수 있습니다. 토큰 사용량이 KoGPT의 총 토큰 수 제한을 초과해 충분한 결과를 얻지 못한 경우, prompt를 줄여 결과 토큰을 확보할 수 있습니다. 만약 토큰 사용량에 여유가 있다면, max_tokens 값을 늘려 더 긴 생성 결과를 얻을 수 있습니다.

요청 처리 시 1~10초의 지연 시간이 발생할 수 있습니다. 에러 발생 시 에러 코드에서 원인을 확인합니다.

요청

쿼리 파라미터
이름 타입 설명 필수
prompt String KoGPT에게 전달할 제시어인 프롬프트
한국어만 지원
구현 예제를 참고해 수행 과제에 적합한 내용으로 구성		 O
max_tokens Integer KoGPT가 생성할 결과의 최대 토큰 수
KoGPT는 지정된 최대 토큰 수 이하 길이의 결과만 반환
결과 토큰 수가 최대 토큰 수보다 적으면, 결과 생성 종료를 알리는 [EOS]까지의 결과만 반환		 O
temperature Double 온도 설정
0 초과 1 이하의 실수 값 사용 가능
temperature 수치가 높을수록 더 창의적인 결과가 생성됨
(기본값: 1)		 X
top_p Double 상위 확률 설정
0 이상 1 이하의 실수 값 사용 가능
top_p 수치가 높을수록 더 창의적인 결과가 생성됨
(기본값: 1)		 X
n Integer KoGPT가 생성할 결과 수
설정값 만큼 요청을 처리하고 쿼터를 차감함
(최대: 16, 기본값: 1)		 X

응답

본문
이름 타입 설명
id String 개별 처리 작업 식별자
generations Generation[] KoGPT가 생성한 결과 정보 배열
usage Usage 토큰 사용량
Generation
이름 타입 설명
text String KoGPT가 생성한 결과
tokens Integer 결과 토큰 수
Usage
이름 타입 설명
prompt_tokens Integer KoGPT에게 전달된 프롬프트의 토큰 수
generated_tokens Integer KoGPT가 생성한 결과의 토큰 수
tokens x n
total_tokens Integer 총 토큰 수
prompt_tokens x n + generated_tokens

예제

요청
curl -v -X POST "https://api.kakaobrain.com/v1/inference/kogpt/generation" \
    -H "Content-Type: application/json" \
    -H "Authorization: KakaoAK ${REST_API_KEY}" \
    -d '{
        "prompt": "오늘 아침 하늘은 곧 비가 올 것 같아서",
        "max_tokens": 120,
        "n": 2
        }'
응답: 성공
HTTP/2 200 OK
Content-Type: application/json; charset=utf-8
{
    "id": "15682c54-3ace-4262-96ac-b38261741787",
    "generations": [
        {
            "text": " 그런지 구름이 많이 껴 있었는데요. 하늘만 바라보고 있었는데... 이런, 날씨가 정말 장난 아니네요 ᅲᅲ 그래도 낮에는 날씨가 쨍쨍!!! 하지만 이제 본격적으로 여름이 다가오고 있다는 뜻이니 얇은 소재의 옷 준비는 필수겠죠?ᄒᄒᄒ 오늘 소개해드릴 옷은 린플러스가 제작한 제품으로, 여름에 편하게 입기 정말 좋은 바지인데요. 린플러스하면 편안함의 대명사로 유명해서 디자인 역시도 편안함을 강조해서 제작이 되었는데요. 어떤 제품으로",
            "tokens": 120    // 결과 토큰 수
        },
        {
            "text": " 조금 불안해 집니다. 지금 시간에 비라도 와서 구름이 좀 얇아져야 더위를 식혀 줄 건데 구름이 두꺼워 지는 것은 비구름이 지나가기 때문이고 구름의 이동에 따라서 아침 날씨가 결정되니까요. 어제도 이런 것 가지고 비를 기다려야 되나 말아야 되나로 꽤나 고심을 했었거든요. 어제도 조금 불안하고 걱정한 만큼 지금 마음도 조금 초조해 지네요. 지난 금요일, 일요일도 역시나 비가 와서 무척이나 습했었어요. 그런 상태에서 월요일인 오늘 아침도 비가 내려서 약간은 흐리멍",
            "tokens": 120    // 결과 토큰 수
        }
    ],
    "usage": {
        "prompt_tokens": 11,    // 프롬프트 토큰 수
        "generated_tokens": 240,    // 생성한 결과의 토큰 수
        "total_tokens": 262    // 총 토큰 수
    }
}
응답: 실패
HTTP/2 401 Unauthorized
Content-Type: application/json; charset=utf-8
{
    "code": -401,
    "msg": "api key not matched"
}

구현 예제

KoGPT API의 호출 방법과 다양한 과제를 수행하기 위한 prompt 구성 및 파라미터 수치 활용 방법을 참고할 수 있습니다.

호출 예제

아래는 Python을 사용한 KoGPT API 호출 예제입니다. REST_API_KEY와 prompt에 실제 사용할 값을 입력해야 합니다.

# coding=utf8
# REST API 호출에 필요한 라이브러리
import requests
import json

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

# KoGPT API 호출을 위한 메서드 선언
# 각 파라미터 기본값으로 설정
def kogpt_api(prompt, max_tokens = 1, temperature = 1.0, top_p = 1.0, n = 1):
    r = requests.post(
        'https://api.kakaobrain.com/v1/inference/kogpt/generation',
        json = {
            'prompt': prompt,
            'max_tokens': max_tokens,
            'temperature': temperature,
            'top_p': top_p,
            'n': n
        },
        headers = {
            'Authorization': 'KakaoAK ' + REST_API_KEY,
            'Content-Type': 'application/json'
        }
    )
    # 응답 JSON 형식으로 변환
    response = json.loads(r.content)
    return response

# KoGPT에게 전달할 명령어 구성
prompt = '''인간처럼 생각하고, 행동하는 '지능'을 통해 인류가 이제까지 풀지 못했던'''

# 파라미터를 전달해 kogpt_api()메서드 호출
response = kogpt_api(
    prompt = prompt,
    max_tokens = 32,
    temperature = 1.0,
    top_p = 1.0,
    n = 3
)

print(response)

다음 문장 만들기

KoGPT의 기본 기능입니다. 주어진 프롬프트 뒤로 이어질 자연스러운 문장을 생성합니다.

prompt= "인간처럼 생각하고, 행동하는 '지능'을 통해 인류가 이제까지 풀지 못했던"
response = kogpt_api(prompt, max_tokens=64, temperature=0.7, top_p=0.8)

아래는 응답에 반환되는 JSON 객체 예시입니다.

{
    'id': 'c0eb60ab-06c4-4d8d-a31a-454361e4fa4c', 
    'generations': [
        {
            'text': ' 난제들을 해결할 수 있을 것이다."-존 매카시(John McCarthy) 교수"인간은 생각하는 존재다. 인간은 스스로 생각하지 않고 행동하는 것은 불가능하다."-찰스 다윈(Charles Darwin) 교수"인간은 자신', 
            'tokens': 64
        }
    ], 
    'usage': {
        'prompt_tokens': 22, 
        'generated_tokens': 64, 
        'total_tokens': 86
    }
}

문장 분류하기

주어진 프롬프트의 분류 예시를 참고해 마지막 문장을 같은 기준으로 분류(Classification)합니다. 분류 대상인 마지막 문장은 예시의 각 문장과 같은 형식으로 입력해야 합니다. 아래는 상품평을 긍정 또는 부정으로 분류 요청하는 예제입니다. 결과가 "긍정" 또는 "부정"이어야 하므로 max_tokens은 1로 지정해 요청합니다.

prompt='''상품 후기를 긍정 또는 부정으로 분류합니다.
가격대비좀 부족한게많은듯=부정
재구매 친구들이 좋은 향 난다고 해요=긍정
ㅠㅠ약간 후회가 됩니다..=부정
이전에 먹고 만족해서 재구매합니다=긍정
튼튼하고 잘 쓸수 있을 것 같습니다. 이 가격에 이 퀄리티면 훌륭하죠='''
response = kogpt_api(prompt, max_tokens=1, temperature=0.4)

아래는 응답에 반환되는 JSON 객체 예시입니다.

{
    'id': '3c472532-43b7-4fb0-82af-6fe122ee24ce', 
    'generations': [
        {
            'text': '긍정', 
            'tokens': 1
        }
    ], 
    'usage': {
        'prompt_tokens': 78, 
        'generated_tokens': 1, 
        'total_tokens': 79
    }
}

뉴스 한 줄 요약하기

주어진 프롬프트의 뉴스 내용을 한 줄 요약합니다. KoGPT가 수행해야 할 과제를 알아볼 수 있도록 프롬프트 끝에 한줄 요약: 형식으로 입력을 구성했습니다.

prompt='''카카오의 임팩트 커머스 카카오메이커스와 카카오브레인이 '세계 동물의 날'을 맞아 멸종 위기 동물 보호에 힘을 보탠다. 

카카오메이커스와 카카오브레인은 4일 세계 동물의 날을 맞아, 카카오브레인의 AI 아티스트 '칼로' 와 현대미술가 고상우 작가가 협업한 제품을 오는 12일까지 카카오메이커스에서 단독 판매한다고 밝혔다. 판매 수익금 전액은 WWF(세계자연기금)에 기부할 예정이다. 

이번 프로젝트에 참여한 AI 아티스트 '칼로'는 'minDALL-E', 'RQ-Transformer' 등 카카오브레인의 초거대 이미지 생성 AI 모델을 발전시켜 하나의 페르소나로 재탄생한 AI 아티스트다. 1.8억 장 규모의 텍스트-이미지 데이터셋을 학습해 이해한 문맥을 바탕으로 다양한 화풍과 스타일로 이미지를 생성할 수 있다. 올해 6월에는 고상우 작가와의 공동 작업으로 생성한 1,000개의 호랑이 이미지를 조합한 디지털 작품으로 전시회를 진행한 바 있다. 

이번 프로젝트를 통해 선보이는 제품은 맨투맨과 머그컵이다. '칼로'가 생성한 호랑이 그림과 푸른색 사진 예술의 선구자인 고상우 작가 특유의 드로잉이 조화롭게 어우러져 완성된 500점의 호랑이 그림 모자이크 'Blue Tiger'가 새겨져 있다. 판매 수익금 전액은 WWF(세계자연기금)에 기부됨과 동시에, 낭비 없는 생산을 위해 주문 수량만큼 제품을 생산하는 카카오메이커스의 환경친화적 주문제작 방식(POD 생산)을 도입했다. 

카카오브레인 대표는 "AI 아티스트 칼로가 생성한 예술 작품으로 멸종 위기 동물 보호 활동에 동참하게 되어 기쁘다"며, "앞으로도 우리의 AI 기술을 통해 사회에 환원할 수 있는 의미 있는 프로젝트에 지속 참여하겠다"며 포부를 전했다. 

카카오 메이커스 실장은 "지난 8월 고양이의 날을 기념한 제품을 기획/판매해 기부한데 이어 사회의 다양한 구성원을 존중하고 배려하는 프로젝트를 이어가고 있다"며 "더 나은 세상을 만들기 위한 이용자들의 관심을 확인하고 있으며, 앞으로도 임팩트 커머스로서 다양한 가치를 담은 메이커스만의 제품을 선보일 것" 이라고 밝혔다.

한줄 요약:'''
response = kogpt_api(prompt, max_tokens=128, top_p=0.7)

아래는 응답에 반환되는 JSON 객체 예시입니다.

{
    'id': '18ba28bc-5d05-4508-b696-0a5d8497093e', 
    'generations': [
        {
            'text': ' 카카오메이커스와 카카오브레인은 4일 세계 동물의 날을 맞아, 카카오메이커스에서 카카오메이커스와 카카오브레인이 멸종 위기 동물 보호에 힘을 보탠다는 취지로 카카오메이커스에서 단독 판매한 제품 수익금 전액을 WWF(세계자연기금)에 기부할 예정이다.[EOS]', 
            'tokens': 64
        }
    ], 
    'usage': {
        'prompt_tokens': 524, 
        'generated_tokens': 64, 
        'total_tokens': 588
    }
}

질문에 답변하기

주어진 프롬프트의 복합적인 정보를 참고하여 질문에 답변합니다. KoGPT가 수행해야 할 과제를 알아볼 수 있도록 프롬프트 끝에 정책제안서를 제출하는 시기는 언제인가?: 형식으로 입력을 구성했습니다.

prompt='''의료 스타트업으로 구성된 원격의료산업협의회가 10월부터 열리는 국정감사 시기에 맞춰 국회와 정부에 비대면 진료법 근거 마련을 촉구하는 정책제안서를 제출한다. 코로나19 사태에 비대면 진료의 한시 허용으로 원격 진료, 의약품 배송 등 서비스가 속속 등장하는 가운데 제도화 논의를 서둘러야 한다는 목소리가 높아질 것으로 전망된다. 코리아스타트업포럼 산하 원격의료산업협의회는 '위드(with) 코로나' 방역 체계 전환을 염두에 두고 비대면 진료 제도화 촉구를 위한 공동 대응 작업을 추진하고 있다. 협의회는 닥터나우, 엠디스퀘어, SH바이오, 메디버디 등 의료 스타트업 13개사로 구성됐다. 협의회는 국정감사 시기를 겨냥해 국회와 주무 부처인 보건복지부에 비대면 진료의 법적 근거 마련을 촉구할 방침이다. 이를 위해 주요 의원실과 관련 의견을 교환하고 있다. 협의회는 궁극적으로 의료법과 약사법 개정이 필요하지만 의료법 테두리 안에서 시행령 개정 등으로도 비대면 진료 가능성과 대상·의료기관 등을 구체화할 수 있다는 복안이다. 복지부 장관령으로 비대면 진료 기간을 명시하는 방안 등을 통해 사업 리스크도 줄일 수 있다. 올해 안에 국내 방역체계 패러다임이 바뀔 것으로 예상되는 점도 비대면 진료 제도화의 필요성을 높이고 있다. 최근 코로나19 백신 접종이 속도를 내면서 방역 당국은 위드 코로나 방역체계 전환을 고려하고 있다. 인구 대비 백신 접종 완료율이 70%가 되는 오는 10월 말에는 전환 논의가 수면 위로 뜰 것으로 보인다.
정책제안서를 제출하는 시기는 언제인가?:'''
response = kogpt_api(prompt, max_tokens=128, temperature=0.2)

아래는 응답에 반환되는 JSON 객체 예시입니다.

{
    'id': '0bacf513-ec4d-40e8-a747-8852ad982e19', 
    'generations': [
        {
            'text': ' 10월[EOS]', 
            'tokens': 3
        }
    ], 
    'usage': {
        'prompt_tokens': 348, 
        'generated_tokens': 3, 
        'total_tokens': 351
    }
}

특정 정보 추려내기

주어진 프롬프트의 내용에서 요청한 정보를 반환합니다. 주어진 사실을 바탕으로 과제를 해결해야 하므로, temperature 파라미터 값을 0.3으로 지정해 비교적 고정적인 결과를 생성하도록 유도합니다.

prompt='''임진왜란(壬辰倭亂)은 1592년(선조 25년) 도요토미 정권이 조선을 침략하면서 발발하여 1598년(선조 31년)까지 이어진 전쟁이다. 또한 임진왜란은 동아시아에 막대한 영향을 끼쳤으며, 두번의 침입이 있어서 제2차 침략은 정유재란이라 따로 부르기도 한다. 또한 이때 조선은 경복궁과 창덕궁 등 2개의 궁궐이 소실되었으며 약 백만명의 인구가 소실되었다.

명칭
일반적으로 임진년에 일어난 왜의 난리란 뜻으로 지칭되며 그 밖에 조선과 일본 사이에 일어난 전쟁이란 뜻에서 조일전쟁(朝日戰爭), 임진년에 일어난 전쟁이란 뜻에서 임진전쟁(壬辰戰爭), 도자기공들이 일본으로 납치된 후 일본에 도자기 문화가 전파되었다 하여 도자기 전쟁(陶瓷器戰爭)이라고도 한다. 일본에서는 당시 연호를 따서 분로쿠의 역(일본어: 文禄の役 분로쿠노에키[*])이라 하며, 중화인민공화국과 중화민국에서는 당시 명나라 황제였던 만력제의 호를 따 만력조선전쟁(萬曆朝鮮戰爭, 중국어: 萬曆朝鮮之役), 혹은 조선을 도와 왜와 싸웠다 하여 항왜원조(抗倭援朝)라고도 하며, 조선민주주의인민공화국에서는 임진조국전쟁(壬辰祖國戰爭)이라고 한다. 그밖에도 7년간의 전쟁이라 하여 7년 전쟁(七年戰爭)으로도 부른다.

임진왜란 때 조선의 왕은?

답:'''
response = kogpt_api(prompt, max_tokens=1, temperature=0.3)

아래는 응답에 반환되는 JSON 객체 예시입니다.

{
    'id': 'b3076338-c59f-49c6-bca9-321548d569f9', 
    'generations': [
        {
            'text': ' 선조', 
            'tokens': 1
        }
    ], 
    'usage': {
        'prompt_tokens': 329, 
        'generated_tokens': 1, 
        'total_tokens': 330
    }
}

말투 바꾸기

주어진 프롬프트의 예시를 참고하여, 마지막 문장의 말투를 요청한 방식으로 바꿉니다. 아래는 반말을 존댓말로 바꾸는 예제입니다. KoGPT가 참고할 수 있는 예시를 포함해 요청합니다.

prompt='''주어진 문장을 존댓말 문장으로 바꿔주세요.

문장:하지마!
존댓말:하지 말아주세요.

문장:나랑 같이 놀러가자
존댓말:저랑 같이 놀러가지 않으실래요?

문장:배고파 밥줘
존댓말:배가고픈데 밥을 먹어도 될까요?

문장:그거 재밌어?
존댓말:그것은 재미 있나요?

문장:뭐하는거야 지금
존댓말:지금 무엇을 하시는 건가요?

문장:당장 제자리에 돌려놔
존댓말:'''
response = kogpt_api(prompt, max_tokens=10, temperature=0.7)

아래는 응답에 반환되는 JSON 객체 예시입니다.

{
    'id': 'ab6014fe-fea1-45ca-8792-647f809906f7', 
    'generations': [
        {
            'text': '당장 제자리에 돌려 놓으세요.\n\n문장', 
            'tokens': 10
        }
    ], 
    'usage': {
        'prompt_tokens': 123, 
        'generated_tokens': 10, 
        'total_tokens': 133
    }
}

채팅하기

주어진 프롬프트의 정보와 대화 예시를 참고해 적절한 대화를 이어나갑니다. 과제 설명에 화자 특징을 묘사한 뒤, Q:와 A: 형식으로 대화 예시를 전달합니다.

prompt='''정보:거주지 서울, 나이 30대, 성별 남자, 자녀 두 명, 전공 인공지능, 말투 친절함
정보를 바탕으로 질문에 답하세요.
Q:안녕하세요 반갑습니다. 자기소개 부탁드려도 될까요?
A:안녕하세요. 저는 서울에 거주하고 있는 30대 남성입니다.
Q:오 그렇군요, 결혼은 하셨나요?
A:'''
response = kogpt_api(prompt, max_tokens=32, temperature=0.3, top_p=0.85)

아래는 응답에 반환되는 JSON 객체 예시입니다. 줄바꿈으로 내용이 구분된 프롬프트의 양식에 맞춰, 마지막 질문에 대한 답변과 다음 예상 질문을 개행문자(/n)로 구분해 결과에 담았습니다. max_tokens 파라미터 값 범위 안에서 생성된 답변의 내용을 파싱(Parsing)해 일부만 활용할 수 있습니다.

{
    'id': '6ad60612-1b71-4dea-9d35-8e3b5923ca72', 
    'generations': [
        {
            'text': '네, 작년에 결혼했습니다.\nQ:결혼하셨군요. 자녀는 몇 명인가요?\nA:네, 자녀는 두 명입니다', 
            'tokens': 32
        }
    ], 
    'usage': {
        'prompt_tokens': 86, 
        'generated_tokens': 32, 
        'total_tokens': 118
    }
}
KoGPT> REST API