Classes

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

// Default (US) region
const client = new SonioxNodeClient({ api_key: 'your-api-key' });

// EU region
const client = new SonioxNodeClient({ api_key: 'your-api-key', region: 'eu' });

// REST TTS
const audio = await client.tts.generate({
  text: 'Hello',
  voice: 'Adrian',
  language: 'en',
});

// WebSocket TTS
const stream = await client.realtime.tts({
  model: 'tts-rt-v1-preview',
  voice: 'Adrian',
  language: 'en',
  audio_format: 'wav',
});

new SonioxNodeClient(options): SonioxNodeClient;

delete(file, signal?): Promise<void>;

// Delete by ID
await client.files.delete('550e8400-e29b-41d4-a716-446655440000');

// Or delete a file instance
const file = await client.files.get('550e8400-e29b-41d4-a716-446655440000');
if (file) {
    await client.files.delete(file);
}

// Or just use the instance method
await file.delete();

delete_all(options): Promise<void>;

// Delete all files
await client.files.delete_all();
console.log(`Deleted all files.`);

// With cancellation
const controller = new AbortController();
await client.files.delete_all({ signal: controller.signal });

get(file, signal?): Promise<SonioxFile | null>;

const file = await client.files.get('550e8400-e29b-41d4-a716-446655440000');
if (file) {
    console.log(file.filename, file.size);
}

list(options): Promise<FileListResult>;

const result = await client.files.list();

// Automatic paging - iterates through ALL files across all pages
for await (const file of result) {
    console.log(file.filename, file.size);
}

// Or access just the first page
for (const file of result.files) {
    console.log(file.filename);
}

// Check if there are more pages
if (result.isPaged()) {
    console.log('More pages available');
}

// Manual paging using cursor
const page1 = await client.files.list({ limit: 10 });
if (page1.next_page_cursor) {
    const page2 = await client.files.list({ cursor: page1.next_page_cursor });
}

// With cancellation
const controller = new AbortController();
const result = await client.files.list({ signal: controller.signal });

upload(file, options): Promise<SonioxFile>;

import * as fs from 'node:fs';

const buffer = await fs.promises.readFile('/path/to/audio.mp3');
const file = await client.files.upload(buffer, { filename: 'audio.mp3' });

const file = await client.files.upload(Bun.file('/path/to/audio.mp3'));

const file = await client.files.upload(buffer, {
    filename: 'audio.mp3',
    client_reference_id: 'order-12345',
});

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

const file = await client.files.upload(buffer, {
    filename: 'audio.mp3',
    signal: controller.signal,
});

create(options, signal?): Promise<SonioxTranscription>;

// Transcribe from URL
const transcription = await client.stt.create({
    model: 'stt-async-v4',
    audio_url: 'https://soniox.com/media/examples/coffee_shop.mp3',
});

// Transcribe from uploaded file
const file = await client.files.upload(buffer);
const transcription = await client.stt.create({
    model: 'stt-async-v4',
    file_id: file.id,
});

// With speaker diarization
const transcription = await client.stt.create({
    model: 'stt-async-v4',
    audio_url: 'https://soniox.com/media/examples/coffee_shop.mp3',
    enable_speaker_diarization: true,
});

delete(id, signal?): Promise<void>;

// Delete by ID
await client.stt.delete('550e8400-e29b-41d4-a716-446655440000');

// Or delete a transcription instance
const transcription = await client.stt.get('550e8400-e29b-41d4-a716-446655440000');
if (transcription) {
    await client.stt.delete(transcription);
}

delete_all(options): Promise<void>;

// Delete all transcriptions
await client.stt.delete_all();
console.log(`Deleted all transcriptions.`);

// With cancellation
const controller = new AbortController();
await client.stt.delete_all({ signal: controller.signal });

destroy(id): Promise<void>;

// Clean up both transcription and uploaded file
const transcription = await client.stt.transcribe({
    model: 'stt-async-v4',
    file: buffer,
    wait: true,
});
// ... use transcription ...
await client.stt.destroy(transcription); // Deletes both

// Or by ID
await client.stt.destroy('550e8400-e29b-41d4-a716-446655440000');

destroy_all(options): Promise<void>;

// Destroy all transcriptions and their files
await client.stt.destroy_all();
console.log(`Destroyed all transcriptions and their files.`);

// With cancellation
const controller = new AbortController();
await client.stt.destroy_all({ signal: controller.signal });

get(id, signal?): Promise<SonioxTranscription | null>;

const transcription = await client.stt.get('550e8400-e29b-41d4-a716-446655440000');
if (transcription) {
    console.log(transcription.status, transcription.model);
}

getTranscript(id, signal?): Promise<SonioxTranscript | null>;

const transcript = await client.stt.getTranscript('550e8400-e29b-41d4-a716-446655440000');
if (transcript) {
    console.log(transcript.text);
    for (const token of transcript.tokens) {
        console.log(token.text, token.start_ms, token.end_ms, token.confidence);
    }
}

