Production

Documentation de l’API Mixanalytic

Référence officielle de l’API https://mixanalytic.com. Envoyez des fichiers audio et recevez une analyse de mix par IA avec des modules au choix et une réponse compacte ou complète.

URL de base : https://mixanalytic.com/api

Authentification

Envoyez votre clé API dans l’en-tête X-API-Key pour chaque requête.

curl -X GET "https://mixanalytic.com/api/test-data" \ -H "X-API-Key: YOUR_API_KEY"
  • 401 clé manquante ou invalide
  • 403 clé d’une offre gratuite sans accès à l’API
  • 429 limite de fréquence dépassée

Portées : write sert à l’envoi et à l’analyse Mixanalytic. content lit les données de recherche de contenu expurgées. content_write enregistre des brouillons non publics. Les portées de contenu sont réservées aux administrateurs.

Points de terminaison

Méthode Chemin Fonction
GET/api/test-dataVérification de la connexion et de l’authentification.
POST/api/uploadEnvoi et analyse d’un fichier audio.
GET/api/analyze/<file_id>Nouvelle analyse par identifiant de fichier (si le fichier d’origine existe encore).
POST/api/masteringEnvoi d’un mix et lancement d’un mastering (quatre masters).
GET/api/mastering/<token>Statut et résultats d’un mastering.
GET/api/mastering/<token>/<variant>.wavTéléchargement d’un master en WAV 24 bits.
GET/api/content/analysis-feedFlux de recherche expurgé réservé aux administrateurs pour les agents de contenu.
POST/api/content/draftsPoint de terminaison d’enregistrement et de mise à jour des brouillons, réservé aux administrateurs pour les agents de contenu.
GET/api/ai-stats?days=30Statistiques d’utilisation des analyses IA.

Requête d’envoi

POST/api/upload

Champ Type Obligatoire Remarques
filemultipart fileOuiFormats autorisés : mp3, wav, flac, m4a, aac, ogg. Maximum : 95MB.
modulesstring/listNonTous les modules sont sélectionnés par défaut si ce champ est omis.
detail_levelstringNonfull (par défaut) ou summary.

Une valeur detail_level invalide renvoie 400. Les fichiers trop volumineux renvoient 413.

Sélection des modules

Définissez les modules d’analyse renvoyés et calculés avec modules.

Formats pris en charge :

  • Chaîne séparée par des virgules : modules=frequency_balance,clarity,mood
  • Chaîne représentant un tableau JSON : modules=["frequency_balance","clarity","mood"]
  • Clé répétée (requête ou formulaire) : modules=frequency_balance&modules=clarity
  • Tous les modules : modules=all ou modules=*
Module Description
frequency_balanceÉvaluation des fréquences et de l’équilibre sur 7 bandes.
dynamic_rangePlage dynamique, facteur de crête, PLR.
stereo_fieldMesures de largeur, de phase et de corrélation.
clarityMesures de clarté et de définition spectrales.
harmonic_contentTonalité et complexité harmonique.
transientsDonnées d’attaque, de densité des transitoires et d’impact des basses.
3d_spatialCohérence de la hauteur, de la profondeur et de la largeur.
surround_compatibilityCompatibilité mono + score de phase.
headphone_optimizationScore d’optimisation de l’écoute au casque.
speaker_optimizationScore d’optimisation de l’écoute sur enceintes.
genreClassification du genre et niveau de confiance.
voicePrésence vocale et caractéristiques de la voix.
instrumentsDétection d’instruments et informations sur l’arrangement.
moodProfil d’ambiance avec énergie et valence.
keywordsMots-clés et étiquettes sémantiques.
loudnessMesurez LUFS, crêtes vraies, saturation numérique et cibles du streaming. Vérifiez distorsion, crêtes des codecs et variations entre plateformes.
noiseMesurez bruit de fond, ronflement secteur, souffle et artefacts. Nettoyez les enregistrements avant que le mastering n’accentue ces défauts.
format_qualityVérifiez encodage avec pertes, coupure spectrale et résolution en bits. Évitez de masteriser des sources MP3, AAC ou suréchantillonnées déjà dégradées.
referenceRéférence
visualizationsURL des éléments visuels d’analyse générés.
ai_insightsRésumé et recommandations générés par un LLM.

Contrôle de la taille des réponses

Utilisez detail_level :

  • full (par défaut) : réponse complète
  • summary : réponse compacte pour les clients frontend ou mobiles

Exemples

1) Envoi + analyse complète

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

