# Typecast AI

> Typecast is an AI text-to-speech platform that converts text into lifelike speech with emotional expression. It offers 700+ voice characters, 37 languages, and emotion control via API, SDK (Python/JavaScript), and MCP integration.

Typecast is developed by Neosapience. The latest model is **ssfm-v30** (released 2026.01).

## API Quick Start

Base URL: `https://api.typecast.ai`
Authentication: `X-API-KEY` header
Dashboard: `https://typecast.ai/developers` (create API keys here)

### Generate Speech (cURL)

```bash
curl -X POST "https://api.typecast.ai/v1/text-to-speech" \
     -H "X-API-KEY: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
         "model": "ssfm-v30",
         "text": "Hello, this is a test.",
         "voice_id": "tc_672c5f5ce59fac2a48faeaee"
     }' --output output.wav
```

Response: Binary audio file (WAV 16-bit 44100Hz or MP3 320kbps)

### List Available Voices

```bash
curl -X GET "https://api.typecast.ai/v2/voices?model=ssfm-v30" \
     -H "X-API-KEY: YOUR_API_KEY"
```

Response: JSON array of voice objects with `voice_id`, `voice_name`, `gender`, `age`, `models`.

---

## API Reference

### POST /v1/text-to-speech

Generate speech from text. Returns binary audio data.

#### Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `text` | string | Text to synthesize (1-2000 characters) |
| `voice_id` | string | Voice ID, starts with `tc_` (e.g., `tc_672c5f5ce59fac2a48faeaee`) |
| `model` | string | `ssfm-v30` (recommended) or `ssfm-v21` |

#### Optional Parameters

**language** (string): ISO 639-3 code. Auto-detected if omitted.

**prompt** (object): Emotion control. Two modes for ssfm-v30:

Smart emotion (auto-detects from context):
```json
{
  "emotion_type": "smart",
  "previous_text": "I just got great news!",
  "next_text": "Let's celebrate!"
}
```

Preset emotion (manual selection):
```json
{
  "emotion_type": "preset",
  "emotion_preset": "happy",
  "emotion_intensity": 1.5
}
```

Available presets: `normal`, `happy`, `sad`, `angry`, `whisper`, `toneup`, `tonedown`
Intensity range: 0.0 - 2.0

**output** (object): Audio customization.
```json
{
  "volume": 100,
  "audio_pitch": 0,
  "audio_tempo": 1.0,
  "audio_format": "wav",
  "target_lufs": -14.0
}
```

| Field | Range | Default | Description |
|-------|-------|---------|-------------|
| `volume` | 0-200 | 100 | Volume level (100 = normal) |
| `audio_pitch` | -12 to +12 | 0 | Pitch in semitones |
| `audio_tempo` | 0.5-2.0 | 1.0 | Speed multiplier |
| `audio_format` | wav, mp3 | wav | Output format |
| `target_lufs` | -70 to 0 | - | Loudness normalization (cannot use with volume) |

**seed** (integer): Control generation variation.

#### Response

- **200**: Binary audio data (WAV: PCM 16-bit mono 44100Hz / MP3: 320kbps 44100Hz)
- **400**: Invalid parameters
- **401**: Invalid API key
- **402**: Insufficient credits
- **404**: Voice model not found
- **422**: Validation error
- **429**: Rate limit exceeded
- **500**: Server error

### GET /v2/voices

List available voice characters with optional filtering.

#### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `model` | string | Filter by model (`ssfm-v30`, `ssfm-v21`) |
| `gender` | string | Filter by gender (`male`, `female`) |
| `age` | string | Filter by age group (`young_adult`, etc.) |

#### Response (200)

```json
[
  {
    "voice_id": "tc_672c5f5ce59fac2a48faeaee",
    "voice_name": "Aria",
    "gender": "female",
    "age": "young_adult",
    "models": ["ssfm-v30"],
    "use_cases": ["narration", "conversation"]
  }
]
```

---

## SDK

### Python

```bash
pip install --upgrade typecast-python
```

```python
from typecast import Typecast
from typecast.models import TTSRequest, SmartPrompt

client = Typecast(api_key="YOUR_API_KEY")

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

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

# List voices
from typecast.models import VoicesV2Filter, TTSModel
voices = client.voices_v2(VoicesV2Filter(model=TTSModel.SSFM_V30))
```

Async support:
```python
from typecast import AsyncTypecast
async with AsyncTypecast() as client:
    response = await client.text_to_speech(request)
```

Error types: `UnauthorizedError`, `PaymentRequiredError`, `RateLimitError`, `InternalServerError`