list(options, signal?): Promise<TranscriptionListResult>;

const result = await client.stt.list();

// Automatic paging - iterates through ALL transcriptions across all pages
for await (const transcription of result) {
    console.log(transcription.id, transcription.status);
}

// Or access just the first page
for (const transcription of result.transcriptions) {
    console.log(transcription.id);
}

// Check if there are more pages
if (result.isPaged()) {
    console.log('More pages available');
}

transcribe(options): Promise<SonioxTranscription>;

// Transcribe from URL and wait for completion
const result = await client.stt.transcribe({
    model: 'stt-async-v4',
    audio_url: 'https://soniox.com/media/examples/coffee_shop.mp3',
    wait: true,
});

// Upload file and transcribe in one call
const result = await client.stt.transcribe({
    model: 'stt-async-v4',
    file: buffer,  // or Blob, ReadableStream
    filename: 'meeting.mp3',
    enable_speaker_diarization: true,
    wait: true,
});

// With wait progress callback
const result = await client.stt.transcribe({
    model: 'stt-async-v4',
    file: buffer,
    wait: true,
    wait_options: {
        interval_ms: 2000,
        on_status_change: (status) => console.log(`Status: ${status}`),
    },
});

// Auto-cleanup uploaded file after transcription
const result = await client.stt.transcribe({
    model: 'stt-async-v4',
    file: buffer,
    wait: true,
    cleanup: ['file'], // Deletes uploaded file, keeps transcription record
});

// Auto-cleanup everything after transcription
const result = await client.stt.transcribe({
    model: 'stt-async-v4',
    file: buffer,
    wait: true,
    cleanup: ['file', 'transcription'], // Deletes both file and transcription record
});

transcribeFromFile(file, options): Promise<SonioxTranscription>;

transcribeFromFileId(file_id, options): Promise<SonioxTranscription>;

transcribeFromUrl(audio_url, options): Promise<SonioxTranscription>;

wait(id, options?): Promise<SonioxTranscription>;

const completed = await client.stt.wait('550e8400-e29b-41d4-a716-446655440000');

// With progress callback
const completed = await client.stt.wait('id', {
    interval_ms: 2000,
    on_status_change: (status) => console.log(`Status: ${status}`),
});

list(signal?): Promise<SonioxModel[]>;

getAuthFromEnv(): WebhookAuthConfig | undefined;

handle(options): WebhookHandlerResultWithFetch;

handleExpress(req, auth?): WebhookHandlerResultWithFetch;

app.post('/webhook', async (req, res) => {
    const result = soniox.webhooks.handleExpress(req);

    if (result.ok && result.event.status === 'completed') {
        const transcript = await result.fetchTranscript();
        console.log(transcript?.text);
    }

    res.status(result.status).json({ received: true });
});

handleFastify(req, auth?): WebhookHandlerResultWithFetch;

handleHono(c, auth?): Promise<WebhookHandlerResultWithFetch>;

handleNestJS(req, auth?): WebhookHandlerResultWithFetch;

handleRequest(request, auth?): Promise<WebhookHandlerResultWithFetch>;

isEvent(payload): payload is WebhookEvent;

parseEvent(payload): WebhookEvent;

verifyAuth(headers, auth): boolean;

createTemporaryKey(request, signal?): Promise<TemporaryApiKeyResponse>;

const sttKey = await client.auth.createTemporaryKey({
  usage_type: 'transcribe_websocket',
  expires_in_seconds: 300,
});

const ttsKey = await client.auth.createTemporaryKey({
  usage_type: 'tts_rt',
  expires_in_seconds: 300,
});

const session = client.realtime.stt({ model: 'stt-rt-v4' });
await session.connect();

const stream = await client.realtime.tts({
  model: 'tts-rt-v1-preview',
  voice: 'Adrian',
  language: 'en',
  audio_format: 'wav',
});
stream.sendText("Hello");
stream.finish();
for await (const chunk of stream) { ... }

const conn = await client.realtime.tts.multiStream();
const stream = await conn.stream({
  model: 'tts-rt-v1-preview',
  voice: 'Adrian',
  language: 'en',
  audio_format: 'wav',
});

stt(config, options?): RealtimeSttSession;

new SonioxFile(data, _http): SonioxFile;

delete(signal?): Promise<void>;

const file = await client.files.get('550e8400-e29b-41d4-a716-446655440000');
if (file) {
    await file.delete();
}

toJSON(): SonioxFileData;

new SonioxTranscription(
   data, 
   _http, 
   transcript?): SonioxTranscription;

delete(): Promise<void>;

const transcription = await client.stt.get('550e8400-e29b-41d4-a716-446655440000');
await transcription.delete();

destroy(): Promise<void>;

