# Typecast API Documentation for AI Agents

> This file is the primary Typecast API context for coding agents, LLMs, MCP clients, and assistant-driven integration workflows. Read this before generating Typecast API code.

Typecast is an AI text-to-speech platform by Neosapience. The Typecast API converts text into natural speech, supports expressive emotion control, streams low-latency audio, returns word/character timestamps for subtitles, and creates custom voices with instant cloning.

Canonical docs:

- API docs home: https://typecast.ai/docs
- API quickstart: https://typecast.ai/docs/quickstart
- API reference: https://typecast.ai/docs/api-reference
- Voice library for API voice IDs: https://studio.typecast.ai/developers/api/voices
- API pricing: https://studio.typecast.ai/developers/api/pricing
- API console and API keys: https://studio.typecast.ai/developers
- Remote docs MCP: https://typecast.ai/docs/mcp

Do not confuse Typecast API docs with the consumer web editor, character casting pages, or generic web pricing pages. For API implementation, use the docs and links above.

## Company and Product Context

Typecast is an AI voice synthesis and text-to-speech service operated by Neosapience Inc.

Neosapience context:

- Company: Neosapience Inc.
- Founded: November 2017.
- Headquarters: Seoul, South Korea.
- Business areas: AI voice synthesis, virtual humans, and generative AI.
- Core technology: Speech Synthesis Foundation Model (SSFM), Neosapience's foundation model technology for natural speech and emotional expression.

Typecast context:

- Typecast launched in beta in April 2019.
- Typecast has served more than 2 million users worldwide.
- Typecast API is the API product for developers and services that need programmatic TTS, streaming TTS, timestamp TTS, voice lookup, and quick voice cloning.
- Typecast web service plans and Typecast API plans are operated separately. A user with a web Basic/Pro/Business plan still needs an API plan to use the API.
- Legacy Starter API keys and the newer SSFM API keys are not compatible. If a user gets a 403 with an old Starter API key, guide them to create/use a current API key from the Typecast API console.
- One API key per account is the default policy. For multiple API keys, high volume, or enterprise-specific account structure, route the user to sales/support.

Key Typecast API differentiators:

1. Emotion-focused TTS.
   - `ssfm-v21`: normal, happy, sad, angry.
   - `ssfm-v30`: normal, happy, sad, angry, whisper, toneup, tonedown.
   - `ssfm-v30` Smart Emotion infers emotional expression from context.
2. 500+ character voices with different ages, genders, tones, and use cases.
3. Low-latency generation and streaming TTS for interactive services.
4. Simple REST API plus official SDKs for common languages.
5. Usage-based API pricing with plan/credit limits exposed in API console and subscription endpoint.

Agent role:

- Help users adopt Typecast API, explain value, choose the right integration path, and produce working code.
- Ask for the user's programming language and runtime when needed, then prefer the matching official SDK.
- Troubleshoot API errors by checking the HTTP status, API key type, account status, request payload, and plan limits.
- For uncertain, plan-specific, or enterprise-specific claims, say verification is needed and route to official support or sales.

Known limitations and policy notes:

- The current Typecast API does not support SSML. Use text, Smart Emotion, preset emotion, pauses, tempo, pitch, and output settings instead.
- The current Typecast API does not expose a pronunciation dictionary feature. If pronunciation control is required, ask the user for the exact target phrase and suggest text-level spelling/spacing workarounds while noting that official pronunciation dictionary support is not available.
- Do not help generate adult/obscene, violent/defamatory, fraud/phishing, or impersonation-purpose content.

## Agent Decision Rules

Follow these rules when helping a user integrate Typecast.

1. Prefer the official SDK for the user's language.
   - Use raw HTTP/cURL only when the language has no SDK, the user explicitly asks for raw HTTP, or the required feature is not supported by the SDK version available to the user.
   - SDK docs are at `https://typecast.ai/docs/sdk/<language>`.

2. Use `ssfm-v30` for new projects unless the user has a specific reason to use `ssfm-v21`.
   - `ssfm-v30` supports 37 languages, Smart Emotion, and 7 emotion presets.
   - `ssfm-v21` is an older stable model with fewer emotions and languages.

