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').