본문으로 건너뛰기

음성 합성 Streaming API

음성 합성 Streaming API는 텍스트와 voice_id를 받아 MP3, PCM 또는 WAV 음성을 HTTP stream이나 WebSocket message로 반환합니다. Base URL은 https://api.kitschlabs.com입니다.

Endpoint​

방식Endpoint용도
POST/v1/text-to-speech/{voice_id}/streamHTTP로 audio binary 수신
WSS/v1/text-to-speech/{voice_id}/stream-inputWebSocket으로 텍스트 전송 및 audio chunk 수신

voice_id는 GET /v1/voices 응답에서 선택합니다. output_format은 mp3_44100_128, pcm_24000 또는 wav_24000을 지원합니다.

HTTP Streaming API​

일반 음성 합성과 같은 JSON body를 보내고 선택한 형식의 audio binary를 stream으로 받습니다.

curl --request POST \
  "https://api.kitschlabs.com/v1/text-to-speech/<VOICE_ID>/stream?output_format=mp3_44100_128" \
  --header "xi-api-key: <API_KEY>" \
  --header "Content-Type: application/json" \
  --data '{
    "text": "오늘도 좋은 하루 보내세요.",
    "language_code": "ko"
  }' \
  --output speech.mp3
필드위치타입필수설명
voice_idpathstring예사용할 음성 ID
output_formatquerystring아니요mp3_44100_128, pcm_24000 또는 wav_24000
textbodystring예합성할 텍스트
language_codebodystring아니요en, ko, ja, zh 중 하나
instructbodystring아니요말하기 방식에 대한 자연어 지시

성공하면 audio/mpeg, audio/pcm 또는 audio/wav Content-Type의 binary response를 반환합니다.

pcm_24000은 header가 없는 24 kHz, mono, signed 16-bit little-endian PCM이며, 별도의 MP3 decode 없이 실시간 재생에 사용할 수 있습니다.

WebSocket Streaming API​

output_format과 language_code를 query parameter로 지정해 연결합니다.

wss://api.kitschlabs.com/v1/text-to-speech/<VOICE_ID>/stream-input?output_format=pcm_24000&language_code=ko

WebSocket handshake에 xi-api-key 헤더를 보내거나 첫 JSON message에 xi_api_key를 포함해 인증합니다. 한 음성을 생성할 텍스트를 message로 보내고 마지막 message에서 flush를 true로 설정합니다.

{"text":"오늘도 ","xi_api_key":"<API_KEY>","generation_config":{"chunk_length_schedule":[120,160,250,290]}}
{"text":"좋은 하루 보내세요.","flush":true}

generation_config.chunk_length_schedule은 audio chunk 생성을 시작할 텍스트 길이를 지정하는 선택 파라미터입니다. 50부터 500까지의 정수를 1개 이상 8개 이하로 전달하며, 기본값은 [120, 160, 250, 290]입니다.

서버는 base64 audio chunk를 반환합니다.

{"audio":"<BASE64_AUDIO_CHUNK>","isFinal":false}

pcm_24000에서는 생성 중 무음 PCM chunk가 반환될 수 있습니다. audio가 포함된 message는 무음 여부와 관계없이 audio stream의 일부로 처리하고, isFinal이 true인 message만 한 음성의 전송 종료로 판단해야 합니다.

한 음성의 전송이 끝나면 마지막 message를 반환합니다.

{"audio":null,"isFinal":true}

연결을 종료하려면 빈 text를 보냅니다.

{"text":""}

text는 string, flush는 boolean이어야 합니다. 잘못된 message나 요청은 error.status와 error.message를 포함한 JSON으로 반환될 수 있습니다.

HTTP 오류 코드와 재시도 기준은 음성 합성 API를 참고하세요.