Clean audio files by API

Every request carries an API key as a bearer token: Authorization: Bearer kvk_live_…. Create keys in Dashboard → AI agents & API (up to 10 active keys). A key is shown once; we store only a hash, so keep it in a secret store and revoke it from the dashboard if it leaks — revocation applies on the next request. Keys carry scopes: cleanup (create, read, cancel jobs; also reads usage) and usage:read.

Requests and responses are JSON. Files never pass through the API itself — they go straight to storage over short-lived presigned URLs.

export KLEERVOX_API_KEY=kvk_live_…   # Dashboard → AI agents & API → API keys# 1. Ask for an upload URL (exact size in bytes + the Content-Type you will send)curl -sS -X POST https://api.kleervox.com/api/v1/cleanups/uploads \  -H "Authorization: Bearer $KLEERVOX_API_KEY" \  -H "Content-Type: application/json" \  -d '{"filename":"interview.mp3","sizeBytes":'"$(stat -c%s interview.mp3)"',"contentType":"audio/mpeg"}'# → data.uploadId, data.putUrl, data.headers, data.curlCommand, data.expiresAt (1 h)# 2. PUT the file straight to storage (the file never passes through the API)curl -fsS -X PUT -H "Content-Type: audio/mpeg" -T interview.mp3 "<putUrl>"# 3. Start the cleanup (a retry with the same Idempotency-Key returns the same job)curl -sS -X POST https://api.kleervox.com/api/v1/cleanups \  -H "Authorization: Bearer $KLEERVOX_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: interview-2026-10-20" \  -d '{"uploadId":"<uploadId>","options":{"output":"mp3","strength":1}}'# → data.job.id, data.job.status = "queued"# 4. Wait for it: long-poll up to 45 s per call, repeat until the status is finalcurl -sS "https://api.kleervox.com/api/v1/cleanups/<jobId>?wait=45" -H "Authorization: Bearer $KLEERVOX_API_KEY"# → data.job.status = "done", data.job.downloadUrl (valid 1 h, re-issued on every GET)# 5. Download the cleaned filecurl -fsS -o interview-clean.mp3 "<downloadUrl>"

From a public URL instead

If the file is already online (a public link, a presigned cloud-storage URL), skip the upload and pass sourceUrl. It must be a public https:// URL without credentials in it; we download it on our side.

curl -sS -X POST https://api.kleervox.com/api/v1/cleanups \  -H "Authorization: Bearer $KLEERVOX_API_KEY" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: podcast-ep-42" \  -d '{"sourceUrl":"https://example.com/podcast-ep-42.mp4","options":{"keepVideo":true}}'

Response envelope

// success{ "success": true, "message": "ok", "data": { "job": { "id": "…", "status": "queued", … } } }// refused request{ "success": false, "message": "API & MCP cleanup is part of the Creator plan (2 h a month included, then per-minute overage). Upgrade to Creator to use Kleervox from an AI agent: …",  "data": null, "error_code": "BILLING_REQUIRED" }

All paths are relative to /api/v1/cleanups.

Accepted inputs: .wav .mp3 .m4a .aac .ogg .opus .flac .webm .mp4 .mov .mkv — checked by inspecting the file on our server, not by its extension. Video keeps its picture track untouched; only the audio is cleaned.

done, failed, cancelled, rejected and expired are final. A finished job’s error is { code, message } with a code from the table below.

Refused requests return the envelope with error_code; failed or rejected jobs carry the same codes in job.error.code (“job” below). Codes are stable — branch on them, never on the message. Malformed input returns 400 VALIDATION_ERROR; exceeding a rate limit returns 429.

• Creator’s included 2 hours a month are used first. Past them, overage is billed on the input audio duration measured by our server, per second, priced per minute. Video is billed on its audio duration.
• Minimum 30 seconds per job.
• Only done jobs are billed. Failed, rejected, cancelled and expired jobs cost nothing; idempotent retries never bill twice.
• A monthly spend limit (default $25, adjustable in the dashboard) caps the total: a job that would cross it is rejected with SPEND_LIMIT_REACHED before any work. New accounts are capped at $25 until the first invoice is paid.
• Invoiced monthly in arrears by Stripe. GET /usage shows this month’s minutes, amount and remaining limit.

Inputs and outputs are deleted 24 hours after a job finishes (with a storage-level rule as a backstop); job records without the file are kept 90 days. Files are processed automatically, never used for training, and filenames and URLs are not written to our logs. Only the host of a sourceUrl is stored, never the full URL.

Connect Kleervox to Claude, ChatGPT, Cursor or any MCP client. It exposes the same jobs as the REST API.

Endpoint: https://mcp.kleervox.com/mcp (Streamable HTTP; API key or OAuth).

https://mcp.kleervox.com/mcp

claude mcp add --transport http kleervox \  https://mcp.kleervox.com/mcp \  --header "Authorization: Bearer <YOUR_API_KEY>"

{  "mcpServers": {    "kleervox": {      "url": "https://mcp.kleervox.com/mcp",      "headers": {        "Authorization": "Bearer <YOUR_API_KEY>"      }    }  }}