Mixanalytic API-Dokumentation
Offizielle API-Referenz für https://mixanalytic.com. Laden Sie Audio hoch und erhalten Sie eine KI-Mixanalyse mit auswählbaren Modulen sowie kompakten oder vollständigen Antworten.
Basis-URL: https://mixanalytic.com/api
Authentifizierung
Senden Sie Ihren API-Schlüssel bei jeder Anfrage im Header X-API-Key.
- 401 fehlender oder ungültiger Schlüssel
- 403 Schlüssel des kostenlosen Tarifs ohne API-Zugriff
- 429 Ratenlimit überschritten
Berechtigungsbereiche: write dient dem Upload und der Analyse in Mixanalytic. content liest bereinigte Daten für die Inhaltsrecherche. content_write speichert nicht öffentliche Inhaltsentwürfe. Inhaltsberechtigungen sind nur für Admins.
Endpunkte
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /api/test-data | Verbindungs- und Authentifizierungsprüfung. |
| POST | /api/upload | Audiodatei hochladen und analysieren. |
| GET | /api/analyze/<file_id> | Erneut anhand der Datei-ID analysieren (wenn die Originaldatei noch vorhanden ist). |
| POST | /api/mastering | Mix hochladen und einen Mastering-Durchlauf (vier Master) starten. |
| GET | /api/mastering/<token> | Status und Ergebnisse eines Mastering-Durchlaufs. |
| GET | /api/mastering/<token>/<variant>.wav | Einen Master als 24-Bit-WAV herunterladen. |
| GET | /api/content/analysis-feed | Bereinigter Recherchefeed für Inhaltsagenten, nur für Admins. |
| POST | /api/content/drafts | Endpunkt zum Speichern und Aktualisieren von Entwürfen für Inhaltsagenten, nur für Admins. |
| GET | /api/ai-stats?days=30 | Nutzungsstatistiken für KI-Analysen. |
Upload-Anfrage
POST/api/upload
| Feld | Typ | Erforderlich | Hinweise |
|---|---|---|---|
| file | multipart file | Ja | Zulässig: mp3, wav, flac, m4a, aac, ogg. Maximal 95MB. |
| modules | string/list | Nein | Ohne Angabe werden standardmäßig alle Module verwendet. |
| detail_level | string | Nein | full (Standard) oder summary. |
Ungültiges detail_level liefert 400. Zu große Dateien liefern 413.
Modulauswahl
Steuern Sie mit modules, welche Analysemodule zurückgegeben und berechnet werden.
Unterstützte Formate:
- Durch Kommas getrennte Zeichenfolge: modules=frequency_balance,clarity,mood
- Zeichenfolge mit JSON-Array: modules=["frequency_balance","clarity","mood"]
- Wiederholter Schlüssel (Abfrage/Formular): modules=frequency_balance&modules=clarity
- Alle Module: modules=all oder modules=*
| Modul | Beschreibung |
|---|---|
| frequency_balance | Frequenz- und Balancebewertung über 7 Bänder. |
| dynamic_range | Dynamikbereich, Crest-Faktor, PLR. |
| stereo_field | Breiten-, Phasen- und Korrelationsmetriken. |
| clarity | Metriken für spektrale Klarheit und Definition. |
| harmonic_content | Tonart und harmonische Komplexität. |
| transients | Daten zu Attack, Transientendichte und Bass-Punch. |
| 3d_spatial | Konsistenz von Höhe, Tiefe und Breite. |
| surround_compatibility | Monokompatibilität + Phasenbewertung. |
| headphone_optimization | Optimierungsbewertung für Kopfhörerwiedergabe. |
| speaker_optimization | Optimierungsbewertung für Lautsprecherwiedergabe. |
| genre | Genreklassifikation und Konfidenz. |
| voice | Präsenz und Eigenschaften der Stimme. |
| instruments | Instrumentenerkennung und Arrangement-Informationen. |
| mood | Stimmungsprofil mit Energie und Valenz. |
| keywords | Semantische Schlagwörter und Tags. |
| loudness | Miss LUFS, True Peak, Clipping und Streaming-Ziele, damit dein Master laut genug bleibt, ohne Verzerrung, Codec-Spitzen oder Überraschungen auf Plattformen. |
| noise | Miss Grundrauschen, Netzbrummen, Zischen und Artefakte. Bereinige Aufnahmen, bevor das Mastering diese Störungen verstärkt. |
| format_quality | Prüfe Verlustkodierung, spektralen Cutoff und Bittiefe. Vermeide Mastering aus beeinträchtigten MP3-, AAC- oder hochskalierten Audioquellen. |
| reference | Referenz |
| visualizations | URLs für erzeugte Analysevisualisierungen. |
| ai_insights | Von einem LLM erstellte Zusammenfassung und Empfehlungen. |
Antwortgröße steuern
Verwenden Sie detail_level:
- full (Standard): vollständige Antwortdaten
- summary: kompakte Antwortdaten für Frontend- und mobile Clients
Beispiele
1) Upload + vollständige Analyse
2) Upload + ausgewählte Module
3) Upload + ausgewählte Module + zusammengefasste Antwortdaten
4) Testendpunkt
5) Clientseitiges JavaScript
Standard-Antwortmetadaten
Erfolgreiche Analyseantworten enthalten:
- requested_modules
- returned_modules
- detail_level
- available_modules
Mastering
Laden Sie einen fertigen Mix hoch und erhalten Sie aus einem Durchlauf vier 24-Bit-WAV-Master: dynamic, balanced, loud, chart. Die API nutzt dieselbe Engine, denselben Preis und dasselbe Monatskontingent wie das Mastering Studio.
- Mastering gibt es für Supporter: 20 Durchläufe pro UTC-Monat sind inklusive, danach nutzt jeder Durchlauf Tokens.
- Ein Durchlauf erstellt alle vier Master. Nach den inklusiven Durchläufen kostet ein Durchlauf 85 Tokens. Schlägt ein Durchlauf fehl, erhalten Sie die Tokens oder den inklusiven Durchlauf zurück.
- Jedes Konto kann jeweils einen Durchlauf ausführen. Dieses Limit gilt gemeinsam mit dem Mastering Studio.
- Master werden 24 Stunden nach Abschluss eines Durchlaufs gelöscht, auf einem Supporter-Konto nach 30 Tagen, sofern der Durchlauf nicht in Meine Master aufbewahrt wird. Laden Sie sie vor dem Zeitpunkt in expires_at der Statusantwort herunter.
- Zum Starten eines Durchlaufs ist der Berechtigungsbereich write erforderlich. Status und Downloads erfordern read.
Mastering-Anfrage
POST/api/mastering
Senden Sie den Mix als multipart/form-data. Nur file ist erforderlich.
| Feld | Typ | Erforderlich | Hinweise |
|---|---|---|---|
| file | multipart file | Ja | Zulässig: mp3, wav, flac, aiff, m4a, aac, ogg. Maximal 95 MB und 12 Minuten. Der Dateiinhalt muss zur Dateiendung passen. |
| tone | number | Nein | Klang-Tilt um 1 kHz, in dB. Negative Werte klingen wärmer, positive heller. -2 bis 2 in Schritten von 0.5. Standard 0. |
| width | number | Nein | Pegel des Seitensignals über 120 Hz, in dB. Negative Werte sind schmaler, positive breiter. Der Bass bleibt in der Mitte. -3 bis 2 in Schritten von 0.5. Standard 0. |
| punch | number | Nein | Glue-Kompression als Vielfaches des für den Mix gemessenen Werts. 0 schaltet Glue aus. 0 bis 1.5 in Schritten von 0.25. Standard 1. |
| loudness | number | Nein | Verschiebt alle vier Lautheitsziele gemeinsam, in LU. Würde lauter die Drums zerquetschen, stoppt der Master früher und weist in seinen Änderungen darauf hin. -3 bis 1.5 in Schritten von 0.5. Standard 0. |
| mono | string | Nein | Macht den Bass unter 120 Hz mono. auto greift nur ein, wenn die Messung des Mixes es erfordert. Einer der Werte auto, on, off. Standard auto. |
| deharsh | string | Nein | Senkt 4–9 kHz nur in den Momenten ab, in denen sie herausstechen. auto greift nur ein, wenn die Messung des Mixes es erfordert. Einer der Werte auto, on, off. Standard auto. |
| source | string | Nein | Legt das Höhenziel fest. ai verändert den Air-Bereich über 10 kHz nie und setzt die Höhen niedriger an. recorded zielt auf hellere Höhen. auto verwendet die KI-Musik-Einschätzung aus dem Bericht zu song_id oder prüft den Upload selbst. Einer der Werte auto, ai, recorded. Standard auto. |
| style | string | Nein | Bestimmt das Gewicht im Bassbereich und welcher Master empfohlen wird. auto verwendet das Genre aus dem Bericht zu song_id. Ohne song_id wird kein Genre angewendet: Der Bassbereich bleibt neutral und die Empfehlung richtet sich nach der Lautheitsspanne. Senden Sie also einen Stil, um eines festzulegen. Einer der Werte auto, pop, rock, hiphop, electronic, rnb, metal, acoustic. Standard auto. |
| song_id | integer | Nein | Die ID eines Songs, den Sie analysiert haben. Statt den Upload zu messen, wird dessen gespeicherter Bericht wiederverwendet. Laden Sie denselben Mix hoch. |
| Idempotency-Key | header | Nein | 1–64 Zeichen: Buchstaben, Ziffern, _ und -. |
Zahlen außerhalb eines Bereichs werden auf diesen begrenzt und auf seine Schrittweite gerundet. Ein Wert, der keine Zahl ist, oder eine unbekannte Auswahl liefert 400 mit invalid_settings.
Senden Sie einen Header Idempotency-Key, um Anfragen sicher zu wiederholen, und verwenden Sie für jeden Mix einen neuen Schlüssel. Wiederholt Ihr Konto einen Schlüssel, solange dessen Durchlauf noch existiert, wird nichts erneut abgebucht oder gestartet: Sie erhalten 200 mit der ursprünglichen Antwort und "replayed": true. Kommt die Wiederholung, während die erste Anfrage noch startet, erhalten Sie 429 busy. Versuchen Sie es nach 503 failed mit einem neuen Schlüssel erneut.
Startantwort
Ein neuer Durchlauf liefert 202:
Ein Durchlauf aus dem Supporter-Kontingent enthält "billed": "included" und "charged": 0. Supporter erhalten außerdem ein Objekt included mit used, cap, reset_date.
Mastering-Status und Downloads
GET/api/mastering/<token>
Fragen Sie den Status alle 3–5 Sekunden ab, innerhalb des Ratenlimits Ihres Schlüssels, bis er done oder error lautet.
- pending: Die Master werden erstellt.
- settling: Der Durchlauf ist fehlgeschlagen, und die Tokens oder der inklusive Durchlauf werden zurückgegeben. Fragen Sie weiter ab.
- done: Die vier Master sind fertig.
- error: Der Durchlauf ist fehlgeschlagen, und alles, was dafür abgebucht wurde, wurde erstattet. Das Feld error nennt den Grund: too_long, too_short, too_quiet, failed.
Eine Antwort mit dem Status done enthält recommended, recommended_reason, warnings, source, settings, masters, expires_at, filename. Jedes Element in masters hat key, url, target_lufs, ceiling, metrics, changes, peaks.
Antworten mit done und error enthalten außerdem access: Ihr Guthaben und Ihre inklusiven Durchläufe nach dem Durchlauf.
Unbekannte oder abgelaufene Durchlauf-Tokens sowie Tokens anderer Konten liefern 404 mit {"status": "expired"}.
Download
GET/api/mastering/<token>/<variant>.wav
Liefert den Master als 24-Bit-WAV-Anhang, benannt nach Ihrem Upload, zum Beispiel My Mix - balanced.wav. variant ist einer der Werte dynamic, balanced, loud, chart.
Eine unbekannte Variante, das Token eines anderen Kontos oder ein abgelaufener oder noch nicht fertiger Durchlauf liefert 404.
Jede Mastering-Antwort enthält Cache-Control: private, no-store.
Mastering-Fehler
Fehler liefern {"error": "invalid_file", "message": "…"}.
| Status | Fehler | Bedeutung |
|---|---|---|
| 400 | invalid_file | Fehlende Datei, nicht unterstütztes Format oder Inhalt passt nicht zur Dateiendung. |
| 400 | invalid_settings | Eine Einstellung ist keine Zahl oder keiner ihrer zulässigen Werte. |
| 400 | invalid_idempotency_key | Der Header Idempotency-Key besteht nicht aus 1–64 Buchstaben, Ziffern, _ oder -. |
| 402 | insufficient_credits | Nicht genug Tokens. Der Antworttext enthält cost und balance. |
| 403 | Forbidden | Ein Schlüssel eines kostenlosen Kontos oder ein Schlüssel ohne den Berechtigungsbereich, den dieser Endpunkt benötigt. Ein Supporter, dessen Verlängerungszahlung fehlgeschlagen ist, ist im kostenlosen Tarif, bis die Zahlung durchgeht; in der Zwischenzeit funktioniert Mastering daher nur im Mastering Studio. Es wird nichts berechnet. |
| 403 | supporter_only | Mastering ist vorerst nur für Supporter-Konten verfügbar. Es wird nichts berechnet. |
| 413 | File too large | Die Datei ist größer als 95 MB, daher wird die Anfrage abgewiesen, bevor sie den Endpunkt erreicht, manchmal ohne JSON-Antwort. Eine Datei knapp über dem Limit erhält stattdessen invalid_file. |
| 429 | busy | Für dieses Konto läuft bereits ein Durchlauf oder startet gerade, über die API oder das Studio. Der Antworttext enthält dessen token; solange der Durchlauf noch startet, ist er null. |
| 429 | Rate Limit Exceeded | Das Limit Ihres Schlüssels pro Minute, Stunde oder Tag wurde erreicht. Die Meldung nennt, welches. |
| 503 | failed | Der Durchlauf konnte nicht starten. Was dafür abgebucht wurde, wird erstattet. |
Mastering-Beispiel
1) Einen Durchlauf starten
2) Abfragen, bis er fertig ist
3) Einen Master herunterladen
Fehlercodes
| Status | Bedeutung | Typische Ursache |
|---|---|---|
| 400 | Ungültige Anfrage | Ungültiges Modul/detail_level, fehlendes file-Feld, leere Datei. |
| 401 | Nicht autorisiert | Fehlender, ungültiger oder abgelaufener API-Schlüssel. |
| 403 | Zugriff verweigert | API-Zugriff für diesen Kontotarif nicht erlaubt. |
| 404 | Nicht gefunden | /api/analyze/<file_id> Datei nicht mehr verfügbar (Löschung zum Datenschutz). |
| 413 | Nutzlast zu groß | Datei größer als 95MB. |
| 429 | Ratenlimit überschritten | Zu viele Anfragen pro Minute, Stunde oder Tag. |
| 500 | Serverfehler | Analyse- oder Laufzeitfehler. |
Frontend-Hinweise
- Für Web- und mobile Clients sollten Sie detail_level=summary bevorzugen.
- Fordern Sie nur die beim ersten Rendern benötigten Module an, um Latenz und Antwortgröße zu reduzieren.
- Behandeln Sie 429 und 500 mit erneuten Versuchen und zunehmenden Wartezeiten.
- Legen Sie keine langlebigen Produktionsschlüssel in öffentlichen Bundles offen.