# Audio Cleaner calling guide — v1

Base URL: `https://gateway.apibasket.com/media/audio-cleaner`. The example defaults to API and function version `1.0.0`; the `/v1/` Skill path is the resource version. Use the versions shown in the published documentation, and configure `AUDIO_CLEANER_API_VERSION`, `AUDIO_CLEANER_FUNCTION_VERSION` and `AUDIO_CLEANER_RELEASE` when intentionally selecting another published version or pinning a release. Every control request uses `Authorization: Bearer $API_BASKET_KEY`. Never send this header to a file upload or download URL.

## Functions

| Function | Method | Request |
|---|---|---|
| denoise_audio / denoise_video / inspect_media / analyze_audio / generate_waveform | POST | file_name, content_type, file_size_bytes |
| upload_parts | POST | task_id, parts: [{part_number, content_md5}] |
| upload_complete | POST | task_id |
| get_task | GET | query task_id |
| list_tasks | GET | optional status, limit, cursor |
| cancel_task | POST | task_id |
| download_links | POST | task_id |
| concurrency | GET | none |
| increase_concurrency | POST | additional_slots, duration_steps, optional starts_at (RFC3339) |
| capabilities | GET | none |

All POST functions except upload_parts require a stable `Idempotency-Key` of 16–200 characters. Persist it before sending. upload_parts needs no client idempotency key: the task identity deduplicates its 50 credit reservation. Re-signing a part does not charge again. Send the exact returned headers in each direct PUT. Parts are 8 MiB except the last; compute base64 MD5 per part. Complete only after all PUTs succeed. Request at most 100 credentials at once. The Python client requests one at a time and keeps memory bounded.

The public execution envelope contains `resp`; unwrap that field when accompanied by the timing and precharge fields. Task creation returns `task`, `part_size_bytes`, `part_count`, `upload_expires_at`. GET returns `task`, `usage` and `artifacts`. `usage` is null until verified success. Success gives decimal-string `duration_seconds`, original integer `channels`, integer `billable_minutes`, integer `billable_channel_minutes`. Never treat missing usage as zero.

## Pricing

Let D be the fully validated selected input audio track duration and C its original channel count. Choose the default track or, if absent, the first. M = ceil(D/60); CM = C×M. Other audio tracks and silent video tails do not add to the price. Waveform downmix does not reduce C.

| Successful operation | Credits |
|---|---:|
| Audio / video denoising | 50×M |
| Media inspection | 10 |
| Technical metrics | 15×CM |
| Waveform | 10×CM |

A 61 second stereo input costs 100 / 10 / 60 / 40 credits respectively. Creation is free. First upload credentials reserve 50 once, before signing. Success returns the full original reservation and charges the full processing fee in one settlement. Returned subscription credits that have expired do not become available again; the success fee uses current credits and can create an amount owed. Later spending remains subject to account and Key limits.

After reservation, cancellation, expiry before success and proven invalid input retain 50 with no processing fee. Service faults return 50 with no processing fee. An uncertain failure is reviewed; do not infer its settlement from a generic error. Before reservation, these states cost zero. Expired successful results keep their original settlement.

## State and limits

UPLOADING → QUEUED → RUNNING → READY → COMPLETED. CANCELED, FAILED and EXPIRED are terminal. READY still occupies a lifecycle slot. Claiming download credentials changes READY to COMPLETED and releases the slot. Stopping polling does not cancel or affect settlement. Cancel only while UPLOADING or unstarted QUEUED; a concurrent start can win. Poll using the same task ID after any interrupted request.

Maximum input: 1 GiB. Supported duration: 3 seconds–24 hours. Supported original channels: 1, 2, 6, 8. Call capabilities for supported containers, sample rates, current retention and concurrency limits; file extension, Content-Type and verified container must agree. Inputs waiting to start expire after 12 hours; processing/recovery protects an active input. Results last 24 hours from success. Download credentials last at most 15 minutes and do not extend result retention.

Download metadata includes SHA-256. Claim explicitly and download explicitly. Three GETs per artifact are shared across reissued credentials; Range consumes one; HEAD is free. A failed stream may have consumed a GET. Never automatically retry a file GET. Obtain fresh credentials explicitly if expired.

## Example

Set `API_BASKET_KEY` privately. Run with Python 3.11+ (standard library only):

```sh
python scripts/audio_cleaner.py run input.wav --operation analyze_audio --state task.json --upload
python scripts/audio_cleaner.py resume --state task.json
python scripts/audio_cleaner.py resume --state task.json --claim --download-dir results
python scripts/audio_cleaner.py cancel --state task.json
python scripts/audio_cleaner.py increase --slots 2 --steps 3 --starts-at 2027-01-01T00:00:00Z --state purchase.json --confirm-credits 60000
```

`--upload` explicitly authorizes the upload reservation and successful processing rate. `--claim` explicitly claims the result; `--download-dir` explicitly downloads and validates artifacts. Without those flags, query only. State contains task metadata and keys, never the API Key, signed URLs or file content. Re-select the original input with `resume --file input.wav --upload` when recovering an interrupted upload. The state file fingerprints the original file and rejects a changed one.

For insufficient credits, replenish credits and retry the same task. For an unknown signing outcome, retry upload_parts on that task. For a purchase timeout, repeat the exact purchase/state command; do not create another state file or purchase key. A final rejected purchase needs a new intent after the underlying problem is corrected. A compensated purchase must not be treated as active. Omitted starts_at begins at confirmed server success; each duration step lasts exactly 24 hours.
