Audixa

Official Node.js + TypeScript SDK for the Audixa Text-to-Speech API

What is Audixa?

Audixa is a powerful AI-powered text-to-speech platform that generates natural, human-like voices. This SDK provides a simple, type-safe way to integrate Audixa's TTS capabilities into your Node.js applications.

Features:

• 🎯 Full TypeScript support with complete type definitions
• 🔄 Dual module support (ESM + CommonJS)
• 🛡️ Robust error handling with custom error classes
• ⏱️ Configurable timeouts and request cancellation
• 📚 Comprehensive JSDoc documentation for IDE auto-completion

Installation

npm install audixa

or with yarn:

yarn add audixa

or with pnpm:

pnpm add audixa

Quick Start

TypeScript

import Audixa from 'audixa';

const audixa = new Audixa('your-api-key');

// Generate TTS and wait for completion
const audioUrl = await audixa.generateTTS({
  text: 'Hello! This is a test of the Audixa text-to-speech API.',
  voice_id: 'emma',
  model: 'base'
});

console.log('Audio URL:', audioUrl);

JavaScript (CommonJS)

const { Audixa } = require('audixa');

const audixa = new Audixa('your-api-key');

audixa.generateTTS({
  text: 'Hello! This is a test of the Audixa text-to-speech API.',
  voice_id: 'emma',
  model: 'base'
}).then(audioUrl => {
  console.log('Audio URL:', audioUrl);
});

JavaScript (ESM)

import Audixa from 'audixa';

const audixa = new Audixa('your-api-key');

const audioUrl = await audixa.generateTTS({
  text: 'Hello! This is a test of the Audixa text-to-speech API.',
  voice_id: 'emma'
});

console.log('Audio URL:', audioUrl);

Configuration

import Audixa from 'audixa';

const audixa = new Audixa('your-api-key', {
  baseUrl: 'https://api.audixa.ai/v3', // Custom API base URL (optional)
  timeout: 30000,                      // Request timeout in ms (default: 30000)
  customEndpointSlug: 'client1'        // Optional default custom endpoint
});

API Reference

Start TTS Generation

Creates a new text-to-speech task and returns the generation details.

const result = await audixa.startTTS({
  // Required parameters
  text: 'Your text here (minimum 30 characters)',
  voice_id: 'emma',

  // Optional parameters
  model: 'base',        // 'base' or 'advanced'
  speed: 1.0,           // 0.5 to 2.0
  audio_format: 'mp3',  // 'wav' or 'mp3'

  // Advanced model only
  cfg_weight: 2.5,      // 1.0 to 5.0
  exaggeration: 0.5     // 0.0 to 1.0
});

console.log('Generation ID:', result.generation_id);
console.log('Status:', result.status);

Poll TTS Status

Check the status of a TTS generation job.

const status = await audixa.getStatus(generation_id);

console.log('Status:', status.status);      // 'IN_QUEUE', 'GENERATING', 'COMPLETED', 'FAILED'
console.log('Audio URL:', status.audio_url); // Available when status is 'COMPLETED'

Complete Polling Example

async function generateAndWait(text: string, voiceId: string): Promise<string> {
  // Start generation
  const { generation_id } = await audixa.startTTS({ text, voice_id: voiceId });

  // Poll until complete
  while (true) {
    const status = await audixa.getStatus(generation_id);

    if (status.status === 'COMPLETED') {
      return status.audio_url!;
    }

    if (status.status === 'FAILED') {
      throw new Error(status.error_message || 'TTS generation failed');
    }

    // Wait 1 second before polling again
    await new Promise(resolve => setTimeout(resolve, 1000));
  }
}

Or use the convenience method:

const audioUrl = await audixa.generateTTS(
  { text: 'Your text here', voice_id: 'emma' },
  { pollInterval: 1000, maxWaitTime: 60000 }
);

Get Available Voices

Retrieve the list of available voices.

const { voices, limit, offset, length } = await audixa.getVoices({
  model: 'base',
  limit: 100,
  offset: 0
});

for (const voice of voices) {
  console.log(`${voice.name} (${voice.voice_id})`);
  console.log(`  Model: ${voice.model}`);
  console.log(`  Gender: ${voice.gender}`);
  console.log(`  Accent: ${voice.accent}`);
  console.log(`  Free: ${voice.free}`);
  console.log(`  Custom: ${voice.is_custom}`);
}

