인증 시작하기
타입캐스트 API를 사용하려면 API 키로 요청을 인증해야 합니다. 다음 단계를 따르세요:
첫 번째 단계 타입캐스트 API 콘솔에서 무료 또는 유료 API 플랜을 시작한 뒤 자동 발급된 API 키를 확인하세요.
두 번째 단계 API 키를 안전하게 보관하세요 - 환경 변수로 저장하는 것을 권장합니다
SSFM 3.1
먼저 model=ssfm-v31로 보이스를 조회하고, 응답의 models에 ssfm-v31이 포함된 보이스를 선택합니다. 다음 요청의 <voice_id_from_v31_list>를 해당 voice_id로 바꾸세요.
curl --request GET \
--url 'https://api.typecast.ai/v3/voices?model=ssfm-v31' \
--header "X-API-KEY: $TYPECAST_API_KEY"
curl --request POST \
--url 'https://api.typecast.ai/v1/text-to-speech' \
--header "X-API-KEY: $TYPECAST_API_KEY" \
--header 'Content-Type: application/json' \
--data '{"voice_id":"<voice_id_from_v31_list>","text":"안녕하세요. 타입캐스트입니다.","model":"ssfm-v31","prompt":{"emotion_type":"preset","emotion_preset":"normal"}}' \
--output speech.wav
첫 번째 요청 실행하기
SDK 설치 pip install --upgrade typecast-python가져오기 및 초기화 from typecast import Typecast from typecast.models import TTSRequest, SmartPrompt # 클라이언트 초기화 client = Typecast(api_key="YOUR_API_KEY") # 텍스트를 음성으로 변환 response = client.text_to_speech(TTSRequest( text="Everything is going to be okay.", model="ssfm-v31", voice_id="tc_674fc11f6720f4e7cf72f3f9", prompt=SmartPrompt( emotion_type="smart", previous_text="I just got the best news!", next_text="I can't wait to celebrate!" ) )) # 오디오 파일 저장 with open('typecast.wav', 'wb') as f: f.write(response.audio_data)
모든 보이스 목록 조회하기
타입캐스트를 효과적으로 사용하려면 Voice ID에 액세스해야 합니다. 최신 /v3/voices 엔드포인트는 다국어 이름, 지원 모델, 감정, 미리듣기 메타데이터가 포함된 보이스 목록을 제공합니다.
모델, 성별, 연령대 및 사용 사례 등의 선택적 쿼리 파라미터를 사용하여 보이스를 필터링할 수 있습니다.
from typecast import Typecast
from typecast.models import VoicesV2Filter, TTSModel
# 클라이언트 초기화
client = Typecast(api_key="YOUR_API_KEY")
# 모든 음성 가져오기 (선택적으로 모델, 성별, 나이, 사용 사례로 필터링)
voices = client.voices_v3(VoicesV2Filter(model=TTSModel.SSFM_V31))
print(f"Found {len(voices)} voices:")
for voice in voices:
for model in voice.models:
print(f"ID: {voice.voice_id}, Name: {voice.voice_name.kor}, Model: {model.version.value}, Emotions: {', '.join(model.emotions)}")
응답은 각각 다음을 포함하는 음성 객체의 JSON 배열입니다:
{
"voice_id": "tc_674fc11f6720f4e7cf72f3f9",
"voice_name": {"eng": "Dylan", "kor": "딜런"},
"models": [
{
"version": "ssfm-v31",
"emotions": ["normal", "happy", "sad", "angry", "whisper", "toneup", "tonedown"]
}
],
"gender": "male",
"age": "young_adult",
"use_cases": ["Conversational", "TikTok/Reels/Shorts", "Audiobook/Storytelling"],
"voice_type": "original",
"preview_url": "https://..."
}
실시간 오디오 스트리밍
저지연 애플리케이션의 경우, 스트리밍 엔드포인트를 사용하여 전체 합성을 기다리지 않고 오디오 청크가 도착하는 즉시 재생할 수 있습니다.
WAV 스트리밍 형식: 32000 Hz, 16비트, 모노 PCM. 첫 번째 청크에 44바이트 WAV 헤더가 포함되며, 이후 청크는 원시 PCM 데이터만 포함합니다.
# pip install typecast-python sounddevice
import sounddevice as sd
from typecast import Typecast
from typecast.models import TTSRequestStream, OutputStream
client = Typecast(api_key="YOUR_API_KEY")
request = TTSRequestStream(
text="이 텍스트를 실시간으로 오디오로 스트리밍합니다.",
model="ssfm-v31",
voice_id="tc_674fc11f6720f4e7cf72f3f9",
output=OutputStream(audio_format="wav", target_lufs=-14.0)
)
with sd.RawOutputStream(samplerate=32000, channels=1, dtype="int16") as player:
buf, first = bytearray(), True
for chunk in client.text_to_speech_stream(request):
if first:
chunk = chunk[44:] # 44바이트 WAV 헤더 건너뛰기
first = False
buf.extend(chunk)
n = len(buf) - (len(buf) % 2) # int16 정렬
if n:
player.write(bytes(buf[:n]))
del buf[:n]
타임스탬프 TTS로 자막 생성하기
POST /v1/text-to-speech/with-timestamps를 사용하면 오디오와 함께 단어 단위 정렬 데이터를 받아 자막, 가라오케, 립싱크 애플리케이션을 만들 수 있습니다.
from typecast import Typecast
from typecast.models import TTSRequestWithTimestamps
client = Typecast(api_key="YOUR_API_KEY")
response = client.text_to_speech_with_timestamps(TTSRequestWithTimestamps(
text="Hello. How are you?",
model="ssfm-v31",
voice_id="tc_6a02d77462e0bcd7c03ad706",
))
# 단어별 타임스탬프 출력
for word in response.words:
print(f"[{word.start_time:.3f}s – {word.end_time:.3f}s] {word.text}")
# SRT 자막 내보내기
srt = response.to_srt()
with open("output.srt", "w") as f:
f.write(srt)
다음 단계
축하합니다! 첫 번째 AI 음성을 만들었습니다. 더 자세히 알아보려면 다음 리소스를 참조하세요: