typecast-python 0.3.0

Official Typecast Python SDK - Convert text to lifelike speech using AI-powered voices

Typecast SDK for Python

The official Python SDK for the Typecast Text-to-Speech API

Convert text to lifelike speech using AI-powered voices

Documentation | API Reference | Get API Key

---

Table of Contents

• Installation
• Quick Start
• Features
• Usage
  • Configuration
  • Text to Speech
  • Voice Discovery
  • Emotion Control
  • Async Client
  • Timestamp TTS
• Supported Languages
• Error Handling
• License

---

Installation

pip install typecast-python

---

Quick Start

from typecast import Typecast
from typecast.models import TTSRequest

client = Typecast(api_key="YOUR_API_KEY")

response = client.text_to_speech(TTSRequest(
    text="Hello! I'm your friendly text-to-speech assistant.",
    model="ssfm-v30",
    voice_id="tc_672c5f5ce59fac2a48faeaee"
))

with open("output.wav", "wb") as f:
    f.write(response.audio_data)

print(f"Saved: output.wav ({response.duration}s)")

---

Features

Feature	Description
Multiple Models	Support for ssfm-v21 and ssfm-v30 AI voice models
37 Languages	English, Korean, Japanese, Chinese, Spanish, and 32 more
Emotion Control	Preset emotions or smart context-aware inference
Audio Customization	Volume, pitch, tempo, and format (WAV/MP3)
Voice Discovery	Filter voices by model, gender, age, and use cases
Async Support	Built-in async client for high-performance applications
Type Hints	Full type annotations with Pydantic models

---

Usage

Configuration

from typecast import Typecast

# Using environment variable (recommended)
# export TYPECAST_API_KEY="your-api-key"
client = Typecast()

# Or pass directly
client = Typecast(
    api_key="your-api-key",
    host="https://api.typecast.ai"  # optional
)

Text to Speech

Basic Usage

from typecast.models import TTSRequest

response = client.text_to_speech(TTSRequest(
    text="Hello, world!",
    voice_id="tc_672c5f5ce59fac2a48faeaee",
    model="ssfm-v30"
))

With Audio Options

from typecast.models import TTSRequest, Output

response = client.text_to_speech(TTSRequest(
    text="Hello, world!",
    voice_id="tc_672c5f5ce59fac2a48faeaee",
    model="ssfm-v30",
    language="eng",
    output=Output(
        volume=120,        # 0-200 (default: 100)
        audio_pitch=2,     # -12 to +12 semitones
        audio_tempo=1.2,   # 0.5x to 2.0x
        audio_format="mp3" # "wav" or "mp3"
    ),
    seed=42  # for reproducible results
))

Voice Discovery

from typecast.models import VoicesV2Filter, TTSModel, GenderEnum, AgeEnum

# Get all voices (V2 API - recommended)
voices = client.voices_v2()

# Filter by criteria
filtered = client.voices_v2(VoicesV2Filter(
    model=TTSModel.SSFM_V30,
    gender=GenderEnum.FEMALE,
    age=AgeEnum.YOUNG_ADULT
))

# Display voice info
print(f"Name: {voices[0].voice_name}")
print(f"Gender: {voices[0].gender}, Age: {voices[0].age}")
print(f"Models: {', '.join(m.version.value for m in voices[0].models)}")

Emotion Control

ssfm-v21: Basic Emotion

from typecast.models import TTSRequest, Prompt

response = client.text_to_speech(TTSRequest(
    text="I'm so excited!",
    voice_id="tc_62a8975e695ad26f7fb514d1",
    model="ssfm-v21",
    prompt=Prompt(
        emotion_preset="happy",  # normal, happy, sad, angry
        emotion_intensity=1.5    # 0.0 to 2.0
    )
))

ssfm-v30: Preset Mode

from typecast.models import TTSRequest, PresetPrompt, TTSModel

response = client.text_to_speech(TTSRequest(
    text="I'm so excited!",
    voice_id="tc_672c5f5ce59fac2a48faeaee",
    model=TTSModel.SSFM_V30,
    prompt=PresetPrompt(
        emotion_type="preset",
        emotion_preset="happy",  # normal, happy, sad, angry, whisper, toneup, tonedown
        emotion_intensity=1.5
    )
))

ssfm-v30: Smart Mode (Context-Aware)

from typecast.models import TTSRequest, SmartPrompt, TTSModel

