키워드 추출 API Reference

키워드 추출 API는 한국어와 영어 문서에 대한 키워드 추출을 지원합니다. 키워드 추출 API를 호출할 때 필요한 정보는 다음과 같습니다.

Request

API 요청 방식은 대상 언어에 따라 구분됩니다. 언어 설정별로 키워드 추출이 실행되기 때문에 sentences 에 맞는 lang 을 설정해야 합니다. 입력한 문서에 맞는 lang 값이 아닌 경우 잘못된 결과가 나오거나 결과가 없을 수 있습니다.

Request Syntax

코드 예제 Request Syntax (한국어 문서)

curl -L -X POST '{API Endpoint URL}' \
 -H 'x-api-key: {API Key}' \
 -H 'Content-Type: application/json' \
 -d '{
    "sentences": [
        "기축 통화는 국제 거래에 결제 수단으로 통용되고 환율 결정에 기준이 되는 통화이다.",
        "1960년 트리핀 교수는 브레턴우즈 체제 에서의 기축 통화인 달러화의 구조적 모순을 지적했다.",
        "한 국가의 재화와 서비스의 수출입 간 차이인 경상 수지는 수입이 수출을 초과하면 적자이고, 수출이 수입을 초과하면 흑자이다."
    ],
    "lang": "ko"
  }'

코드 예제 Request Syntax (영어 문서)

curl -L -X POST '{API Endpoint URL}' \
 -H 'x-api-key: {API Key}' \
 -H 'Content-Type: application/json' \
 -d '{
    "sentences": [
        "Tomatoes are a significant source of umami flavor.",
        "It is consumed in diverse ways: raw or cooked, and in many dishes, sauces, salads, and drinks.",
        "While tomatoes are fruits—botanically classified as berries—they are commonly used culinarily as a vegetable ingredient or side dish."
    ],
    "lang": "en"
  }'

표 API 호출 방식

메서드	요청 URL
POST	`{API Endpoint URL}` - API 호출 시 필요한 Endpoint 경로 - 카카오 i 클라우드 콘솔 > 도메인 목록 > AI API 인증정보 > API Endpoint URL에서 조회

Request Header

파라미터	타입	필수여부	설명
x-api-key	String	필수	`{API Key}`: API 호출 시 필요한 인증키 - 카카오 i 클라우드 콘솔 > 도메인 목록 > AI API 인증정보 > API Key에서 조회
Content-Type	String	필수	다음의 방식을 지원 - `application/json`

Request Elements

파라미터	타입	필수여부	설명
sentences	Array	필수	문장 입력 (최대 16,200 자, 공백 포함)
max_candidate_num	Integer	선택	최대 추출 키워드 개수 설정값 - 1에서 50 사이의 정수 - 기본값: 5
lang	String	선택	대상 언어 - `ko`: 한국어(기본값) - `en`: 영어

Response

Response Syntax

코드 예제 Response Syntax (한국어 문서)

{
    "result": [
        {
            "keyword": "기축 통화",
            "weight": 0.746829
        },
        {
            "keyword": "브레턴우즈",
            "weight": 0.734244
        },
        {
            "keyword": "트리핀 교수",
            "weight": 0.609244
        },
        {
            "keyword": "구조적 모순",
            "weight": 0.609244
        },
        {
            "keyword": "경상 수지",
            "weight": 0.586826
        }
    ],
    "elapsed_time": "0.032178",
    "version": "1.2.4",
    "lang": "ko",
    "max_candidate_num": 5
}

코드 예제 Response Syntax (영어 문서)

{
    "result": [
        {
            "keyword": "vegetable ingredient",
            "weight": 0.999442
        },
        {
            "keyword": "side dish",
            "weight": 0.651105
        },
        {
            "keyword": "diverse ways",
            "weight": 0.635727
        },
        {
            "keyword": "many dishes",
            "weight": 0.558579
        }
    ],
    "elapsed_time": "0.284797",
    "version": "1.2.4",
    "lang": "en",
    "max_candidate_num": 5
}

Response Elements

필드	타입	필수여부	설명
version	String	필수	API 버전
result ▼	Array	필수	키워드 추출 결과
keyword	String	필수	추출 키워드
weight	Float	필수	추출 키워드의 중요도(`0.0` ~ `1.0`)
elapsed_time	String	필수	키워드 추출에 걸린 처리 시간(sec)
max_candidate_num	Integer	필수	최대 추출 키워드 개수 설정값 - 1에서 50 사이의 정수 - 기본값: 5
lang	String	필수	요청 시 설정한 언어 - ko: 한국어 (기본값) - en: 영어
code	Integer	선택	응답 코드 - 자세한 설명은 Status Code 참고
msg	String	선택	응답 메시지 - 오류 발생 시 세부 정보 출력

Status Code

응답 코드	응답 내용	설명
200	-	API 호출 성공
400	Bad Request	요청 주소가 잘못된 경우
	INVALID_SIGNATURE	요청 Endpoint 주소의 signature가 잘못된 경우
	FAILED_WHEN_PARSING_BODY_AS_JSON	입력이 JSON 형식이 아님
	UNSUPPORTED_REQUEST_METHOD	호출 형식(post)이 잘못됨
	UNSUPPORTED_PARAMETER	지원하지 않는 파라미터 값이 입력됨
	UNSUPPORTED_LANG	lang에 지원하지 않는 값이 입력됨
	UNSUPPORTED_MAX_CANDIDATE_NUM	max_candidate_num에 지원하지 않은 값이 입력됨
	UNEXPECTED_MAX_CANDIDATE_NUM	max_candidate_num에 지원하지 않은 값이 입력됨
	UNASSIGNED_SENTENCES	sentences parameter가 입력되지 않음
	UNSUPPORT_SENTENCES	문장 입력 타입이 잘못됨
	EXCEED_MAX_SENTENCES_LEN	입력 문장의 글자 수 초과
	NO_RESULT	추출 결과가 없음
401	Authentication failed	x-api-key 헤더가 없거나 값이 잘못된 경우
404	NOT FOUND	지원하지 않는 Method로 요청을 보낸 경우
405	Method Not Allowed	지원하지 않는 Method로 요청을 보낸 경우
413	Request Entity Too Large	요청의 크기가 제한보다 큰 경우
415	Unsupported content type	Content Type 헤더가 없거나 규격에 맞지 않는 경우
425	Domain not found	요청한 도메인이 삭제되어 없을 경우
	Domain not deployed	요청한 도메인이 아직 배포되지 않은 경우
429	Too many Requests	설정한 한도를 초과해서 요청한 경우
503	INTERNAL ERROR	예상하지 못한 서버 오류가 발생한 경우

API 성능

카카오 i 클라우드의 키워드 추출 API는 평균 1만~2만자 기준의 입력 문서에 대해 초당 150건의 요청(150 TPS)을 처리합니다. 이는 초당 약 2백만 글자를 처리하는 속도에 해당합니다.

구분	설명
초당 처리 성능	평균 1만~2만자 기준의 입력 문서 기준 초당 150건 요청(150 TPS)을 처리
초당 처리 글자	2백만 글자

안내
위에 제시된 키워드 추출 API 성능보다 더 높은 성능이 필요한 경우에는 헬프데스크 > 기술문의 또는 상담 및 도입 문의 신청으로 문의하시기 바랍니다.