Node SDK

The Soniox Node SDK gives you fully typed access to our Async and Real-time Speech-to-Text APIs and Text-to-Speech APIs.

Quickstart

Install

Install via your preferred package manager:

npm install @soniox/node

yarn add @soniox/node

pnpm add @soniox/node

bun add @soniox/node

Set your API key

Terminal

export SONIOX_API_KEY=<YOUR_API_KEY>

Get API key

Create a Soniox account and log in to the Console to get your API key.

See all available environment variables in the SDK reference.

Environment variables

The client reads the following env vars as fallbacks when the matching client option is not provided:

Variable	Maps to option
`SONIOX_API_KEY`	`api_key`
`SONIOX_REGION`	`region`
`SONIOX_BASE_DOMAIN`	`base_domain`
`SONIOX_API_BASE_URL`	`base_url`
`SONIOX_WS_URL`	`realtime.ws_base_url`
`SONIOX_TTS_API_URL`	`tts_api_url`
`SONIOX_TTS_WS_URL`	`realtime.tts_ws_url`

Resolution precedence: explicit option → env var → base_domain → region → US root default. region is shorthand for base_domain: '{region}.soniox.com', so setting it resolves every host family (api.*, stt-rt.*, tts-rt.*) to the regional variant. See Full SDK reference → Environment variables for the full table and notes.

Client options

The client also accepts options for selecting a regional endpoint or overriding individual service URLs. All fields are optional — see SonioxNodeClientOptions for the full type.

import { SonioxNodeClient } from "@soniox/node";

const client = new SonioxNodeClient({
  api_key: process.env.SONIOX_API_KEY,

  // Shorthand for selecting a regional deployment.
  // Valid values: 'eu' | 'jp'. Leave undefined for the US (no region prefix).
  region: "eu",

  // Or override individual service URLs directly:
  // base_url: 'https://api.eu.soniox.com',               // REST API
  // tts_api_url: 'https://tts-rt.eu.soniox.com',         // TTS REST
  // realtime: {
  //   ws_base_url: 'wss://stt-rt.eu.soniox.com/transcribe-websocket',
  //   tts_ws_url: 'wss://tts-rt.eu.soniox.com/tts-websocket',
  // },
});

Create your first real-time session

import { SonioxNodeClient } from "@soniox/node";

const stream = await createFakeAudioStream();

// Create a Soniox client
// The API key is read from the SONIOX_API_KEY environment variable.
const client = new SonioxNodeClient();

// Create a real-time session
const session = client.realtime.stt({
    model: "stt-rt-v4",
});

// Listen for transcription results
session.on("result", (result) => {
    const text = result.tokens.map((t) => t.text).join("");
    if (text) console.log(text);
});

// Listen for errors
session.on("error", (err) => console.error("Error:", err));

// Connect to Soniox and stream audio
await session.connect();

// Stream audio in chunks and wait for the session to finish.
// The server auto-detects common audio formats (e.g. mp3).
await session.sendStream(stream, {
    pace_ms: 60,  // Throttle sending by 60 ms per chunk to simulate a live source
    finish: true, // Signal end of audio and wait for remaining results
});


// Demo helper: fetch an MP3 and return its body as an async-iterable stream.
// In a real app you'd stream audio from a microphone or other live source.
async function createFakeAudioStream() {
    const res = await fetch("https://soniox.com/media/examples/coffee_shop.mp3");
    if (!res.ok) throw new Error(`Request failed: ${res.status} ${res.statusText}`);
    if (!res.body) throw new Error("No response body");

    return res.body;
}

Learn more about Real-time transcription.

Create your first async transcription

import { SonioxNodeClient } from '@soniox/node';
import { readFile } from 'node:fs/promises';
const audio = await readFile('audio.mp3');

const client = new SonioxNodeClient();
const transcription = await client.stt.transcribe({
    model: 'stt-async-v4',
    file: audio,
    filename: 'audio.mp3',
    wait: true,
});

console.log(transcription.transcript?.text);

Learn more about Async transcription.

Generate your first speech

import { SonioxNodeClient } from "@soniox/node";

const client = new SonioxNodeClient();

const bytesWritten = await client.tts.generateToFile("hello.wav", {
    text: "Hello from Soniox text-to-speech.",
    voice: "Adrian",
    model: "tts-rt-v1-preview",
    language: "en",
    audio_format: "wav",
});

console.log(`Wrote ${bytesWritten} bytes`);

Learn more about REST speech generation and Real-time speech generation.