페이지 이동경로
  • 문서>
  • 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-Typeapplication/json으로 설정해야 합니다. KoGPT가 수행해야 할 과제에 대한 설명과 예시, 입력을 prompt 파라미터로 전달해야 합니다. 개념 및 용어구현 예제를 참고해 선택 파라미터의 값을 조정하면 요구사항에 더 잘 부합하는 결과를 유도할 수 있습니다.

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

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

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

요청

헤더
이름 설명 필수
Authorization Authorization: KakaoAK ${REST_API_KEY}
인증 방식, REST API 키로 인증 요청
O
Content-Type Content-Type: application/json
요청 데이터 타입
O
본문
이름 타입 설명 필수
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_KEYprompt에 실제 사용할 값을 입력해야 합니다.

# 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='''카카오(대표이사 정신아)의 카카오프렌즈가 서울페스타 2024에 참여한다고 29일 밝혔다. 서울페스타는 서울시에서 주최하는 서울 대표 봄축제로 서울의 다양한 매력을 전 세계에 홍보하는 행사다. 카카오는 황금연휴 기간 서울 곳곳에서 카카오프렌즈를 활용한 행사로 나들이객들과 관광객들에게 색다른 즐거움을 선사할 계획이다.
먼저, 카카오는 5월 1일부터 6일까지 광화문광장에서 라이언과 춘식이로 꾸며진 포토존을 운영한다. 6m가 넘는 초대형 라이언과 춘식이 애드벌룬이 설치돼 축제 분위기를 한껏 살릴 예정이며, 라이언과 춘식이가 그려진 포토카드를 나눠주는 이벤트도 진행한다. 포토카드는 4일을 제외한 매일 11시부터 포토존 앞에서 선착순으로 배부한다.
또한, ‘프렌즈와 떠나는 별빛 여행’을 주제로 한강 드론 라이트 쇼를 선보인다. 1,000여 대의 드론이 라이언과 춘식이의 탄생 세계관과 K-컬처를 즐기는 라이언과 춘식이의 모습을 그려내며 한강의 밤하늘을 수놓을 예정이다. 5월 6일 저녁 8시 잠실한강공원에서 관람 가능하며, 자세한 내용은 라이언&춘식 인스타그램에서 확인할 수 있다.
한편, 카카오톡 ‘펑’에서 ‘라이언 서울로컬로드’ 콘텐츠도 연재한다. 광화문, 잠실을 시작으로 라이언이 서울의 다양한 지역을 직접 방문하고 소개하는 일상 공유 콘텐츠를 통해 팬들과 실시간으로 소통할 예정이다.
최선 카카오 프렌즈크리에이티브 리더는 “K-캐릭터인 카카오프렌즈의 매력을 서울 곳곳에서 발견할 수 있도록 이번 행사를 준비했다” 며 “앞으로도 시민들의 일상 속에 더 가까이 다가갈 수 있도록 카카오프렌즈의 다양한 활동들을 전개할 예정이니 많은 기대 바란다” 라고 전했다.

한줄 요약:'''
response = kogpt_api(prompt, max_tokens=64, temperature=0.1)

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

{
    'id': '2f9c0346-7258-4b47-bd35-90a63a0686eb', 
    'generations': [
        {
            'text': ' 카카오프렌즈가 5월 1일부터 6일까지 서울페스타 2024에 참여해 황금연휴 기간 서울 곳곳에서 카카오프렌즈를 활용한 행사로 나들이객들과 관광객들에게 색다른 즐거움을 선사할 계획이라고 29일 밝혔다.', 
            'tokens': 51
        }
    ], 
    'usage': {
        'prompt_tokens': 401, 
        'generated_tokens': 51, 
        'total_tokens': 452
    }
}

질문에 답변하기

주어진 프롬프트의 복합적인 정보를 참고하여 질문에 답변합니다. 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
    }
}