Quickstart

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

SDK
Direct API

Install SDK

pip install --upgrade typecast-python

All SDKs require the latest version.

Python: If you have an older version, upgrade with pip install --upgrade typecast-python
Javascript: If you have an older version, upgrade with npm update @neosapience/typecast-js
C#: Update with dotnet add package typecast-csharp
Java: Update the version in your pom.xml or build.gradle
Kotlin: Update the version in your build.gradle.kts
Rust: Update the version in your Cargo.toml

Import 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)

You can set up your API key in two ways:

Configure it directly in your application code
Set it as a shell environment variable

# Set for current session
export TYPECAST_API_KEY='YOUR_API_KEY'

import requests
import os

api_key = os.environ.get("TYPECAST_API_KEY", "YOUR_API_KEY")

url = "https://api.typecast.ai/v1/text-to-speech"
headers = {"X-API-KEY": api_key, "Content-Type": "application/json"}
payload = {
    "text": "Everything is going to be okay.",
    "model": "ssfm-v30",
    "voice_id": "tc_672c5f5ce59fac2a48faeaee",
    "prompt": {
        "emotion_type": "smart",
        "previous_text": "I just got the best news!",
        "next_text": "I can't wait to celebrate!"
    }
}

response = requests.post(url, headers=headers, json=payload)

if response.status_code == 200:
    with open('typecast.wav', 'wb') as f:
        f.write(response.content)
    print("Audio file saved as typecast.wav")
else:
    print(f"Error: {response.status_code} - {response.text}")

Audio Output Settings

You can customize the audio output by adding an output object to your request:

Parameter	Type	Range	Default	Description
`volume`	integer	0–200	100	Relative volume scaling. Cannot be used with `target_lufs`.
`target_lufs`	number	-70–0	—	Absolute loudness normalization in LUFS. Cannot be used with `volume`.
`audio_pitch`	integer	-12–12	0	Pitch adjustment in semitones.
`audio_tempo`	number	0.5–2.0	1.0	Speed multiplier.
`audio_format`	string	wav, mp3	wav	Output audio format.

Use target_lufs for consistent loudness across different clips. Use volume for simple relative scaling.

Example: output with target_lufs

{
    "text": "Consistent loudness example.",
    "model": "ssfm-v30",
    "voice_id": "tc_672c5f5ce59fac2a48faeaee",
    "output": {
        "target_lufs": -14.0,
        "audio_format": "mp3"
    }
}

To browse and select available voice IDs for your requests, please refer to Listing all voices in our API Reference.

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.

You can explore our complete voice catalog in more detail on the Voices page, where you’ll find additional information about each voice’s characteristics, sample audio clips, and recommended use cases.

SDK
Direct API

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

import requests
import os

api_key = os.environ.get("TYPECAST_API_KEY", "YOUR_API_KEY")

url = "https://api.typecast.ai/v2/voices"
headers = {"X-API-KEY": api_key}
params = {"model": "ssfm-v30"}  # Optional: model, gender, age, use_cases

response = requests.get(url, headers=headers, params=params)

if response.status_code == 200:
    voices = response.json()
    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']}, Emotions: {', '.join(model['emotions'])}")
else:
    print(f"Error: {response.status_code} - {response.text}")

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

You’ll need a valid voice ID when making text-to-speech requests. With ssfm-v30, all 7 emotion presets are available across all voices.

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.

SDK
Direct API

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

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]

See each SDK documentation for more languages (Go, Rust, Swift, C#, Kotlin, C) with real-time playback examples.

# pip install requests sounddevice
import requests
import sounddevice as sd
import os

api_key = os.environ.get("TYPECAST_API_KEY", "YOUR_API_KEY")

response = requests.post(
    "https://api.typecast.ai/v1/text-to-speech/stream",
    headers={"X-API-KEY": api_key, "Content-Type": "application/json"},
    json={
        "text": "Stream this text as audio in real time.",
        "model": "ssfm-v30",
        "voice_id": "tc_672c5f5ce59fac2a48faeaee",
    },
    stream=True
)
response.raise_for_status()

with sd.RawOutputStream(samplerate=32000, channels=1, dtype="int16") as player:
    buf, first = bytearray(), True
    for chunk in response.iter_content(chunk_size=4096):
        if not chunk:
            continue
        if first:
            chunk = chunk[44:]  # Skip WAV header
            first = False
        buf.extend(chunk)
        n = len(buf) - (len(buf) % 2)
        if n:
            player.write(bytes(buf[:n]))
            del buf[:n]

Parameter	Type	Range	Default	Description
`audio_pitch`	integer	-12–12	0	Pitch adjustment in semitones.
`audio_tempo`	number	0.5–2.0	1.0	Speed multiplier.
`audio_format`	string	wav, mp3	wav	Output audio format.

volume and target_lufs are not supported in streaming mode.

Next steps

Congratulations on creating your first AI voice! Here are some resources to help you dive deeper:

API Reference

Learn how to use the Typecast API

Models

Learn about ssfm-v30 and ssfm-v21 models

Changelog

See the latest API changes and updates

GET STARTED

SDKs

INTEGRATIONS

Get Started with Authentication

Make your first request

Audio Output Settings

List all voices

Stream audio in real time

Next steps

API Reference

Models

Changelog

GET STARTED

SDKs

INTEGRATIONS

Documentation Index

​Get Started with Authentication

​Make your first request

​Audio Output Settings

​List all voices

​Stream audio in real time

​Next steps

API Reference

Models

Changelog

Get Started with Authentication

Make your first request

Audio Output Settings

List all voices

Stream audio in real time

Next steps