Produzione
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.
curl -X GET "https://mixanalytic.com/api/test-data" \
-H "X-API-Key: YOUR_API_KEY"
- 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 Mix Analyzer. 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). |
| 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 100MB. |
| 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 per mantenere il master abbastanza forte senza distorsioni, picchi dovuti ai codec o sorprese 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 per non fare per errore il mastering da sorgenti MP3, AAC o audio aumentato di risoluzione ma già degradato prima della pubblicazione. |
| 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
curl -X POST "https://mixanalytic.com/api/upload" \
-H "X-API-Key: YOUR_API_KEY" \
-F "file=@/path/to/track.mp3"
2) Caricamento e moduli selezionati
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) Caricamento, moduli selezionati e risposta sintetica
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) Endpoint di prova
curl -X GET "https://mixanalytic.com/api/test-data" \
-H "X-API-Key: YOUR_API_KEY"
5) JavaScript lato client
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);
Metadati standard della risposta
Le risposte di analisi riuscite includono:
- requested_modules
- returned_modules
- detail_level
- available_modules
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 100MB. |
| 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.