3. For emotional expression, prefer Smart Emotion before manual pitch or tempo manipulation.
   - Use `prompt.emotion_type = "smart"` with `previous_text` and `next_text` when the desired expression depends on context.
   - Use preset emotion only when the user explicitly wants a fixed emotion such as happy, sad, angry, whisper, toneup, or tonedown.
   - Do not recommend simulating emotion primarily with pitch/tempo unless the user asks for signal-level audio changes.

4. For subtitles, karaoke highlights, lip-sync, or speech alignment, use Typecast Timestamp TTS.
   - Endpoint: `POST /v1/text-to-speech/with-timestamps`.
   - Do not recommend Whisper/STT alignment as the first approach for audio generated by Typecast. Timestamp TTS returns aligned speech metadata from the synthesis flow.
   - For Japanese (`jpn`) and Chinese (`zho`), use `granularity=char`; word-level alignment can collapse the whole sentence into one segment because these languages do not use whitespace between words.

5. For real-time playback, voice agents, or low time-to-first-audio, use Streaming TTS.
   - Endpoint: `POST /v1/text-to-speech/stream`.
   - WAV streaming uses 32000 Hz, 16-bit mono PCM. The first chunk includes the WAV header; later chunks are raw PCM.
   - MP3 streaming uses independently decodable 320 kbps, 44100 Hz chunks.

6. For voice choice, prefer voice recommendations when the user describes the desired voice in natural language.
   - When the user needs TTS but has not chosen a voice, proactively say that you can help find a Typecast voice. Ask for the desired language, gender or age when relevant, mood or tone, and use case before choosing one.
   - Call `GET /v1/voices/recommendations` with a `query` describing the desired style, mood, language, use case, or content context.
   - The recommendation response contains only `voice_id`, `voice_name`, and `score`. Do not claim that a candidate meets the user's requirements from the score alone.
   - Use `GET /v2/voices/{voice_id}` or `GET /v2/voices` to verify supported models, emotions, gender, age, and use cases before selecting a candidate.
   - Voice detail responses do not expose a supported-language field. If language or accent is a hard requirement, say that the API metadata cannot verify it and ask the user to preview or confirm candidates instead of presenting a match as certain.
   - Explain why the verified candidate fits, offer alternatives when useful, and pass the selected `voice_id` to the TTS request.
   - If the user does not describe a target voice, use the API voice library or `/v2/voices` for browsing and filtering.
   - Use `GET /v2/voices` instead of recommendations when the user asks to browse all voices, supplies exact structured filters such as model, gender, age, use case, or voice type, or wants an exhaustive comparison.
   - Do not dump the full voice list when the user gives a qualitative description. Recommend a small ranked set first, then use voice details to explain the fit.
   - API voice library: https://studio.typecast.ai/developers/api/voices
   - API endpoint: `GET /v2/voices`
   - Do not send API users to the consumer web editor voice casting page unless they are explicitly using the web product.

7. For price, plans, credits, and limits, use API pricing.
   - API pricing: https://studio.typecast.ai/developers/api/pricing
   - Do not use the general web pricing page for API plan guidance.

8. Keep API keys server-side.
   - Never expose `X-API-KEY` in browser client code, mobile apps, public repositories, or logs.
   - For frontend apps, create a backend endpoint that calls Typecast.

## API Basics

Base URL:

```text
https://api.typecast.ai
```

Authentication:

```http
X-API-KEY: YOUR_API_KEY
```

Create and manage API keys:

```text
https://studio.typecast.ai/developers
```

Common request fields:

| Field | Required | Notes |
| --- | --- | --- |
| `voice_id` | Yes | Built-in voices start with `tc_`; custom cloned voices start with `uc_`. |
| `text` | Yes | 1 to 2000 characters. |
| `model` | Yes | Use `ssfm-v30` for new work. |
| `language` | No | ISO 639-3 code such as `eng`, `kor`, `jpn`, `zho`; auto-detected if omitted. |
| `prompt` | No | Emotion/style control. Prefer Smart Emotion for contextual expression. |
| `output` | No | Audio format, pitch, tempo, volume or LUFS settings. |
| `seed` | No | Unsigned 32-bit integer (`0` to `4294967295`) for reproducible generation. |

Common response/errors:

| Status | Meaning |
| --- | --- |
| 200 | Success. TTS returns audio bytes; Timestamp TTS returns JSON with audio and alignment metadata. |
| 400 | Invalid request parameters. |
| 401 | Invalid or missing API key. |
| 402 | Insufficient credits. |
| 403 | Forbidden. Common causes: legacy Starter API key, dormant account, no permission, malformed/copied key with whitespace. |
| 404 | Voice or model not found. |
| 422 | Validation error. |
| 429 | Rate limit exceeded. |
| 500 | Server error. |