Get Generation History

Retrieve your recent generation history.

const history = await audixa.getHistory({
  limit: 20,
  offset: 0,
  status: 'COMPLETED'
});

console.log('History length:', history.length);

Custom Endpoints

Use a dedicated endpoint slug for enterprise routing. You can set a default slug on the client or provide it per request.

const audixa = new Audixa('your-api-key', {
  customEndpointSlug: 'client1'
});

// Uses /v3/custom/client1/tts
const result = await audixa.startTTS({
  text: 'Hello from a custom endpoint',
  voice_id: 'emma'
});

Per-request override:

const result = await audixa.startTTS(
  { text: 'Hello', voice_id: 'emma' },
  { customEndpointSlug: 'client2' }
);

Error Handling

The SDK provides a custom AudixaError class for comprehensive error handling:

import Audixa, { AudixaError } from 'audixa';

const audixa = new Audixa('your-api-key');

try {
  const result = await audixa.startTTS({
    text: 'Hello world',
    voice_id: 'emma'
  });
} catch (error) {
  if (error instanceof AudixaError) {
    console.log('Error code:', error.code);
    console.log('HTTP status:', error.status);
    console.log('Message:', error.message);

    switch (error.code) {
      case 'INVALID_API_KEY':
        console.log('Please check your API key');
        break;
      case 'INSUFFICIENT_CREDITS':
        console.log('Please add more credits to your account');
        break;
      case 'INVALID_PARAMS':
        console.log('Please check your request parameters');
        break;
      case 'FORBIDDEN':
        console.log('You do not have access to this resource');
        break;
      case 'RATE_LIMITED':
        console.log('Too many requests');
        break;
      case 'TIMEOUT':
        console.log('The request timed out');
        break;
      case 'NETWORK_ERROR':
        console.log('Network error occurred');
        break;
    }
  }
}

Error Codes

| Code | HTTP Status | Description | |------|-------------|-------------| | INVALID_PARAMS | 400 | Invalid request parameters | | INVALID_API_KEY | 401 | Invalid or missing API key | | INSUFFICIENT_CREDITS | 402 | Not enough credits in account | | FORBIDDEN | 403 | Access denied to resource | | NOT_FOUND | 404 | Resource not found | | RATE_LIMITED | 429 | Rate limit exceeded | | TIMEOUT | - | Request timed out | | NETWORK_ERROR | - | Network connectivity issue |

Request Cancellation

All methods support cancellation via AbortController:

const controller = new AbortController();

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  const result = await audixa.startTTS(
    { text: 'Hello world', voice_id: 'emma' },
    { signal: controller.signal }
  );
} catch (error) {
  if (error instanceof AudixaError && error.code === 'TIMEOUT') {
    console.log('Request was cancelled');
  }
}

TypeScript Types

All types are exported for use in your TypeScript projects:

import Audixa, {
  // Options
  AudixaOptions,
  RequestOptions,

  // TTS types
  StartTTSRequest,
  StartTTSResponse,
  TTSStatusResponse,
  TTSResponse,
  TTSModel,
  TTSStatus,
  TTSHistoryStatus,
  TTSAudioFormat,

  // Voice types
  GetVoicesResponse,
  VoicesResponse,
  Voice,

  // History types
  HistoryResponse,
  HistoryItem,

  // Error types
  AudixaError,
  AudixaErrorCode
} from 'audixa';

Type Definitions

// TTS Request
interface StartTTSRequest {
  text: string;
  voice_id: string;
  model?: 'base' | 'advanced';
  speed?: number;
  cfg_weight?: number;
  exaggeration?: number;
  audio_format?: 'wav' | 'mp3';
}

// TTS Response
interface TTSResponse {
  generation_id: string;
  status: 'IN_QUEUE' | 'GENERATING' | 'COMPLETED' | 'FAILED';
  audio_url?: string | null;
  error_message?: string | null;
}

// Voice
interface Voice {
  voice_id: string;
  name: string;
  model: 'base' | 'advanced';
  gender?: string;
  accent?: string;
  free: boolean;
  is_custom: boolean;
}

Full API Documentation

For complete API documentation, visit: https://docs.audixa.ai

License

MIT © anurag-pro

Links

• Audixa Website
• Audixa Dashboard
• API Documentation
• GitHub Repository
• npm Package

audixa-npm-package