response = client.text_to_speech(TTSRequest(
    text="Everything is perfect.",
    voice_id="tc_672c5f5ce59fac2a48faeaee",
    model=TTSModel.SSFM_V30,
    prompt=SmartPrompt(
        emotion_type="smart",
        previous_text="I just got the best news!",
        next_text="I can't wait to celebrate!"
    )
))

Async Client

import asyncio
from typecast import AsyncTypecast
from typecast.models import TTSRequest

async def main():
    async with AsyncTypecast(api_key="YOUR_API_KEY") as client:
        response = await client.text_to_speech(TTSRequest(
            text="Hello from async!",
            model="ssfm-v30",
            voice_id="tc_672c5f5ce59fac2a48faeaee"
        ))

        with open("output.wav", "wb") as f:
            f.write(response.audio_data)

asyncio.run(main())

Timestamp TTS

Use text_to_speech_with_timestamps() to receive base64 audio plus word/character-level timestamps aligned with the synthesized speech. The result object exposes save_audio(), to_srt(), and to_vtt() helpers so you can finish the typical "audio + subtitles" flow in one line.

from typecast import Typecast
from typecast.models import TTSRequestWithTimestamps

client = Typecast(api_key="YOUR_API_KEY")
resp = client.text_to_speech_with_timestamps(
    TTSRequestWithTimestamps(
        voice_id="tc_60e5426de8b95f1d3000d7b5",
        text="Hello. How are you?",
        model="ssfm-v30",
        language="eng",
    ),
)
resp.save_audio("hello.wav")
print(resp.to_srt())   # SRT subtitles
print(resp.to_vtt())   # WebVTT subtitles

Caption splits follow BBC/Netflix subtitle guidelines: 7s/42-char cue maximums.

# Real-time karaoke / highlight: iterate the words array directly.
for w in resp.words or []:
    print(f"[{w.start:.2f}s - {w.end:.2f}s] {w.text}")

Pass granularity="word" or granularity="char" to receive only one of the two alignment arrays. For non-whitespace languages (Japanese, Chinese), pair with granularity="char" — word-level alignment will collapse the entire sentence into a single segment.

---

Supported Languages

View all 37 supported languages

Code	Language	Code	Language	Code	Language
eng	English	jpn	Japanese	ukr	Ukrainian
kor	Korean	ell	Greek	ind	Indonesian
spa	Spanish	tam	Tamil	dan	Danish
deu	German	tgl	Tagalog	swe	Swedish
fra	French	fin	Finnish	msa	Malay
ita	Italian	zho	Chinese	ces	Czech
pol	Polish	slk	Slovak	por	Portuguese
nld	Dutch	ara	Arabic	bul	Bulgarian
rus	Russian	hrv	Croatian	ron	Romanian
ben	Bengali	hin	Hindi	hun	Hungarian
nan	Hokkien	nor	Norwegian	pan	Punjabi
tha	Thai	tur	Turkish	vie	Vietnamese
yue	Cantonese

from typecast.models import LanguageCode

# Auto-detect (recommended)
response = client.text_to_speech(TTSRequest(
    text="こんにちは",
    voice_id="...",
    model="ssfm-v30"
))

# Explicit language
response = client.text_to_speech(TTSRequest(
    text="안녕하세요",
    voice_id="...",
    model="ssfm-v30",
    language=LanguageCode.KOR
))

---

Error Handling

from typecast import (
    Typecast,
    TypecastError,
    BadRequestError,
    UnauthorizedError,
    PaymentRequiredError,
    NotFoundError,
    UnprocessableEntityError,
    RateLimitError,
    InternalServerError,
)

try:
    response = client.text_to_speech(request)
except UnauthorizedError:
    print("Invalid API key")
except PaymentRequiredError:
    print("Insufficient credits")
except RateLimitError:
    print("Rate limit exceeded - please retry later")
except TypecastError as e:
    print(f"Error {e.status_code}: {e.message}")

Exception	Status Code	Description
BadRequestError	400	Invalid request parameters
UnauthorizedError	401	Invalid or missing API key
PaymentRequiredError	402	Insufficient credits
NotFoundError	404	Resource not found
UnprocessableEntityError	422	Validation error
RateLimitError	429	Rate limit exceeded
InternalServerError	500	Server error

---

License

Apache-2.0 © Neosapience