음성 (뉴톤) Beta

Beta 서비스 중에는 기능의 변경이 발생하거나 일시적으로 서비스 접근이 불가할 수 있습니다. 변경내역

카카오에서는 웹 상에서 손쉽게 사용할 수 있는 음성 API를 제공합니다. 사용자는 마이크와 스피커를 이용해 사람의 음성 언어를 인식하거나 합성할 수 있습니다.

현재 카카오에서 제공하는 음성 API는 다음과 같습니다.

  • 음성 인식 (뉴톤)
    사람이 말하는 음성 언어를 컴퓨터가 해석해 그 내용을 문자 데이터로 변환하는 음성-문자 변환 시스템 (Speech-to-Text system) 입니다.
  • 음성 합성 (뉴톤톡)
    앞의 기능과 반대로 문자 데이타를 사람이 이해할 수 있는 음성 언어로 변환하는 문자-음성 변환 시스템 (Text-to-Speech system) 입니다.

공통사항

  • REST API 키를 사용해 호출합니다.

    • '내 애플리케이션 > 설정 > 음성'에서 음성 서비스 사용을 활성화해야 합니다.

enable_speech.png

쿼터 제한 안내

제휴를 맺어 제한된 쿼터를 증량할 수 있습니다.

제휴 신청하기

'제휴 신청하기' > 하단 '제휴제안 등록' > '카카오i 제휴 제안하기'

음성 인식 (뉴톤)

음성 인식 API는 사람이 말하는 음성 언어를 컴퓨터가 해석해 문자 데이터로 변환하여 줍니다. 사람의 음성이 인식 될 때마다 중간 인식 결과를 반환하여 주며, 사람의 음성이 끝날 때 최종 인식 결과를 반환하여 줍니다.

[Request]

POST /v1/recognize HTTP/1.1
Host: kakaoi-newtone-openapi.kakao.com
Transfer-Encoding: chunked
Content-Type: application/octet-stream
X-DSS-Service: {service_mode}
Authorization: KakaoAK {rest_api_key}
  • 음성 데이터는 Mono channel, 16000 Hz samplerate, 16 bit depth인 RAW PCM 포맷만 지원합니다.
  • service_mode에 아래의 서비스 모드 도메인 종류 중 하나를 넣어 헤더에 담아 POST로 요청합니다.
서비스 모드 도메인 종류
서비스 모드 도메인 설명
Dictation 받아쓰기 인식 모드이며 주로 일반적인 문장, 대화체 인식에 사용
Local POI 인식 모드 이며 주로 주소, 지역명 인식에 사용 (예 : 카카오맵 앱 음성 인식)

예를 들면,

curl -v -X POST "https://kakaoi-newtone-openapi.kakao.com/v1/recognize" \
-H "Transfer-Encoding: chunked" \
-H "Content-Type: application/octet-stream" \
-H "X-DSS-Service: DICTATION" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk" \
--data-binary @heykakao.wav

샘플 오디오 파일 다운로드하기

[Response]

요청이 성공하면 multipart/form-data 타입으로 응답을 받습니다. 서브 파트는 json 객체로 아래 값을 포함합니다.

필드 설명
type 인식 서버에서 발생한 이벤트 명
value 인식 서버에서 이벤트가 발생했을 때 반환한 값
nBest 인식 결과 후보 리스트 (finalResult인 경우만)

type(발생할 수 있는 이벤트)에는 아래와 같은 값이 올 수 있습니다.

type 설명
beginPointDetection 사용자가 말하기 시작하는 것으로 판단되었을 때
partialResult 사용자가 말을 끝내기 전에 음성의 중간 인식 결과가 나왔을 때로, value에 중간 결과가 담김. 여러 번 발생할 수 있음
endPointDetection 사용자가 말하는 것을 끝마친 것으로 판단되었을 때
finalResult 사용자가 말한 음성의 최종 인식 결과가 나왔을 때로, value에 최종 인식 결과가 담김
errorCalled 음성 인식이 실패 했을 때로, value에 에러 메시지가 담김
음성 인식 에러 코드

