Full Node SDK reference

Environment variables

Environment variables configure the client when no explicit option is passed. Every variable has a matching option on new SonioxNodeClient({ ... }) — see SonioxNodeClientOptions.

Variable	Maps to option	Default
`SONIOX_API_KEY`	`api_key`	-
`SONIOX_REGION`	`region`	- (US root)
`SONIOX_BASE_DOMAIN`	`base_domain` — derives all `{api,stt-rt,tts-rt}.{base_domain}` hosts	-
`SONIOX_API_BASE_URL`	`base_url` (REST API)	`https://api.soniox.com`
`SONIOX_WS_URL`	`realtime.ws_base_url` (STT WebSocket)	`wss://stt-rt.soniox.com/transcribe-websocket`
`SONIOX_TTS_API_URL`	`tts_api_url` (TTS REST)	`https://tts-rt.soniox.com`
`SONIOX_TTS_WS_URL`	`realtime.tts_ws_url` (TTS WebSocket)	`wss://tts-rt.soniox.com/tts-websocket`
`SONIOX_API_WEBHOOK_HEADER`	Webhook auth header name	-
`SONIOX_API_WEBHOOK_SECRET`	Webhook auth header value	-

Resolution precedence

For every configurable host, the SDK resolves in this order:

Explicit option on new SonioxNodeClient({ ... }) (e.g. base_url, tts_api_url, realtime.ws_base_url, realtime.tts_ws_url).
Matching environment variable (SONIOX_API_BASE_URL, SONIOX_TTS_API_URL, SONIOX_WS_URL, SONIOX_TTS_WS_URL).
base_domain / SONIOX_BASE_DOMAIN — derives all service endpoints from {service}.{base_domain}.
region / SONIOX_REGION — shorthand for base_domain: '{region}.soniox.com'.
Root US default (no region prefix).

Setting region: 'eu' or region: 'jp' resolves every host family — api.*, stt-rt.*, and tts-rt.* — to the matching regional variant. Use SONIOX_TTS_API_URL / SONIOX_TTS_WS_URL (or the corresponding explicit options) only when you need to override just the TTS hosts while leaving the rest of the client at its default region.

Client

Available client methods

Method	Description
`client.files.upload(file, options)`	Upload file
`client.files.list(options)`	List files
`client.files.get(id)`	Get file
`client.files.delete(id)`	Delete file
`client.files.delete_all()`	Delete all files
---	---
`client.stt.create(options)`	Create transcription
`client.stt.list(options)`	List transcriptions
`client.stt.get(id)`	Get transcription
`client.stt.getTranscript(id)`	Get transcription transcript
`client.stt.delete(id)`	Delete transcription
`client.stt.destroy(id)`	Delete transcription and its file
`client.stt.wait(id)`	Wait for transcription to complete
`client.stt.transcribe(options)`	Transcribe audio
`client.stt.transcribeFromUrl(url, options)`	Transcribe audio from URL
`client.stt.transcribeFromFile(file, options)`	Transcribe audio from file
`client.stt.transcribeFromFileId(id, options)`	Transcribe audio from file ID
`client.stt.delete_all()`	Delete all transcriptions
`client.stt.destroy_all()`	Delete all transcriptions and their files
---	---
`client.tts.generate(options)`	Generate speech audio from text
`client.tts.generateStream(options)`	Generate speech audio as a streaming async iterable
`client.tts.generateToFile(output, options)`	Generate speech audio and write it to a file or writable stream
`client.tts.listModels()`	List available TTS models and voices
---	---
`client.models.list()`	List available models
---	---
`client.webhooks.handle(options)`	Handle webhook
`client.webhooks.handleRequest(request, options)`	Handle webhook with Fetch API
`client.webhooks.handleExpress(req, options)`	Handle webhook with Express
`client.webhooks.handleFastify(req, options)`	Handle webhook with Fastify
`client.webhooks.handleNestJS(req, options)`	Handle webhook with NestJS
`client.webhooks.handleHono(c, options)`	Handle webhook with Hono
`client.webhooks.getAuthFromEnv()`	Get webhook auth from environment variables
`client.webhooks.verifyAuth(headers, auth)`	Verify webhook auth
`client.webhooks.parseEvent(body)`	Parse webhook event
`client.webhooks.isEvent(body)`	Check if body is a webhook event
---	---
`client.auth.createTemporaryKey(options)`	Create temporary API key
---	---
`client.realtime.stt(options)`	Create real-time STT session
`client.realtime.tts(input?)`	Create a single real-time TTS stream (opens its own WebSocket)
`client.realtime.tts.multiStream()`	Open a TTS WebSocket connection that can host multiple streams

File

Available file instance methods

Method	Description
`file.delete()`	Delete file

Transcription

Available transcription instance methods

Method	Description
`transcription.getTranscript()`	Get transcription transcript
`transcription.delete()`	Delete transcription
`transcription.destroy()`	Delete transcription and its file
`transcription.wait()`	Wait for transcription to complete
`transcription.refresh()`	Refresh transcription

Transcript

Method	Description
`transcript.segments()`	Get transcript segments
`transcript.text`	Transcript text
`transcript.tokens`	Transcript tokens

Real-time STT Session

Method	Description
`realtime.stt.connect()`	Establish websocket connection
`realtime.stt.close()`	Close websocket connection
`realtime.stt.finalize()`	Request server to finalize current transcription
`realtime.stt.finish()`	Gracefully finish the session
`realtime.stt.keepAlive()`	Send keepalive message
`realtime.stt.off()`	Remove event handler
`realtime.stt.on()`	Register event handler
`realtime.stt.once()`	Register one-time event handler
`realtime.stt.sendAudio(audio)`	Send audio chunk
`realtime.stt.sendStream(stream, options)`	Send audio stream
`realtime.stt.pause()`	Pause audio transmission
`realtime.stt.resume()`	Resume audio transmission
`realtime.stt.paused`	Whether the session is currently paused
`realtime.stt.state`	Current session state

Real-time TTS Stream

Method	Description
`stream.sendText(text, options?)`	Send one text chunk to the TTS stream
`stream.sendStream(source)`	Pipe an async iterable of text chunks into the stream
`stream.finish()`	Signal that no more text will be sent
`stream.cancel()`	Cancel generation and terminate the stream
`stream.close()`	Close the stream (and the WebSocket for single-stream usage)
`stream.on()`	Register event handler
`stream.once()`	Register one-time event handler
`stream.off()`	Remove event handler
`stream.state`	Current stream lifecycle state
`stream.streamId`	Identifier of this TTS stream

Real-time TTS Connection

Method	Description
`connection.connect()`	Open the WebSocket connection
`connection.stream(input?)`	Open a new TTS stream on this connection
`connection.close()`	Close the WebSocket connection and terminate all active streams
`connection.on()`	Register event handler
`connection.once()`	Register one-time event handler
`connection.off()`	Remove event handler
`connection.isConnected`	Whether the WebSocket is currently connected

On this page