botnoi-voice-js

TypeScript/JavaScript client for the Botnoi Voice Text-to-Speech API.

Installation

npm install botnoi-voice-js

Quick Start

ESM (import)

import { BotnoiTTS } from 'botnoi-voice-js';

const tts = new BotnoiTTS({ token: 'YOUR_BOTNOI_TOKEN' });

async function main() {
  // Use v2 for the latest TTS models
  const response = await tts.v2('สวัสดีครับ Botnoi Voice', {
    speaker: '8', // Note: v1 and v2 have different valid speaker IDs!
  });
  
  console.log('Audio URL:', response.audioUrl);
  
  // Download and save locally (Node.js/Bun/Deno only)
  const savedPath = await response.save('output.mp3');
  console.log(`Saved to ${savedPath}`);
}

main();

CJS (require)

const { BotnoiTTS } = require('botnoi-voice-js');

const tts = new BotnoiTTS({ token: 'YOUR_BOTNOI_TOKEN' });

tts.v2('สวัสดีครับ Botnoi Voice', { speaker: '8' }).then(response => {
  console.log('Audio URL:', response.audioUrl);
});

API Versions: v1 vs v2

The SDK provides two methods corresponding to Botnoi's API endpoints:

• tts.v1(text, options): Uses the original TTS models.
• tts.v2(text, options): Uses the newer, higher-quality TTS models with better prosody and natural pauses.

⚠️ IMPORTANT: Valid speaker IDs differ between v1 and v2. For example, speaker: '1' might work in v1 but throw a 403 Not Found Speaker! error in v2. Always check the Botnoi Voice Dashboard for the correct speaker ID.

API Reference

BotnoiTTS Constructor

| Parameter | Type | Required | Default | Description | |---|---|---|---|---| | token | string | Yes | - | Your Botnoi Developer API Token | | timeout | number | No | 30000 | Request timeout in milliseconds |

Generate Options

Passed as the second argument to v1() and v2().

| Option | Type | Default | Description | |---|---|---|---| | speaker | string | '1' | Voice speaker ID (Check dashboard for v1/v2 IDs) | | volume | number | 1.0 | Speech volume (0.0 - 2.0) | | speed | number | 1.0 | Speech speed (0.5 - 2.0) | | mediaType | 'mp3'\|'wav'\|'ogg' | 'mp3' | Output audio format | | language | 'th'\|'en' | 'th' | Language code | | saveFile | boolean | true | Save file on Botnoi servers |

Error Handling

The SDK exposes BotnoiAuthError and BotnoiAPIError for fine-grained error handling.

import { BotnoiTTS, BotnoiAuthError, BotnoiAPIError } from 'botnoi-voice-js';

const tts = new BotnoiTTS({ token: 'YOUR_TOKEN' });

try {
  await tts.v2('test', { speaker: '999' }); // Invalid speaker ID
} catch (error) {
  if (error instanceof BotnoiAuthError) {
    console.error('Invalid token or unauthorized!');
  } else if (error instanceof BotnoiAPIError) {
    // Will print "API error 403: Not Found Speaker!" if the speaker doesn't exist
    console.error(`API Error (${error.statusCode}):`, error.message);
  } else {
    console.error('Unknown error:', error.message);
  }
}

Environment Compatibility

| Environment | Fetch API | .save() method | Notes | |---|---|---|---| | Node.js 18+ | ✅ Native | ✅ Supported | Full support out of the box. | | Bun | ✅ Native | ✅ Supported | Fast execution, full compatibility. | | Deno | ✅ Native | ✅ Supported | Via npm compatibility layer. | | Browser | ✅ Native | ❌ Unsupported | You can generate URLs, but saving direct to disk requires browser APIs. |

Differences from Python SDK

If you are migrating from botnoi-voice-py, note the following idiomatic JavaScript changes:

• snake_case properties are now camelCase (e.g., media_type -> mediaType, save_file -> saveFile, audio_url -> audioUrl).
• Constructor takes an options object: new BotnoiTTS({ token: "..." }) instead of BotnoiTTS(token="...").
• The save() method is asynchronous: await response.save('out.mp3').