Skip to main content
The Audixa Node.js SDK provides a type-safe client for the Audixa text-to-speech API, with full TypeScript support and built-in error handling.

​
Installation

npm install audixa

​
Quick Start

import Audixa from 'audixa';

const audixa = new Audixa('YOUR_API_KEY');

// Generate TTS and wait for completion
const audioUrl = await audixa.generateTTS({
  text: 'Hello! Welcome to Audixa.',
  voice_id: 'am_ethan',
  model: 'base'
});

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

​
Configuration

import Audixa from 'audixa';

const audixa = new Audixa('YOUR_API_KEY', {
  baseUrl: 'https://api.audixa.ai/v3',   // Default
  timeout: 30000,                          // Request timeout in ms (default: 30s)
  customEndpointSlug: 'my-custom-slug',    // Optional: route TTS to custom endpoint
});

​
API Reference

​
startTTS(payload, options?)

Starts an async TTS generation job. Returns immediately with a generation_id. 
const response = await audixa.startTTS({
  text: 'Hello from Audixa!',
  voice_id: 'am_ethan',
  model: 'base',
  speed: 1.0,
  audio_format: 'wav'
});

console.log(response.generation_id); // "gen_abc123"
console.log(response.status);        // "IN_QUEUE"
Parameters:
ParameterTypeRequiredDescription
textstring✅Text to convert (min 30 chars)
voice_idstring✅Voice identifier
model'base' | 'advanced'❌Model to use (default: 'base')
speednumber❌Speed multiplier, 0.5–2.0 (default: 1.0)
cfg_weightnumber❌Advanced model: guidance strength, 1.0–5.0
exaggerationnumber❌Advanced model: expressiveness, 0.0–1.0
audio_format'wav' | 'mp3'❌Output format (default: 'wav')
Options:
OptionTypeDescription
signalAbortSignalCancel the request
customEndpointSlugstringOverride endpoint slug for this request

​
getStatus(generationId, options?)

Check the status of a generation. 
const status = await audixa.getStatus('gen_abc123');

if (status.status === 'COMPLETED') {
  console.log('Audio:', status.audio_url);
}
Returns: TTSResponse with status, audio_url, voice_id, model, etc.

​
generateTTS(payload, options?)

Convenience method: starts TTS and polls until completion. Returns the audio URL. 
const audioUrl = await audixa.generateTTS({
  text: 'Hello! This will wait for completion.',
  voice_id: 'am_ethan',
  model: 'advanced',
  cfg_weight: 3.5,
  exaggeration: 0.7,
  audio_format: 'mp3'
}, {
  pollInterval: 1000,  // Poll every 1 second (default: 1000ms)
  maxWaitTime: 120000  // Max wait 2 minutes (default: 120000ms)
});

console.log('Audio URL:', audioUrl);
Additional Options (besides signal, customEndpointSlug):
OptionTypeDefaultDescription
pollIntervalnumber1000Milliseconds between status checks
maxWaitTimenumber120000Maximum wait time in milliseconds

​
getVoices(params?, options?)

List available voices with optional filtering. 
const { voices } = await audixa.getVoices({
  model: 'base',
  limit: 50
});

for (const voice of voices) {
  console.log(`${voice.name} (${voice.voice_id}) - ${voice.gender}`);
}
Parameters:
ParameterTypeDefaultDescription
model'base' | 'advanced'—Filter by model
limitnumber100Max results (1–500)
offsetnumber0Skip results

​
getHistory(params?, options?)

Retrieve generation history. 
const { history } = await audixa.getHistory({
  limit: 10,
  status: 'COMPLETED'
});

for (const item of history) {
  console.log(`${item.generation_id}: ${item.status} - ${item.voice_id}`);
}
Parameters:
ParameterTypeDefaultDescription
limitnumber20Max results (1–100)
offsetnumber0Skip results
statusstring—Filter: IN_QUEUE, GENERATING, COMPLETED, FAILED, EXPIRED

​
TypeScript Types

