Documentazione API di Mixanalytic
Riferimento API ufficiale per https://mixanalytic.com. Usa questa API per caricare audio e ricevere analisi del mix con AI, moduli selezionabili e risposte compatte o complete.
URL di base: https://mixanalytic.com/api
Autenticazione
Invia la chiave API nell'header X-API-Key per ogni richiesta.
- 401 chiave mancante o non valida
- 403 chiave del piano gratuito senza accesso API
- 429 limite di richieste superato
Ambiti: write serve per il caricamento e l'analisi di Mixanalytic. content legge dati di ricerca dei contenuti con dati sensibili oscurati. content_write salva bozze di contenuti non pubbliche. Gli ambiti dei contenuti sono riservati agli amministratori.
Endpoint
| Metodo | Percorso | Scopo |
|---|---|---|
| GET | /api/test-data | Verifica della connessione e dell'autenticazione. |
| POST | /api/upload | Carica e analizza un file audio. |
| GET | /api/analyze/<file_id> | Analizza di nuovo tramite ID del file (se il file originale esiste ancora). |
| POST | /api/mastering | Carica un mix e avvia un mastering (quattro master). |
| GET | /api/mastering/<token> | Stato e risultati di un mastering. |
| GET | /api/mastering/<token>/<variant>.wav | Scarica un master come WAV a 24 bit. |
| GET | /api/content/analysis-feed | Feed di ricerca con dati sensibili oscurati per agenti di contenuti, riservato agli amministratori. |
| POST | /api/content/drafts | Endpoint di salvataggio o aggiornamento delle bozze per agenti di contenuti, riservato agli amministratori. |
| GET | /api/ai-stats?days=30 | Statistiche di utilizzo delle analisi AI. |
Richiesta di caricamento
POST/api/upload
| Campo | Tipo | Obbligatorio | Note |
|---|---|---|---|
| file | multipart file | Sì | Consentiti: mp3, wav, flac, m4a, aac, ogg. Max 95MB. |
| modules | string/list | No | Se omesso, vengono usati tutti i moduli per impostazione predefinita. |
| detail_level | string | No | full (predefinito) o summary. |
Un valore detail_level non valido restituisce 400. I file troppo grandi restituiscono 413.
Selezione dei moduli
Controlla quali moduli di analisi vengono restituiti (e calcolati) con modules.
Formati supportati:
- Stringa separata da virgole: modules=frequency_balance,clarity,mood
- Stringa di array JSON: modules=["frequency_balance","clarity","mood"]
- Chiave ripetuta (query/modulo): modules=frequency_balance&modules=clarity
- Tutti i moduli: modules=all o modules=*
| Modulo | Descrizione |
|---|---|
| frequency_balance | Punteggi di frequenza e bilanciamento su 7 bande. |
| dynamic_range | Gamma dinamica, fattore di cresta, PLR. |
| stereo_field | Metriche di larghezza, fase e correlazione. |
| clarity | Metriche di chiarezza e definizione spettrale. |
| harmonic_content | Tonalità e complessità armonica. |
| transients | Dati di attacco, densità dei transienti e impatto delle basse frequenze. |
| 3d_spatial | Coerenza di altezza, profondità e larghezza. |
| surround_compatibility | Compatibilità mono e punteggio di fase. |
| headphone_optimization | Punteggio di ottimizzazione della riproduzione in cuffia. |
| speaker_optimization | Punteggio di ottimizzazione della riproduzione tramite altoparlanti. |
| genre | Classificazione del genere e livello di confidenza. |
| voice | Presenza vocale e caratteristiche della voce. |
| instruments | Rilevamento degli strumenti e informazioni sull'arrangiamento. |
| mood | Profilo dell'atmosfera con energia e valenza. |
| keywords | Parole chiave ed etichette semantiche. |
| loudness | Misura LUFS, true peak, clipping e obiettivi dello streaming. Controlla distorsioni, picchi dovuti ai codec e variazioni di riproduzione sulle piattaforme. |
| noise | Misura rumore di fondo, ronzio di rete, fruscio e artefatti per ripulire le registrazioni prima che il mastering li renda più forti, brillanti e difficili da nascondere. |
| format_quality | Controlla codifica lossy, taglio spettrale e profondità in bit. Evita il mastering da MP3, AAC o sorgenti aumentate di risoluzione ma già degradate. |
| reference | Riferimento |
| visualizations | URL delle risorse visive generate per l'analisi. |
| ai_insights | Riepilogo e consigli generati da LLM. |
Controllo delle dimensioni della risposta
Usa detail_level:
- full (predefinito): risposta completa
- summary: risposta compatta per client web e mobile
Esempi
1) Caricamento e analisi completa
2) Caricamento e moduli selezionati
3) Caricamento, moduli selezionati e risposta sintetica
4) Endpoint di prova
5) JavaScript lato client
Metadati standard della risposta
Le risposte di analisi riuscite includono:
- requested_modules
- returned_modules
- detail_level
- available_modules
Mastering
Carica un mix finito e ricevi quattro master WAV a 24 bit da un solo mastering: dynamic, balanced, loud, chart. L'API usa lo stesso motore, lo stesso prezzo e la stessa quota mensile del Mastering Studio.
- Il mastering è riservato ai Supporter: 20 mastering per mese UTC sono inclusi, poi ogni mastering usa i token.
- Un mastering crea tutti e quattro i master. Dopo i mastering inclusi, un mastering costa 85 token. Se un mastering non riesce, ti restituiamo i token o il mastering incluso.
- Ogni account esegue un solo mastering alla volta, contando anche quelli avviati dal Mastering Studio.
- I master vengono eliminati 24 ore dopo la fine di un mastering, o dopo 30 giorni su un account Supporter, a meno che il mastering non venga conservato in I miei master. Scaricali prima dell'orario expires_at indicato nella risposta di stato.
- Per avviare un mastering serve l'ambito write. Stato e download richiedono read.
Richiesta di mastering
POST/api/mastering
Invia il mix come multipart/form-data. È obbligatorio solo file.
| Campo | Tipo | Obbligatorio | Note |
|---|---|---|---|
| file | multipart file | Sì | Consentiti: mp3, wav, flac, aiff, m4a, aac, ogg. Max 95 MB e 12 minuti. Il contenuto del file deve corrispondere all'estensione. |
| tone | number | No | Tilt del tono intorno a 1 kHz, in dB. Un valore negativo rende il suono più caldo, uno positivo più brillante. Da -2 a 2 con passo 0.5. Predefinito 0. |
| width | number | No | Livello del side sopra i 120 Hz, in dB. Un valore negativo restringe l'immagine stereo, uno positivo la allarga. I bassi restano al centro. Da -3 a 2 con passo 0.5. Predefinito 0. |
| punch | number | No | Compressione glue come multiplo di quanto misurato sul mix. 0 disattiva la compressione glue. Da 0 a 1.5 con passo 0.25. Predefinito 1. |
| loudness | number | No | Sposta insieme tutti e quattro i target di loudness, in LU. Se alzare ancora schiacciasse la batteria, il master si ferma prima e lo indica tra le sue modifiche. Da -3 a 1.5 con passo 0.5. Predefinito 0. |
| mono | string | No | Rende mono i bassi sotto i 120 Hz. Con auto si attiva solo quando le misure del mix lo richiedono. Uno tra auto, on, off. Predefinito auto. |
| deharsh | string | No | Attenua la banda 4–9 kHz solo nei momenti in cui emerge. Con auto si attiva solo quando le misure del mix lo richiedono. Uno tra auto, on, off. Predefinito auto. |
| source | string | No | Imposta il target degli acuti. ai non tocca mai la fascia dell'aria sopra i 10 kHz e punta ad acuti più contenuti. recorded punta a una parte alta più brillante. auto usa il rilevamento della musica IA dal report di song_id, oppure controlla direttamente il file caricato. Uno tra auto, ai, recorded. Predefinito auto. |
| style | string | No | Imposta il peso delle basse e quale master viene consigliato. auto usa il genere del report di song_id. Senza song_id non viene applicato alcun genere: le basse restano neutre e il consiglio segue la gamma di loudness, quindi invia uno stile per sceglierne uno. Uno tra auto, pop, rock, hiphop, electronic, rnb, metal, acoustic. Predefinito auto. |
| song_id | integer | No | L'id di un brano che hai analizzato. Viene riutilizzato il suo report salvato invece di misurare il file caricato. Carica lo stesso mix. |
| Idempotency-Key | header | No | 1–64 caratteri: lettere, cifre, _ e -. |
I numeri fuori intervallo vengono riportati nell'intervallo e arrotondati al suo passo. Un valore non numerico o una scelta sconosciuta restituisce 400 con invalid_settings.
Invia un header Idempotency-Key per ripetere la richiesta in sicurezza, con una chiave nuova per ogni mix. Se il tuo account ripete una chiave mentre il suo mastering esiste ancora, non viene addebitato né avviato nulla di nuovo: ricevi 200 con il corpo originale più "replayed": true. Se la ripetizione arriva mentre la prima richiesta è ancora in avvio, ricevi 429 busy. Dopo 503 failed, riprova con una chiave nuova.
Risposta di avvio
Un nuovo mastering restituisce 202:
Un mastering dalla quota Supporter ha "billed": "included" e "charged": 0. I Supporter ricevono anche un oggetto included con used, cap, reset_date.
Stato del mastering e download
GET/api/mastering/<token>
Interroga lo stato ogni 3–5 secondi, entro il limite di richieste della tua chiave, finché non è done o error.
- pending: stiamo creando i master.
- settling: il mastering non è riuscito e stiamo restituendo i token o il mastering incluso. Continua a interrogare lo stato.
- done: i quattro master sono pronti.
- error: il mastering non è riuscito e quanto addebitato è stato restituito. Il campo error indica il motivo: too_long, too_short, too_quiet, failed.
Una risposta con stato done contiene recommended, recommended_reason, warnings, source, settings, masters, expires_at, filename. Ogni elemento di masters ha key, url, target_lufs, ceiling, metrics, changes, peaks.
Le risposte done ed error includono anche access: il tuo saldo e i mastering inclusi dopo questo mastering.
Un token sconosciuto o scaduto, o il token di un altro account, restituisce 404 con {"status": "expired"}.
Download
GET/api/mastering/<token>/<variant>.wav
Restituisce il master come allegato WAV a 24 bit con il nome del file caricato, ad esempio My Mix - balanced.wav. variant è uno tra dynamic, balanced, loud, chart.
Una variante sconosciuta, il token di un altro account o un mastering scaduto o non ancora completato restituisce 404.
Ogni risposta di mastering include Cache-Control: private, no-store.
Errori di mastering
Gli errori restituiscono {"error": "invalid_file", "message": "…"}.
| Stato | Errore | Significato |
|---|---|---|
| 400 | invalid_file | File mancante, formato non supportato o contenuto che non corrisponde all'estensione. |
| 400 | invalid_settings | Un'impostazione non è un numero o non è tra le scelte consentite. |
| 400 | invalid_idempotency_key | L'header Idempotency-Key non è composto da 1–64 lettere, cifre, _ o -. |
| 402 | insufficient_credits | Token insufficienti. Il corpo della risposta include cost e balance. |
| 403 | Forbidden | Chiave di un account gratuito o chiave senza l'ambito richiesto da questo endpoint. Un Supporter il cui pagamento di rinnovo è fallito resta sul piano gratuito finché il pagamento non va a buon fine, quindi nel frattempo il mastering funziona solo nel Mastering Studio. Non viene addebitato nulla. |
| 403 | supporter_only | Per ora il mastering è disponibile solo per gli account Supporter. Non viene addebitato nulla. |
| 413 | File too large | Il file supera i 95 MB, quindi la richiesta viene rifiutata prima di raggiungere l'endpoint, a volte senza corpo JSON. Un file appena oltre il limite riceve invece invalid_file. |
| 429 | busy | Per questo account è già in corso o in avvio un mastering, dall'API o dallo studio. Il corpo della risposta include il suo token, che vale null finché quel mastering è ancora in avvio. |
| 429 | Rate Limit Exceeded | È stato raggiunto il limite al minuto, all'ora o al giorno della tua chiave. Il messaggio indica quale. |
| 503 | failed | Non è stato possibile avviare il mastering. Quanto addebitato viene restituito. |
Esempio di mastering
1) Avvia un mastering
2) Interroga lo stato fino al completamento
3) Scarica un master
Codici di errore
| Stato | Significato | Causa tipica |
|---|---|---|
| 400 | Richiesta non valida | Modulo/detail_level non valido, campo file mancante o file vuoto. |
| 401 | Non autorizzato | Chiave API mancante, non valida o scaduta. |
| 403 | Accesso negato | Accesso API non consentito per il livello dell'account. |
| 404 | Non trovato | /api/analyze/<file_id> file non più disponibile (eliminazione per la privacy). |
| 413 | Contenuto troppo grande | File più grande di 95MB. |
| 429 | Limite di richieste superato | Troppe richieste al minuto, all'ora o al giorno. |
| 500 | Errore del server | Errore di analisi o di esecuzione. |
Note per il frontend
- Per i client web e mobile, preferisci detail_level=summary.
- Richiedi solo i moduli necessari per il primo rendering per ridurre la latenza e le dimensioni della risposta.
- Gestisci 429 e 500 con nuovi tentativi e intervalli di attesa crescenti.
- Non esporre chiavi di produzione di lunga durata nei pacchetti pubblici.