텍스트 음성 변환

스트리밍 텍스트 음성 변환(Streaming TTS)

SDK

수동 HTTP 호출보다 안전하고 빠른 통합을 위해 SDK를 사용하세요.

SDK 가이드

실시간 스트리밍을 사용하여 텍스트에서 음성을 생성합니다. 전체 합성이 완료되기 전에 오디오 재생을 시작할 수 있습니다.

이 엔드포인트는 오디오 데이터를 청크 단위로 스트리밍하여 즉각적인 피드백이 필요한 애플리케이션에서 낮은 지연 시간의 오디오 재생을 가능하게 합니다.

스트리밍 형식:

WAV 형식: 첫 번째 청크에는 WAV 헤더(스트리밍용 size=0xFFFFFFFF)와 원시 PCM 데이터가 포함됩니다. 이후 청크에는 PCM 데이터만 포함됩니다.
MP3 형식: 각 청크에는 독립적으로 디코딩할 수 있는 후처리된 MP3 데이터가 포함됩니다.

사용 사례:

대화형 AI, 챗봇, 실시간 음성 비서 등
즉각적인 오디오 피드백이 필요한 인터랙티브 애플리케이션
전체 합성을 기다리는 것이 비실용적인 장문 콘텐츠

요청 파라미터: 표준 TTS 엔드포인트와 동일한 TTSRequest 스키마를 사용합니다. output.audio_format을 "wav" 또는 "mp3"로 설정하여 스트리밍 형식을 제어합니다.

POST/v1/text-to-speech/stream

cURL

# 스트리밍 오디오를 ffplay로 파이핑하여 실시간 재생.
# 사전 설치: ffmpeg (brew/choco/apt install ffmpeg)
curl -N -s --request POST \
  --url https://api.typecast.ai/v1/text-to-speech/stream \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data @- <<EOF | ffplay -autoexit -nodisp -loglevel error -i pipe:0
{
  "voice_id": "tc_60e5426de8b95f1d3000d7b5",
  "text": "문의해 주셔서 감사합니다. 금요일 오후 7시로 예약이 확정되었습니다.",
  "model": "ssfm-v30"
}
EOF

"[Binary audio stream - WAV chunks]"

인증

X-API-KEYstringheader필수

인증을 위한 API 키입니다. Typecast API 콘솔에서 API 키를 발급받을 수 있습니다.

본문

application/json

스트리밍 텍스트 음성 변환 요청 파라미터

seedinteger

재현 가능한 음성 생성을 위한 부호 없는 정수 시드. 동일한 시드와 동일한 입력 파라미터로 항상 같은 오디오 결과를 생성합니다.

0 이상의 정수만 허용됩니다. 음수 값은 사용할 수 없습니다.
생략하면 서버가 매번 랜덤 시드를 생성하여 약간의 변이가 발생합니다.

textstringrequired

음성으로 변환할 텍스트. 최소 1자, 최대 2000자. 텍스트 길이에 따라 크레딧이 소비됩니다. 영어, 한국어, 일본어, 중국어를 포함한 여러 언어를 지원합니다. 특수 문자와 구두점은 자동으로 처리됩니다.

modelssfm-v30 | ssfm-v21required

음성 합성에 사용할 보이스 모델.

ssfm-v30: 향상된 플로우와 추가 감정 프리셋이 있는 최신 모델(권장)
ssfm-v21: 빠르고 안정적인 모델로 신뢰할 수 있는 품질 제공

ssfm-v30ssfm-v21

outputobject

피치(-12 ~ +12 반음), 속도(0.5x ~ 2.0x), 형식(wav/mp3), target_lufs(-70 ~ 0 LUFS) 등 스트리밍 오디오 출력 설정. 참고: 스트리밍 모드에서는 volume을 사용할 수 없습니다.

Show nested model

audio_pitchinteger

성별과 나이에 영향을 주는 반음 단위의 피치 조정: -12(한 옥타브 낮게, 더 깊은 목소리), -6(반 옥타브 낮게), 0(원래 피치, 기본값), +6(반 옥타브 높게), +12(한 옥타브 높게, 더 높은 목소리)

audio_temponumber

음성 속도 제어: 0.5(절반 속도, 매우 느리고 명확함), 0.75(보통보다 약간 느림), 1.0(보통 말하기 속도, 기본값), 1.5(보통보다 50% 빠름), 2.0(두 배 속도, 매우 빠른 음성)

target_lufsinteger

스트리밍 출력 음성의 목표 절대 음량(LUFS) 설정. 원본 음성의 크기와 상관없이 일정한 라우드니스로 정규화합니다. volume 파라미터와 함께 사용할 수 없습니다.

권장값: -14(일반적인 스트리밍 표준), -23(방송 표준).

audio_formatwav | mp3

스트리밍용 출력 오디오 형식.

WAV 형식:

비압축 PCM 오디오
16비트 깊이, 모노 채널, 32000 Hz 샘플링 속도
청크 단위 전송: 첫 번째 청크는 WAV 헤더(size = 0xFFFFFFFF)를 포함하고, 이후 청크에는 원시 PCM 데이터가 이어집니다
도착하는 즉시 오디오를 재생하고 싶을 때 권장

MP3 형식:

압축된 MPEG Layer III 오디오
320 kbps 비트레이트, 44100 Hz 샘플링 속도
청크 단위 전송: 각 청크에는 독립적으로 디코딩 가능한 MPEG 프레임이 포함됩니다
대역폭이 제한된 클라이언트에 권장

wavmp3

promptPrompt

생성된 음성의 감정 및 스타일 설정, 감정 유형(happy/sad/angry/normal) 및 강도(0.0~2.0)를 포함하여 감정 표현을 제어합니다

스마트 프롬프트 (ssfm-v30)

next_textstring

TTSRequest의 text 필드 이후에 오는 텍스트. 감정 추론을 위한 전방 컨텍스트를 제공합니다.

모델은 흐름을 분석합니다: previous_text → text(합성됨) → next_text

최대 2000자
모델이 감정 전환을 예측하는 데 도움
다음 컨텍스트가 없으면 비워 둡니다

emotion_typestring

프롬프트 유형을 식별하는 판별자 필드. 컨텍스트 인식 감정 추론을 위해 "smart"로 설정해야 합니다.

previous_textstring

TTSRequest의 text 필드 이전에 오는 텍스트. 감정 추론을 위한 후방 컨텍스트를 제공합니다.

모델은 흐름을 분석합니다: previous_text → text(합성됨) → next_text

최대 2000자
모델이 감정 빌드업과 컨텍스트를 이해하는 데 도움
이전 컨텍스트가 없으면 비워 둡니다

프리셋 프롬프트 (ssfm-v30)

emotion_typestring

프롬프트 유형을 식별하는 판별자 필드. 프리셋 기반 감정 제어를 위해 "preset"으로 설정해야 합니다.

생성된 음성에 적용할 감정 프리셋.

지원되는 감정: normal, happy, sad, angry, whisper, toneup, tonedown

/v2/voices API를 통해 각 보이스에 사용 가능한 감정을 확인하세요.

normalsadhappyangrywhispertoneuptonedown

emotion_intensitynumber

생성된 음성의 감정 표현 강도를 제어합니다.

0.0: 완전히 중립적, 감정 색채 없음
0.5: 미묘한 감정 힌트
1.0: 표준 감정 표현(기본값)
1.5: 강한 감정 강조
2.0: 최대 강도, 매우 표현력 있음

프롬프트 (ssfm-v21)

emotion_presetobject

적용할 감정 프리셋.

ssfm-v21 지원 감정: normal, happy, sad, angry

/v2/voices API를 통해 각 보이스에 사용 가능한 감정을 확인하세요.

emotion_intensityobject

감정 표현 강도 제어(0.0~2.0).

0.0: 완전히 중립적
1.0: 표준 표현(기본값)
2.0: 최대 강도

languagestring

ISO 639-3 표준을 따르는 언어 코드. 대소문자 구분 안 함("KOR"과 "kor" 모두 허용). 제공하지 않으면 텍스트 내용을 기반으로 자동 감지됩니다.

ssfm-v30 지원 언어 (37개)

코드	언어
ARA	아랍어
IND	인도네시아어
POR	포르투갈어
BEN	벵골어
ITA	이탈리아어
RON	루마니아어
BUL	불가리아어
JPN	일본어
RUS	러시아어
CES	체코어
KOR	한국어
SLK	슬로바키아어
DAN	덴마크어
MSA	말레이어
SPA	스페인어
DEU	독일어
NAN	민남어
SWE	스웨덴어
ELL	그리스어
NLD	네덜란드어
TAM	타밀어
ENG	영어
NOR	노르웨이어
TGL	타갈로그어
FIN	핀란드어
PAN	펀자브어
THA	태국어
FRA	프랑스어
POL	폴란드어
TUR	터키어
HIN	힌디어
UKR	우크라이나어
VIE	베트남어
HRV	크로아티아어
YUE	광둥어
ZHO	중국어
HUN	헝가리어

ssfm-v21 지원 언어 (27개)

코드	언어
ARA	아랍어
IND	인도네시아어
RON	루마니아어
BUL	불가리아어
ITA	이탈리아어
RUS	러시아어
CES	체코어
JPN	일본어
SLK	슬로바키아어
DAN	덴마크어
KOR	한국어
SPA	스페인어
DEU	독일어
MSA	말레이어
SWE	스웨덴어
ELL	그리스어
NLD	네덜란드어
TAM	타밀어
ENG	영어
POL	폴란드어
TGL	타갈로그어
FIN	핀란드어
POR	포르투갈어
UKR	우크라이나어
FRA	프랑스어
HRV	크로아티아어
ZHO	중국어

voice_idstringrequired

보이스 식별자. 두 가지 prefix 를 지원합니다.

tc_ — 기본 제공되는 타입캐스트 보이스 (예: tc_60e5426de8b95f1d3000d7b5). 사용 가능한 ID 는 보이스 목록 조회 를 참조하세요.
uc_ — 퀵 클로닝 으로 생성한 커스텀 보이스 (예: uc_64a1b2c3d4e5f6a7b8c9d0e1). 본인이 소유한 클로닝 보이스만 사용할 수 있습니다.

대소문자 구분: prefix 는 소문자만 사용합니다.

응답

200Success - Returns streaming audio data in chunksaudio/wav · audio/mpeg

cURL

# 스트리밍 오디오를 ffplay로 파이핑하여 실시간 재생.
# 사전 설치: ffmpeg (brew/choco/apt install ffmpeg)
curl -N -s --request POST \
  --url https://api.typecast.ai/v1/text-to-speech/stream \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data @- <<EOF | ffplay -autoexit -nodisp -loglevel error -i pipe:0
{
  "voice_id": "tc_60e5426de8b95f1d3000d7b5",
  "text": "문의해 주셔서 감사합니다. 금요일 오후 7시로 예약이 확정되었습니다.",
  "model": "ssfm-v30"
}
EOF

"[Binary audio stream - WAV chunks]"