The SDK exports all types for full type safety: 
import Audixa, {
  // Request/Response types
  StartTTSRequest,
  StartTTSResponse,
  TTSResponse,
  TTSStatusResponse,
  VoicesResponse,
  Voice,
  HistoryResponse,
  HistoryItem,

  // Enums
  TTSModel,         // "base" | "advanced"
  TTSAudioFormat,   // "wav" | "mp3"
  TTSStatus,        // "IN_QUEUE" | "GENERATING" | "COMPLETED" | "FAILED"

  // Configuration
  AudixaOptions,
  RequestOptions,

  // Errors
  AudixaError,
} from 'audixa';

​
Key Type Definitions

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

interface TTSResponse {
  generation_id: string;
  status: 'IN_QUEUE' | 'GENERATING' | 'COMPLETED' | 'FAILED';
  input_text: string;
  voice_id: string;
  voice_name?: string | null;
  model: 'base' | 'advanced';
  tokens: number;
  credits_cost: number;
  dollar_cost?: number | null;
  method?: string | null;
  audio_url?: string | null;
  error_message?: string | null;
  created_at: string;
  started_at?: string | null;
  completed_at?: string | null;
}

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

interface AudixaOptions {
  baseUrl?: string;           // Default: "https://api.audixa.ai/v3"
  timeout?: number;           // Default: 30000ms
  customEndpointSlug?: string;
}

​
Error Handling

The SDK provides typed errors for all API failures: 
import Audixa, { AudixaError } from 'audixa';

const audixa = new Audixa('YOUR_API_KEY');

try {
  const audioUrl = await audixa.generateTTS({
    text: 'Hello from Audixa!',
    voice_id: 'am_ethan',
    model: 'base'
  });
} catch (error) {
  if (error instanceof AudixaError) {
    console.error('Code:', error.code);           // e.g. "AUTHENTICATION_ERROR"
    console.error('Status:', error.statusCode);   // e.g. 401
    console.error('Message:', error.message);
    
    switch (error.code) {
      case 'AUTHENTICATION_ERROR':
        // Invalid or missing API key (401)
        break;
      case 'INSUFFICIENT_BALANCE':
        // Account balance too low (402)
        break;
      case 'RATE_LIMITED':
        // Too many requests (429)
        break;
      case 'VALIDATION_ERROR':
        // Invalid parameters (400/422)
        break;
      case 'NETWORK_ERROR':
        // Network connectivity issue
        break;
      case 'TIMEOUT_ERROR':
        // Request timed out
        break;
      case 'GENERATION_ERROR':
        // TTS generation failed
        break;
    }
  }
}

​
Error Codes

CodeHTTP StatusDescription
AUTHENTICATION_ERROR401Invalid or missing API key
INSUFFICIENT_BALANCE402Account has insufficient funds
RATE_LIMITED429Rate limit exceeded
VALIDATION_ERROR400/422Invalid request parameters
API_ERROR500+Server-side error
NETWORK_ERROR—Network connectivity issue
TIMEOUT_ERROR—Request timed out
GENERATION_ERROR—TTS generation failed

​
Request Cancellation

Use AbortSignal to cancel in-flight requests: 
const controller = new AbortController();

// Set a 10-second timeout
setTimeout(() => controller.abort(), 10000);

try {
  const audioUrl = await audixa.generateTTS({
    text: 'This might take a while...',
    voice_id: 'am_ethan',
    model: 'advanced'
  }, {
    signal: controller.signal
  });
} catch (error) {
  if (error instanceof AudixaError && error.code === 'TIMEOUT_ERROR') {
    console.log('Request cancelled due to timeout');
  }
}

​
Custom Endpoints

Route TTS requests through a custom endpoint: 
// Set globally in constructor
const audixa = new Audixa('YOUR_API_KEY', {
  customEndpointSlug: 'my-custom-slug'
});

// Or per-request
const audioUrl = await audixa.generateTTS({
  text: 'Using custom endpoint...',
  voice_id: 'custom_voice_123',
  model: 'advanced'
}, {
  customEndpointSlug: 'my-custom-slug'
});

​
Environment Variables

Set your API key via environment variable instead of passing it directly: 
export AUDIXA_API_KEY=your_api_key_here

// Will automatically use AUDIXA_API_KEY env variable
const audixa = new Audixa();