Blog

Tutorial

minimax-music-1.5 API Tutorial: curl und Python Requests

Nov 12, 2026
Titelbild: Auf warmem Kohlegrund durchzieht ein breites bernsteinfarbenes Lichtband schräg einen schmalen Spalt, ergänzt durch dezente dunkle geometrische Blöcke, kompositorisch zurückhaltend mit viel Freiraum.
Auf dieser Seite

Anforderungen von minimax-music-1.5 an die Anfrage

Bevor man die erste Codezeile schreibt, sollte man klären, was ein Musikgenerierungsaufruf eigentlich enthält. Anders als bei Textvervollständigung gibt es bei Musikanfragen zwei kreative Eingaben mit je eigener Zuständigkeit sowie einige Steuerparameter zur Formung der Ausgabe.

Auf hoher Ebene enthält eine minimax-music-1.5-Anfrage:

  • Stil- oder Prompt-Beschreibung – die musikalische Richtung: Genre, Stimmung, Instrumentierung, Tempo-Gefühl, Produktionsmerkmale.
  • Songtext – der tatsächlich gesungene Text, wenn das Stück Gesang enthält. Bei rein instrumentalen Anfragen leer lassen oder weglassen.
  • Struktursteuerung – etwa die Zieldauer des generierten Stücks, die die Länge der Komposition des Modells begrenzt.
  • Modellbezeichner – minimax-music-1.5 – sorgt dafür, dass das Gateway die Aufgabe an das richtige Backend weiterleitet.

Das mentale Modell, das man sich einprägen sollte: Die Stileingabe sagt dem Modell, wie es klingen soll, die Texteingabe sagt ihm, was gesungen wird. Beide sind nicht austauschbar. Wenn man eine Genre-Beschreibung in das Textfeld packt, erhält man wirre Ausgaben; wenn man den Text leer lässt, aber ein Stück mit Gesang anfordert, muss das Modell selbst etwas erfinden. Entscheiden Sie vor dem Start, in welchem der beiden Modi Sie sich befinden.

Zwei weitere Punkte sollte man verinnerlichen, bevor man Code schreibt:

  1. Musikgenerierung ist nicht sofort. Die Erzeugung eines fertigen Stücks benötigt echte Rechenzeit, daher ist die API von Grund auf asynchron konzipiert. Man reicht eine Aufgabe ein und ruft das Ergebnis später ab. Jedes Tutorial, das nur einen blockierenden Aufruf zeigt, verbirgt die Polling-Schleife vor Ihnen.
  2. Die Ausgabe wird per Referenz geliefert. Man erhält eine URL zu den generierten Audiodaten, keine eingebetteten Rohbytes. Diese müssen separat heruntergeladen oder gestreamt werden.

Sobald man diese drei Dinge klar benennen kann – den Unterschied zwischen Stil und Text, den asynchronen Lebenszyklus und die URL-basierte Ausgabe –, ist der eigentliche Request-Body leicht zu lesen.

Ersteinrichtung auf HiAPI

Vor dem ersten Aufruf benötigt man drei Dinge: einen API-Schlüssel, die Basis-Endpunktadresse und die Angewohnheit, den Schlüssel nicht fest im Code zu hinterlegen.

API-Schlüssel

Erstellen Sie den Schlüssel in Ihrer HiAPI-Kontokonsole. Behandeln Sie ihn wie ein Passwort: Er authentifiziert jede Anfrage und ist an die Nutzung Ihres Kontos gebunden. Niemals ins Repository committen, niemals in einen öffentlichen Gist einfügen und niemals in ein Mobile- oder Browser-Bundle packen.

Basis-Endpunktadresse

Alle Aufrufe gehen an das HiAPI-Gateway, das minimax-music-1.5 hinter einer einheitlichen Schnittstelle bereitstellt. Sie benötigen keine separaten Zugangsdaten oder SDKs pro Modell – der Modellname im Request-Body wählt das Backend. Die genaue Basis-URL und den aktuellen Anfragepfad entnehmen Sie der API-Referenzdokumentation.

Den Schlüssel aus dem Quellcode heraushalten

Das Muster, das von Wegwerfskripten bis zur Produktion funktioniert, sind Umgebungsvariablen:

export HIAPI_API_KEY="your-key-here"

Dann liest man ihn zur Laufzeit aus. In Python ist das os.environ["HIAPI_API_KEY"]; in der Shell $HIAPI_API_KEY. Wenn Sie lokal eine .env-Datei verwenden, fügen Sie sie vor dem ersten Commit zu .gitignore hinzu – nicht danach. Bei deployten Diensten injizieren Sie den Schlüssel über den Secret-Manager der Plattform, statt ihn ins Image zu backen.