음성 인식 API는 인식 실패 시, 아래와 같은 에러코드를 전달합니다. 에러코드 의미는 다음과 같습니다.

Error code Error message 설명
0 ERROR_NONE 오류 아님
1 ERROR_AUDIO 오디오 녹음 관련 오류
2 ERROR_NETWORK 네트웍 관련 오류
3 ERROR_NETWORK_TIMEOUT 네트웍 타임아웃
4 ERROR_NO_RESULT 결과 없음
5 ERROR_CLIENT_INETRNAL 클라이언트 내부 오류
6 ERROR_SERVER_INTERNAL 서버 내부 오류
7 ERROR_SERVER_TIMEOUT 서버 타임아웃
8 ERROR_SERVER_AUTHENTICATION 인증 실패
11 ERROR_SERVER_UNSUPPORT_SERVICE 음성서버에서 지원하지 않는 서비스 코드
12 ERROR_SERVER_USERDICT_EMPTY 사용자사전이 꼭 필요한 서비스에서 사용자사전이 비어있는 오류
13 ERROR_SERVER_ALLOWED_REQUESTS_EXCESS 음성 서비스 최대 허용 횟수 초과
15 ERROR_AUDIO_DATA_WAIT_TIMEOUT 오디오 데이터 대기 시간 초과 오류
17 ERROR_SERVER_OBSOLETE_SERVICE 더이상 서비스하지 않음

예를 들면,

HTTP/1.1 200 OK
Server: openresty
Content-Type: multipart/form-data; boundary=----newtoneVTbQxBkSwFtywRol; type="application/json"
Transfer-Encoding: chunked
Connection: keep-alive

------newtoneVTbQxBkSwFtywRol
Content-Type: application/json; charset=UTF-8

{"type":"beginPointDetection","value":"BPD"}
------newtoneVTbQxBkSwFtywRol
Content-Type: application/json; charset=UTF-8

{"type":"partialResult","value":"헤이"}
------newtoneVTbQxBkSwFtywRol
Content-Type: application/json; charset=UTF-8

{"type":"partialResult","value":"헤이 카카오"}
------newtoneVTbQxBkSwFtywRol
Content-Type: application/json; charset=UTF-8

{"type":"endPointDetection","value":"EPD"}
------newtoneVTbQxBkSwFtywRol
Content-Type: application/json; charset=UTF-8
Speech-Length: 2

{"type":"finalResult","value":"헤이 카카오","nBest":[{"value":"헤이 카카오","score":97},{"value":"헤이 카카오야","score":0}]}
------newtoneVTbQxBkSwFtywRol--

음성 합성 (뉴톤톡)

음성 합성 API는 문자 데이타를 사람이 이해할 수 있는 음성 언어로 변환하여 줍니다. 음성 합성 내부 규칙은 음성 합성 기본 내부 규칙을 참고해주세요.

[Request]

POST /v1/synthesize HTTP/1.1
Host: kakaoi-newtone-openapi.kakao.com
Content-Type: application/xml
Authorization: KakaoAK {rest_api_key}
  • xml 포맷으로 합성하고자 하는 텍스트를 요청 바디에 담아 전송합니다.
  • xml 의 root element는 speak 입니다.
  • 하위에는 유일하게 voice element만을 가지며 합성하고자 하는 문장 1줄을 의미합니다.
  • 아래는 voice element 가 가지는 attribute 목록입니다.
attribute name attribute value 설명
name WOMAN_READ_CALM 여성 차분한 낭독체 (default)
MAN_READ_CALM 남성 차분한 낭독체
WOMAN_DIALOG_BRIGHT 여성 밝은 대화체
MAN_DIALOG_BRIGHT 남성 밝은 대화체
speechStyle SS_READ_SPEECH 기본 속도
SS_ALT_FAST_1 빠르게
SS_ALT_SLOW_1 느리게

