페이지 이동경로
  • 문서>
  • 음성>
  • REST API

음성

개발 가이드

이 문서는 음성 REST API 사용 방법을 소개합니다.

주의

음성 인식 REST API는 현재 Beta 서비스 중입니다. Beta 서비스 중에는 기능의 변경이 발생하거나 일시적으로 서비스 접근이 불가할 수 있습니다.

변경 이력
변경 날짜 변경 사항
2019.03.25 베타 서비스 개시
2019.04.12 xml 타입 오류일 때 HTTP 상태 코드 400으로 수정
2019.07.23 데모 링크 추가
2019.10.14 카카오 SSML(Speech Synthesis Markup Language) 지원
음성인식 응답 헤더 X-STT-Session-Id 추가
음성합성 응답 헤더 X-TTS-Session-Id 추가
시작하기 전에

음성 인식/합성 API를 사용하려면 [내 애플리케이션] > [음성] > [활성화 설정] 항목을 'ON'으로 설정합니다.

음성 인식하기

음성 인식 API는 사람이 말하는 음성 언어를 컴퓨터가 해석해 문자 데이터로 변환하는 API입니다. 사람의 음성이 인식 될 때마다 중간 인식 결과를 반환하여 주며, 사람의 음성이 끝날 때 최종 인식 결과를 반환합니다. 음성 데이터는 Mono channel, 16000 Hz samplerate, 16 bit depth인 RAW PCM 포맷만 지원합니다.

음성 데이터를 POST로 전송합니다. 실시간 또는 크기가 큰 음성 파일의 전송은 Transfer-Encoding: chunked 헤더를 추가하고, chunk 단위로 전송합니다. 요청이 성공하면 multipart/form-data 타입으로 응답을 받으며, 요청 결과에 대한 헤더들을 포함합니다.

Request
URL
POST /v1/recognize HTTP/1.1
Host: kakaoi-newtone-openapi.kakao.com
Transfer-Encoding: chunked
Content-Type: application/octet-stream
Authorization: KakaoAK ${REST_API_KEY}
Response
Header
Name Description
X-STT-Session-Id 음성 인식 요청에 대한 unique session id
Field
Name Description
type 음성 인식 서버에서 발생한 이벤트 명
value 음성 인식 서버에서 이벤트가 발생했을 때 반환한 값
nBest 음성 인식 결과 후보 리스트 (finalResult인 경우만)
Type (발생할 수 있는 이벤트)
Type Description
beginPointDetection 사용자가 말하기 시작하는 것으로 판단되었을 때
partialResult 사용자가 말을 끝내기 전에 음성의 중간 인식 결과가 나왔을 때로, value에 중간 결과가 담김. 여러 번 발생할 수 있음
endPointDetection 사용자가 말하는 것을 끝마친 것으로 판단되었을 때
finalResult 사용자가 말한 음성의 최종 인식 결과가 나왔을 때로, value에 최종 인식 결과가 담김
errorCalled 음성 인식이 실패 했을 때로, value에 에러 메시지가 담김

음성 인식 에러 코드
Error code Error message Description
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 더이상 서비스하지 않음
Sample
Request
curl -v -X POST "https://kakaoi-newtone-openapi.kakao.com/v1/recognize" \
-H "Transfer-Encoding: chunked" \
-H "Content-Type: application/octet-stream" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \
--data-binary @heykakao.wav
Response: 성공
HTTP/1.1 200 OK
Server: openresty
Content-Type: multipart/form-data; boundary=----newtoneVTbQxBkSwFtywRol; type="application/json"
Transfer-Encoding: chunked
Connection: keep-alive
X-STT-Session-Id: 232ca0e9e99f5e2ba62fcfc7c91a6f8bb7bc28eb

------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는 문자 데이타를 사람이 이해할 수 있는 음성 언어로 변환하는 문자-음성 변환 시스템 (Text-to-Speech system)입니다. 음성 합성 내부 규칙은 음성 합성 기본 내부 규칙을 참고합니다.

xml(ssml) 포맷으로 합성하고자 하는 텍스트를 요청 바디에 담아 전송합니다. ssml 의 root element는 speak 이며 한 번만 등장합니다. speak 태그 하위에는 합성할 텍스트 또는 다른 ssml 태그가 올 수 있습니다. 요청이 성공하면 응답 바디에 MP3 데이터를 담아 보내며 요청 결과에 대한 헤더들을 포함합니다.

자세한 설명은 카카오 SSML 가이드를 참고합니다.

Request
URL
POST /v1/synthesize HTTP/1.1
Host: kakaoi-newtone-openapi.kakao.com
Content-Type: application/xml
Authorization: KakaoAK ${REST_API_KEY}
Response
header
Name Description
X-TTS-TEXT 합성 텍스트를 url-encoding 한 형태
X-TEXT-LENGTH 합성 텍스트의 총 글자수
X-TTS-Session-Id 합성 요청에 대한 unique session id
Sample
Request
curl -v -X POST "https://kakaoi-newtone-openapi.kakao.com/v1/synthesize" \
-H "Content-Type: application/xml" \
-H "Authorization: KakaoAK ${REST_API_KEY}" \
-d '<speak> 그는 그렇게 말했습니다. 
<voice name="MAN_DIALOG_BRIGHT">잘 지냈어? 나도 잘 지냈어.</voice> 
<voice name="WOMAN_DIALOG_BRIGHT" speechStyle="SS_ALT_FAST_1">금요일이 좋아요.</voice> </speak>' > result.mp3
Response
Content-Type: audio/mpeg
Transfer-Encoding: chunked
Connection: keep-alive
X-TTS-Session-Id: ca19616181a33854735251a5fcc79be8453278d1
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

더보기