텍스트 음성 변환

타임스탬프 포함 텍스트 음성 변환(TTS with Timestamps)

SDK

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

텍스트로부터 음성을 생성하면서 단어·문자 단위 타임스탬프를 함께 반환합니다. 자막 싱크, 문자 단위 하이라이트 애니메이션, 발화 구간 시각화 등에 활용할 수 있습니다.

요청 본문은 표준 /v1/text-to-speech 엔드포인트와 동일합니다(voice_id, text, model, language, prompt, output). 응답은 바이너리 오디오가 아닌 JSON 이며, base64 로 인코딩된 오디오와 함께 words / characters 배열을 포함합니다.

필요에 따라 granularity 쿼리 파라미터로 단어 단위 또는 문자 단위 중 한쪽만 받아 응답 크기를 줄일 수 있습니다.

언어 주의. 일본어(jpn), 중국어(zho) 처럼 단어 사이에 공백이 없는 언어는 word 단위 정렬이 문장 전체를 하나의 "단어" 로 묶어 버립니다. 이런 언어에서는 항상 granularity=char 를 지정해 문자 단위 타임스탬프를 받으세요.

사용 가능한 보이스 목록은 보이스 목록 조회 를 참조하세요.

POST/v1/text-to-speech/with-timestamps

cURL

curl --request POST \
  --url https://api.typecast.ai/v1/text-to-speech/with-timestamps \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data @- <<EOF
{
  "voice_id": "tc_60e5426de8b95f1d3000d7b5",
  "text": "집중력이 떨어질 땐 5분간 스트레칭을 해보세요.",
  "model": "ssfm-v30",
  "language": "kor",
  "prompt": {
    "emotion_type": "preset",
    "emotion_preset": "normal",
    "emotion_intensity": 1.0
  }
}
EOF

{
  "audio": "UklGRs...(base64 오디오 생략)",
  "words": [
    {
      "end": 0.76,
      "text": "집중력이",
      "start": 0.08
    },
    {
      "end": 1.26,
      "text": "떨어질",
      "start": 0.8
    },
    {
      "end": 1.52,
      "text": "땐",
      "start": 1.3
    },
    {
      "end": 2.02,
      "text": "5분간",
      "start": 1.56
    },
    {
      "end": 2.7,
      "text": "스트레칭을",
      "start": 2.06
    },
    {
      "end": 3.2,
      "text": "해보세요.",
      "start": 2.74
    }
  ],
  "characters": [
    {
      "end": 0.26,
      "text": "집",
      "start": 0.08
    },
    {
      "end": 0.43,
      "text": "중",
      "start": 0.26
    },
    {
      "end": 0.6,
      "text": "력",
      "start": 0.43
    },
    {
      "end": 0.76,
      "text": "이",
      "start": 0.6
    },
    {
      "end": 0.8,
      "text": " ",
      "start": 0.76
    },
    {
      "end": 0.94,
      "text": "떨",
      "start": 0.8
    },
    {
      "end": 1.1,
      "text": "어",
      "start": 0.94
    },
    {
      "end": 1.26,
      "text": "질",
      "start": 1.1
    },
    {
      "end": 1.3,
      "text": " ",
      "start": 1.26
    },
    {
      "end": 1.52,
      "text": "땐",
      "start": 1.3
    },
    {
      "end": 1.56,
      "text": " ",
      "start": 1.52
    },
    {
      "end": 1.68,
      "text": "5",
      "start": 1.56
    },
    {
      "end": 1.84,
      "text": "분",
      "start": 1.68
    },
    {
      "end": 2.02,
      "text": "간",
      "start": 1.84
    },
    {
      "end": 2.06,
      "text": " ",
      "start": 2.02
    },
    {
      "end": 2.18,
      "text": "스",
      "start": 2.06
    },
    {
      "end": 2.3,
      "text": "트",
      "start": 2.18
    },
    {
      "end": 2.42,
      "text": "레",
      "start": 2.3
    },
    {
      "end": 2.56,
      "text": "칭",
      "start": 2.42
    },
    {
      "end": 2.7,
      "text": "을",
      "start": 2.56
    },
    {
      "end": 2.74,
      "text": " ",
      "start": 2.7
    },
    {
      "end": 2.88,
      "text": "해",
      "start": 2.74
    },
    {
      "end": 3.02,
      "text": "보",
      "start": 2.88
    },
    {
      "end": 3.14,
      "text": "세",
      "start": 3.02
    },
    {
      "end": 3.18,
      "text": "요",
      "start": 3.14
    },
    {
      "end": 3.2,
      "text": ".",
      "start": 3.18
    }
  ],
  "audio_format": "wav",
  "audio_duration": 3.2
}

인증

X-API-KEYstringheader필수

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

쿼리 매개변수

granularityword | char

반환할 타임스탬프 배열을 선택합니다.

생략: words 와 characters 모두 반환
word: words 만 반환 (characters 는 null)
char: characters 만 반환 (words 는 null)

공백 없는 언어(예: jpn, zho): word 정렬은 문장 전체를 하나의 구간으로 반환하므로, 의미 있는 타임스탬프를 얻으려면 char 를 사용하세요.

wordchar

본문

application/json

TTSRequestWith-timestamps parameters

textstringrequired

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

modelssfm-v30 | ssfm-v21required

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

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

ssfm-v30ssfm-v21

outputobject

볼륨(0-200), 피치(-12~+12 반음), 템포(0.5배~2.0배), 형식(wav/mp3)을 포함한 오디오 출력 설정으로 최종 오디오 특성을 제어합니다

remove_silence_ms(정수, 0~1000ms)로 검출된 무음 구간을 줄일 수 있습니다.

Show nested model

volumeinteger

출력 음성의 상대적인 음량 조절: 0(완전 무음), 50(절반 볼륨), 100(표준 볼륨, 기본값), 150(표준보다 50% 크게), 200(최대 볼륨, 표준의 두 배).

출력된 음성마다 음량이 다를 경우, 단순 비율 조절인 volume을 사용하면 음성 간의 음량 편차가 더욱 커질 수 있습니다. 일정한 음량 출력이 필요한 경우 target_lufs 사용을 권장합니다.

주의: target_lufs와 동시에 사용할 수 없습니다.

필수 범위: 0 <= x <= 200

audio_pitchinteger

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

audio_temponumber

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

target_lufsnumber

출력 음성의 목표 절대 음량(LUFS) 설정. 원본 음성의 크기와 상관없이 모든 음성을 일정한 크기로 정규화하여 생성합니다. 값이 0에 가까울수록 소리가 커지며, -70에 가까울수록 작아집니다.

필수 범위: -70 <= x <= 0
권장값: -14 (일반적인 스트리밍 표준), -23 (방송 표준)
주의: volume 파라미터와 함께 사용할 수 없습니다. 절대적인 음량 기준이 필요할 때는 target_lufs를, 상대적인 비율 조절이 필요할 때는 volume을 선택하여 사용하세요.

audio_formatwav | mp3

출력 오디오 형식.

WAV 형식:

비압축 PCM 오디오
16비트 깊이, 모노 채널, 44100 Hz 샘플링 속도
더 높은 품질, 더 큰 파일 크기
전문 오디오 제작에 권장

MP3 형식:

압축된 MPEG Layer III 오디오
320 kbps 비트레이트, 44100 Hz 샘플링 속도
더 작은 파일 크기
웹 스트리밍 및 배포에 권장

wavmp3

remove_silence_msinteger

무음 제거를 적용하면 음성 내 무음 구간 중 지정한 길이보다 긴 구간을 해당 길이로 줄입니다. 단위는 밀리초(ms)입니다. 지정값은 제거할 시간이 아니라 남길 무음 길이입니다.

입력값:

0부터 1000까지의 정수, 권장 범위는 0~200.
생략 또는 null: 무음 제거를 적용하지 않습니다.
0: 0ms 초과의 무음을 제거합니다. 기능을 끄는 값이 아닙니다.
불리언·문자열·소수·범위 밖 값은 허용하지 않습니다.

예시: 100을 지정하면 음성 내 무음 구간 중 100ms보다 긴 구간을 100ms로 줄입니다. 값이 작을수록 더 짧은 무음 구간까지 제거 대상에 포함되고, 각 구간에서 남기는 무음도 짧아집니다.

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

GET /v3/voices API 응답의 models 필드에서 각 보이스에 사용 가능한 감정을 확인하세요.

normalsadhappyangrywhispertoneuptonedown

emotion_intensitynumber

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

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

프롬프트 (ssfm-v21)

emotion_presetobject

적용할 감정 프리셋.

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

GET /v3/voices API 응답의 models 필드에서 각 보이스에 사용 가능한 감정을 확인하세요.

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	중국어

타임스탬프 엔드포인트 주의. 일본어(jpn) · 중국어(zho) 처럼 단어 사이에 공백이 없는 언어는 word 단위 정렬이 문장 전체를 하나의 구간으로 묶어 버립니다. 이런 언어에서는 항상 granularity=char 를 함께 지정해 문자 단위 타임스탬프를 받으세요.

voice_idstringrequired

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

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

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

