Get Started with Authentication
To use the Typecast API, you'll need to authenticate your requests with an API key. Follow these steps:
First Step Visit your Typecast API Console to generate a new API key
Second Step Keep your API key secure - we recommend storing it as an environment variable
Make your first request
Install SDK pip install --upgrade typecast-pythonImport and Initialize from typecast import Typecast from typecast.models import TTSRequest, SmartPrompt # Initialize client client = Typecast(api_key="YOUR_API_KEY") # Convert text to speech 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!" ) )) # Save audio file with open('typecast.wav', 'wb') as f: f.write(response.audio_data)
List all voices
To use Typecast effectively, you need access to voice IDs. The /v2/voices endpoint provides a complete list of available voices with their unique identifiers, names, supported models, and emotions.
You can filter voices by model, gender, age, and use cases using optional query parameters.
from typecast import Typecast
from typecast.models import VoicesV2Filter, TTSModel
# Initialize client
client = Typecast(api_key="YOUR_API_KEY")
# Get all voices (optionally filter by model, gender, age, use_cases)
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)}")
The response will be a JSON array of voice objects, each containing:
{
"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"]
}
Stream audio in real time
For low-latency applications, use the streaming endpoint to play audio as chunks arrive - no need to wait for full synthesis.
WAV streaming format: 32000 Hz, 16-bit, mono PCM. The first chunk includes a 44-byte WAV header; subsequent chunks are raw PCM only.
# 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="Stream this text as audio in real time.",
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:] # Skip 44-byte WAV header
first = False
buf.extend(chunk)
n = len(buf) - (len(buf) % 2) # int16 alignment
if n:
player.write(bytes(buf[:n]))
del buf[:n]
Generate subtitles with Timestamp TTS
Need word-level timing for captions, karaoke, or lip-sync? Use the timestamp TTS endpoint - it returns the audio together with per-word (and optionally per-character) alignment data.
from typecast import Typecast
from typecast.models import TTSRequestWithTimestamps
client = Typecast(api_key="YOUR_API_KEY")
result = client.text_to_speech_with_timestamps(TTSRequestWithTimestamps(
text="Hello. How are you?",
model="ssfm-v30",
voice_id="tc_60e5426de8b95f1d3000d7b5",
))
with open("output.wav", "wb") as f:
f.write(result.audio_bytes())
# Export SRT captions
with open("output.srt", "w") as f:
f.write(result.to_srt())
Next steps
Congratulations on creating your first AI voice! Here are some resources to help you dive deeper: