키워드 매칭 API Reference

키워드 매칭 API는 기본적으로 ‘완전일치 키워드 매칭’ 기능과 함께 ‘유사 키워드 매칭’ 옵션을 제공합니다. ‘완전일치 키워드 매칭’ 기능은 문장에서 참조 키워드와 완전하게 일치하는 키워드의 포함 여부를 확인할 때 사용하며, ‘유사 키워드 매칭’ 옵션은 참조 키워드와 완전하게 일치하지는 않아도 유사한 키워드를 함께 탐색할 때 사용합니다.

Request

API 요청 방식은 API 기본 기능인 ‘완전일치 키워드 매칭’ 기능만 사용하는 경우와 해당 기능과 함께 유사 키워드 매칭 옵션을 함께 사용하는 경우에 따라 구분됩니다.

Request Syntax

코드 예제 Request Syntax_완전일치 키워드 매칭

키워드 매칭 API의 기본 기능인 ‘완전일치 키워드 매칭’ 기능만 사용 시, semantic_match 파라미터를 false로 설정해야 합니다.

예시: “기축 통화는 국제 거래에 결제 수단으로 통용되고 환율 결정에 기준이 되는 통화이다.”라는 문장과 함께 참조 키워드로 “기축 통화”가 입력된 경우, 참조 키워드를 매칭하여 반환합니다.

curl -L -X POST '{API Endpoint URL}' \
 -H 'x-api-key: {API Key}' \
 -H 'Content-Type: application/json' \
 -d '{
      "sentences": [
        "기축 통화는 국제 거래에 결제 수단으로 통용되고 환율 결정에 기준이 되는 통화이다.",
        "1960년 트리핀 교수는 브레턴우즈 체제 에서의 기축 통화인 달러화의 구조적 모순을 지적했다.",
        "한 국가의 재화와 서비스의 수출입 간 차이인 경상 수지는 수입이 수출을 초과하면 적자이고, 수출이 수입을 초과하면 흑자이다.",
        "그는 “미국이 경상 수지 적자를 허용하지 않아 국제 유동성 공급이 중단되면 세계 경제는 크게 위축될 것”이라면서도 “반면 적자 상태가 지속돼 달러화가 과잉 공급되면 준비 자산으로서의 신뢰도가 저하되고 고정 환율 제도도 붕괴될 것”이라고 말했다."
      ],
    "reference_keywords": [
      "기축 통화",
      "유동성 과잉"
    ],
    "semantic_match": false,
    "lang": "ko"
  }'

코드 예제 Request Syntax_완전일치 키워드 매칭 + 유사 키워드 매칭 옵션

키워드 매칭 API의 기본 기능인 ‘완전일치 키워드 매칭’ 기능과 참조 키워드와 의미상으로 유사한 키워드를 함께 탐색하고 싶은 경우에는 semantic_match를 true로 설정합니다.

예시: “기축 통화는 국제 거래에 결제 수단으로 통용되고 환율 결정에 기준이 되는 통화이다.”라는 문장과 참조 키워드로 “유동성 과잉”이 입력된 경우, 유사한 후보인 “유동성 공급”을 탐색하고 유사도 점수를 함께 반환합니다.

curl -L -X POST '{API Endpoint URL}' \
 -H 'x-api-key: {API Key}' \
 -H 'Content-Type: application/json' \
 -d '{
      "sentences": [
        "기축 통화는 국제 거래에 결제 수단으로 통용되고 환율 결정에 기준이 되는 통화이다.",
        "1960년 트리핀 교수는 브레턴우즈 체제 에서의 기축 통화인 달러화의 구조적 모순을 지적했다.",
        "한 국가의 재화와 서비스의 수출입 간 차이인 경상 수지는 수입이 수출을 초과하면 적자이고, 수출이 수입을 초과하면 흑자이다.",
        "그는 “미국이 경상 수지 적자를 허용하지 않아 국제 유동성 공급이 중단되면 세계 경제는 크게 위축될 것”이라면서도 “반면 적자 상태가 지속돼 달러화가 과잉 공급되면 준비 자산으로서의 신뢰도가 저하되고 고정 환율 제도도 붕괴될 것”이라고 말했다."
      ],
      "reference_keywords": [
        "기축 통화",
        "유동성 과잉"
      ],
      "semantic_match": true,
      "lang": "ko"
    }'

