맞춤법 검사 API 호출 가이드

페이지 이동경로

맞춤법 검사 API Reference

카카오 i 클라우드의 맞춤법 검사 API를 호출할 때 필요한 개발 정보는 다음과 같습니다.

Request

Request Syntax

코드 예제 Request Syntax_도움말 출력

도움말 출력을 보려면 help 옵션을 on으로 설정합니다.

curl -v -X POST '{API Endpoint URL}' \
 -H 'x-api-key: {API Key}' \
 -H 'Content-Type: {application/json | application/x-www-form-urlencoded}' \
 -d '{
      "query": "심여를 기울여개발한 \n맛춤법 검사기",
      "help": "on"
    }'

코드 예제 Request Syntax_띄어쓰기만 사용

띄어쓰기 기능만 사용을 하려면 only_space 옵션을 on으로 설정합니다.

curl -v -X POST '{API Endpoint URL}' \
 -H 'x-api-key: {API Key}' \
 -H 'Content-Type: {application/json | application/x-www-form-urlencoded}' \
 -d '{
      "query": "심여를 기울여개발한 \n맛춤법 검사기",
      "only_space": "on"
    }'

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(권장)
- application/x-www-form-urlencoded

Request Elements

파라미터 타입 필수여부 설명 예시
query String 필수 맞춤법 검사 대상(어절, 문장, 문서)
- 최대 문서 글자수: 50,000자
- 최대 문장 글자수: 5,000자
* 입력 양식과 제약 사항 참고
‘심여를 기울여개발한 맛춤법 검사기’ 입력시, 다음과 같이 교정됨
- 심혈을 기울여 개발한 맞춤법 검사기
help String 선택 맞춤법 검사기 도움말 출력 옵션
- off(기본값): 도움말 출력을 하지 않음
- on: 도움말을 출력
‘심여를 기울여’ 입력시, 다음과 같이 출력함
- off(기본값): 도움말 출력하지 않음
- on: “마음과 힘을 아울러 이르는 말’은 ‘심혈’입니다.”
only_space String 선택 음절 변화 없이 띄어쓰기만 사용하는 옵션
- off(기본값): 음절 변화와 띄어쓰기 모두 교정
- on: 음절 변화 없이 띄어쓰기 교정
‘일해라절해라 하지마세요’ 입력 시, 다음과 같이 출력함
- off(기본값): 일해라 절해라 하지 마세요
- on: 이래라저래라 하지 마세요
disable_weak String 선택 신조어/순화어/방언/외래어 교정을 하지 않는 옵션(only_space 옵션과 혼합하여 사용 불가)
- off(기본값): 신조어/순화어/방언/외래어를 교정
- on: 신조어/순화어/방언/외래어를 교정하지 않음
‘얼집 쌤들이 짱이야; 난닝구 입은 고참 가오 떨어진다; 자방틀 돌리는소리가 불술기 같어유; 굿나잇 인 푸캣’ 입력 시, 다음과 같이 출력함
- off(기본값): 어린이집 선생님들이 최고야; 러닝셔츠 입은 선임 체면 떨어진다; 재봉틀 돌리는 소리가 기차 같아요; 굿 나이트푸껫
- on: 얼집 선생님들이 짱이야; 난닝구 입은 고참 가오 떨어진다; 자방틀 돌리는 소리가 불수리 같어유; 굿나잇 인 푸캣
disable_new String 선택 신조어 교정을 하지 않는 옵션(only_space 옵션과 혼합하여 사용 불가)
- off(기본값): 신조어를 교정
- on: 신조어를 교정하지 않음
‘얼집 쌤들이 짱이야’ 입력 시, 다음과 같이 출력함
- off(기본값): 어린이집 선생님들이 최고야
- on: 얼집 선생님들이 짱이야
disable_purified String 선택 순화어 교정을 하지 않는 옵션(only_space 옵션과 혼합하여 사용 불가)
- off(기본값): 순화어를 교정
- on: 순화어를 교정하지 않음
‘난닝구 입은 고참 가오 떨어진다’ 입력 시, 다음과 같이 출력함
- off(기본값): 러닝셔츠 입은 선임 체면 떨어진다
- on: 난닝구 입은 고참 가오 떨어진다
disable_dialect String 선택 방언어 교정을 하지 않는 옵션(only_space 옵션과 혼합하여 사용 불가)
- off(기본값): 방언어를 교정
- on: 방언어를 교정하지 않음
‘자방틀 돌리는소리가 불술기 같어유’ 입력 시, 다음과 같이 출력함
- off(기본값): 재봉틀 돌리는 소리가 기차 같아요
- on: 자방틀 돌리는 소리가 불수리 같어유
disable_foreignword String 선택 외래어 교정을 하지 않는 옵션(only_space 옵션과 혼합하여 사용 불가)
- off(기본값): 외래어를 교정
- on: 외래어를 교정하지 않음
‘굿나잇 인 푸캣’ 입력 시, 다음과 같이 출력함
- off(기본값): 굿 나이트푸껫
- on: 굿나잇 인 푸캣
popular_word String 선택 외래어 교정 시, 자주쓰는 외래어로 치환하는 옵션(only_space, foreignword, disable_weak 옵션과 혼합하여 사용 불가)
- off(기본값): 자주쓰는 외래어로 치환하지 않음
- on: 자주쓰는 외래어로 치환
‘토르티야 콤보메뉴에 앱설루트 한잔’ 입력 시, 다음과 같이 출력함
- off(기본값): 토르티야 콤보 메뉴에 앱설루트 한잔
- on: 또띠아 콤보 메뉴에</span> 앱솔루트 한잔

