@soniox/client

Official Soniox Web SDK for client-side applications.

Full Web SDK Documentation

Installation

npm install @soniox/client

Quick Start

import { SonioxClient } from '@soniox/client';

// Create a client and fetch temporary API key from your backend
const client = new SonioxClient({
  api_key: async () => {
    const res = await fetch('/api/get-temporary-key', { method: 'POST' });
    const { api_key } = await res.json();
    return api_key;
  },
});

Error handling

REST TTS and other HTTP-backed calls throw SonioxHttpError on non-2xx responses, network failures, and aborted requests.

import { SonioxClient, SonioxHttpError } from '@soniox/client';

try {
  const audio = await client.tts.generate({
    text: 'Hello',
    voice: 'Adrian',
    language: 'en',
  });
} catch (err) {
  if (err instanceof SonioxHttpError) {
    console.error(err.code, err.statusCode, err.bodyText);
  }
}

Realtime TTS timestamps

The realtime (WebSocket) TTS API can return character-level audio timestamps. Set return_timestamps: true on the stream; the alignment for each frame is delivered as the second argument of the audio event (it is undefined for audio-only frames). Timestamps are WebSocket-only — the REST endpoint ignores the flag — and map to the model's preprocessed text, not your raw input.

const stream = await client.realtime.tts({
  voice: 'Adrian',
  language: 'en',
  audio_format: 'pcm_s16le',
  sample_rate: 24000,
  return_timestamps: true,
});

stream.on('audio', (chunk, timestamps) => {
  play(chunk);
  if (timestamps) {
    timestamps.characters.forEach((char, i) => {
      console.log(char, timestamps.character_start_times_seconds[i], timestamps.character_end_times_seconds[i]);
    });
  }
});

stream.sendText('Hello world', { end: true });

For the full documentation please go to our docs: Full Web SDK Documentation