표 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자 (공백 포함) * 문서는 실제 문서가 아니며, 문장의 집합을 의미
reference_keywords	Array	필수	키워드 매칭에 사용할 참조 키워드 - 최대 100개(콤마로 구분) - 키워드 당 최대 20자 (공백 포함)
semantic_match	Boolean	필수	유사 키워드 매칭 옵션의 사용 여부 설정 - true: 옵션을 사용 - false: 옵션을 사용하지 않음
lang	String	필수	언어 설정(현재는 한국어만 지원중) - `ko`: 한국어

Response

Response Syntax

코드 예제 Response Syntax_완전일치 키워드 매칭

‘완전일치 키워드 매칭’ 기능만 사용할 경우, semantic_match를 false로 설정합니다.

{
  "result": {
    "total_score": 0.5,
    "details": [
      {
        "reference_keyword": "기축 통화",
        "matched_keyword": "기축 통화",
        "score": 1
      },
      {
        "reference_keyword": "유동성 과잉",
        "matched_keyword": null,
        "score": 0
      }
    ]
  },
  "elapsed_time": "0.004256",
  "version": "1.2.9",
  "semantic_match": false,
  "lang": "ko"
}

코드 예제 Response_완전일치 키워드 매칭 + 유사 키워드 매칭 옵션

‘완전일치 키워드 매칭’ 기능과 ‘유사 키워드 매칭’ 옵션을 함께 사용할 경우, semantic_match를 true로 설정합니다.

{
  "result": {
    "total_score": 0.800244,
    "details": [
      {
        "reference_keyword": "기축 통화",
        "matched_keyword": "기축 통화",
        "score": 1
      },
      {
        "reference_keyword": "유동성 과잉",
        "matched_keyword": "유동성 공급",
        "score": 0.600488
      }
    ]
  },
  "elapsed_time": "0.019791",
  "version": "1.2.9",
  "semantic_match": true,
  "lang": "ko"
}

Response Elements

필드	타입	필수여부	설명
status	Integer	필수	응답 코드 - 자세한 설명은 Status Code 참고
message	String	필수	응답 메시지 - 오류 발생 시 세부 정보 출력
result ▼	Dictionary	필수	API 응답 결과
total_score	Float	필수	매칭 키워드의 유사도 스코어 평균값 - `1.0`은 완전한 일치를 의미
details ▼	Array	필수	키워드 매칭 결과
reference_keyword	String	필수	요청 시 입력한 참조 키워드
matched_keyword	String	필수	참조 키워드와 일치하는 키워드
score	Float	필수	입력된 키워드와 매칭 키워드의 유사도 - `1.0`은 완전한 일치를 의미 - `1.0`보다 낮을 수록 유사도가 낮음
elapsed_time	String	필수	키워드 매칭에 걸린 처리 시간(sec)
version	String	필수	API 버전
semantic_match	Boolean	필수	유사 키워드 매칭 옵션의 사용 여부 - `true`: 옵션을 사용 - `false`: 옵션을 사용하지 않음
lang	String	필수	요청 시 설정한 언어 - `ko`: 한국어
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	파라미터에 지원하지 않는 값이 입력된 경우
	UNASSIGNED_SEMANTIC_MATCH	semantic_match 파라미터가 누락된 경우
	UNSUPPORTED_SEMANTIC_MATCH	semantic_match에 null 혹은 지원하지 않는 값이 입력된 경우
	UNASSGIGNED_LANG	lang에 값이 입력되지 않은 경우
	UNSUPPORTED_LANG	lang에 지원하지 않는 값이 입력된 경우
	UNASSIGNED_REFERENCE_KEYWORDS	참조 키워드가 입력되지 않은 경우
	UNSUPPORT_REFERENCE_KEYWORDS	참조 키워드의 입력 타입이 맞지 아닌 경우
	EXCEED_MAX_SENTENCES_LEN	입력 글자수가 초과된 경우
	EXCEED_MAX_REFERENCE_KEYWORDS_COUNT	참조 키워드의 갯수가 100개를 초과한 경우
	EXCEED_MAX_REFERENCE_KEYWORDS_LEN	참조 키워드의 길이가 20자를 초과한 경우
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만자 기준의 입력 문서에 대해 초당 600개의 요청(600 TPS)을 처리합니다. 이는 초당 약 3백만 글자를 처리하는 속도에 해당합니다.

구분	설명
초당 처리 성능	평균 1만~2만 자 기준의 입력 문서에 대해 초당 600개 요청(600 TPS)을 처리 - 초당 약 3백만 글자를 처리

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

클라우드 가이드 센터 User Guide

키워드 매칭 API 호출 가이드

페이지 이동경로

키워드 매칭 API Reference

Request

Request Syntax

Request Header

Request Elements

Response

Response Syntax

Response Elements

Status Code

API 성능