General TTS API Reference

General TTS API는 텍스트의 음성 변환(Text to Speech)을 지원합니다. General TTS API를 호출할 때 필요한 정보는 다음과 같습니다.

Request

General TTS API의 요청 Syntax, Header, Body는 다음과 같습니다.

Request Syntax

코드 예제 Request Syntax

curl -v
  -H "x-api-key: {API Key}" \
  -H "Content-Type: application/xml" \
  -H "X-TTS-Engine: {Engine}" \
  -H "X-TTS-Encoding: {Encoding 방식}" \
  -H "X-TTS-Samplerate: {Sample Rate}" \
  -d '<speak>
      <voice name="Summer">신난다</voice>
    </speak>' \
{API Endpoint URL}

메서드	요청 URL
POST	{API Endpoint URL} - API 호출 시 필요한 Endpoint 경로 - 카카오 i 클라우드 콘솔 > 도메인 목록 > AI API 인증정보 > API Endpoint URL에서 조회

Request Header

파라미터	타입	필수 여부	설명
x-api-key	String	필수	{API Key} - 카카오 i 클라우드 콘솔 > 도메인 목록 > AI API 인증정보 > API Key에서 조회
Content-Type	String	필수	application/xml로 고정
X-TTS-Engine	String	필수	{Engine} - 음성 합성 방식 - plain: 사전에 녹음한 음성 데이터를 연결하여 합성 - deep: 딥러닝 방식으로 자연스러운 음성 합성
X-TTS-Encoding	String	선택	{Encoding 방식} - 출력 포맷 - mp3(기본값), RAWPCM
X-TTS-Samplerate	Integer	선택	{Sample Rate} - 샘플링 속도 (1초당 추출되는 샘플 개수) - 22050(기본값), 44100

Request Body

요청 Body는 SSML 형식의 합성 요청 텍스트를 포함합니다. SSML 지원 사항에 대한 자세한 설명은 SSML 가이드를 참고하시기 바랍니다.

표 SSML 지원 태그 및 어트리뷰트 목록

태그	필수 여부	속성	설명
<speak>	필수	-	SSML의 루트 요소 - 음성 변환할 전체 텍스트에 적용
<voice>	선택	name	음색 설정 - 지정 가능한 음색은 요청의 X-TTS-Engine 값에 따라 상이함 - 지정하지 않으면 Summer(기본값)으로 합성하여 응답
<prosody>	선택	rate volume	음성 속도와 음량 지정
<break>	선택	time	끊어 읽기 지정
<kakao:effect>	선택	tone	존댓말을 반말로 전환해 음성 변환
<say-as>	선택	interpret-as format	알파벳 읽기, 고유어/한자어 숫자 발음 등 텍스트 발음법 설정 - 하위에 카카오 커스텀 태그 포함
<sub>	선택	alias	텍스트의 발음 직접 입력
<audio>	선택	clipBegin clipEnd repeatCount repeatDur soundLevel src speed	합성한 음성에 외부 음원 삽입

Sample Code

안내
아래 예제 코드는 모두 음성 합성 결과 바이너리 파일을 test.mp3으로 저장하도록 요청합니다.

예제 코드 한 문장을 하나의 기본 목소리(Summer)로 합성: Plain Voice / 기본값 (mp3 22k)

curl -v \
  -H "x-api-key: {API Key}" \
  -H "Content-Type: application/xml" \
  -H "X-TTS-Engine: plain" \
  -d '<speak>신난다</speak>' \
{API Endpoint URL} > test.mp3

예제 코드 여러 문장을 서로 다른 목소리로 합성: Plain Voice / 기본값 (mp3 22k)

curl -v \
  -H "x-api-key: {API Key}" \
  -H "Content-Type: application/xml" \
  -H "X-TTS-Engine: plain" \
  -d '<speak>
      <voice name="Summer">안녕하세요. 반가워요.</voice>
      <voice name="Roman">잘 지냈어요?</voice>
    </speak>' \
{API Endpoint URL} > test.mp3