Response

Response Syntax

코드 예제 Response Syntax_도움말 출력

{
  "version": "2.1.5",
  "sentences": [
    {
      "sentence": "심여를 기울여개발한 카카오맛춤법 검사기에요.",
      "result": [
        {
          "input": "심여를",
          "output": "심혈을",
          "etype": "spell",
          "help": [
            "'마음과 힘을 아울러 이르는 말'은 '심혈'입니다."
          ],
          "example": [
            "<color1>심혈</color1>을 기울이다.",
            "평생 동안 <color1>심혈</color1>을 바친 사업이 실패로 돌아갔다.",
            "소비자들을 사로잡을 만한 신제품 개발에 <color1>심혈</color1>을 쏟았다."
          ]
        },
        {
          "input": "기울여개발한",
          "output": "기울여 개발한",
          "etype": "space",
          "help": [
            "띄어쓰기 오류입니다. 대치어를 참고하여 고쳐 쓰세요."
          ]
        },
        {
          "input": "카카오맛춤법",
          "output": "카카오 맞춤법",
          "etype": "space_spell",
          "help": [
            "'맛춤법'의 옳은 표기는 '맞춤법'입니다."
          ]
        },
        {
          "input": "검사기에요.",
          "output": "검사기예요.",
          "etype": "spell",
          "help": [
            "올바르지 않은 어미의 사용입니다. '검사기예요.'로 고쳐 씁니다."
          ]
        }
      ]
    }
  ],
  "copyright": "도움말 설명과 예문 출처: 국립국어원 우리말샘, CC BY 라이선스"
}

코드 예제 Response Syntax_띄어쓰기만 사용

{
  "version": "2.1.5",
  "sentences": [
    {
      "sentence": "심여를 기울여개발한 카카오맛춤법 검사기에요.",
      "result": [
        {
          "input": "심여를",
          "output": "심여를",
          "etype": "no_error"
        },
        {
          "input": "기울여개발한",
          "output": "기울여 개발한",
          "etype": "space"
        },
        {
          "input": "카카오맛춤법",
          "output": "카카오 맛춤법",
          "etype": "space"
        },
        {
          "input": "검사기에요.",
          "output": "검사기에요.",
          "etype": "no_error"
        }
      ]
    }
  ]
}

Response Elements

필드 타입 필수여부 설명
version String 필수 API 버전
sentences ▼ Array 필수 문장 단위 맞춤법 검사 결과
   sentence String 필수 입력 문장
   result ▼ Array 필수 어절 단위 맞춤법 검사 결과
     input String 필수 입력 어절
     output String 필수 입력 어절 교정 결과
     etype String 필수 입력 어절 오류 타입
- no_error: 옳은 어절
- spell: 철자 오류
- space: 띄어쓰기 오류
- space_spell: 철자+띄어쓰기 오류
- doubt: 오류 의심
     help String 선택 맞춤법 검사기 도움말
- 요청 시 help 기능을 활성화했을 경우에만 반환
example String 선택 맞춤법 검사기 예문
- 요청 시 help 기능을 활성화했을 경우에만 반환

Status Code

응답 코드 응답 내용 설명
200 - API 호출 성공
400 Bad Request 요청 주소가 잘못된 경우
  INVALID_SIGNATURE 요청 Endpoint 주소의 signature가 잘못된 경우
  INPUT_TEXT_OVERFLOW 입력 문서 크기 초과 (최대 문서 크기: 약 50,000자)
  INPUT_SENTENCE_OVERFLOW 입력 문장 크기 초과 (최대 문장 크기: 약 5,000자)
  PARSE_EXCEPTION JSON 포맷에 어긋나는 경우
  UNSUPPORTED_PARAMETER 제공되지 않는 파라미터가 입력된 경우
  INVALID_PARAMETER_TYPE 입력 파라미터 형식이 옳지 않은 경우
  INVALID_PARAMETER_VALUE 입력 파라미터 값이 옳지 않은 경우
  UNSUPPORTED_PARAMETER_COMBINATION 같이 사용할 수 없는 파라미터를 사용한 경우
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는 평균 12어절 입력 텍스트에 대해 초당 1,000개의 요청(1,000 TPS)을 처리할 수 있으며, 최대 입력 텍스트(50,000자)에 대해 평균 처리 시간은 약 3초가 소요됩니다.

구분 설명
초당 처리 성능 평균 12어절 입력 텍스트 기준 초당 1,000개 요청(1,000 TPS)을 처리
평균 처리 시간 최대 입력 텍스트(50,000자) 기준 약 3초

위에 제시된 맞춤법 API 성능보다 더 높은 맞춤법 검사 성능이 필요한 경우에는 헬프데스크 > 기술문의 또는 사전 컨설팅 신청으로 문의해 주시기 바랍니다.