Tutorial
minimax-music-1.5 API Tutorial: curl und Python Requests
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:
- 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.
- 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.\nist 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.dumpsmitdata=oderjson=payloadverwenden. Beides funktioniert;json=payloadlässtrequestsden Inhaltstyp für Sie setzen. Wenn Sie ein Dictionary ohne Serialisierung direkt andata=übergeben, erhält der Server einen formularcodierten Body und lehnt ihn ab.- Immer
timeoutsetzen. 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ösenKeyError, wenn Sie auf ein nicht vorhandenes Feld zugreifen. - Das Response-Objekt behalten. Beim Debuggen liefern
response.status_codeundresponse.textweit 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:
- Eingereicht (Submitted) – Sie haben die Aufgabenkennung, die Arbeit ist in der Warteschlange oder läuft.
- Abgeschlossen (Finished) – das Audio ist fertig, die Antwort enthält eine URL darauf.
- 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 WortBearerund 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
requestsverwenden, übergeben Siejson=payloadoderdata=json.dumps(payload). Ein rohes Dictionary andata=wird formularcodiert. - Validieren Sie Feldnamen und -typen gegen die API-Referenzdokumentation:
modelmuss exaktminimax-music-1.5sein,durationeine Ganzzahl, Textzeilenumbrüche müssen in JSON korrekt als\nmaskiert 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/runningals „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
failedmeldet, 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 →-
Tutorial
gpt-6.2-sol Praxisleitfaden: 5 hochwertige Einsatzszenarien für Textmodelle im Geschäftsalltag
-
Tutorial
gpt-6.2-astra Praxisleitfaden: Integration und Umsetzung von 5 hochwertigen Text-Szenarien
Eine Entwickler-Checkliste von der Szenarioauswahl bis zur technischen Umsetzung
-
Tutorial
Tripo H3.1 Anwendungsszenarien in der Praxis: 5 wertvolle Einsatzmöglichkeiten und Umsetzungshinweise
Von Text-zu-3D bis Multi-View-Rekonstruktion: den richtigen Modus und die richtigen Parameter je nach Geschäftsszenario wählen