JavaScript REST Guide

Audixa does not require or publish a Node.js SDK package. Node.js 18 and later include fetch, so you can call the REST API directly and keep the request and polling behavior visible in your application.

Requirements

Node.js 18 or later.
An Audixa API key created in Developers.
A minimum $10 top-up or an active subscription.

Set the key in your server environment:

export AUDIXA_API_KEY="YOUR_API_KEY"

This is server-side code. Do not embed an API key in JavaScript delivered to a browser.

Quick Start

JavaScript (ES module)

const API_URL = 'https://api.audixa.ai/v3/tts';
const API_KEY = process.env.AUDIXA_API_KEY;

if (!API_KEY) throw new Error('AUDIXA_API_KEY is required');

const authHeaders = { 'X-API-Key': API_KEY };

async function requestJson(url, options = {}) {
  const response = await fetch(url, options);
  const body = await response.json().catch(() => ({}));
  if (!response.ok) {
    throw new Error(body.detail || `Audixa request failed (${response.status})`);
  }
  return body;
}

async function startTTS(payload) {
  return requestJson(API_URL, {
    method: 'POST',
    headers: { ...authHeaders, 'Content-Type': 'application/json' },
    body: JSON.stringify(payload)
  });
}

async function getStatus(generationId) {
  const query = new URLSearchParams({ generation_id: generationId });
  return requestJson(`${API_URL}?${query}`, {
    method: 'GET',
    headers: authHeaders
  });
}

async function generateTTS(payload, pollIntervalMs = 2000) {
  let generation = await startTTS(payload);

  while (!['COMPLETED', 'FAILED'].includes(generation.status)) {
    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
    generation = await getStatus(generation.generation_id);
  }

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

const generation = await generateTTS({
  text: 'Hello from Audixa. This request is long enough to generate speech.',
  voice_id: 'am_ethan',
  model: 'base',
  audio_format: 'mp3'
});

console.log(generation.audio_url);

Request Contract

Parameter	Type	Required	Description
`text`	`string`	Yes	At least 1 character; minimum charge is 30 characters (8 tokens); maximum length depends on the active plan
`voice_id`	`string`	Yes	Accessible voice compatible with the selected model
`model`	`base` or `advanced`	No	Defaults to `base`
`audio_format`	`wav` or `mp3`	No	Defaults to `wav`
`speed`	`number`	No	Delivery multiplier from 0.5 to 2.0
`cfg_weight`	`number`	No	Advanced model guidance from 1.0 to 5.0
`exaggeration`	`number`	No	Advanced model expressiveness from 0.0 to 1.0
`language_code`	`string`	No	Model-specific language code

The initial POST response normally has status IN_QUEUE. Poll the same /tts endpoint with generation_id; do not treat the create response as completed audio.

TypeScript Types

These local interfaces describe the REST fields used by the example. They are not imported from an Audixa package.

type TTSStatus = 'IN_QUEUE' | 'GENERATING' | 'COMPLETED' | 'FAILED';

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

interface TTSResponse {
  generation_id: string;
  status: TTSStatus;
  input_text: string;
  voice_id: string;
  voice_name?: string | null;
  model: 'base' | 'advanced';
  tokens: number;
  dollar_cost?: number | null;
  audio_url?: string | null;
  error_message?: string | null;
  created_at: string;
  started_at?: string | null;
  completed_at?: string | null;
}

List Compatible Voices

const query = new URLSearchParams({ model: 'base', limit: '50' });
const response = await fetch(`https://api.audixa.ai/v3/voices?${query}`, {
  headers: authHeaders
});

if (!response.ok) throw new Error(await response.text());
const { voices } = await response.json();

for (const voice of voices) {
  console.log(`${voice.name}: ${voice.voice_id} (${voice.model})`);
}

Error Handling

Check the HTTP status before consuming a success response:

HTTP status	Meaning
`400` or `422`	Invalid text, voice, model, or parameter value
`401`	Missing or invalid API key
`402`	Available balance cannot cover the request
`403`	The active plan cannot access the requested voice or model
`429`	Request or concurrency limit reached
`500+`	Server-side failure

FAILED is an asynchronous generation status, not necessarily an HTTP error. Always handle both transport errors and terminal generation statuses.

Cancellation and Timeouts

Use AbortController for a request-level timeout chosen by your application:

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);

try {
  const response = await fetch('https://api.audixa.ai/v3/voices?model=base', {
    headers: authHeaders,
    signal: controller.signal
  });
  if (!response.ok) throw new Error(await response.text());
} finally {
  clearTimeout(timeout);
}

Aborting a polling request does not cancel a generation already accepted by the API.

Getting Started

API Guides

Language Examples

Dashboard

Requirements

Quick Start

Request Contract

TypeScript Types

List Compatible Voices

Error Handling

Cancellation and Timeouts

​Requirements

​Quick Start

​Request Contract

​TypeScript Types

​List Compatible Voices

​Error Handling

​Cancellation and Timeouts

Requirements

Quick Start

Request Contract

TypeScript Types

List Compatible Voices

Error Handling

Cancellation and Timeouts