2) Envoi + modules sélectionnés

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) Envoi + modules sélectionnés + réponse résumée

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) Point de terminaison de test

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

5) JavaScript côté 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);

Métadonnées standard des réponses

Les réponses d’analyse réussies incluent :

  • requested_modules
  • returned_modules
  • detail_level
  • available_modules

Mastering

Envoyez un mix finalisé et recevez quatre masters WAV 24 bits en un seul mastering : dynamic, balanced, loud, chart. L’API utilise le même moteur, le même prix et le même quota mensuel que le Studio de mastering.

  • Le mastering est réservé aux abonnés Supporter : 20 masterings par mois UTC sont inclus, puis chaque mastering utilise des jetons.
  • Un mastering crée les quatre masters. Après les masterings inclus, un mastering coûte 85 jetons. Si un mastering échoue, ses jetons ou le mastering inclus vous sont rendus.
  • Chaque compte ne peut lancer qu’un mastering à la fois, Studio de mastering compris.
  • Les masters sont supprimés 24 heures après la fin d'un mastering, ou après 30 jours sur un compte Supporter, sauf si le mastering est conservé dans Mes masters. Téléchargez-les avant la date expires_at indiquée dans la réponse de statut.
  • Lancer un mastering nécessite la portée write. Le statut et les téléchargements nécessitent read.

Requête de mastering

POST/api/mastering

Envoyez le mix en multipart/form-data. Seul file est obligatoire.

Champ Type Obligatoire Remarques
filemultipart fileOuiFormats autorisés : mp3, wav, flac, aiff, m4a, aac, ogg. Maximum 95 Mo et 12 minutes. Le contenu du fichier doit correspondre à l’extension.
tonenumberNonInclinaison du timbre autour de 1 kHz, en dB. Une valeur négative rend le son plus chaud, une valeur positive plus brillant. De -2 à 2 par pas de 0.5. Par défaut : 0.
widthnumberNonNiveau du signal side au-dessus de 120 Hz, en dB. Une valeur négative resserre l’image, une valeur positive l’élargit. Les basses restent centrées. De -3 à 2 par pas de 0.5. Par défaut : 0.
punchnumberNonCompression de cohésion, en multiple de la valeur mesurée sur le mix. 0 désactive la cohésion. De 0 à 1.5 par pas de 0.25. Par défaut : 1.
loudnessnumberNonDéplace les quatre cibles de sonie ensemble, en LU. Si monter le niveau risque d’écraser la batterie, le master s’arrête avant et le signale dans ses changements. De -3 à 1.5 par pas de 0.5. Par défaut : 0.
monostringNonPasse les basses en mono sous 120 Hz. auto ne l’applique que si les mesures du mix le justifient. Valeurs possibles : auto, on, off. Par défaut : auto.
deharshstringNonAtténue la zone 4–9 kHz uniquement aux moments où elle ressort. auto ne l’applique que si les mesures du mix le justifient. Valeurs possibles : auto, on, off. Par défaut : auto.
sourcestringNonDéfinit la cible des aigus. ai ne touche jamais à la zone d’air au-dessus de 10 kHz et vise des aigus plus discrets. recorded vise un haut du spectre plus brillant. auto utilise la détection de musique IA du rapport de song_id, ou vérifie lui-même le fichier envoyé. Valeurs possibles : auto, ai, recorded. Par défaut : auto.
stylestringNonDétermine le poids des basses et le master recommandé. auto utilise le genre du rapport de song_id. Sans song_id, aucun genre n’est appliqué : les basses restent neutres et la recommandation suit la plage de loudness. Envoyez donc un style pour en choisir un. Valeurs possibles : auto, pop, rock, hiphop, electronic, rnb, metal, acoustic. Par défaut : auto.
song_idintegerNonL’identifiant d’un morceau que vous avez analysé. Son rapport enregistré est réutilisé au lieu de mesurer le fichier envoyé. Envoyez le même mix.
Idempotency-KeyheaderNon1 à 64 caractères : lettres, chiffres, _ et -.

Les nombres hors plage sont ramenés dans la plage et arrondis à son pas. Une valeur non numérique, ou un choix inconnu, renvoie 400 avec invalid_settings.

Envoyez un en-tête Idempotency-Key pour réessayer sans risque, avec une nouvelle clé pour chaque mix. Si votre compte répète une clé tant que son mastering existe encore, rien n’est débité ni relancé : vous recevez 200 avec le corps d’origine et "replayed": true. Si la répétition arrive pendant que la première requête démarre encore, vous recevez 429 busy. Après 503 failed, réessayez avec une nouvelle clé.

