Description

AillomVox client (TypeScript)


Official browser + Node.js SDK for AillomVox: one WebSocket to the gateway (wss://vox.aillom.com/ws), PCM16 streaming, transcripts, tools, and REST helpers for the public catalog (GET /api/providers) and pricing (GET /api/pricing).

Companion server, dashboard, and adapter code ship from the Vox product monorepo; this repository is only the npm client surface.

—

Installation

npm install aillom-vox-client

Security considerations

• API keys are secrets. Never commit real keys, never paste them into public tickets or client-side source that ships to browsers unless you accept that end users can extract them.
• Browser apps: a key embedded in frontend JavaScript or Web apps is visible in DevTools and bundled files. Safer patterns: your backend exchanges a session cookie or a short-lived token for voice access, or proxies the WebSocket with the real key on the server.
• Do not put apikey in the WebSocket URL (e.g. wss://.../ws?apiKey=...). That string is prone to leaking via server logs, reverse proxies, and referrer headers. The SDK uses x-api-key headers in Node.js and falls back to the first JSON config.apikey field in browsers, where custom WebSocket headers are unavailable.
• debug: true: logs structured config with apikey redacted, but may still log other inbound JSON; transcripts can contain PII. Keep debug off in production.
• TLS: use wss:// against production (wss://vox.aillom.com/ws), not ws://, except on trusted local networks.
• User data: voice audio and transcripts flow through the gateway; document your own privacy policy and minimize what you log on the client.

Documentation in this repo

| Doc | Purpose |
| :— | :— |
| docs/PROTOCOL.md | WebSocket lifecycle, handshake JSON, PCM rules |
| docs/PROVIDERS.md | Provider matrix, public USD/min rate card, tts_engine for aillomvox |
| docs/VOICES.md | Voice catalog notes |
| docs/TOOLS.md | Client-side tools |
| docs/TROUBLESHOOTING.md | Common failures |

Hosted docs: https://vox.aillom.com/docs

—

What changed in v2.1

• The canonical WebSocket endpoint is wss://vox.aillom.com/ws. If you still have wss://wss.aillom.com/ws (or https://wss.aillom.com), the SDK migrates the host automatically via normalizeWebSocketUrl() and migrateLegacyGatewayUrl() — you can drop the legacy host from config whenever you like.
• gatewayUrl accepts either a WebSocket URL or an HTTPS origin; both are normalized.
• Auth now matches the live gateway: Node.js uses x-api-key; browser sessions keep using config.apikey.
• New helpers: AillomVox.fetchProviders({ includeVoices }), AillomVox.fetchPricing(), AillomVox.fetchVoices(), AillomVox.fetchVoicePreview(), AillomVox.deleteVoice(), AillomVox.cloneVoiceDetailed(), sendHangup(), sendText(), and sendImage().
• Events: playbackclearbuffer (barge-in), state, control, and raw for advanced logging.
• Config: workspaceId, firstMessage, farewellMessage, ttsEngine (for provider: 'aillomvox'), and advanced timing knobs. Per-session model overrides are ignored by the current gateway; use fetchProviders() to inspect server defaults.

—

Quick start

Use the SDK in your app

You do not need to clone this repository to use the SDK. In your own project:

npm install aillom-vox-client

Then import it:

import { AillomVox } from 'aillom-vox-client';
const client = new AillomVox({
  apiKey: 'avYOURAPI_KEY',
  provider: 'aillomvox',
  ttsEngine: 'inworld',
  voice: 'Aanya',
  language: 'en-US',
  sampleRate: 16000,
  systemPrompt: 'You are a concise and helpful assistant.',
});
await client.connect();

If you want a new browser app from zero:

npm create vite@latest my-vox-app -- --template vanilla-ts
cd my-vox-app
npm install
npm install aillom-vox-client
npm run dev

Run the ready-made example UI

Clone the repository only when you want to run the example app that already has UI, microphone capture, playback, transcripts and logs.

Windows PowerShell:

winget install --id OpenJS.NodeJS.LTS -e
winget install --id Git.Git -e
git clone https://github.com/aillom/aillom-vox-client.git
cd aillom-vox-clientexamplesnpm-quickstart
npm install
npm run dev

Ubuntu / Debian:

sudo apt update
sudo apt install -y git curl ca-certificates
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVMDIR/nvm.sh" ] && . "$NVMDIR/nvm.sh"
nvm install --lts
nvm use --lts
git clone https://github.com/aillom/aillom-vox-client.git
cd aillom-vox-client/examples/npm-quickstart
npm install
npm run dev

macOS:

brew install node git
git clone https://github.com/aillom/aillom-vox-client.git
cd aillom-vox-client/examples/npm-quickstart
npm install
npm run dev

Open the Vite URL, paste your av... key, wait for the dynamic provider, TTS engine, and voice lists to load, then click Start call. Use Refresh catalog if you want to reload the live lists. Full setup and troubleshooting steps are in docs/NPMQUICKSTART.md.

Terminal smoke test

mkdir vox-smoke && cd vox-smoke
npm init -y
npm install aillom-vox-client
node -e "const { AillomVox } = require('aillom-vox-client'); Promise.all([AillomVox.fetchProviders({ includeVoices: false }), AillomVox.fetchPricing()]).then(([providers, pricing]) => console.log({ providers: providers.count, pricing: pricing.count }))"

Expected output:

{ providers: 7, pricing: 7 }

Realtime voice snippet

import { AillomVox } from 'aillom-vox-client';
const client = new AillomVox({
  apiKey: process.env.AILLOMVOX_KEY!,
  provider: 'aillomvox',
  ttsEngine: 'inworld',
  voice: 'Aanya',
  language: 'en-US',
  sampleRate: 16000,
  systemPrompt: 'You are a concise, professional assistant.',
  firstMessage: 'Hello! How can I help you today?',
});
client.on('transcript', (t) => console.log(t.role, t.text));
client.on('audio', (pcm) => {
  / Int16 LE mono — play or forward /
});
client.on('playbackclearbuffer', () => {
  / Flush scheduled playback — user interrupted assistant /
});
await client.connect();

Load the live provider + voice tree

import { AillomVox } from 'aillom-vox-client';
const catalog = await AillomVox.fetchProviders({ includeVoices: false });
const pricing = await AillomVox.fetchPricing();
console.log({ catalog, pricing });

—

List pricing (USD / minute)

Published alongside the marketing site; full table in docs/PROVIDERS.md. The SDK exports the same rows as data:

import { VOXPROVIDERRATECARD } from 'aillom-vox-client';
for (const row of VOXPROVIDERRATECARD) {
  console.log(row.label, row.provider, row.usdPerMinute);
}

The live endpoint is the preferred source for public list prices. Invoices can differ (credits, negotiated SKUs). Use the product billing UI as the contract.

Current public providers and prices

Use AillomVox.fetchPricing() for the live table. Current public list prices:

| Provider | Model / stack | USD/min |
| :— | :— | —: |
| aillomvox | Soniox STT · Groq Llama 3.3 70B · selectable TTS | 0.04 |
| aws | nova-2-sonic | 0.06 |
| gemini | gemini-3.1-flash-live-preview | 0.06 |
| qwen | qwen3.5-omni-flash-realtime | 0.06 |
| grok | grok-voice-think-fast-1.0 | 0.10 |
| openai | gpt-realtime-mini | 0.10 |
| ultravox | ultravox-70B | 0.10 |

For provider: 'aillomvox', current TTS engines are inworld, xai, lmnt, soniox, rime, and fish. Cartesia is disabled in the public client docs for now; aillomvoxmax is deprecated.

—

Raw WebSocket (no SDK)

const ws = new WebSocket('wss://vox.aillom.com/ws');
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'config',
    apikey: 'YOURAPIKEY',
    provider: 'aillomvox',
    tts_engine: 'inworld',
    voice: 'Aanya',
    language: 'en-US',
    sample_rate: 16000,
    system_prompt: 'You are a helpful assistant.',
  }));
};
ws.onmessage = (event) => {
  if (event.data instanceof ArrayBuffer) {
    / PCM chunk /
  }
};

—

Examples

See examples/README.md for how to run the browser demos and the TypeScript sample (npx serve, tsx, API keys).

| Path | Description |
| :— | :— |
| examples/npm-quickstart/ | Published npm package test app with voice catalog, mic, playback, transcripts and text input |
| examples/sdk-usage.ts | TypeScript sample with catalog fetch + handlers |
| examples/01-basic/ | Minimal browser demo |
| examples/02-advanced-dashboard/ | Larger UI example |
| examples/03-smart-home/ | Tool-calling illustration |
| examples/04-customer-support/ | Support-style UI |

—

Voice clone (REST)

AillomVox.cloneVoice(blob, apiKey, { gatewayUrl, workspaceId, providers, language, transcription }) posts to /api/voices/clone with x-api-key and returns the primary voice_id. Use cloneVoiceDetailed() when you need the per-provider clone result, and deleteVoice() to remove a workspace-owned clone. Production voice cloning is unlocked after the user’s first paid top-up; the free $1.00 signup credit is for call testing.

—

License

ISC © Aillom Technologies