Noise Suppression WebSocket API

Stream raw PCM audio over a WebSocket and receive the same audio back with background noise removed. The service runs AI noise suppression on Telnyx infrastructure. It is independent of calls: use it for any audio source, for example before you send audio to a speech-to-text engine.

To remove noise from a live Voice API or TeXML call, use in-call noise suppression instead. This page covers the standalone WebSocket API.

Endpoint

wss://api.telnyx.com/v2/noise_suppression

Authentication

Send your API key in the Authorization header of the WebSocket upgrade request:

Authorization: Bearer YOUR_API_KEY

A request without valid credentials fails with HTTP 401 before the WebSocket opens.

Connection lifecycle

1. Handshake

Set all options as query parameters on the upgrade request. You cannot change them during the session.

GET /v2/noise_suppression?format=l16&sample_rate=16000&channels=1 HTTP/1.1
Host: api.telnyx.com
Upgrade: websocket
Connection: Upgrade
Authorization: Bearer YOUR_API_KEY
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==

2. Streaming

Send audio as binary frames. For each binary frame you send, the server returns exactly one message:

a binary frame with denoised audio, or
a text frame with a JSON error (see Errors).

Client → Server  binary: 640 bytes (20 ms)
Client ← Server  binary: 640 bytes denoised
Client → Server  binary: 640 bytes (20 ms)
Client ← Server  binary: 640 bytes denoised

3. End of stream

When you have no more audio, send this text frame:

{"type": "end_of_stream"}

The server then returns all remaining audio, including the audio held back by the model’s processing delay, as one final binary frame. Then it closes the connection with close code 1000. Keep reading until you receive the close frame.

Client → Server  text:   {"type":"end_of_stream"}
Client ← Server  binary: remaining denoised audio
Client ← Server  close:  1000 end_of_stream

Always send end_of_stream before you stop. If you close the WebSocket without it, the server cannot send the remaining audio, and the end of your stream is lost.

Query parameters

Parameter	Type	Default	Description
`format`	string	`l16`	Audio encoding. `l16` or `f32le`. Used for both input and output.
`sample_rate`	integer	`16000`	Sample rate in Hz. Any integer from `8000` to `48000`. Used for both input and output. See Sample rates.
`channels`	integer	`1`	Number of channels. Only `1` (mono) is supported.
`model`	string	`rook`	Noise suppression model. `rook` or `quail`. See Models.
`quality`	string or number	`balanced`	Enhancement strength. See Quality.

An unsupported value closes the connection with an invalid_params error and close code 1008. See Errors.

Sample rates

The service accepts any integer sample rate from 8000 to 48000 Hz. A value outside that range closes the connection with an invalid_params error and close code 1008. The output uses the same sample rate as the input. Use the native sample rate of your audio. Send telephony and PSTN (narrowband) audio at 8000. Do not upsample 8 kHz audio to a higher rate. The full-band model treats the missing upper band as noise and lowers the speech level by about 14 dB.

Models

You select the model family with model. The service selects the model variant that matches your sample_rate.

`model`	Use for	`8000`	`8001` to `16000`	`16001` to `48000`
`rook` (default)	Audio for human listeners	8 kHz model	16 kHz model	48 kHz model
`quail`	Audio for speech-to-text	8 kHz model	16 kHz model	16 kHz model

Above 16000, quail processes the audio with the 16 kHz model. The output keeps your sample rate, but its audio bandwidth is limited to the 16 kHz model’s bandwidth (8 kHz).

Quality

quality sets the enhancement strength: how much noise the model removes.

Value	Enhancement strength
A number from `0.0` to `1.0`	The given strength. `0.0` is the lightest processing, `1.0` is the strongest.
`low_latency`	`0.5`. Lighter processing. The name is kept for compatibility.
`balanced`	`0.8`. The default.
`high_quality`	`1.0`. The strongest processing.

Any other value, for example 1.5 or max, closes the connection with an invalid_params error.

Audio format

Audio is raw mono PCM with no container and no header. Do not send WAV headers. Strip the header and send only the sample data.

`format`	Sample type	Bytes per sample	Byte order
`l16`	16-bit signed integer	2	little-endian
`f32le`	32-bit float, range -1.0 to 1.0	4	little-endian

The output uses the same format and sample_rate as the input.

l16 is little-endian. This is different from the big-endian L16 of RTP (RFC 3551). Byte-swap RTP payloads before you send them.

Chunk size