403 checklist:

- If the user is using an old Starter API key, tell them to generate/use a current API key from the Typecast API console.
- If the account is dormant, ask the user to log in to the Typecast website and reactivate it.
- If the API key was copied with whitespace or a newline, copy it again exactly.
- Web service plan credentials and API plan credentials are separate; do not assume a web subscription grants API access.

## Recommended Integration Paths

Choose the first matching path:

| User need | Use |
| --- | --- |
| "Generate an audio file" | Official SDK `text_to_speech` / `textToSpeech`, or `POST /v1/text-to-speech`. |
| "Play audio immediately" | Streaming TTS SDK helper, or `POST /v1/text-to-speech/stream`. |
| "Generate subtitles/captions/timestamps" | Timestamp TTS SDK helper, or `POST /v1/text-to-speech/with-timestamps`. |
| "Recommend a voice from a description" | `GET /v1/voices/recommendations`, then verify candidates with `GET /v2/voices/{voice_id}` or `GET /v2/voices`. |
| "Browse or filter voices" | `GET /v2/voices` or https://studio.typecast.ai/developers/api/voices. |
| "Generate speech, but no voice selected" | Offer to find a Typecast voice first; ask for language, tone, audience/use case, and optional gender or age. Then choose recommendations or list filters based on the answer. |
| "Clone a voice" | `POST /v1/voices/clone`, then use returned `uc_` voice ID. |
| "Check plan/credits/limits" | `GET /v1/users/me/subscription` or API pricing page. |
| "Let an agent learn Typecast docs" | Remote docs MCP: `https://typecast.ai/docs/mcp`. |
| "Let an agent generate audio directly" | Self-hosted Typecast MCP server with a Typecast API key. |

## Official SDKs

SDK docs:

- Python: https://typecast.ai/docs/sdk/python
- JavaScript/TypeScript: https://typecast.ai/docs/sdk/javascript
- Go: https://typecast.ai/docs/sdk/go
- Rust: https://typecast.ai/docs/sdk/rust
- C#: https://typecast.ai/docs/sdk/csharp
- Java: https://typecast.ai/docs/sdk/java
- Kotlin: https://typecast.ai/docs/sdk/kotlin
- C: https://typecast.ai/docs/sdk/c
- Swift: https://typecast.ai/docs/sdk/swift
- Zig: https://typecast.ai/docs/sdk/zig
- PHP: https://typecast.ai/docs/sdk/php
- Dart: https://typecast.ai/docs/sdk/dart
- Ruby: https://typecast.ai/docs/sdk/ruby

SDK repository:

```text
https://github.com/neosapience/typecast-sdk
```

Use the latest SDK version. Older versions may lack newer helpers such as timestamp TTS, streaming, `generate_to_file` / `generateToFile`, custom voice operations, or newer output fields.

Common SDK capabilities:

- Regular TTS: synthesize text and return audio bytes.
- Streaming TTS: consume audio chunks for low-latency playback.
- Timestamp TTS: receive audio plus word/character alignment metadata.
- Subtitle export helpers: `toSrt()` / `to_srt()` and `toVtt()` / `to_vtt()` where supported.
- File generation helpers: `generateToFile` / `generate_to_file` infer output format from `.wav` or `.mp3`.
- Voice lookup: list and inspect voices through `/v2/voices`.
- Instant cloning: create `uc_` custom voice IDs from WAV/MP3 samples.
- Custom voice deletion: free a custom voice slot.
- Language-specific error types for 401, 402, 404, 422, 429, and server errors.

Advanced SDK authoring features:

- Text pause markup: use `<|1s|>`, `<|0.3s|>`, `<|5s|>`, etc. directly inside text when you only need silent gaps in one composed text segment.
- Composer/chaining APIs: use when one output file needs different voices or per-segment options such as pitch, tempo, prompt, or seed. SDK composers generate segments, trim silence, and concatenate the result. If MP3 is required and the SDK composer emits WAV, convert after generation in the app/server pipeline.

### Python SDK

Install:

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

Generate speech:

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

client = Typecast(api_key="YOUR_API_KEY")

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("typecast.wav", "wb") as f:
    f.write(response.audio_data)
