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

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)`);

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

| 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