Korean Grammar Checker API

카카오클라우드의 Korean Grammar Checker API를 호출할 때 필요한 개발 정보는 다음과 같습니다.

API 사용 준비

API를 호출하기 위해 필요한 사전 작업은 API 사용 준비 문서를 참고하시기 바랍니다.

Request

Request Syntax

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

도움말 출력

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

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

띄어쓰기만 사용

curl -v -X POST '{API 주소}' \
 -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 주소} - API 호출 시 필요한 Endpoint 경로 - 카카오클라우드 콘솔 > 엔드포인트 목록 > AI API 인증정보 > API 주소에서 조회

Request Header

파라미터	유형	필수 여부	설명
x-api-key	String	필수	{API Key}: API 호출 시 필요한 인증키 - 카카오클라우드 콘솔 > 엔드포인트 목록 > 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: 또띠아 콤보 메뉴에 앱솔루트 한잔

Response

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 라이선스"
}

띄어쓰기만 사용

{
  "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 성능

카카오클라우드의 Korean Grammar Checker API는 평균 12어절 입력 텍스트에 대해 초당 1,000개의 요청(1,000 TPS)을 처리할 수 있으며, 최대 입력 텍스트(50,000자)에 대해 평균 처리 시간은 약 3초가 소요됩니다.

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

안내

위에 제시된 맞춤법 API 성능보다 더 높은 맞춤법 검사 성능이 필요한 경우에는 헬프데스크 > 기술 문의 또는 상담 및 도입 문의 신청으로 문의하시기 바랍니다.