음성 합성 Streaming API

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

Endpoint

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

voice_id는 GET /v1/voices 응답에서 선택합니다. output_format은 mp3_44100_128 또는 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_id	path	string	예	사용할 음성 ID
output_format	query	string	아니요	mp3_44100_128 또는 wav_24000
text	body	string	예	합성할 텍스트
language_code	body	string	아니요	en, ko, ja, zh 중 하나
instruct	body	string	아니요	말하기 방식에 대한 자연어 지시

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

WebSocket Streaming API

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

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

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

{"text":"오늘도 ","xi_api_key":"<API_KEY>"}

{"text":"좋은 하루 보내세요.","flush":true}

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

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

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

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

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

{"text":""}

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

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