Mixanalytic API Documentation
Official API reference for https://mixanalytic.com. Use this API to upload audio and receive AI-powered mix analysis with selectable modules and compact/full response modes.
Base URL: https://mixanalytic.com/api
Authentication
Send your API key in the X-API-Key header for every request.
- 401 missing/invalid key
- 403 free-tier key without API access
- 429 rate limit exceeded
Scopes: write is for Mixanalytic upload/analysis. content reads redacted content research data. content_write saves non-public content drafts. Content scopes are admin-only.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| GET | /api/test-data | Connectivity/auth check. |
| POST | /api/upload | Upload + analyze audio file. |
| GET | /api/analyze/<file_id> | Re-analyze by file ID (if original file still exists). |
| POST | /api/mastering | Upload a mix and start one mastering run (four masters). |
| GET | /api/mastering/<token> | Status and results of a mastering run. |
| GET | /api/mastering/<token>/<variant>.wav | Download one master as a 24-bit WAV. |
| GET | /api/content/analysis-feed | Admin-only redacted research feed for content agents. |
| POST | /api/content/drafts | Admin-only draft save/update endpoint for content agents. |
| GET | /api/ai-stats?days=30 | Usage stats for AI analysis. |
Upload Request
POST/api/upload
| Field | Type | Required | Notes |
|---|---|---|---|
| file | multipart file | Yes | Allowed: mp3, wav, flac, m4a, aac, ogg. Max 95MB. |
| modules | string/list | No | Defaults to all modules if omitted. |
| detail_level | string | No | full (default) or summary. |
Invalid detail_level returns 400. Oversized files return 413.
Module Selection
Control which analysis modules are returned (and computed) with modules.
Formats supported:
- Comma-separated string: modules=frequency_balance,clarity,mood
- JSON array string: modules=["frequency_balance","clarity","mood"]
- Repeated key (query/form): modules=frequency_balance&modules=clarity
- All modules: modules=all or modules=*
| Module | Description |
|---|---|
| frequency_balance | 7-band frequency and balance scoring. |
| dynamic_range | Dynamic range, crest factor, PLR. |
| stereo_field | Width/phase/correlation metrics. |
| clarity | Spectral clarity and definition metrics. |
| harmonic_content | Key and harmonic complexity. |
| transients | Attack, transient density, and low-end punch data. |
| 3d_spatial | Height/depth/width consistency. |
| surround_compatibility | Mono compatibility + phase score. |
| headphone_optimization | Headphone playback optimization score. |
| speaker_optimization | Speaker playback optimization score. |
| genre | Genre classification and confidence. |
| voice | Vocal presence and voice characteristics. |
| instruments | Instrument detection and arrangement info. |
| mood | Mood profile with energy/valence. |
| keywords | Semantic keywords and tags. |
| loudness | Measure LUFS, true peak, clipping, and streaming targets so your master stays loud enough without distortion, codec peaks, or platform surprises. |
| noise | Measure noise floor, mains hum, hiss, and artifacts so you can clean recordings before they get louder, brighter, and harder to hide in mastering. |
| format_quality | Check lossy encoding, spectral cutoff, and bit depth so you do not master from degraded MP3, AAC, or upscaled audio sources by mistake before release. |
| reference | Reference |
| visualizations | URLs for generated analysis visual assets. |
| ai_insights | LLM-generated summary and recommendations. |
Response Size Control
Use detail_level:
- full (default): full payload
- summary: compact payload for frontend/mobile clients
Examples
1) Upload + full analysis
2) Upload + selected modules
3) Upload + selected modules + summary payload
4) Test endpoint
5) Client-side JavaScript
Standard Response Metadata
Successful analysis responses include:
- requested_modules
- returned_modules
- detail_level
- available_modules
Mastering
Upload a finished mix and get four 24-bit WAV masters from one run: dynamic, balanced, loud, chart. The API uses the same engine, price and monthly quota as the Mastering Studio.
- Mastering is for Supporters: 20 runs per UTC month are included, then each run uses tokens.
- One run makes all four masters. After the included runs, a run costs 85 tokens. If a run fails, its tokens or included run are given back.
- Each account makes one run at a time, shared with the Mastering Studio.
- Masters are deleted 24 hours after a run finishes, or 30 days on a Supporter account, unless the run is kept in My masters. Download them before expires_at in the status response.
- Starting a run needs the write scope. Status and downloads need read.
Mastering Request
POST/api/mastering
Send the mix as multipart/form-data. Only file is required.
| Field | Type | Required | Notes |
|---|---|---|---|
| file | multipart file | Yes | Allowed: mp3, wav, flac, aiff, m4a, aac, ogg. Max 95 MB and 12 minutes. The file contents must match the extension. |
| tone | number | No | Tone tilt around 1 kHz, in dB. Negative is warmer, positive is brighter. -2 to 2 in steps of 0.5. Default 0. |
| width | number | No | Side level above 120 Hz, in dB. Negative is narrower, positive is wider. The bass stays centred. -3 to 2 in steps of 0.5. Default 0. |
| punch | number | No | Glue compression as a multiple of what the mix measured. 0 turns glue off. 0 to 1.5 in steps of 0.25. Default 1. |
| loudness | number | No | Moves all four loudness targets together, in LU. If louder would squash the drums, the master stops earlier and says so in its changes. -3 to 1.5 in steps of 0.5. Default 0. |
| mono | string | No | Makes the bass mono below 120 Hz. auto applies it only when the mix measures a need for it. One of auto, on, off. Default auto. |
| deharsh | string | No | Turns 4–9 kHz down only in the moments it jumps out. auto applies it only when the mix measures a need for it. One of auto, on, off. Default auto. |
| source | string | No | Sets the treble target. ai never moves the air band above 10 kHz and aims the highs lower. recorded aims for a brighter top. auto uses the AI-music verdict from the song_id report, or checks the upload itself. One of auto, ai, recorded. Default auto. |
| style | string | No | Sets the low-end weight and which master is recommended. auto uses the genre from the song_id report. Without song_id, no genre is applied: the low end stays neutral and the recommendation follows the loudness range, so send a style to choose one. One of auto, pop, rock, hiphop, electronic, rnb, metal, acoustic. Default auto. |
| song_id | integer | No | The id of a song you analysed. Its stored report is reused instead of measuring the upload. Upload the same mix. |
| Idempotency-Key | header | No | 1–64 characters: letters, digits, _ and -. |
Numbers outside a range are clamped and rounded to its step. A value that is not a number, or an unknown choice, returns 400 with invalid_settings.
Send an Idempotency-Key header to retry safely, with a new key for each mix. If your account repeats a key while its run still exists, nothing is charged or started again: you get 200 with the original body plus "replayed": true. A repeat that arrives while the first request is still starting gets 429 busy. After 503 failed, retry with a new key.
Start Response
A new run returns 202:
A run from the Supporter quota has "billed": "included" and "charged": 0. Supporters also get an included object with used, cap, reset_date.
Mastering Status and Downloads
GET/api/mastering/<token>
Poll every 3–5 seconds, within your key's rate limit, until the status is done or error.
- pending: the masters are being made.
- settling: the run failed and its tokens or included run are being given back. Keep polling.
- done: the four masters are ready.
- error: the run failed and what it was charged has been given back. The error field says why: too_long, too_short, too_quiet, failed.
A done response contains recommended, recommended_reason, warnings, source, settings, masters, expires_at, filename. Each item in masters has key, url, target_lufs, ceiling, metrics, changes, peaks.
Done and error responses also include access: your balance and included runs after the run.
Unknown or expired tokens, and other accounts' tokens, return 404 with {"status": "expired"}.
Download
GET/api/mastering/<token>/<variant>.wav
Returns the master as a 24-bit WAV attachment named after your upload, for example My Mix - balanced.wav. variant is one of dynamic, balanced, loud, chart.
An unknown variant, another account's token, or a run that has expired or is not done returns 404.
Every mastering response carries Cache-Control: private, no-store.
Mastering Errors
Errors return {"error": "invalid_file", "message": "…"}.
| Status | Error | Meaning |
|---|---|---|
| 400 | invalid_file | Missing file, unsupported format, or contents that don't match the extension. |
| 400 | invalid_settings | A setting is not a number or not one of its choices. |
| 400 | invalid_idempotency_key | The Idempotency-Key header is not 1–64 letters, digits, _ or -. |
| 402 | insufficient_credits | Not enough tokens. The body includes cost and balance. |
| 403 | Forbidden | A Free account's key, or a key without the scope this endpoint needs. A Supporter whose renewal payment failed is on Free until it goes through, so meanwhile mastering works only in the Mastering Studio. Nothing is charged. |
| 403 | supporter_only | Mastering is open to Supporter accounts only for now. Nothing is charged. |
| 413 | File too large | The file is over 95 MB, so the request is refused before it reaches the endpoint, sometimes without a JSON body. A file just over the limit gets invalid_file instead. |
| 429 | busy | A run is already in progress or starting for this account, from the API or the studio. The body includes its token, which is null while that run is still starting. |
| 429 | Rate Limit Exceeded | Your key's per-minute, per-hour or per-day limit was reached. The message says which. |
| 503 | failed | The run could not start. Anything charged for it is given back. |
Mastering Example
1) Start a run
2) Poll until done
3) Download a master
Error Codes
| Status | Meaning | Typical Cause |
|---|---|---|
| 400 | Bad Request | Invalid module/detail_level, missing file field, empty file. |
| 401 | Unauthorized | Missing, invalid, or expired API key. |
| 403 | Forbidden | API access not allowed for account tier. |
| 404 | Not Found | /api/analyze/<file_id> file no longer available (privacy deletion). |
| 413 | Payload Too Large | File larger than 95MB. |
| 429 | Rate Limit Exceeded | Too many requests per minute/hour/day. |
| 500 | Server Error | Analysis/runtime failure. |
Frontend Notes
- For web/mobile clients, prefer detail_level=summary.
- Request only modules needed for first render to reduce latency and payload.
- Handle 429 and 500 with retry + backoff.
- Do not expose long-lived production keys in public bundles.