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

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.

Instant cloning

Clone a custom voice from a short audio sample (≤ 25 MB), then use it just like any built-in voice. The cloned voice ID has a uc_ prefix and works with text_to_speech directly.

from typecast import Typecast
from typecast.models import TTSRequest

client = Typecast(api_key="YOUR_API_KEY")

# 1) Clone
voice = client.clone_voice(
    audio="path/to/sample.wav",   # str path | Path | bytes | file object
    name="my-voice",               # 1-30 chars
    model="ssfm-v30",              # or "ssfm-v21"
)
print(voice.voice_id)              # uc_64a1b2...

# 2) Synthesize with the cloned voice
audio = client.text_to_speech(TTSRequest(
    text="Hello from my cloned voice!",
    voice_id=voice.voice_id,
    model="ssfm-v30",
))
with open("output.wav", "wb") as f:
    f.write(audio.audio_data)

# 3) Delete when done
client.delete_voice(voice.voice_id)

Limits

• Audio file: max 25 MB. Supported formats: WAV, MP3.
• Voice name: 1–30 characters.
• Model: ssfm-v21 or ssfm-v30.

Async usage is identical via AsyncTypecast:

from typecast import AsyncTypecast

async with AsyncTypecast(api_key="YOUR_API_KEY") as client:
    voice = await client.clone_voice(audio="sample.wav", name="my-voice", model="ssfm-v30")
    await client.delete_voice(voice.voice_id)

Supported Languages

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}")

License

Apache-2.0 © Neosapience