예제 코드 여러 문장을 서로 다른 목소리로 합성: Deep Voice / 기본값 (mp3 22k)

curl -v \
  -H "x-api-key: {API Key}" \
  -H "Content-Type: application/xml" \
  -H "X-TTS-Engine: deep" \
  -d '<speak>
      <voice name="Summer">안녕하세요. 반가워요.</voice>
      <voice name="Roman">잘 지냈어요?</voice>
    </speak>' \
{API Endpoint URL} > test.mp3

Response

General TTS의 응답 Syntax, Header, Body는 다음과 같습니다.

Response Syntax

HTTP/1.1 200 OK
Server: nginx
Date: Thu, 28 Apr 2022 12:27:20 GMT
Content-Type: audio/mpeg
Transfer-Encoding: chunked
Connection: keep-alive
X-Request-Id: {request-id}
X-Tts-Length: {int}
X-Tts-Session-Id: {session-id}
X-Tts-Text: {합성 텍스트의 url 인코딩 결과}
X-Metering-Count: {int}
X-kic-product-id: {int}

Response Header

필드	타입	설명
Content-Type	String	audio/mpeg 으로 고정
X-Request-Id	String	클라이언트와 공유하는 Request ID
X-Tts-Length	Integer	합성한 텍스트의 길이 (글자 수, 공백 및 구두점 포함)
X-Tts-Session-Id	String	TTS 서버에 의해 부여된 세션 ID
X-Tts-Text	String	합성 텍스트의 URL 인코딩 결과
X-Metering-Count	Integer	변환 요청한 텍스트의 글자 수 (공백 및 구두점 포함) 및 요청한 X-TTS-Engine에 따른 카카오 i 클라우드 상품 ID - 미터링 기준치로 활용
X-kic-product-id	String	카카오 i 클라우드 상품 ID - 요청의 X-TTS-Engine 값에 따라 반환

Response Body

요청한 X-TTS-Encoding 형식의 오디오 바이너리 데이터로 응답합니다.

Status Code

응답 코드	응답 내용	설명
200	-	API 호출 성공
400	BAD_REQUEST	요청 Method가 표준이 아닐 경우
400	INVALID_AUDIO_FORMAT	지원하지 않는 오디오 포맷으로 요청한 경우
400	INVALID_SIGNATURE	요청 Endpoint 주소의 signature가 잘못된 경우
400	INVALID_SSML	요청한 SSML이 잘못되었을 경우
400	INVALID_SPEAKER	Plain Voice 에서 지원하지 않는 목소리로 요청한 경우
400	INVALID_TTS_ENGINE	지원하지 않는 TTS 엔진 유형으로 요청한 경우
400	NO_CONTENT	비어 있는 요청을 보냈거나, 외부 음원 다운로드에 실패한 경우
400	NOT_MATCHED	가이드에 존재하지 않는 음성으로 요청한 경우 -ex. voice name="kakao"
400	TTS_TEXT_ERROR	합성 요청 텍스트에 문제가 있는 경우
401	Authentication failed	x-api-key 값이 잘못된 경우
403	Forbidden	x-api-key 헤더가 없는 경우
404	NOT_FOUND	- API가 지원하지 않는 Method로 요청한 경우 - API Endpoint URL이 올바르지 않은 경우
405	Method Not Allowed	카카오 i 클라우드가 지원하지 않는 Method로 요청한 경우
413	Request Entity Too Large	요청의 크기가 제한보다 큰 경우
415	Unsupported content type	Content Type 헤더가 없거나 규격에 맞지 않는 경우
425	DOMAIN_NOT_FOUND	요청한 도메인이 삭제되어 없을 경우
425	DOMAIN_NOT_DEPLOYED	요청한 도메인이 아직 배포되지 않은 경우
429	Too many Requests	설정한 한도를 초과해서 요청한 경우
503	INTERNAL_SERVER_ERROR	예상하지 못한 서버 오류가 발생한 경우