Produktion

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.

curl -X GET "https://mixanalytic.com/api/test-data" \ -H "X-API-Key: YOUR_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-dataVerbindungs- und Authentifizierungsprüfung.
POST/api/uploadAudiodatei hochladen und analysieren.
GET/api/analyze/<file_id>Erneut anhand der Datei-ID analysieren (wenn die Originaldatei noch vorhanden ist).
POST/api/masteringMix hochladen und einen Mastering-Durchlauf (vier Master) starten.
GET/api/mastering/<token>Status und Ergebnisse eines Mastering-Durchlaufs.
GET/api/mastering/<token>/<variant>.wavEinen Master als 24-Bit-WAV herunterladen.
GET/api/content/analysis-feedBereinigter Recherchefeed für Inhaltsagenten, nur für Admins.
POST/api/content/draftsEndpunkt zum Speichern und Aktualisieren von Entwürfen für Inhaltsagenten, nur für Admins.
GET/api/ai-stats?days=30Nutzungsstatistiken für KI-Analysen.

Upload-Anfrage

POST/api/upload

Feld Typ Erforderlich Hinweise
filemultipart fileJaZulässig: mp3, wav, flac, m4a, aac, ogg. Maximal 95MB.
modulesstring/listNeinOhne Angabe werden standardmäßig alle Module verwendet.
detail_levelstringNeinfull (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_balanceFrequenz- und Balancebewertung über 7 Bänder.
dynamic_rangeDynamikbereich, Crest-Faktor, PLR.
stereo_fieldBreiten-, Phasen- und Korrelationsmetriken.
clarityMetriken für spektrale Klarheit und Definition.
harmonic_contentTonart und harmonische Komplexität.
transientsDaten zu Attack, Transientendichte und Bass-Punch.
3d_spatialKonsistenz von Höhe, Tiefe und Breite.
surround_compatibilityMonokompatibilität + Phasenbewertung.
headphone_optimizationOptimierungsbewertung für Kopfhörerwiedergabe.
speaker_optimizationOptimierungsbewertung für Lautsprecherwiedergabe.
genreGenreklassifikation und Konfidenz.
voicePräsenz und Eigenschaften der Stimme.
instrumentsInstrumentenerkennung und Arrangement-Informationen.
moodStimmungsprofil mit Energie und Valenz.
keywordsSemantische Schlagwörter und Tags.
loudnessMiss LUFS, True Peak, Clipping und Streaming-Ziele, damit dein Master laut genug bleibt, ohne Verzerrung, Codec-Spitzen oder Überraschungen auf Plattformen.
noiseMiss Grundrauschen, Netzbrummen, Zischen und Artefakte. Bereinige Aufnahmen, bevor das Mastering diese Störungen verstärkt.
format_qualityPrüfe Verlustkodierung, spektralen Cutoff und Bittiefe. Vermeide Mastering aus beeinträchtigten MP3-, AAC- oder hochskalierten Audioquellen.
referenceReferenz
visualizationsURLs für erzeugte Analysevisualisierungen.
ai_insightsVon 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

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

2) Upload + ausgewählte Module

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) Upload + ausgewählte Module + zusammengefasste Antwortdaten

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) Testendpunkt

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

5) Clientseitiges JavaScript

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);

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
filemultipart fileJaZulässig: mp3, wav, flac, aiff, m4a, aac, ogg. Maximal 95 MB und 12 Minuten. Der Dateiinhalt muss zur Dateiendung passen.
tonenumberNeinKlang-Tilt um 1 kHz, in dB. Negative Werte klingen wärmer, positive heller. -2 bis 2 in Schritten von 0.5. Standard 0.
widthnumberNeinPegel 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.
punchnumberNeinGlue-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.
loudnessnumberNeinVerschiebt 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.
monostringNeinMacht 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.
deharshstringNeinSenkt 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.
sourcestringNeinLegt 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.
stylestringNeinBestimmt 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_idintegerNeinDie ID eines Songs, den Sie analysiert haben. Statt den Upload zu messen, wird dessen gespeicherter Bericht wiederverwendet. Laden Sie denselben Mix hoch.
Idempotency-KeyheaderNein1–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:

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

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
400invalid_fileFehlende Datei, nicht unterstütztes Format oder Inhalt passt nicht zur Dateiendung.
400invalid_settingsEine Einstellung ist keine Zahl oder keiner ihrer zulässigen Werte.
400invalid_idempotency_keyDer Header Idempotency-Key besteht nicht aus 1–64 Buchstaben, Ziffern, _ oder -.
402insufficient_creditsNicht genug Tokens. Der Antworttext enthält cost und balance.
403ForbiddenEin 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.
403supporter_onlyMastering ist vorerst nur für Supporter-Konten verfügbar. Es wird nichts berechnet.
413File too largeDie 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.
429busyFü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.
429Rate Limit ExceededDas Limit Ihres Schlüssels pro Minute, Stunde oder Tag wurde erreicht. Die Meldung nennt, welches.
503failedDer Durchlauf konnte nicht starten. Was dafür abgebucht wurde, wird erstattet.

Mastering-Beispiel

1) Einen Durchlauf starten

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) Abfragen, bis er fertig ist

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

3) Einen Master herunterladen

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

Fehlercodes

Status Bedeutung Typische Ursache
400Ungültige AnfrageUngültiges Modul/detail_level, fehlendes file-Feld, leere Datei.
401Nicht autorisiertFehlender, ungültiger oder abgelaufener API-Schlüssel.
403Zugriff verweigertAPI-Zugriff für diesen Kontotarif nicht erlaubt.
404Nicht gefunden/api/analyze/<file_id> Datei nicht mehr verfügbar (Löschung zum Datenschutz).
413Nutzlast zu großDatei größer als 95MB.
429Ratenlimit überschrittenZu viele Anfragen pro Minute, Stunde oder Tag.
500ServerfehlerAnalyse- 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.