Each binary frame must contain a whole number of samples: a multiple of 2 bytes for l16, a multiple of 4 bytes for f32le.
The maximum binary frame size is 65,536 bytes.
20 ms chunks are a good default. At 16 kHz l16, 20 ms is 640 bytes. At 8 kHz l16, 20 ms is 320 bytes.

Buffering and latency

The model processes audio in fixed-size internal frames, and it has a short processing delay. The server keeps input that does not fill a complete frame and processes it together with your next chunk. As a result:

A response can be smaller or larger than the matching request. It can also be an empty binary frame. Ignore empty frames.
The output starts with the model’s processing delay. The first samples you receive correspond to that delay, not to your first input samples.
When you send end_of_stream, the server returns all of the audio that it still holds. The total output is your input length plus the processing delay.

Session duration

Sessions are limited to 590 seconds (just under 10 minutes). Reconnect to continue longer streams. At the limit, the server returns the remaining audio, sends a max_session_duration error message, and closes the connection with code 1008. You do not lose audio. To end with a normal close (1000) instead, send end_of_stream before the limit and then open a new connection for the rest of the stream.

Errors

HTTP errors (handshake)

Code	Cause
400	`sample_rate` or `channels` is not a valid non-negative integer
401	Missing or invalid API key
503	The server is restarting and does not accept new sessions. Reconnect with backoff.

Error messages

The server sends errors as JSON text frames:

{
  "type": "error",
  "code": "invalid_params",
  "message": "unsupported sample_rate 96000 (supported: 8000-48000 Hz)"
}

code is a stable identifier. message is a human-readable description; do not parse it.

Error codes

Error code	Close code	Cause
`invalid_params`	1008	A query parameter has an unsupported value: `format`, `sample_rate`, `channels`, `model`, or `quality`.
`max_session_duration`	1008	The session reached the 590-second limit. The server returns the remaining audio before it closes.
`session_error`	1011	The server could not start the noise suppression session.
`processing_error`	1011	The noise suppression engine failed.
`encode_error`	1011	The server could not encode the denoised audio.
`server_shutdown`	1001	The server is restarting, for example during a deploy. The server returns the remaining audio before it closes.
`max_connections`	1013	The server has too many open sessions. Try again later.
`overloaded`	1013	The server is overloaded and does not accept new sessions. Try again later.
`chunk_too_large`	None, the session continues	The binary frame is larger than 65,536 bytes. The server drops the chunk.
`decode_error`	None, the session continues	The frame length is not a whole number of samples. The server drops the chunk.
`unsupported_message`	None, the session continues	The server does not recognize the text frame. The only supported text frame is `end_of_stream`.

Close codes

When the server closes the connection, the close frame reason is the error code. Before every close that the server makes with a code other than 1000, including at the session limit, it sends the matching error message. A close caused by a network failure comes without an error message.

Close code	Reason	What to do
1000	`end_of_stream`	Nothing. Normal end: the server returned all audio after your `end_of_stream`.
1001	`server_shutdown`	The server is restarting. Reconnect with backoff.
1008	`invalid_params`	A query parameter has an unsupported value. Fix the parameter before you reconnect.
1008	`max_session_duration`	The session reached the 590-second limit. Reconnect to continue.
1011	`session_error`, `processing_error`, `encode_error`	Server error. Reconnect and try again.
1013	`max_connections`, `overloaded`	The service is busy and does not accept new sessions. Open sessions continue. Reconnect after a short wait.

Reconnecting

Close code 1001 and HTTP 503 mean that the server is restarting, for example during a deploy. Close codes 1011 (server error) and 1013 (service busy) are also temporary. None of these are errors in your request. Reconnect with exponential backoff; the new session goes to a healthy server. The new session starts empty: the service keeps no state between connections. Audio that you sent after the server started to close is not returned. For a live stream, continue with new audio on the new connection. For a file, send the file again.

Next steps

See Examples for complete Python and Node.js code that denoises a WAV file.

​Endpoint

​Authentication

​Connection lifecycle

​1. Handshake

​2. Streaming

​3. End of stream

​Query parameters

​Sample rates

​Models

​Quality

​Audio format

​Chunk size

​Buffering and latency

​Session duration

​Errors

​HTTP errors (handshake)

​Error messages

​Error codes

​Close codes

​Reconnecting

​Next steps

Endpoint

Authentication

Connection lifecycle

1. Handshake

2. Streaming

3. End of stream

Query parameters

Sample rates

Models

Quality

Audio format

Chunk size

Buffering and latency

Session duration

Errors

HTTP errors (handshake)

Error messages

Error codes

Close codes

Reconnecting

Next steps