응답

200Success - Returns base64 audio and timestampsapplication/json

audiostring

base64 로 인코딩된 오디오 바이트. audio_format 확장자로 디코딩해 파일로 저장할 수 있습니다.

wordsobject[]

단어 단위 타임스탬프(문장부호 포함). 요청이 granularity=char 일 때는 null.

Show nested model

endnumber

이 구간의 종료 시각(오디오 시작 기준 초).

textstring

원본 transcript 의 텍스트 조각 (문장부호 포함).

startnumber

이 구간의 시작 시각(오디오 시작 기준 초).

charactersobject[]

문자 단위 타임스탬프(문장부호와 공백 포함). 요청이 granularity=word 일 때는 null.

Show nested model

endnumber

이 구간의 종료 시각(오디오 시작 기준 초).

textstring

원본 transcript 의 텍스트 조각 (문장부호/공백 포함).

startnumber

이 구간의 시작 시각(오디오 시작 기준 초).

audio_formatwav | mp3

audio 필드의 오디오 인코딩 포맷 — wav 또는 mp3 (요청의 output.audio_format 에 따라 결정).

wavmp3

audio_durationnumber

생성된 오디오의 길이(초).

cURL

curl --request POST \
  --url https://api.typecast.ai/v1/text-to-speech/with-timestamps \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data @- <<EOF
{
  "voice_id": "tc_60e5426de8b95f1d3000d7b5",
  "text": "집중력이 떨어질 땐 5분간 스트레칭을 해보세요.",
  "model": "ssfm-v30",
  "language": "kor",
  "prompt": {
    "emotion_type": "preset",
    "emotion_preset": "normal",
    "emotion_intensity": 1.0
  }
}
EOF

{
  "audio": "UklGRs...(base64 오디오 생략)",
  "words": [
    {
      "end": 0.76,
      "text": "집중력이",
      "start": 0.08
    },
    {
      "end": 1.26,
      "text": "떨어질",
      "start": 0.8
    },
    {
      "end": 1.52,
      "text": "땐",
      "start": 1.3
    },
    {
      "end": 2.02,
      "text": "5분간",
      "start": 1.56
    },
    {
      "end": 2.7,
      "text": "스트레칭을",
      "start": 2.06
    },
    {
      "end": 3.2,
      "text": "해보세요.",
      "start": 2.74
    }
  ],
  "characters": [
    {
      "end": 0.26,
      "text": "집",
      "start": 0.08
    },
    {
      "end": 0.43,
      "text": "중",
      "start": 0.26
    },
    {
      "end": 0.6,
      "text": "력",
      "start": 0.43
    },
    {
      "end": 0.76,
      "text": "이",
      "start": 0.6
    },
    {
      "end": 0.8,
      "text": " ",
      "start": 0.76
    },
    {
      "end": 0.94,
      "text": "떨",
      "start": 0.8
    },
    {
      "end": 1.1,
      "text": "어",
      "start": 0.94
    },
    {
      "end": 1.26,
      "text": "질",
      "start": 1.1
    },
    {
      "end": 1.3,
      "text": " ",
      "start": 1.26
    },
    {
      "end": 1.52,
      "text": "땐",
      "start": 1.3
    },
    {
      "end": 1.56,
      "text": " ",
      "start": 1.52
    },
    {
      "end": 1.68,
      "text": "5",
      "start": 1.56
    },
    {
      "end": 1.84,
      "text": "분",
      "start": 1.68
    },
    {
      "end": 2.02,
      "text": "간",
      "start": 1.84
    },
    {
      "end": 2.06,
      "text": " ",
      "start": 2.02
    },
    {
      "end": 2.18,
      "text": "스",
      "start": 2.06
    },
    {
      "end": 2.3,
      "text": "트",
      "start": 2.18
    },
    {
      "end": 2.42,
      "text": "레",
      "start": 2.3
    },
    {
      "end": 2.56,
      "text": "칭",
      "start": 2.42
    },
    {
      "end": 2.7,
      "text": "을",
      "start": 2.56
    },
    {
      "end": 2.74,
      "text": " ",
      "start": 2.7
    },
    {
      "end": 2.88,
      "text": "해",
      "start": 2.74
    },
    {
      "end": 3.02,
      "text": "보",
      "start": 2.88
    },
    {
      "end": 3.14,
      "text": "세",
      "start": 3.02
    },
    {
      "end": 3.18,
      "text": "요",
      "start": 3.14
    },
    {
      "end": 3.2,
      "text": ".",
      "start": 3.18
    }
  ],
  "audio_format": "wav",
  "audio_duration": 3.2
}