// Clean up both transcription and uploaded file
const transcription = await client.stt.transcribe({
    model: 'stt-async-v4',
    file: buffer,
    wait: true,
});
// ... use transcription ...
await transcription.destroy(); // Deletes both transcription and file

getTranscript(options?): Promise<SonioxTranscript | null>;

const transcription = await client.stt.get('550e8400-e29b-41d4-a716-446655440000');
if (transcription) {
    const transcript = await transcription.getTranscript();
    if (transcript) {
        console.log(transcript.text);
    }
}

// Force re-fetch from API
const freshTranscript = await transcription.getTranscript({ force: true });

refresh(signal?): Promise<SonioxTranscription>;

let transcription = await client.stt.get('550e8400-e29b-41d4-a716-446655440000');
transcription = await transcription.refresh();
console.log(transcription.status);

toJSON(): SonioxTranscriptionData;

wait(options): Promise<SonioxTranscription>;

const transcription = await client.stt.create({
    model: 'stt-async-v4',
    audio_url: 'https://soniox.com/media/examples/coffee_shop.mp3',
});

// Simple wait
const completed = await transcription.wait();

// Wait with progress callback
const completed = await transcription.wait({
    interval_ms: 2000,
    on_status_change: (status) => console.log(`Status: ${status}`),
});

new SonioxTranscript(data): SonioxTranscript;

segments(options?): TranscriptSegment[];

const transcript = await transcription.getTranscript();

// Group by both speaker and language (default)
const segments = transcript.segments();

// Group by speaker only
const bySpeaker = transcript.segments({ group_by: ['speaker'] });

for (const s of segments) {
    console.log(`[Speaker ${s.speaker}] ${s.text}`);
}

new FileListResult(
   initialResponse, 
   _http, 
   _limit, 
   _signal): FileListResult;

asyncIterator: AsyncIterator<SonioxFile>;

isPaged(): boolean;

toJSON(): ListFilesResponse<SonioxFileData>;

new TranscriptionListResult(
   initialResponse, 
   _http, 
   _options, 
   _signal?): TranscriptionListResult;

asyncIterator: AsyncIterator<SonioxTranscription>;

isPaged(): boolean;

toJSON(): ListTranscriptionsResponse<SonioxTranscriptionData>;

const session = new RealtimeSttSession(apiKey, wsUrl, { model: 'stt-rt-v4' });

session.on('result', (result) => {
  console.log(result.tokens.map(t => t.text).join(''));
});

await session.connect();
session.sendAudio(audioChunk);
await session.finish();

get paused(): boolean;

get state(): SttSessionState;

new RealtimeSttSession(
   apiKey, 
   wsBaseUrl, 
   config, 
   options?): RealtimeSttSession;

asyncIterator: AsyncIterator<RealtimeEvent>;

close(): void;

connect(): Promise<void>;

finalize(options?): void;

finish(): Promise<void>;

keepAlive(): void;

off<E>(event, handler): this;

on<E>(event, handler): this;

once<E>(event, handler): this;

pause(): void;

resume(): void;

sendAudio(data): void;

sendStream(stream, options?): Promise<void>;

get size(): number;

new RealtimeSegmentBuffer(options?): RealtimeSegmentBuffer;

add(result): RealtimeSegment[];

flushAll(): RealtimeSegment[];

reset(): void;

new RealtimeUtteranceBuffer(options?): RealtimeUtteranceBuffer;

addResult(result): RealtimeSegment[];

markEndpoint(): RealtimeUtterance | undefined;

reset(): void;

toJSON(): Record<string, unknown>;

toString(): string;

toJSON(): Record<string, unknown>;

toString(): string;

toJSON(): Record<string, unknown>;

toString(): string;

toJSON(): Record<string, unknown>;

toString(): string;

toJSON(): Record<string, unknown>;

toString(): string;

toJSON(): Record<string, unknown>;

toString(): string;

toJSON(): Record<string, unknown>;

toString(): string;

toJSON(): Record<string, unknown>;

toString(): string;

toJSON(): Record<string, unknown>;

toString(): string;

toJSON(): Record<string, unknown>;

toString(): string;

const conn = new RealtimeTtsConnection(apiKey, wsUrl, ttsDefaults);
await conn.connect();

const s1 = conn.stream({ model, voice, language, audio_format });
s1.sendText("Hello");
s1.finish();
for await (const chunk of s1) { ... }

conn.close();

get isConnected(): boolean;

new RealtimeTtsConnection(
   apiKey, 
   wsUrl, 
   ttsDefaults?, 
   options?): RealtimeTtsConnection;

TypedEmitter<TtsConnectionEvents>.constructor

close(): void;

connect(): Promise<void>;

emit<E>(event, ...args): void;

TypedEmitter.emit

off<E>(event, handler): this;

TypedEmitter.off

on<E>(event, handler): this;

TypedEmitter.on

once<E>(event, handler): this;