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.
- 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-data | Vérification de la connexion et de l’authentification. |
| POST | /api/upload | Envoi 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/mastering | Envoi 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>.wav | Téléchargement d’un master en WAV 24 bits. |
| GET | /api/content/analysis-feed | Flux de recherche expurgé réservé aux administrateurs pour les agents de contenu. |
| POST | /api/content/drafts | Point de terminaison d’enregistrement et de mise à jour des brouillons, réservé aux administrateurs pour les agents de contenu. |
| GET | /api/ai-stats?days=30 | Statistiques d’utilisation des analyses IA. |
Requête d’envoi
POST/api/upload
| Champ | Type | Obligatoire | Remarques |
|---|---|---|---|
| file | multipart file | Oui | Formats autorisés : mp3, wav, flac, m4a, aac, ogg. Maximum : 95MB. |
| modules | string/list | Non | Tous les modules sont sélectionnés par défaut si ce champ est omis. |
| detail_level | string | Non | full (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_range | Plage dynamique, facteur de crête, PLR. |
| stereo_field | Mesures de largeur, de phase et de corrélation. |
| clarity | Mesures de clarté et de définition spectrales. |
| harmonic_content | Tonalité et complexité harmonique. |
| transients | Données d’attaque, de densité des transitoires et d’impact des basses. |
| 3d_spatial | Cohérence de la hauteur, de la profondeur et de la largeur. |
| surround_compatibility | Compatibilité mono + score de phase. |
| headphone_optimization | Score d’optimisation de l’écoute au casque. |
| speaker_optimization | Score d’optimisation de l’écoute sur enceintes. |
| genre | Classification du genre et niveau de confiance. |
| voice | Présence vocale et caractéristiques de la voix. |
| instruments | Détection d’instruments et informations sur l’arrangement. |
| mood | Profil d’ambiance avec énergie et valence. |
| keywords | Mots-clés et étiquettes sémantiques. |
| loudness | Mesurez LUFS, crêtes vraies, saturation numérique et cibles du streaming. Vérifiez distorsion, crêtes des codecs et variations entre plateformes. |
| noise | Mesurez bruit de fond, ronflement secteur, souffle et artefacts. Nettoyez les enregistrements avant que le mastering n’accentue ces défauts. |
| format_quality | Vé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. |
| reference | Référence |
| visualizations | URL des éléments visuels d’analyse générés. |
| ai_insights | Ré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
2) Envoi + modules sélectionnés
3) Envoi + modules sélectionnés + réponse résumée
4) Point de terminaison de test
5) JavaScript côté client
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 |
|---|---|---|---|
| file | multipart file | Oui | Formats autorisés : mp3, wav, flac, aiff, m4a, aac, ogg. Maximum 95 Mo et 12 minutes. Le contenu du fichier doit correspondre à l’extension. |
| tone | number | Non | Inclinaison 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. |
| width | number | Non | Niveau 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. |
| punch | number | Non | Compression 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. |
| loudness | number | Non | Dé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. |
| mono | string | Non | Passe 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. |
| deharsh | string | Non | Atté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. |
| source | string | Non | Dé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. |
| style | string | Non | Dé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_id | integer | Non | L’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-Key | header | Non | 1 à 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 :
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 |
|---|---|---|
| 400 | invalid_file | Fichier manquant, format non pris en charge ou contenu ne correspondant pas à l’extension. |
| 400 | invalid_settings | Un réglage n’est pas un nombre ou ne fait pas partie de ses choix. |
| 400 | invalid_idempotency_key | L’en-tête Idempotency-Key ne contient pas 1 à 64 lettres, chiffres, _ ou -. |
| 402 | insufficient_credits | Jetons insuffisants. Le corps de la réponse inclut cost et balance. |
| 403 | Forbidden | La 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é. |
| 403 | supporter_only | Le mastering est pour l’instant réservé aux comptes Supporter. Rien n’est facturé. |
| 413 | File too large | Le 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. |
| 429 | busy | Un 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. |
| 429 | Rate Limit Exceeded | La limite par minute, par heure ou par jour de votre clé a été atteinte. Le message indique laquelle. |
| 503 | failed | Le mastering n’a pas pu démarrer. Tout ce qui a été débité vous est rendu. |
Exemple de mastering
1) Lancer un mastering
2) Interroger le statut jusqu’à la fin
3) Télécharger un master
Codes d’erreur
| Statut | Signification | Cause habituelle |
|---|---|---|
| 400 | Requête incorrecte | Module ou detail_level invalide, champ file manquant, fichier vide. |
| 401 | Non autorisé | Clé API manquante, invalide ou expirée. |
| 403 | Interdit | Accès à l’API non autorisé pour cette offre de compte. |
| 404 | Introuvable | /api/analyze/<file_id> fichier devenu indisponible (suppression pour confidentialité). |
| 413 | Données trop volumineuses | Fichier de plus de 95MB. |
| 429 | Limite de fréquence dépassée | Trop de requêtes par minute, par heure ou par jour. |
| 500 | Erreur 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.