키워드 매칭 API 호출 가이드

페이지 이동경로

키워드 매칭 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_matchtrue로 설정합니다.

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

{
  "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_matchtrue로 설정합니다.

{
  "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 성능보다 더 높은 성능이 필요한 경우에는 헬프데스크 > 기술문의 또는 사전 컨설팅 신청으로 문의해 주시기 바랍니다.