### JavaScript / TypeScript

```bash
npm install @neosapience/typecast-js@latest
```

```typescript
import { TypecastClient } from '@neosapience/typecast-js';

const client = new TypecastClient({ apiKey: 'YOUR_API_KEY' });

// Generate speech
const audio = await client.textToSpeech({
    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!"
    }
});

await fs.promises.writeFile('output.wav', Buffer.from(audio.audioData));

// List voices
const voices = await client.getVoicesV2({
    model: 'ssfm-v30',
    gender: 'female'
});
```

Response type: `{ audioData: Buffer, duration: number, format: string }`

Supports ESM & CommonJS. Full TypeScript types included. Requires Node.js 18+.

---

## Models

### ssfm-v30 (Latest, 2026.01)
- Natural prosody and rhythm
- 7 emotion presets + smart emotion
- 37 languages: eng, kor, ara, ben, bul, yue, zho, hrv, ces, dan, nld, fin, fra, deu, ell, hin, hun, ind, ita, jpn, msa, nan, nor, pol, por, pan, ron, rus, slk, spa, swe, tgl, tam, tha, tur, ukr, vie

### ssfm-v21 (2025.04)
- Lower latency
- 4 emotion presets: normal, happy, sad, angry
- 27 languages

---

## Supported Languages (37, ssfm-v30)

| Code | Language | Code | Language |
|------|----------|------|----------|
| eng | English | kor | Korean |
| jpn | Japanese | zho | Chinese |
| spa | Spanish | fra | French |
| deu | German | rus | Russian |
| por | Portuguese | ita | Italian |
| ara | Arabic | hin | Hindi |
| vie | Vietnamese | tha | Thai |
| tur | Turkish | pol | Polish |
| nld | Dutch | swe | Swedish |
| ind | Indonesian | tgl | Tagalog |

(+ ben, bul, yue, hrv, ces, dan, fin, ell, hun, msa, nan, nor, pan, ron, slk, tam, ukr)

---

## Integrations

### MCP Server (Model Context Protocol)

Typecast provides an official MCP server for use with Claude Desktop and other MCP-compatible AI clients.

- **Repository**: [github.com/neosapience/typecast-api-mcp-server-sample](https://github.com/neosapience/typecast-api-mcp-server-sample)
- **Requires**: Python 3.10+
- **Exposed tools**: `get_voices`, `text_to_speech`

Claude Desktop configuration (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "typecast": {
      "command": "python",
      "args": ["-m", "typecast_mcp_server"],
      "env": {
        "TYPECAST_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

The MCP server supports all ssfm-v30 features: 7 emotion presets, smart emotion, 37 languages, and audio customization.

### Claude Skills

Official Typecast skills for Claude Code CLI.

- **Repository**: [github.com/neosapience/typecast-skills](https://github.com/neosapience/typecast-skills)
- **Features**: Emotion AI with context-aware expression, 500+ voices, 37 languages

### Pipecat (Real-time Voice AI)

TypecastTTSService for building real-time conversational voice AI agents.

- **Repository**: [github.com/neosapience/pipecat-typecast](https://github.com/neosapience/pipecat-typecast)
- **Use case**: Real-time voice AI agents, interactive voice applications

### n8n (Workflow Automation)

Community node for n8n workflow automation.

- **Documentation**: [typecast.ai/docs/integrations/n8n](https://typecast.ai/docs/integrations/n8n)
- **Repository**: [github.com/neosapience/n8n-nodes-typecast](https://github.com/neosapience/n8n-nodes-typecast)
- **Works on**: n8n Cloud and self-hosted

### Zapier

No-code workflow automation integration.

- **Documentation**: [typecast.ai/docs/integrations/zapier](https://typecast.ai/docs/integrations/zapier)

### Multi-language SDK

Beyond Python and JavaScript, Typecast provides SDK support for additional languages.

- **Repository**: [github.com/neosapience/typecast-sdk](https://github.com/neosapience/typecast-sdk)
- **Languages**: Python, JavaScript/TypeScript, C/C++, C#, Java, Kotlin, Go, Rust, Swift

---

## Pricing

Plans and pricing: [https://typecast.ai/pricing](https://typecast.ai/pricing)

## Optional

- [Blog](https://typecast.ai/learn/): Articles on AI voice generation, TTS, and more
- [Usage Policy](https://typecast.ai/policy): Guidelines on appropriate usage
- [Attribution Guidelines](https://typecast.ai/guideline): Attribution requirements for free users