Skip to main content

Package

Typecast Python SDK

Source Code

Typecast Python SDK Source Code

​
Installation

Install the Typecast Python SDK using pip: 
pip install typecast-python
The package is installed as typecast-python, but imported as typecast.

​
Quick Start

Here’s a simple example to convert text to speech: 
from typecast.client import Typecast
from typecast.models import TTSRequest, Output

# Initialize client
cli = Typecast(api_key="YOUR_API_KEY")

# Convert text to speech
response = cli.text_to_speech(TTSRequest(
    text="Hello there! I'm your friendly text-to-speech agent.",
    model="ssfm-v21",
    voice_id="tc_62a8975e695ad26f7fb514d1",
    output=Output(audio_format="wav")
))

# Save audio file
with open('output.wav', 'wb') as f:
    f.write(response.audio_data)

print(f"Duration: {response.duration}s, Format: {response.format}")

​
Features

The Typecast Python SDK provides powerful features for text-to-speech conversion:
  • 🎙️ Multiple Voice Models: Support for various AI voice models (ssfm-v21, v20, etc.)
  • 🌍 Multi-language Support: 27 languages including English, Korean, Spanish, Japanese, Chinese, and more
  • 😊 Emotion Control: Adjust emotional expression (happy, sad, angry, normal) with intensity control
  • 🎚️ Audio Customization: Control volume, pitch, tempo, and output format (WAV/MP3)
  • ⚡ Async Support: Built-in async client for high-performance applications
  • 🔍 Voice Discovery: List and search available voices by model

​
Configuration

You can configure the API key using environment variables or pass it directly to the client: 
export TYPECAST_API_KEY="your-api-key-here"

​
Advanced Usage

​
Emotion and Audio Control

Control emotions, pitch, tempo, and other audio parameters: 
from typecast.client import Typecast
from typecast.models import TTSRequest, Prompt, Output, LanguageCode

cli = Typecast()

response = cli.text_to_speech(TTSRequest(
    text="I am so excited to show you these features!",
    model="ssfm-v21",
    voice_id="tc_62a8975e695ad26f7fb514d1",
    language=LanguageCode.ENG,
    prompt=Prompt(
        emotion_preset="happy",      # Options: normal, happy, sad, angry
        emotion_intensity=1.5        # Range: 0.0 to 2.0
    ),
    output=Output(
        volume=120,                  # Range: 0 to 200
        audio_pitch=2,               # Range: -12 to +12 semitones
        audio_tempo=1.2,             # Range: 0.5x to 2.0x
        audio_format="mp3"           # Options: wav, mp3
    ),
    seed=42                          # For reproducible results
))

​
Voice Discovery

List and filter available voices: 
# List all voices
voices = cli.voices()

# Filter by model
v21_voices = cli.voices(model="ssfm-v21")

# Get specific voice
voice = cli.get_voice("tc_62a8975e695ad26f7fb514d1")
print(f"Voice: {voice.voice_name}")
print(f"Available emotions: {voice.emotions}")

# Common voice fields: voice_id, voice_name, emotions, languages, models, gender, age_range

​
Async Client

For high-performance applications, use the async client: 
import asyncio
from typecast.async_client import AsyncTypecast
from typecast.models import TTSRequest, LanguageCode, Output

async def main():
    async with AsyncTypecast() as cli:
        response = await cli.text_to_speech(TTSRequest(
            text="Hello from async!",
            model="ssfm-v21",
            voice_id="tc_62a8975e695ad26f7fb514d1",
            language=LanguageCode.ENG,
            output=Output(audio_format="wav")
        ))
        
        with open('async_output.wav', 'wb') as f:
            f.write(response.audio_data)

asyncio.run(main())

​
Supported Languages

Recommended: Use the LanguageCode enum for type-safe language selection. You can also pass the ISO 639-3 code as a string (e.g., "eng"). The SDK supports 27 languages with ISO 639-3 codes:
LanguageCodeLanguageCodeLanguageCode
EnglishengJapanesejpnUkrainianukr
KoreankorGreekellIndonesianind
SpanishspaTamiltamDanishdan
GermandeuTagalogtglSwedishswe
FrenchfraFinnishfinMalaymsa
ItalianitaChinesezhoCzechces
PolishpolSlovakslkPortuguesepor
DutchnldArabicaraBulgarianbul
RussianrusCroatianhrvRomanianron
Use the LanguageCode enum for type-safe language selection: 
from typecast.models import LanguageCode

request = TTSRequest(
    text="Hello",
    language=LanguageCode.ENG,
    ...
)

​
Error Handling

The SDK provides specific exceptions for different HTTP status codes: 
from typecast.exceptions import (
    BadRequestError,           # 400
    UnauthorizedError,         # 401
    PaymentRequiredError,      # 402
    NotFoundError,             # 404
    UnprocessableEntityError,  # 422
    InternalServerError,       # 500
    TypecastError              # Base exception
)

# All SDK exceptions have status_code and message attributes

try:
    response = cli.text_to_speech(request)
except UnauthorizedError:
    print("Invalid API key")
except PaymentRequiredError:
    print("Insufficient credits")
except TypecastError as e:
    print(f"Error: {e.message}, Status: {e.status_code}")