고객 지원API 콘솔로 이동
시작하기

빠른 시작

타입캐스트를 시작하고 첫 번째 AI 음성을 만들어 보세요.

인증 시작하기

타입캐스트 API를 사용하려면 API 키로 요청을 인증해야 합니다. 다음 단계를 따르세요:

  1. 첫 번째 단계

    타입캐스트 API 콘솔을 방문하여 새 API 키를 생성하세요

  2. 두 번째 단계

    API 키를 안전하게 보관하세요 - 환경 변수로 저장하는 것을 권장합니다

첫 번째 요청 실행하기

  1. SDK 설치
    pip install --upgrade typecast-python
  2. 가져오기 및 초기화
    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-v30",
    voice_id="tc_672c5f5ce59fac2a48faeaee",
    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에 액세스해야 합니다. /v2/voices 엔드포인트는 고유 식별자, 이름, 지원 모델 및 감정이 포함된 사용 가능한 보이스의 전체 목록을 제공합니다.

모델, 성별, 연령대 및 사용 사례 등의 선택적 쿼리 파라미터를 사용하여 보이스를 필터링할 수 있습니다.

from typecast import Typecast
from typecast.models import VoicesV2Filter, TTSModel

# 클라이언트 초기화
client = Typecast(api_key="YOUR_API_KEY")

# 모든 음성 가져오기 (선택적으로 모델, 성별, 나이, 사용 사례로 필터링)
voices = client.voices_v2(VoicesV2Filter(model=TTSModel.SSFM_V30))

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}, Model: {model.version.value}, Emotions: {', '.join(model.emotions)}")

응답은 각각 다음을 포함하는 음성 객체의 JSON 배열입니다:

{
  "voice_id": "tc_672c5f5ce59fac2a48faeaee",
  "voice_name": "Dylan",
  "models": [
    {
      "version": "ssfm-v30",
      "emotions": ["normal", "happy", "sad", "angry", "whisper", "toneup", "tonedown"]
    }
  ],
  "gender": "male",
  "age": "young_adult",
  "use_cases": ["Conversational", "TikTok/Reels/Shorts", "Audiobook/Storytelling"]
}

실시간 오디오 스트리밍

저지연 애플리케이션의 경우, 스트리밍 엔드포인트를 사용하여 전체 합성을 기다리지 않고 오디오 청크가 도착하는 즉시 재생할 수 있습니다.

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-v30",
    voice_id="tc_672c5f5ce59fac2a48faeaee",
    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-v30",
    voice_id="tc_60e5426de8b95f1d3000d7b5",
))

# 단어별 타임스탬프 출력
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 음성을 만들었습니다. 더 자세히 알아보려면 다음 리소스를 참조하세요:

API 레퍼런스

타입캐스트 API 사용 방법 알아보기

모델

ssfm-v30 및 ssfm-v21 모델에 대해 알아보기

변경 로그

최신 API 변경 사항 및 업데이트 확인

⌘I