예를 들면,

curl -v -X POST "https://kakaoi-newtone-openapi.kakao.com/v1/synthesize" \
-H "Content-Type: application/xml" \
-H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk" \
-d '<speak>
<voice>그는 그렇게 말했습니다.</voice>
<voice name="MAN_DIALOG_BRIGHT">잘 지냈어? 나도 잘 지냈어.</voice>
<voice name="WOMAN_DIALOG_BRIGH" speechStyle="SS_ALT_FAST_1">금요일이 좋아요.</voice>
</speak>' > result.mp3

[Response]

요청이 성공하면, 응답 body에 mp3 데이터를 담아 보냅니다. 응답은 아래 헤더를 포함합니다.

헤더 설명
X-TTS-TEXT 합성 텍스트를 url-encoding 한 형태
X-TEXT-LENGTH 합성 텍스트의 총 글자수

예를 들면,

Content-Type: audio/mpeg
Transfer-Encoding: chunked
Connection: keep-alive
X-TTS-TEXT: %ec%95%88%eb%85%95%21+%eb%b0%98%ea%b0%80%ec%9b%8c.+%ec%9e%98+%ec%a7%80%eb%83%88%ec%96%b4%3f+%eb%82%98%eb%8f%84+%ec%9e%98+%ec%a7%80%eb%83%88%ec%96%b4.+%ea%b8%88%ec%9a%94%ec%9d%bc%ec%9d%b4+%ec%a2%8b%ec%95%84%ec%9a%94.
Server: Apache
Date: Mon, 21 Jan 2019 07:00:00 GMT
TTS-CACHE-VERSION: 5
X-TEXT-LENGTH: 48

카카오 음성 합성 기본 내부 규칙

1. 표준어 및 한글 사용
  • "카카오 음성 합성 엔진"은 한국어 문장 합성기로, 영어 문장 합성은 지원하지 않습니다.
    • 다만 흔히 사용하는 영어 단어, 약어, 유명인 이름, 기업명 등은 예외적으로 한국식 발음으로 읽습니다.
  • 사투리나 은어, 비속어, 오타등은 합성음이 부자연스러울 수 있습니다.
  • URL -> "링크", 이메일 주소->"이메일 주소" 라는 발음으로 변환됩니다.
  • 미리 정의된 "ㅋㅋ", "ㅎㅎ" 등의 대화체 단어는 아래와 같이 합성됩니다.
단어 합성음
ㅎㅎ 흐흐 (3개 이상부터 "흐흐흐"로 통일)
ㅋㅋ 크크 (3개 이상부터 "크크크"로 통일)
ㅇㅋ 오케이
ㅇㅇ
ㄴㄴ
ㅃㅇ 빠이
ㅎㅇ 하이
2. 적절한 문장 부호 사용
  • 쉼표, 마침표, 느낌표, 물음표 등의 문장부호를 적절하게 사용합니다.
  • 특히 쉼표를 이용하여, 합성음에서의 인위적인 끊어읽기를 유도할 수 있습니다.
3. 특수기호
  • 흔히 쓰이는 특수기호를 제외하고는, 합성시 무시됩니다.
  • 마침표(.), 물음표(?), 탭(\t). 뉴라인(\n)을 기준으로 문장을 분리합니다.
  • 한글 자소, 한자 및 외래어등은 합성시 무시됩니다.
  • 흔히 사용되는 특수기호는 다음과 같습니다.
특수기호 합성음
$ 달러
¥
£ 파운드
유로
°
섭씨
화씨
4. 허용하지 않는 문장
  • 피싱에 사용될 가능성이 높은 문장
  • 음란성 문장

변경내역

변경 날짜 변경 이력
2019.03.25 베타 서비스 개시
2019.04.12 xml 타입 오류일 때 http status code 400으로 수정

Last Modified : 2019-04-12