Quick Start

Get your API key

Store it as an environment variable:

export CLEANVOICE_API_KEY="your_api_key"

Install the SDK

pip install cleanvoice-sdk

npm install @cleanvoice/cleanvoice-sdk
# or: pnpm add @cleanvoice/cleanvoice-sdk  |  yarn add @cleanvoice/cleanvoice-sdk

No installation needed — just use curl.

Clean your audio

You can pass a public URL, a local file path, or a NumPy array — the SDK handles uploading and polling automatically.

from cleanvoice import Cleanvoice

client = Cleanvoice.from_env()

# Option 1: public URL
result = client.process("https://example.com/episode.mp3", fillers=True, long_silences=True)

# Option 2: local file path (SDK uploads it for you)
result = client.process("/path/to/episode.mp3", fillers=True, long_silences=True)

# Option 3: NumPy array  (useful in audio pipelines / Jupyter)
result = client.process((audio_array, sample_rate), fillers=True)

result.audio.download("cleaned.mp3")

You can pass a public URL or a local file path — the SDK handles uploading and polling automatically.

import Cleanvoice from '@cleanvoice/cleanvoice-sdk';

const client = new Cleanvoice({ apiKey: process.env.CLEANVOICE_API_KEY });

// Option 1: public URL
const result = await client.process('https://example.com/episode.mp3', {
  fillers: true,
  longSilences: true,
  removeNoise: true,
  normalize: true,
});

// Option 2: local file path (SDK uploads it for you)
const result = await client.process('/path/to/episode.mp3', { fillers: true });

console.log('Download:', result.url);

You can submit a public URL directly, or upload a local file first to get a URL.

If your file is already online:

curl -X POST https://api.cleanvoice.ai/v2/edits \
  -H "X-API-Key: $CLEANVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "files": ["https://example.com/episode.mp3"],
      "config": {
        "fillers": { "enabled": true },
        "long_silences": { "enabled": true }
      }
    }
  }'

If your file is local — upload it first:

# 1. Get a signed upload URL
curl -X POST https://api.cleanvoice.ai/v2/uploads \
  -H "X-API-Key: $CLEANVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "filename": "episode.mp3" }'
# → returns { "upload_url": "...", "file_url": "..." }

# 2. Upload your file
curl -X PUT "UPLOAD_URL" -H "Content-Type: audio/mpeg" --data-binary @episode.mp3

# 3. Submit the edit using the file_url
curl -X POST https://api.cleanvoice.ai/v2/edits \
  -H "X-API-Key: $CLEANVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "files": ["FILE_URL"], "config": { "fillers": { "enabled": true } } } }'

Then poll for the result:

curl https://api.cleanvoice.ai/v2/edits/EDIT_ID \
  -H "X-API-Key: $CLEANVOICE_API_KEY"

process() blocks until the job finishes — typically ~30s for 2–3 min clips, 5–10 min for 1h files.

Deliver results directly to your storage

Pass a pre-signed PUT URL as signed_url when creating an edit. When processing finishes, Cleanvoice will PUT the cleaned file directly to your storage (S3, GCS, etc.) — no extra download step needed.

Generate the signed URL from your storage provider first, then include it in the request:

edit_id = client.create_edit(
    "https://example.com/episode.mp3",
    fillers=True,
    signed_url="https://your-bucket.s3.amazonaws.com/cleaned.mp3?X-Amz-Signature=...",
)

const editId = await client.createEdit(
  'https://example.com/episode.mp3',
  {
    fillers: true,
    signedUrl: 'https://your-bucket.s3.amazonaws.com/cleaned.mp3?X-Amz-Signature=...',
  }
);

curl -X POST https://api.cleanvoice.ai/v2/edits \
  -H "X-API-Key: $CLEANVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "files": ["https://example.com/episode.mp3"],
      "config": { "fillers": { "enabled": true } }
    },
    "signed_url": "https://your-bucket.s3.amazonaws.com/cleaned.mp3?X-Amz-Signature=..."
  }'

Once the job completes, the cleaned file will appear in your bucket. You can still poll the edit to track status.

Need a public URL for your file?

If your file is sitting in cloud storage, grab a direct download link:

Dropbox — Share → Copy link, then change ?dl=0 to ?dl=1
Google Drive — Share (anyone with link), then use https://drive.google.com/uc?export=download&id=FILE_ID
S3 — aws s3 presign s3://bucket/file.mp3 --expires-in 3600

What to clean

Not sure which options to turn on? See Edit Settings for common presets, or the Configuration Reference for every option.