Réponse au lancement

Un nouveau mastering renvoie 202 :

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

Un mastering pris sur le quota Supporter contient "billed": "included" et "charged": 0. Les abonnés Supporter reçoivent aussi un objet included avec used, cap, reset_date.

Statut et téléchargements du mastering

GET/api/mastering/<token>

Interrogez le statut toutes les 3 à 5 secondes, dans la limite de fréquence de votre clé, jusqu’à ce qu’il soit done ou error.

  • pending : les masters sont en cours de création.
  • settling : le mastering a échoué et ses jetons ou son mastering inclus sont en cours de restitution. Continuez à interroger le statut.
  • done : les quatre masters sont prêts.
  • error : le mastering a échoué et ce qui a été débité vous a été rendu. Le champ error en indique la raison : too_long, too_short, too_quiet, failed.

Une réponse au statut terminé contient recommended, recommended_reason, warnings, source, settings, masters, expires_at, filename. Chaque élément de masters contient key, url, target_lufs, ceiling, metrics, changes, peaks.

Les réponses terminées ou en erreur incluent aussi access : votre solde et vos masterings inclus après ce mastering.

Un identifiant (token) inconnu ou expiré, ou appartenant à un autre compte, renvoie 404 avec {"status": "expired"}.

Téléchargement

GET/api/mastering/<token>/<variant>.wav

Renvoie le master en pièce jointe WAV 24 bits nommée d’après votre fichier envoyé, par exemple My Mix - balanced.wav. variant prend l’une des valeurs suivantes : dynamic, balanced, loud, chart.

Une variante inconnue, l’identifiant (token) d’un autre compte, ou un mastering expiré ou non terminé renvoie 404.

Chaque réponse de mastering inclut Cache-Control: private, no-store.

Erreurs de mastering

Les erreurs renvoient {"error": "invalid_file", "message": "…"}.

Statut Erreur Signification
400invalid_fileFichier manquant, format non pris en charge ou contenu ne correspondant pas à l’extension.
400invalid_settingsUn réglage n’est pas un nombre ou ne fait pas partie de ses choix.
400invalid_idempotency_keyL’en-tête Idempotency-Key ne contient pas 1 à 64 lettres, chiffres, _ ou -.
402insufficient_creditsJetons insuffisants. Le corps de la réponse inclut cost et balance.
403ForbiddenLa clé d’un compte gratuit, ou une clé sans la portée requise par cet endpoint. Un abonné Supporter dont le paiement de renouvellement a échoué repasse à l’offre gratuite jusqu’à ce que le paiement soit validé ; en attendant, le mastering ne fonctionne que dans le Studio de mastering. Rien n’est facturé.
403supporter_onlyLe mastering est pour l’instant réservé aux comptes Supporter. Rien n’est facturé.
413File too largeLe fichier dépasse 95 Mo : la requête est refusée avant d’atteindre l’endpoint, parfois sans corps JSON. Un fichier juste au-dessus de la limite reçoit invalid_file à la place.
429busyUn mastering est déjà en cours ou en train de démarrer pour ce compte, depuis l’API ou le studio. Le corps de la réponse inclut son token, qui vaut null tant que ce mastering démarre encore.
429Rate Limit ExceededLa limite par minute, par heure ou par jour de votre clé a été atteinte. Le message indique laquelle.
503failedLe mastering n’a pas pu démarrer. Tout ce qui a été débité vous est rendu.

Exemple de mastering

1) Lancer un mastering

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) Interroger le statut jusqu’à la fin

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

3) Télécharger un master

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

Codes d’erreur

Statut Signification Cause habituelle
400Requête incorrecteModule ou detail_level invalide, champ file manquant, fichier vide.
401Non autoriséClé API manquante, invalide ou expirée.
403InterditAccès à l’API non autorisé pour cette offre de compte.
404Introuvable/api/analyze/<file_id> fichier devenu indisponible (suppression pour confidentialité).
413Données trop volumineusesFichier de plus de 95MB.
429Limite de fréquence dépasséeTrop de requêtes par minute, par heure ou par jour.
500Erreur serveurÉchec de l’analyse ou de l’exécution.

Remarques pour le frontend

  • Pour les clients web ou mobiles, privilégiez detail_level=summary.
  • Demandez uniquement les modules nécessaires au premier affichage pour réduire la latence et le volume des réponses.
  • Gérez 429 et 500 avec de nouvelles tentatives et un délai progressif.
  • N’exposez pas de clés de production à longue durée de vie dans des bundles publics.