Typecast SDK for JavaScript

The official JavaScript/TypeScript 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
• Supported Languages
• Error Handling
• TypeScript Support
• License

---

Installation

npm install @neosapience/typecast-js

Node.js 16/17 Users

This SDK uses the native fetch API. Node.js 18+ has built-in fetch support, but if you're using Node.js 16 or 17, you need to install a fetch polyfill:

npm install isomorphic-fetch

Then import it once at your application's entry point:

import 'isomorphic-fetch';  // ESM
// or
require('isomorphic-fetch');  // CommonJS

---

Quick Start

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

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

const audio = await client.textToSpeech({
  text: "Hello! I'm your friendly text-to-speech assistant.",
  model: "ssfm-v30",
  voice_id: "tc_672c5f5ce59fac2a48faeaee"
});

await fs.promises.writeFile(`output.${audio.format}`, Buffer.from(audio.audioData));
console.log(`Saved: output.${audio.format} (${audio.duration}s)`);

CommonJS Example

const { TypecastClient } = require('@neosapience/typecast-js');
const fs = require('fs');

async function main() {
  const client = new TypecastClient({ apiKey: 'YOUR_API_KEY' });
  const audio = await client.textToSpeech({
    text: "Hello! I'm your friendly text-to-speech assistant.",
    model: "ssfm-v30",
    voice_id: "tc_672c5f5ce59fac2a48faeaee"
  });
  await fs.promises.writeFile(`output.${audio.format}`, Buffer.from(audio.audioData));
}

main();

---

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
TypeScript	Full type definitions included
Zero Dependencies	Uses native fetch API

---

Usage

Configuration

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

// Using environment variable (recommended)
// export TYPECAST_API_KEY="your-api-key"
const client = new TypecastClient();

// Or pass directly
const client = new TypecastClient({
  apiKey: 'your-api-key',
  baseHost: 'https://api.typecast.ai'  // optional
});

Text to Speech

Basic Usage

const audio = await client.textToSpeech({
  text: "Hello, world!",
  voice_id: "tc_672c5f5ce59fac2a48faeaee",
  model: "ssfm-v30"
});

With Audio Options

const audio = await client.textToSpeech({
  text: "Hello, world!",
  voice_id: "tc_672c5f5ce59fac2a48faeaee",
  model: "ssfm-v30",
  language: "eng",
  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

// Get all voices (V2 API - recommended)
const voices = await client.getVoicesV2();

// Filter by criteria
const filtered = await client.getVoicesV2({
  model: 'ssfm-v30',
  gender: 'female',
  age: 'young_adult'
});

// Display voice info
console.log(`Name: ${voices[0].voice_name}`);
console.log(`Gender: ${voices[0].gender}, Age: ${voices[0].age}`);
console.log(`Models: ${voices[0].models.map(m => m.version).join(', ')}`);

Emotion Control

ssfm-v21: Basic Emotion

const audio = await client.textToSpeech({
  text: "I'm so excited!",
  voice_id: "tc_62a8975e695ad26f7fb514d1",
  model: "ssfm-v21",
  prompt: {
    emotion_preset: "happy",  // normal, happy, sad, angry
    emotion_intensity: 1.5    // 0.0 to 2.0
  }
});

ssfm-v30: Preset Mode

import { PresetPrompt } from '@neosapience/typecast-js';

const audio = await client.textToSpeech({
  text: "I'm so excited!",
  voice_id: "tc_672c5f5ce59fac2a48faeaee",
  model: "ssfm-v30",
  prompt: {
    emotion_type: "preset",
    emotion_preset: "happy",  // normal, happy, sad, angry, whisper, toneup, tonedown
    emotion_intensity: 1.5
  } as PresetPrompt
});

ssfm-v30: Smart Mode (Context-Aware)

import { SmartPrompt } from '@neosapience/typecast-js';

const audio = await client.textToSpeech({
  text: "Everything is perfect.",
  voice_id: "tc_672c5f5ce59fac2a48faeaee",
  model: "ssfm-v30",
  prompt: {
    emotion_type: "smart",
    previous_text: "I just got the best news!",
    next_text: "I can't wait to celebrate!"
  } as SmartPrompt
});

---

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

// Auto-detect (recommended)
const audio = await client.textToSpeech({
  text: "こんにちは",
  voice_id: "...",
  model: "ssfm-v30"
});

// Explicit language
const audio = await client.textToSpeech({
  text: "안녕하세요",
  voice_id: "...",
  model: "ssfm-v30",
  language: "kor"
});

---

Error Handling

import { TypecastClient, TypecastAPIError } from '@neosapience/typecast-js';

try {
  const audio = await client.textToSpeech({ ... });
} catch (error) {
  if (error instanceof TypecastAPIError) {
    console.error(`Error ${error.statusCode}: ${error.message}`);

    // Handle specific errors
    switch (error.statusCode) {
      case 401: // Invalid API key
      case 402: // Insufficient credits
      case 422: // Validation error
      case 429: // Rate limit exceeded
    }
  }
}

---

TypeScript Support

Full type definitions are included:

import type {
  TTSRequest,
  TTSResponse,
  TTSModel,
  LanguageCode,
  Prompt,
  PresetPrompt,
  SmartPrompt,
  Output,
  VoiceV2Response,
  VoicesV2Filter
} from '@neosapience/typecast-js';

---

License

Apache-2.0 © Neosapience