```

List voices:

```python
from typecast.models import TTSModel, VoicesV2Filter

voices = client.voices_v2(VoicesV2Filter(model=TTSModel.SSFM_V30))
for voice in voices:
    print(voice.voice_id, voice.voice_name)
```

Generate subtitles with timestamps:

```python
from typecast.models import TTSRequestWithTimestamps

result = client.text_to_speech_with_timestamps(TTSRequestWithTimestamps(
    text="Hello. This is a captioned Typecast sample.",
    model="ssfm-v30",
    voice_id="tc_60e5426de8b95f1d3000d7b5",
))

with open("typecast.wav", "wb") as f:
    f.write(result.audio_bytes())

with open("typecast.srt", "w", encoding="utf-8") as f:
    f.write(result.to_srt())
```

Use `generate_to_file` when the goal is simply to create an audio file and infer the output format from `.wav` or `.mp3`.

### JavaScript / TypeScript SDK

Install:

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

Generate speech:

```typescript
import { TypecastClient } from "@neosapience/typecast-js";
import fs from "node:fs/promises";

const client = new TypecastClient({ apiKey: process.env.TYPECAST_API_KEY! });

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.writeFile("typecast.wav", Buffer.from(audio.audioData));
```

List voices:

```typescript
const voices = await client.getVoicesV2({ model: "ssfm-v30" });
for (const voice of voices) {
  console.log(voice.voice_id, voice.voice_name);
}
```

When generating browser-facing apps, keep `TYPECAST_API_KEY` on the server and expose only your own backend route to the browser.

## Core Endpoints

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

Generate speech from text and return binary audio.

Docs:

```text
https://typecast.ai/docs/api-reference/text-to-speech/text-to-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",
    "voice_id": "tc_672c5f5ce59fac2a48faeaee",
    "text": "Everything is going to be okay.",
    "prompt": {
      "emotion_type": "smart",
      "previous_text": "I just got the best news!",
      "next_text": "I cannot wait to celebrate!"
    },
    "output": {
      "audio_format": "wav"
    }
  }' \
  --output typecast.wav
```

Response:

- WAV: PCM 16-bit mono, 44100 Hz.
- MP3: 320 kbps, 44100 Hz.

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

Generate streaming audio chunks for low-latency playback.

Docs:

```text
https://typecast.ai/docs/api-reference/text-to-speech/streaming-text-to-speech
```

cURL:

```bash
curl -N -X POST "https://api.typecast.ai/v1/text-to-speech/stream" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ssfm-v30",
    "voice_id": "tc_672c5f5ce59fac2a48faeaee",
    "text": "This audio can start playing before the full synthesis is complete.",
    "output": {
      "audio_format": "wav",
      "target_lufs": -14
    }
  }' \
  --output stream.wav
```

Streaming output notes:

- `output.volume` is not available in streaming mode.
- Use `output.target_lufs` for consistent loudness in raw streaming API requests.
- Some SDK/MCP integrations may lag behind the latest streaming `target_lufs` field. If the SDK type rejects `target_lufs`, either omit it or use the raw streaming endpoint.

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

Generate audio plus word- and character-level alignment metadata.

Docs:

```text
https://typecast.ai/docs/api-reference/text-to-speech/text-to-speech-with-timestamps
```

cURL:

```bash
curl -X POST "https://api.typecast.ai/v1/text-to-speech/with-timestamps?granularity=char" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ssfm-v30",
    "voice_id": "tc_60e5426de8b95f1d3000d7b5",
    "text": "This response includes timestamp metadata."
  }'