Eine schnelle Prüfung, bevor Sie etwas bauen: Stellen Sie sicher, dass der Prozess, den Sie gleich ausführen, den Schlüssel sieht (führen Sie echo $HIAPI_API_KEY in derselben Shell aus). Die meisten „Authentifizierung fehlgeschlagen“-Meldungen lassen sich darauf zurückführen, dass der Schlüssel in einem Terminal exportiert, das Skript aber in einem anderen ausgeführt wurde.

Die erste funktionierende Anfrage mit curl

Beginnen Sie mit curl. Es entfernt jede Abstraktion und zeigt Ihnen genau, was über die Leitung geht. Die folgende Anfrage generiert ein kurzes Stück mit Gesang; passen Sie die Feldwerte an Ihre Absicht an.

curl -X POST "$HIAPI_BASE_URL/minimax-music-1.5" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-1.5",
    "prompt": "Warmes Indie-Folk, Fingerpicking-Akustikgitarre, sanft gebürstete Drums, intimer Nahfeld-Gesang",
    "lyrics": "[verse]\nMorgenlicht fällt auf den Küchenboden\n[chorus]\nWir sind immer noch hier, wir sind immer noch hier",
    "duration": 30
  }'

Zeile für Zeile erklärt:

  • -X POST – Generierung ist eine Erstellungsoperation, keine Leseoperation.
  • Authorization: Bearer $HIAPI_API_KEY – der Schlüssel aus dem vorherigen Abschnitt, von der Shell expandiert, sodass er nicht in Ihrer Historie auftaucht, solange Sie die Variable referenzieren.
  • Content-Type: application/json – das Gateway erwartet JSON; das Weglassen dieses Headers ist eine häufige Ursache für verwirrende 4xx-Antworten.
  • model – bindet die Anfrage an minimax-music-1.5.
  • prompt – die Stilbeschreibung. Geben Sie Instrumentierung und Stimmung konkret an, nicht nur ein Adjektiv.
  • lyrics – der Gesangstext, mit leichten Abschnitts-Tags wie [verse] und [chorus] zur Strukturierung. \n ist der JSON-Zeilenumbruch.
  • duration – begrenzt die Länge des generierten Stücks in Sekunden.

Zurück kommt eine Aufgabenreferenz, kein Audio. Fangen Sie sie ab:

curl -s -X POST "$HIAPI_BASE_URL/minimax-music-1.5" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | tee job.json

Mit -d @payload.json den Request-Body aus einer Datei zu lesen, hält Ihre Shell-Historie sauber und macht den Übergang zu Python zum Kinderspiel – die Datei ist der Body. Prüfen Sie die Antwort, notieren Sie die Aufgaben- oder Task-Kennung sowie etwaige Statusfelder; Sie benötigen die Kennung, um das Ergebnis abzurufen.

Die Anfrage nach Python portieren

Die Python-Version sollte sich wie eine Übertragung des curl-Aufrufs anfühlen, nicht wie eine Neufassung. Verwenden Sie requests, lesen Sie den Schlüssel aus der Umgebungsvariable und halten Sie den Request-Body als Dictionary, damit er lesbar bleibt.

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "minimax-music-1.5",
    "prompt": "Warmes Indie-Folk, Fingerpicking-Akustikgitarre, sanft gebürstete Drums, intimer Nahfeld-Gesang",
    "lyrics": "[verse]\nMorgenlicht fällt auf den Küchenboden\n[chorus]\nWir sind immer noch hier, wir sind immer noch hier",
    "duration": 30,
}

response = requests.post(
    f"{BASE_URL}/minimax-music-1.5",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    data=json.dumps(payload),
    timeout=60,
)
response.raise_for_status()
job = response.json()
print(json.dumps(job, indent=2))

Einige Portierungshinweise, um Überraschungen zu vermeiden:

  • json.dumps mit data= oder json=payload verwenden. Beides funktioniert; json=payload lässt requests den Inhaltstyp für Sie setzen. Wenn Sie ein Dictionary ohne Serialisierung direkt an data= übergeben, erhält der Server einen formularcodierten Body und lehnt ihn ab.
  • Immer timeout setzen. Ohne Timeout hängt ein hängender Verbindungsaufbau Ihren Prozess unbegrenzt auf. Beachten Sie, dass dieses Timeout das Einreichen abdeckt, nicht die Generierung – das ist Thema des nächsten Abschnitts.
  • Vor dem Parsen raise_for_status() aufrufen. Dadurch wird aus 4xx oder 5xx eine klare Exception statt eines mysteriösen KeyError, wenn Sie auf ein nicht vorhandenes Feld zugreifen.
  • Das Response-Objekt behalten. Beim Debuggen liefern response.status_code und response.text weit mehr Informationen als eine geparste Fehlermeldung.

