---
name: masterblaster
description: Master audio tracks with the Master Blaster API (masterblaster.mediaatlas.si): upload a WAV/FLAC/MP3, get a mastered 24-bit WAV, a measured report and a signed proof of origin. Use when the user asks to master, polish or loudness-match a song, to check what mastering did to a track, to verify a mastered file, or to buy or top up Master Blaster tracks.
---

# Master Blaster: mastering through the API

Master Blaster masters a track with a text-guided model plus our own safeguards (your sound stays yours, limits come from your track, every master is measured). The API is plain HTTPS. Full reference: https://masterblaster.mediaatlas.si/docs

## Before you start: the key

1. The API key is in the environment as `MASTERBLASTER_API_KEY` (it starts with `mb_`). Never print it, never put it in a file in a repository, never send it anywhere but `masterblaster.mediaatlas.si`.
2. No key yet? A person has to pay once, in the browser (Stripe). Give them one of these links and ask them to send you the key shown after paying:
   - Pricing and buying: https://masterblaster.mediaatlas.si/#pricing (3 EUR per track up to 5 minutes, or a monthly plan from 24 EUR for 12 tracks)
   - Or make the payment link yourself, no key needed: `python3 scripts/master.py buy track 5` (5 tracks) or `python3 scripts/master.py buy plan 1` (a plan of 12 tracks a month). It prints a Stripe Checkout link for the person to open.
3. Each agent should have its own key; do not share one key between agents.

## Master a track

Use the script (Python 3, standard library only; it uploads, waits, downloads both files, and tells what changed):

```
python3 scripts/master.py track.wav --out ./mastered
python3 scripts/master.py track.wav --chips balance,warmer --target -16 --out ./mastered
python3 scripts/master.py track.wav --clip     # 20 s demo excerpt, free of charge for keys with the clip mode
```

It writes `original.wav` and `mastered.wav` into `--out` and prints the loudness before and after, the findings, and the proof ID (`MB-XXXX-XXXX`).

Without the script, the same by hand:

```
curl -X POST "https://masterblaster.mediaatlas.si/v1/masters?mode=full&target=-16" -H "Authorization: Bearer $MASTERBLASTER_API_KEY" --data-binary @track.wav
# -> 202 {"id": "...", "url": "/v1/masters/<id>"}
curl https://masterblaster.mediaatlas.si/v1/masters/<id> -H "Authorization: Bearer $MASTERBLASTER_API_KEY"
# poll every 5-10 s until status is "done" (or "error"), then download result.files.original / .mastered
```

Options: `chips` (wishes from `GET /api/prompts`, for example `balance`, `warmer`, `clearer`), `target` (`source` keeps the track's own loudness, or `-14`, `-16`, `-18` LUFS), `mode` (`full` or `clip`).

## How long, and how long the files stay

- A 4 minute track takes under a minute of work once it is running; the queue can add more. Poll every 5 to 10 seconds. Do not poll faster than your key's `rpm` (default 30 requests per minute).
- **Results are deleted 24 hours after the job is done** (the clock starts when it is done, not when you submitted it). Download both files as soon as `status` is `done`. The `expires_s` field says how many seconds are left. Demo results without a key are deleted after one hour.

## Errors you will meet

| HTTP | `error.code` | What to do |
|---|---|---|
| 401 | `invalid_key` | The key is unknown or revoked. Ask the person for a new one. |
| 402 | `payment_required` | Prepaid tracks used up, or a monthly plan whose payment failed. Send the person to https://masterblaster.mediaatlas.si/#pricing, or `python3 scripts/master.py buy track 5` for a link. A paused plan resumes by itself when its payment goes through. |
| 413 | `too_large` | The track is longer or larger than the key allows (`GET /v1/usage` shows the limits). |
| 429 | `rate_limited` / `quota_exceeded` | Wait for the `Retry-After` seconds. A quota that is used up stays so until the next day or month. |
| 503 | `busy` | The queue is full: retry in a few minutes. |

`python3 scripts/master.py usage` shows the key's limits, what it used this month, the prepaid tracks left and the plan.

## Check what you got

- Open the report in `result.findings`: if mastering made something worse (clipping, mono loss, harshness), it says so in plain words. Tell the person, do not hide it.
- Every master carries a proof (ID `MB-XXXX-XXXX`, signed). To verify a file or an ID: https://masterblaster.mediaatlas.si/verify, or `GET /api/verify?id=MB-XXXX-XXXX`. A master that was edited afterwards is reported as changed.
- The master can sound worse than the original on a track the model does not suit. Always keep the original and let the person listen before release.

## Privacy

The service keeps no account and no audio beyond the retention above; only counts per key are kept for invoicing. Do not upload music the person has no rights to.