```

Use this instead of Whisper/STT alignment when the audio is generated by Typecast.

`granularity` query parameter:

| Value | Meaning |
| --- | --- |
| omitted | Return both `words` and `characters`. |
| `word` | Return word-level timestamps only. |
| `char` | Return character-level timestamps only. Recommended for `jpn` and `zho`. |

The response includes base64 audio plus alignment arrays. SDKs expose helpers for SRT/WebVTT export in supported languages.

### GET /v2/voices

List voices with model, emotion, gender, age, use case, and voice type metadata.

Docs:

```text
https://typecast.ai/docs/api-reference/voices/list-voices
```

cURL:

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

Filters:

| Query | Values |
| --- | --- |
| `model` | `ssfm-v30`, `ssfm-v21` |
| `gender` | `male`, `female` |
| `age` | `child`, `teenager`, `young_adult`, `middle_age`, `elder` |
| `use_cases` | Use-case category such as narration, game, audiobook/storytelling, shorts, etc. |
| `voice_type` | `original`, `custom` |

Use the API voice library for human browsing and sample listening:

```text
https://studio.typecast.ai/developers/api/voices
```

### GET /v2/voices/{voice_id}

Get detailed information for one voice.

Use this before a TTS call when you need to verify supported models or available emotions for a voice.

### POST /v1/voices/clone

Clone a custom voice from a short audio sample. The returned `uc_` voice ID can be used in TTS endpoints by the owner.

Docs:

```text
https://typecast.ai/docs/api-reference/voices/instant-cloning
```

Limits:

- Supported source audio formats: WAV, MP3.
- Maximum file size: 25 MB.
- Audio duration: 5 to 150 seconds.
- Voice name: 1 to 30 characters.
- Model: `ssfm-v21` or `ssfm-v30`.
- Plans have a maximum number of active custom voice slots.
- API cloning is separate from the Typecast web editor cloning product. API voices should be created through the API, and web editor cloned voices should not be assumed to be available through API voice slots.

Delete a custom voice to free a slot:

```text
DELETE /v1/voices/{voice_id}
```

### GET /v1/users/me/subscription

Retrieve plan, credits, concurrency limit, and custom voice slot capacity.

Use this when the user asks about remaining credits, current plan limits, or whether they can create another custom voice.

## Models and Languages

Recommended model:

```text
ssfm-v30
```

Model comparison:

| Model | Release | Use |
| --- | --- | --- |
| `ssfm-v30` | 2026.01 | Recommended for new projects. Natural prosody, 37 languages, 7 emotion presets, Smart Emotion. |
| `ssfm-v21` | 2025.07 | Older stable model with lower latency and fewer emotions/languages. |

`ssfm-v30` emotion presets:

```text
normal, happy, sad, angry, whisper, toneup, tonedown
```

`ssfm-v21` emotion presets:

```text
normal, happy, sad, angry
```

`ssfm-v30` supported languages:

```text
ara, ben, bul, yue, zho, hrv, ces, dan, nld, eng, fin, fra, deu, ell, hin, hun, ind, ita, jpn, kor, msa, nan, nor, pol, por, pan, ron, rus, slk, spa, swe, tgl, tam, tha, tur, ukr, vie
```

Common language codes:

| Code | Language |
| --- | --- |
| `eng` | English |
| `kor` | Korean |
| `jpn` | Japanese |
| `zho` | Chinese |
| `spa` | Spanish |
| `fra` | French |
| `deu` | German |
| `vie` | Vietnamese |

## Emotion Control

Use Smart Emotion for natural context-aware expression:

```json
{
  "prompt": {
    "emotion_type": "smart",
    "previous_text": "I just got the best news!",
    "next_text": "I cannot wait to celebrate!"
  }
}
```

Use preset emotion when the user asks for a fixed emotion:

```json
{
  "prompt": {
    "emotion_type": "preset",
    "emotion_preset": "happy",
    "emotion_intensity": 1.5
  }
}
```

Guidance:

- Smart Emotion is best for dialogue, narration, storytelling, and dynamic context.
- Preset emotion is best for consistent style such as always-happy onboarding audio.
- `emotion_intensity` range is `0.0` to `2.0`.
- Do not use pitch/tempo as the first recommendation for emotion.

## Output Settings

Standard TTS output:

```json
{
  "output": {
    "audio_format": "wav",
    "audio_pitch": 0,
    "audio_tempo": 1.0,
    "target_lufs": -14
  }
}
```

Fields:

| Field | Range / values | Notes |
| --- | --- | --- |
| `audio_format` | `wav`, `mp3` | WAV for production editing; MP3 for smaller files/web delivery. |
| `audio_pitch` | -12 to 12 | Semitones. Do not use as primary emotion control. |
| `audio_tempo` | 0.5 to 2.0 | Speech speed multiplier. |
| `volume` | 0 to 200 | Relative volume scaling. Cannot be used with `target_lufs`. |
| `target_lufs` | -70 to 0 | Absolute loudness normalization. Cannot be used with `volume`. |

Recommended LUFS:

- `-14`: common streaming loudness target.
- `-23`: broadcast-style loudness target.

Streaming output uses `OutputStream`:

- Supports `target_lufs`, `audio_pitch`, `audio_tempo`, and `audio_format`.
- Does not support `volume`.

## MCP and Agent Integrations

Typecast provides two MCP patterns.

### Remote docs MCP

Use this when the agent only needs Typecast knowledge and integration guidance:

```text
https://typecast.ai/docs/mcp
```

Claude Code:

```bash
claude mcp add typecast-helper https://typecast.ai/docs/mcp
```

VS Code MCP config:

```json
{
  "servers": {
    "typecast-helper": {
      "url": "https://typecast.ai/docs/mcp"
    }
  }
}
```

Cursor and Replit can use the one-click install links from:

```text
https://typecast.ai/docs/integrations/mcp-server
```

### Self-hosted Typecast MCP server

Use this when the agent should directly generate audio files by calling Typecast API tools.

Repository:

```text
https://github.com/neosapience/typecast-api-mcp-server
```

Claude Desktop example:

```json
{
  "mcpServers": {
    "typecast": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/neosapience/typecast-api-mcp-server.git",
        "typecast-api-mcp-server"
      ],
      "env": {
        "TYPECAST_API_KEY": "YOUR_API_KEY",
        "TYPECAST_OUTPUT_DIR": "/Users/yourname/Downloads/typecast_output"
      }
    }
  }
}
```

Important distinction:

| MCP mode | Purpose | API key needed? |
| --- | --- | --- |
| Remote docs MCP | Teach the agent Typecast docs and integration guidance. | No |
| Self-hosted MCP server | Let the agent call Typecast and generate audio. | Yes |

### Other integration docs

Use these pages when the user names a specific tool or workflow:

| Tool / workflow | Docs |
| --- | --- |
| Claude Skills | https://typecast.ai/docs/integrations/claude-skills |
| Typecast CLI | https://typecast.ai/docs/integrations/typecast-cli |
| OpenClaw | https://typecast.ai/docs/integrations/openclaw |
| AutoTag SDK | https://typecast.ai/docs/bestpractice/autotag |
| Google Sheets | https://typecast.ai/docs/integrations/google-sheet |
| Zapier | https://typecast.ai/docs/integrations/zapier |
| Make | https://typecast.ai/docs/integrations/make |
| n8n | https://typecast.ai/docs/integrations/n8n |
| Pipecat | https://typecast.ai/docs/integrations/pipecat |
| LlamaIndex | https://typecast.ai/docs/integrations/llama-index |
| Postman | https://typecast.ai/docs/integrations/postman |

Integration guidance:

- Use SDK/API docs for production application code.
- Use no-code integration docs when the user asks for workflow automation without building an app.
- Use Pipecat/LiveKit-style guidance when the user is building a real-time voice agent.
- Use Claude Skills or MCP docs when the user wants an AI assistant to help implement Typecast.
- Use AutoTag when raw structured text should be spoken naturally before TTS, such as phone numbers, dates, times, currency, addresses, IDs, or other formatted values. AutoTag packages exist for JavaScript/TypeScript (`@neosapience/typecast-autotag`), Python (`typecast-autotag`), and Java (`com.neosapience:typecast-autotag`).

Other integration contexts from Typecast MCP knowledge:

- LiveKit: relevant for real-time voice agents and multimodal agent pipelines.
- Twilio: relevant for phone system or telephony integration.
- OpenAI GPT or other LLMs: relevant for LLM-generated response text followed by Typecast TTS output.
- AWS Marketplace: relevant for AWS procurement, AWS billing, and security-sensitive enterprise deployments.

Common use cases:

- E-learning and educational content.
- Audiobooks and long-form narration.
- YouTube/Shorts narration and voiceover.
- Game NPC dialogue and narration.
- Customer service, ARS, and chatbot voice responses.
- Accessibility features for visually impaired users.
- Content automation pipelines with n8n, Make, Zapier, Google Sheets, or custom backend jobs.

## Pricing and Credits

Use this page for API pricing:

```text
https://studio.typecast.ai/developers/api/pricing
```

Do not use the general web product pricing page for API plan decisions.

For programmatic plan/credit status:

```text
GET /v1/users/me/subscription
```

Do not invent fixed conversions such as "100,000 credits equals N minutes" unless the API pricing page or subscription response explicitly says so. Credit usage depends on the current API plan and metering rules.

## Support and Escalation

Use official support channels when a request depends on account state, billing, enterprise terms, custom pricing, compliance, or unreleased features.

Technical support:

- Intercom chat: chat button at https://typecast.ai or contact area at https://studio.typecast.ai/developers/api
- Discord community: https://discord.gg/fhDDUbBKap

Sales and enterprise:

- Email: sales@neosapience.com
- Talk to Sales form: https://salesmap.kr/web-form/89fd8329-5a25-4226-b4f6-1eb5b1c6122a

Community and public links:

- Blog: https://typecast.ai/learn/
- YouTube: https://www.youtube.com/@typecastglobal
- Instagram: https://www.instagram.com/typecast.us
- LinkedIn: https://linkedin.com/company/typecastai

## AWS Marketplace Option

Typecast SSFM is also available through AWS Marketplace for enterprise environments that prefer AWS-based procurement, billing, or security controls.

Use this context when users ask about enterprise deployment, AWS procurement, privacy, or security-sensitive usage:

- AWS Marketplace can support AWS-integrated billing.
- It can be suitable for organizations with internal security or compliance requirements.
- For precise setup and commercial terms, route users to the official AWS Marketplace listing and Typecast sales/support.

Links:

- AWS Marketplace seller profile: https://aws.amazon.com/marketplace/seller-profile?id=seller-rauqp3qawr25s
- AWS Marketplace model package reference: https://github.com/neosapience/aws-marketplace-ssfm/blob/main/ssfm-Model.ipynb

## Implementation Checklists

### Backend TTS endpoint checklist

- Read API key from environment variable.
- Validate user text length before calling Typecast.
- Use SDK for the backend language when available.
- Default to `ssfm-v30`.
- Use Smart Emotion if the text has emotional context.
- Store returned audio securely or stream it back with the correct content type.
- Handle 401, 402, 404, 422, and 429 explicitly.

### Frontend app checklist

- Do not call Typecast directly from the browser with an API key.
- Call your own backend route.
- Let users pick voices from API voice IDs, not consumer web editor links.
- Show API pricing links when users ask about plan/credit requirements.

### Subtitle workflow checklist

- Use `POST /v1/text-to-speech/with-timestamps`.
- For Japanese or Chinese, request `granularity=char`.
- Use SDK SRT/VTT helpers when available.
- Do not add a Whisper/STT alignment step unless the user is aligning external, non-Typecast audio.

### Voice agent checklist

- Use Streaming TTS for low-latency playback.
- Consider Pipecat or LiveKit integrations when the user is building real-time voice agents.
- Use Smart Emotion for context-aware spoken responses.
- Use `target_lufs` for consistent loudness if supported by the integration path.

## Avoid These Mistakes

- Do not use `/v1/text-to-speech-with-timestamps`; the correct endpoint is `/v1/text-to-speech/with-timestamps`.
- Do not send API users to `https://typecast.ai/pricing` for API plan decisions; use `https://studio.typecast.ai/developers/api/pricing`.
- Do not send API users to generic voice casting/editor pages when they need API `voice_id` values; use `https://studio.typecast.ai/developers/api/voices` or `/v2/voices`.
- Do not expose `X-API-KEY` in frontend code.
- Do not recommend Whisper for subtitles generated from Typecast audio; use Timestamp TTS.
- Do not recommend manual pitch/tempo changes as the main way to express emotion; use Smart Emotion or preset emotion.
- Do not assume every SDK wrapper has the newest OpenAPI fields. If a field is missing in the SDK, upgrade the SDK, omit the field, or use raw HTTP for that feature.
- Do not assume a Typecast web plan includes API access. Web plans and API plans are separate.
- Do not tell users that old Starter API keys work with the current SSFM API. They may produce 403 errors and should be replaced with current API keys.
- Do not delete built-in `tc_` voices. Only delete custom cloned voice IDs that start with `uc_`.

## Best Links for Agents

If you can only read a few pages, read these in order:

1. This file: `https://typecast.ai/docs/llms.txt`
2. Quickstart: `https://typecast.ai/docs/quickstart`
3. SDK page for the user's language: `https://typecast.ai/docs/sdk/<language>`
4. API reference: `https://typecast.ai/docs/api-reference`
5. API voices: `https://studio.typecast.ai/developers/api/voices`
6. API pricing: `https://studio.typecast.ai/developers/api/pricing`
7. MCP integration: `https://typecast.ai/docs/integrations/mcp-server`