Das Ergebnis dieses Skripts ist dieselbe Aufgabenreferenz wie bei curl. Alles nach dem Einreichen – Polling, Wiederholungen, Download – ist sprachunabhängig identisch, weshalb es einen eigenen Abschnitt verdient.

Den Lebenszyklus asynchroner Aufgaben handhaben

Der häufigste Fehler bei der Musikgenerierung ist, sie wie eine Chat-Vervollständigung zu behandeln: senden, warten, Stück lesen. Der Einreichungsaufruf kehrt schnell zurück, aber das Audio existiert noch nicht. Ihr Code muss den Kreis schließen.

Drei Zustände

Jede Aufgabe durchläuft eine kleine Zustandsmaschine:

  1. Eingereicht (Submitted) – Sie haben die Aufgabenkennung, die Arbeit ist in der Warteschlange oder läuft.
  2. Abgeschlossen (Finished) – das Audio ist fertig, die Antwort enthält eine URL darauf.
  3. Fehlgeschlagen (Failed) – die Generierung wurde abgebrochen; die Antwort erklärt den Grund.

Ihre Polling-Schleife sollte alle drei Zustände unterscheiden können. Der Status submitted bedeutet weiter warten, nicht erneut versuchen.

Polling, nicht hämmern

Eine naive Schleife, die Statusprüfungen so schnell wie die CPU es zulässt abschickt, verbraucht Ratenlimits und liefert keine neuen Informationen – das Rendern eines Stücks dauert Dutzende Sekunden, daher sind Hunderte Prüfungen pro Minute reine Verschwendung. Fügen Sie Backoff hinzu:

import time

