Skip to content
KugelAudioDocs

Speech enhancement

Guide to speech enhancement with Clarity: remove background noise from speech or keep one speaker's voice, pick REST or streaming, plans, limits and errors.

On this page

Speech enhancement cleans up recorded or live speech with Clarity (clarity-1). It removes background noise and keeps the speech, or, when you give it a short sample of one person, it keeps only that person's voice and removes everything else.

TaskWhat it doesUse it when
noise_removalRemoves background noise and keeps the speech.One person is talking over traffic, fans, keyboard clicks or room noise.
target_speaker_extraction ("keep one voice")Keeps one person's voice and removes every other voice and sound. You identify that person with a 2–8 second sample of them speaking.Several people are audible (a call center floor, a meeting, a TV in the background) and you only want one of them.

The SDKs pick the task for you: pass a speaker sample and they keep that voice, leave it out and they remove noise. The output is always mono 16-bit PCM at 24 kHz, the same length as your input.

Choose how to send audio

You haveUseReference
A recording, up to 300 secondsclient.enhance.generate, or POST /v1/audio/enhanceSDKs, REST
Live audio, enhanced as it arrivesclient.enhance.stream, or the /v1/audio/enhance/stream WebSocketSDKs, WebSocket
Many short live audios, without a new connection eachA session: one warm WebSocket that carries one audio after anotherWebSocket
A voice agent built on LiveKit or PipecatThe input filter, which cleans the user's audio before VAD and STT hear itLiveKit, Pipecat

Quick start

Remove the noise from a recording, then keep only one voice from another. Every request needs an API key.

from kugelaudio import KugelAudio, load_audio

client = KugelAudio(api_key="YOUR_API_KEY")

# Remove background noise
result = client.enhance.generate_sync(load_audio("call.wav"), model="clarity-1")
result.save("call-clean.wav")

# Keep one voice: pass a 2-8 second sample of that person
result = client.enhance.generate_sync(
    load_audio("meeting.wav"),
    model="clarity-1",
    speaker=load_audio("speaker.wav"),
)
result.save("one-voice.wav")

The input can be any WAV with 16-, 24- or 32-bit integer or 32-bit float samples, mono or stereo, at 8 to 48 kHz. Real-time streaming, the async and blocking variants and every option are in the SDK reference for Python and TypeScript.

Free month and paid plan

Every organization gets Clarity free until 30 October 2026, or for one calendar month counted from when speech enhancement is enabled for it, whichever is later. The Enhancement page of the dashboard counts the days down. The free month covers Clarity only, not text-to-speech.

Nor does it cover speech to text.

Free monthPaid
CostNot billed.Billed from your organization's credits per second of input audio; see pricing.
LimitsFair use: currently 10 requests per minute and 2 requests or streams at a time.Your organization's normal API rate limits.
Ends30 October 2026, or one calendar month after enhancement was enabled if that is later. Requests are then refused with 402 FREE_PERIOD_ENDED until you switch to paid.Does not end.

An organization owner or admin switches to paid on the Enhancement page of the dashboard. The switch is one way: there is no going back to the free month. It applies to new requests within about a minute; a stream that is already open keeps the plan it started with until it closes.

How paid usage is billed:

  • Per second of input audio processed, rounded up to the next whole second, with a one-second minimum per request.
  • A stream that disconnects early is billed for the audio processed up to that point.
  • A request that fails with an error is not billed.

Before a recording is enhanced, its cost (its input length at your price) is checked against your remaining credits; if they don't cover it, the request is refused with 402 INSUFFICIENT_CREDITS and nothing is processed. A live stream needs credit for at least one second to open and is billed for its input when it ends. Usage shows up on the Usage page shortly after each request.

Limits and errors

The requests-per-minute limit refills continuously rather than resetting on the minute: with a limit of 10, you can send up to 10 requests at once, and after that one more every 6 seconds. The concurrency limit counts requests and streams that are still running.

Statuserror_codeWhat it meansWhat to do
429RATE_LIMITEDYour plan's limit is reached. Rate limit exceeded (N requests per minute) or Concurrent generation limit reached (N).For requests per minute, wait the Retry-After seconds. The concurrency limit has no Retry-After: retry once one of your open requests or streams has finished. On the free month, switching to paid moves you to your organization's own limits.
402INSUFFICIENT_CREDITSPaid plan only: your remaining credits don't cover the recording, or are spent when a stream opens.Top up your credits.
402FREE_PERIOD_ENDEDFree plan only: your free Clarity month is over (or your organization has none).Switch to paid on the Enhancement page of the dashboard.
503MODEL_UNAVAILABLENot a limit of yours: enhancement is at capacity.Retry after the Retry-After seconds.

The SDKs raise the same error classes as for text-to-speech:

  • RateLimitError for 429, with the wait in retry_after (Python) or retryAfter (JavaScript) when the server sent one.
  • InsufficientCreditsError for both 402s.
  • AuthenticationError for a missing or rejected API key, or an organization without access to speech enhancement.
  • ConnectionError (KugelAudioConnectionError in Python) for 503 and network failures. In the browser, a live stream refused while connecting is always a ConnectionError, because the browser does not reveal the reason; see the SDK reference.

Every status and error_code the enhancement endpoints return, including validation errors, is in the endpoint reference; the shared error format is in Error codes.

A good speaker sample

Keeping one voice only works as well as the sample you give it.

  • 2–8 seconds of speech. Shorter or longer samples are rejected.
  • That person alone. No one else talking, not even briefly.
  • Little background noise. A quiet room is best. If you only have a noisy recording of the person, run it through noise removal first and use the result as the sample.

Next steps