메인 콘텐츠로 건너뛰기
타입캐스트 API를 위한 공식 Node.js 라이브러리입니다. AI 기반 음성을 사용하여 텍스트를 생동감 있는 음성으로 변환하세요. Javascript와 TypeScript 모두에서 작동합니다. 전체 TypeScript 타입이 포함되어 있습니다. ESM 및 CommonJS를 지원합니다. Node.js 18+ 및 최신 브라우저에서 작동합니다. Node.js 16/17 사용자는 isomorphic-fetch 폴리필을 설치해야 합니다.

패키지

Typecast Javascript/Typescript SDK

소스 코드

Typecast Javascript/Typescript SDK 소스 코드

​
설치

npm install @neosapience/typecast-js@latest
버전 0.1.5 이상이 설치되어 있는지 확인하세요. npm list @neosapience/typecast-js로 버전을 확인할 수 있습니다. 이전 버전이 있다면 npm update @neosapience/typecast-js를 실행하여 업데이트하세요.

​
빠른 시작

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

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

main();

​
기능

타입캐스트 Javascript/TypeScript SDK는 텍스트 음성 변환을 위한 강력한 기능을 제공합니다:
  • 다중 음성 모델: ssfm-v30(최신) 및 ssfm-v21 AI 음성 모델 지원
  • 다국어 지원: 영어, 한국어, 스페인어, 일본어, 중국어 등 37개 언어 지원
  • 감정 조절: 감정 프리셋(normal, happy, sad, angry, whisper, toneup, tonedown) 또는 스마트 문맥 인식 추론
  • 오디오 사용자 정의: 볼륨(0-200), 피치(-12 ~ +12 반음), 템포(0.5x ~ 2.0x), 형식(WAV/MP3) 제어
  • 캐릭터 탐색: 모델, 성별, 연령대, 사용 사례별 필터링이 가능한 V2 Voices API
  • TypeScript 지원: 전체 타입 정의 포함
  • 의존성 없음: 네이티브 fetch API 사용 (Node.js 18+ 및 브라우저에서 작동)

​
설정

환경 변수 또는 생성자를 통해 API 키를 설정하세요: 
// 환경 변수 사용
// export TYPECAST_API_KEY="your-api-key-here"
const client = new TypecastClient({
  apiKey: process.env.TYPECAST_API_KEY!
});

// 또는 직접 전달
const client = new TypecastClient({
  apiKey: 'your-api-key-here'
});

​
고급 사용법

​
감정 조절 (ssfm-v30)

ssfm-v30은 두 가지 감정 제어 모드를 제공합니다: 프리셋 및 스마트.
AI가 문맥에서 감정을 추론하도록 합니다:
import { SmartPrompt } from '@neosapience/typecast-js';

const audio = await client.textToSpeech({
  text: "Everything is going to be okay.",
  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
});

​
음성 조절

볼륨, 피치, 템포 및 출력 형식을 제어합니다: 
const audio = await client.textToSpeech({
  text: "Customized audio output!",
  voice_id: "tc_672c5f5ce59fac2a48faeaee",
  model: "ssfm-v30",
  output: {
    volume: 120,          // 범위: 0 ~ 200 (기본값: 100)
    audio_pitch: 2,       // 범위: -12 ~ +12 반음
    audio_tempo: 1.2,     // 범위: 0.5x ~ 2.0x
    audio_format: "mp3"   // 옵션: wav, mp3
  },
  seed: 42                // 재현 가능한 결과를 위해
});

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

​
캐릭터 탐색 (V2 API)

향상된 메타데이터로 사용 가능한 캐릭터를 나열하고 필터링합니다: 
// 모든 음성 가져오기
const voices = await client.getVoicesV2();

// 기준으로 필터링
const filtered = await client.getVoicesV2({
  model: 'ssfm-v30',
  gender: 'female',
  age: 'young_adult'
});

// 음성 정보 표시
voices.forEach(voice => {
  console.log(`ID: ${voice.voice_id}, Name: ${voice.voice_name}`);
  console.log(`Gender: ${voice.gender}, Age: ${voice.age}`);
  console.log(`Models: ${voice.models.map(m => m.version).join(', ')}`);
  console.log(`Use cases: ${voice.use_cases?.join(', ')}`);
});

​
다국어 콘텐츠

SDK는 자동 언어 감지와 함께 37개 언어를 지원합니다: 
// 언어 자동 감지 (권장)
const audio = await client.textToSpeech({
  text: "こんにちは。お元気ですか。",
  voice_id: "tc_672c5f5ce59fac2a48faeaee",
  model: "ssfm-v30"
});

// 또는 명시적으로 언어 지정
const koreanAudio = await client.textToSpeech({
  text: "안녕하세요. 반갑습니다.",
  voice_id: "tc_672c5f5ce59fac2a48faeaee",
  model: "ssfm-v30",
  language: "kor"  // ISO 639-3 언어 코드
});

await fs.promises.writeFile(`output.${audio.format}`, Buffer.from(audio.audioData));

​
지원 언어

SDK는 자동 언어 감지와 함께 37개 언어를 지원합니다:
코드언어코드언어코드언어
eng영어jpn일본어ukr우크라이나어
kor한국어ell그리스어ind인도네시아어
spa스페인어tam타밀어dan덴마크어
deu독일어tgl타갈로그어swe스웨덴어
fra프랑스어fin핀란드어msa말레이어
ita이탈리아어zho중국어ces체코어
pol폴란드어slk슬로바키아어por포르투갈어
nld네덜란드어ara아랍어bul불가리아어
rus러시아어hrv크로아티아어ron루마니아어
ben벵골어hin힌디어hun헝가리어
nan민난어nor노르웨이어pan펀자브어
tha태국어tur터키어vie베트남어
yue광둥어
지정하지 않으면 입력 텍스트에서 언어가 자동으로 감지됩니다.

​
오류 처리

SDK는 API 오류 처리를 위한 TypecastAPIError를 제공합니다: 
import { TypecastClient, TypecastAPIError } from '@neosapience/typecast-js';

try {
  const audio = await client.textToSpeech({
    text: "Hello world",
    voice_id: "tc_672c5f5ce59fac2a48faeaee",
    model: "ssfm-v30"
  });
} catch (error) {
  if (error instanceof TypecastAPIError) {
    // TypecastAPIError는 statusCode, message, response를 노출합니다
    switch (error.statusCode) {
      case 401:
        console.error('Invalid API key');
        break;
      case 402:
        console.error('Insufficient credits');
        break;
      case 422:
        console.error('Validation error:', error.response);
        break;
      case 429:
        console.error('Rate limit exceeded - please try again later');
        break;
      default:
        console.error(`API error (${error.statusCode}):`, error.message);
    }
  } else {
    console.error('Unexpected error:', error);
  }
}

​
TypeScript 지원

이 SDK는 TypeScript로 작성되었으며 전체 타입 정의를 제공합니다: 
import type {
  TTSRequest,
  TTSResponse,
  TTSModel,
  LanguageCode,
  Prompt,
  PresetPrompt,
  SmartPrompt,
  Output,
  VoiceV2Response,
  VoicesV2Filter
} from '@neosapience/typecast-js';