def wait_for_job(job_id, base_url, api_key, interval=2.0, max_wait=300):
    deadline = time.time() + max_wait
    while time.time() < deadline:
        r = requests.get(
            f"{base_url}/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "finished":
            return data
        if status == "failed":
            raise RuntimeError(f"job failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} not finished after {max_wait}s")

Die genauen Polling-Pfade und Status-Strings entnehmen Sie der API-Referenzdokumentation – betrachten Sie die obigen Namen als schematisch und gleichen Sie sie mit den Werten in der Dokumentation ab.

Das Richtige wiederholen

Wiederholungen gehören zu zwei verschiedenen Ebenen; sie zu vermischen führt zu doppelter Arbeit. Transport-Wiederholungen – der HTTP-Aufruf selbst schlägt wegen 5xx oder Verbindungsabbruch fehl – können bei Polling-Anfragen sicher wiederholt werden. Generierungs-Wiederholungen sind neue Einreichungen und kosten ein weiteres Rendering, daher nur bei explizit als fehlgeschlagen gemeldeten Aufgaben und mit begrenzter Anzahl. Niemals eine Einreichung wiederholen, nur weil das Polling langsam ist.

Speichern Sie die Aufgabenkennung schließlich in dem Moment, in dem Sie sie erhalten. Wenn Ihr Prozess zwischen Einreichung und Fertigstellung abstürzt, ist die Kennung die einzige Möglichkeit, das fertige Stück ohne kostenpflichtige Neugenerierung wiederherzustellen.

Texte, Stil und Dauer-Eingaben abstimmen

Ein brauchbares Stück von minimax-music-1.5 zu bekommen, hängt vor allem davon ab, die beiden Textfelder bewusst zu formulieren. Einige Gewohnheiten entscheiden, ob die Ausgabe Durchschnittsware ist oder etwas, das Sie wirklich veröffentlichen würden.

Den Stil-Prompt als Produzenten-Briefing schreiben

Ein einzelnes Genre-Wort lässt dem Modell zu viel Freiheit. Stapeln Sie konkrete Dimensionen:

  • Genre und Ära – „Trip-Hop der späten 90er“ schlägt „Elektronik“.
  • Instrumentierung – Nennen Sie Hauptinstrumente und Rhythmusgruppe.
  • Stimmung und Energie – „melancholisch, aber treibend“ erzeugt eine Spannung, die ein einzelnes Adjektiv nicht ausdrücken kann.
  • Produktionsmerkmale – „Lo-Fi, Bandsättigung, breite Stereo-Bühne“ lenken den Mix.

Bleiben Sie bei ein bis zwei Sätzen. Lange absatzartige Prompts verwässern eher, als dass sie verfeinern.

Den Songtext mit Tags strukturieren

Leichte Abschnittsmarker – [verse], [chorus], [bridge] – geben dem Modell eine Landkarte und erzeugen oft eine klarere Songstruktur als unmarkierter Textblock. Halten Sie jede Zeile kurz genug zum Singen; zwölf Wörter pro Zeile passen selten zu einer Melodie. Bei instrumentalen Stücken lassen Sie lyrics ganz weg, statt eine leere Zeichenkette mit Stiltext darin zu senden.

Die Dauer am Material ausrichten

Die Dauer begrenzt die Komposition. Eine kurze Dauer mit einem vollständigen Verse-Chorus-Verse-Textblatt erzwingt Verdichtung, was gehetzt klingt; eine lange Dauer mit zwei Textzeilen lädt zu Wiederholungen ein. Entscheiden Sie zuerst die Form des Songs und setzen Sie dann die passende Dauer. Wenn Sie ein längeres Werk benötigen, erweitern Sie den Text, statt die Dauer zu verlängern und zu hoffen, dass es funktioniert.

Mit kleinen Änderungen iterieren

Wenn ein Stück fast passt, aber nicht ganz, ändern Sie jeweils nur eine Eingabe – die Instrumentierung im Prompt, oder ein Tempowort, oder die eine Textzeile, die nicht funktioniert. Alles gleichzeitig zu ändern macht es unmöglich zu erkennen, welches Feld die Verbesserung gebracht hat. Speichern Sie Ihren besten Request-Body in einer Datei und verzweigen Sie davon.

Häufige Fehler beheben

Die meisten Fehlschläge fallen in einige wenige erkennbare Kategorien. Symptom abgleichen, Lösung anwenden, weitermachen.

Authentifizierungsfehler

Symptom: 401 oder 403 mit einer Meldung zu Zugangsdaten.

  • Prüfen Sie, ob der Header Authorization: Bearer <key> lautet – das Wort Bearer und das Leerzeichen sind erforderlich.
  • Vergewissern Sie sich, dass die Umgebungsvariable tatsächlich in dem Prozess gesetzt ist, der die Anfrage stellt. Ein in einer Shell exportierter Schlüssel erreicht keinen Cron-Job oder Docker-Container.
  • Prüfen Sie auf überflüssige Leerzeichen oder Zeilenumbrüche, die mit dem Schlüssel kopiert wurden.

Fehlerhafter Request-Body

Symptom: 400 mit einer Validierungsmeldung.

  • Senden Sie Content-Type: application/json. Fehlt dieser Header, missversteht der Server einen völlig korrekten Body.
  • Wenn Sie requests verwenden, übergeben Sie json=payload oder data=json.dumps(payload). Ein rohes Dictionary an data= wird formularcodiert.
  • Validieren Sie Feldnamen und -typen gegen die API-Referenzdokumentation: model muss exakt minimax-music-1.5 sein, duration eine Ganzzahl, Textzeilenumbrüche müssen in JSON korrekt als \n maskiert sein.
  • Im Zweifel isolieren Sie mit curl -d @payload.json, ob der Body selbst gültig ist, bevor Python ins Spiel kommt.

Timeouts und Verbindungsfehler

Symptom: Die Anfrage hängt oder wirft einen Verbindungsfehler.

  • Setzen Sie für jeden Aufruf ein explizites timeout. Das Einreichungs-Timeout sollte großzügig genug für Warteschlangenverzögerungen sein, ist aber keine Renderzeit.
  • Setzen Sie Ihr Polling-Timeout nicht gleich dem gesamten max_wait; eine einzelne langsame Statusprüfung sollte eine noch laufende Aufgabe nicht abbrechen.
  • Wenn Einreichungen wiederholt Timeouts haben, während Polling erfolgreich ist, ist Ihr Body möglicherweise zu groß – kürzen Sie den Text.

Polling-Fehler

Symptom: Sie pollen kontinuierlich und sehen nie finished, oder Sie pollen die falsche Ressource.

  • Stellen Sie sicher, dass Sie die Aufgabenkennung aus der Einreichungsantwort verwenden, nicht eine Request-ID oder einen Korrelations-Header.
  • Behandeln Sie submitted/running als „weiter warten“, nicht als „Einreichung wiederholen“. Wiederholtes Einreichen erzeugt ein zweites Stück.
  • Fügen Sie Backoff hinzu. Aggressives Polling provoziert Ratenlimits, die wie ein Fehler aussehen, aber selbst verschuldet sind.
  • Wenn die Aufgabe failed meldet, lesen Sie die Meldung, bevor Sie erneut einreichen – ungültige Text-Tags oder außerhalb des Bereichs liegende Dauern schlagen jedes Mal auf dieselbe Weise fehl.

Wenn Sie feststecken, kehren Sie zum rohen curl-Aufruf mit -v zurück, um die tatsächliche Statuszeile und die Header zu sehen. Dieser Schritt beseitigt die meisten Unklarheiten schneller als jede Menge Python-Debugging.

Ähnliche Artikel

Alle Artikel ansehen →

Starte mit persistenten KI-Artefakten

Hol dir deinen API-Key und rufe Bild-, Video- und Audiomodelle über eine einzige task-basierte API auf.

API-Dokumentation lesen