Quickstart: Krisp API

Clean a noisy WAV file in real time with the Krisp Voice Isolation API, from API key to cleaned audio.

In this quickstart you stream a noisy WAV file to the /voice-isolation endpoint and save the cleaned audio, with background voices and noise removed, to a new file.

You need:

  • Python 3.9 or later
  • A 16 kHz, mono, 16-bit PCM WAV file. To convert any audio file with ffmpeg:
ffmpeg -i input.mp3 -ar 16000 -ac 1 -sample_fmt s16 sample.wav
📘

Region

The Krisp API currently runs in the US region. From other regions, expect extra latency. See Region and latency.

Get an API key

Sign up in the Developers Portal, then go to API Keys → Create key.

Export it as an environment variable. Keep the API key on your backend: never put it in a browser or mobile app.

export KRISP_API_KEY="your-api-key"
setx KRISP_API_KEY "your-api-key"

Install the dependencies

pip install requests "websockets>=14"

Create the script

Save this as quickstart.py. It creates a short-lived session token from your API key, opens the /voice-isolation WebSocket, streams the file at real-time pace in 30 ms frames, and writes the cleaned audio the server sends back to cleaned.wav.

import asyncio
import json
import os
import sys
import wave

import requests
import websockets

URL = "wss://streaming.krisp.ai/voice-isolation"
SAMPLE_RATE = 16000
FRAME_MS = 30  # every audio message must be exactly 30 ms


def create_session_token() -> str:
    resp = requests.post(
        "https://api.developers.krisp.ai/v2/sdk/tokens/session",
        json={"usage_type": "viva", "expiration_ttl": 100},
        headers={"Authorization": f"api-key {os.environ['KRISP_API_KEY']}"},
    )
    resp.raise_for_status()
    return resp.json()["data"]["session_key"]


async def main(path: str) -> None:
    headers = {"Authorization": f"api-key {create_session_token()}"}
    async with websockets.connect(URL, additional_headers=headers) as ws:
        await ws.send(json.dumps({
            "model": "VIVA-tel",
            "sample_rate": SAMPLE_RATE,
            "suppression_level": 100,
        }))
        hello = json.loads(await ws.recv())
        if hello["type"] != "ready":
            raise RuntimeError(hello)

        async def send_audio() -> None:
            with wave.open(path, "rb") as wav:
                frames_per_chunk = SAMPLE_RATE * FRAME_MS // 1000
                frame_bytes = frames_per_chunk * 2  # 16-bit samples
                while chunk := wav.readframes(frames_per_chunk):
                    # Pad the last frame with silence so it is also exactly 30 ms.
                    await ws.send(chunk.ljust(frame_bytes, b"\x00"))
                    await asyncio.sleep(FRAME_MS / 1000)  # real-time pace
            await asyncio.sleep(1)  # let the last cleaned frames arrive
            await ws.close()

        sender = asyncio.create_task(send_audio())
        frames = 0
        with wave.open("cleaned.wav", "wb") as out:
            out.setnchannels(1)
            out.setsampwidth(2)
            out.setframerate(SAMPLE_RATE)
            async for message in ws:
                if isinstance(message, bytes):
                    out.writeframes(message)
                    frames += 1
                else:
                    print(message)  # an error message, if the server sends one
        await sender
        print(f"Wrote {frames} frames ({frames * FRAME_MS / 1000:.1f} s) to cleaned.wav")


asyncio.run(main(sys.argv[1]))

Run it

python quickstart.py sample.wav

When the file has been streamed, the script prints how many seconds of cleaned audio it wrote to cleaned.wav. Play sample.wav and cleaned.wav side by side: the main speaker stays, and background voices and noise are removed.

If the session token request fails, check that KRISP_API_KEY is set and that your team has access to Voice Isolation. The Authentication page lists every error code. If the server sends an error during the session, the script prints it; see Voice Isolation API errors.

Next steps


Did this page help you?