Production

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.

curl -X GET "https://mixanalytic.com/api/test-data" \ -H "X-API-Key: YOUR_API_KEY"
  • 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-dataConnectivity/auth check.
POST/api/uploadUpload + analyze audio file.
GET/api/analyze/<file_id>Re-analyze by file ID (if original file still exists).
POST/api/masteringUpload 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>.wavDownload one master as a 24-bit WAV.
GET/api/content/analysis-feedAdmin-only redacted research feed for content agents.
POST/api/content/draftsAdmin-only draft save/update endpoint for content agents.
GET/api/ai-stats?days=30Usage stats for AI analysis.

Upload Request

POST/api/upload

Field Type Required Notes
filemultipart fileYesAllowed: mp3, wav, flac, m4a, aac, ogg. Max 95MB.
modulesstring/listNoDefaults to all modules if omitted.
detail_levelstringNofull (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_balance7-band frequency and balance scoring.
dynamic_rangeDynamic range, crest factor, PLR.
stereo_fieldWidth/phase/correlation metrics.
claritySpectral clarity and definition metrics.
harmonic_contentKey and harmonic complexity.
transientsAttack, transient density, and low-end punch data.
3d_spatialHeight/depth/width consistency.
surround_compatibilityMono compatibility + phase score.
headphone_optimizationHeadphone playback optimization score.
speaker_optimizationSpeaker playback optimization score.
genreGenre classification and confidence.
voiceVocal presence and voice characteristics.
instrumentsInstrument detection and arrangement info.
moodMood profile with energy/valence.
keywordsSemantic keywords and tags.
loudnessMeasure LUFS, true peak, clipping, and streaming targets so your master stays loud enough without distortion, codec peaks, or platform surprises.
noiseMeasure noise floor, mains hum, hiss, and artifacts so you can clean recordings before they get louder, brighter, and harder to hide in mastering.
format_qualityCheck lossy encoding, spectral cutoff, and bit depth so you do not master from degraded MP3, AAC, or upscaled audio sources by mistake before release.
referenceReference
visualizationsURLs for generated analysis visual assets.
ai_insightsLLM-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

curl -X POST "https://mixanalytic.com/api/upload" \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@/path/to/track.mp3"

2) Upload + selected modules

curl -X POST "https://mixanalytic.com/api/upload" \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@/path/to/track.mp3" \ -F "modules=frequency_balance,dynamic_range,genre,mood,keywords"

3) Upload + selected modules + summary payload

curl -X POST "https://mixanalytic.com/api/upload" \ -H "X-API-Key: YOUR_API_KEY" \ -F "file=@/path/to/track.mp3" \ -F "modules=frequency_balance,stereo_field,clarity,ai_insights" \ -F "detail_level=summary"

4) Test endpoint

curl -X GET "https://mixanalytic.com/api/test-data" \ -H "X-API-Key: YOUR_API_KEY"

5) Client-side JavaScript

const formData = new FormData(); formData.append('file', fileInput.files[0]); formData.append('modules', 'frequency_balance,dynamic_range,mood,ai_insights'); formData.append('detail_level', 'summary'); const res = await fetch('https://mixanalytic.com/api/upload', { method: 'POST', headers: { 'X-API-Key': 'YOUR_API_KEY' }, body: formData }); const data = await res.json(); console.log(data.analysis, data.returned_modules);

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
filemultipart fileYesAllowed: mp3, wav, flac, aiff, m4a, aac, ogg. Max 95 MB and 12 minutes. The file contents must match the extension.
tonenumberNoTone tilt around 1 kHz, in dB. Negative is warmer, positive is brighter. -2 to 2 in steps of 0.5. Default 0.
widthnumberNoSide 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.
punchnumberNoGlue compression as a multiple of what the mix measured. 0 turns glue off. 0 to 1.5 in steps of 0.25. Default 1.
loudnessnumberNoMoves 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.
monostringNoMakes 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.
deharshstringNoTurns 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.
sourcestringNoSets 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.
stylestringNoSets 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_idintegerNoThe id of a song you analysed. Its stored report is reused instead of measuring the upload. Upload the same mix.
Idempotency-KeyheaderNo1–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:

{ "token": "3b9f0c2e7d4a41f6a8e5c1b2d3f4a5b6", "status": "pending", "status_url": "/api/mastering/3b9f0c2e7d4a41f6a8e5c1b2d3f4a5b6", "billed": "tokens", "charged": 85, "balance": 415, "expires_in_hours": 720 }

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
400invalid_fileMissing file, unsupported format, or contents that don't match the extension.
400invalid_settingsA setting is not a number or not one of its choices.
400invalid_idempotency_keyThe Idempotency-Key header is not 1–64 letters, digits, _ or -.
402insufficient_creditsNot enough tokens. The body includes cost and balance.
403ForbiddenA 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.
403supporter_onlyMastering is open to Supporter accounts only for now. Nothing is charged.
413File too largeThe 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.
429busyA 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.
429Rate Limit ExceededYour key's per-minute, per-hour or per-day limit was reached. The message says which.
503failedThe run could not start. Anything charged for it is given back.

Mastering Example

1) Start a run

curl -X POST "https://mixanalytic.com/api/mastering" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Idempotency-Key: YOUR_UNIQUE_KEY_FOR_THIS_MIX" \ -F "file=@/path/to/mix.wav" \ -F "style=electronic" \ -F "loudness=0.5"

2) Poll until done

curl "https://mixanalytic.com/api/mastering/TOKEN" \ -H "X-API-Key: YOUR_API_KEY"

3) Download a master

curl -o "mix - balanced.wav" "https://mixanalytic.com/api/mastering/TOKEN/balanced.wav" \ -H "X-API-Key: YOUR_API_KEY"

Error Codes

Status Meaning Typical Cause
400Bad RequestInvalid module/detail_level, missing file field, empty file.
401UnauthorizedMissing, invalid, or expired API key.
403ForbiddenAPI access not allowed for account tier.
404Not Found/api/analyze/<file_id> file no longer available (privacy deletion).
413Payload Too LargeFile larger than 95MB.
429Rate Limit ExceededToo many requests per minute/hour/day.
500Server ErrorAnalysis/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.