minimax-music-3 API: curl- und Python-Leitfaden

Um auf hiapi mit minimax-music-3 einen Track zu erzeugen, genügt ein einziger Aufruf von POST /v1/tasks plus Polling – genau dasselbe asynchrone Aufgabenmuster, das alle Modelle auf der Plattform verwenden. Dieser Leitfaden dokumentiert echte Anfragen und Antworten (Aufgabenerstellung, Polling und die endgültige Audio-URL), sodass der Code unten direkt kopiert und ausgeführt werden kann und nicht nur illustrativ ist.

Was du vorbereiten musst

1. Einen hiapi-API-Schlüssel – erstelle ihn in der Konsole. Er wird bei jeder Anfrage als Bearer-Token gesendet.
2. Das war's. Anders als Modelle für Bild-zu-Video oder Bild-zu-Bild akzeptiert minimax-music-3 keine Datei- oder URL-Eingaben – es generiert ausschließlich aus Text.

Minimal funktionsfähige Anfrage (curl)

Aufgabe erstellen:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-3",
    "input": {
      "prompt": "chill lofi hip hop beat, mellow piano, soft drums",
      "lyrics": "[Instrumental]"
    }
  }'

Antwort:

{"code":200,"data":{"taskId":"tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55"},"message":"success"}

Aufgabe abfragen, bis sie abgeschlossen ist:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55 \
  -H "Authorization: Bearer sk-<your-key>"

Während die Aufgabe läuft, durchläuft status nacheinander handling → archiving und wird schließlich zu success (oder failed). In Tests benötigte ein Track von der Einreichung bis success etwa zweieinhalb Minuten. Die Antwort nach Abschluss sieht so aus:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55",
    "status": "success",
    "model": "minimax-music-3",
    "created": 1787018905,
    "completed": 1787019051,
    "storage": "temp",
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M09A11R6WEC2JDQ8RK6E7N55-0.wav",
        "artifactId": "78585",
        "expireAt": 1787623851
      }
    ]
  },
  "message": "success"
}

output[0].url ist die WAV-Datei. Beachte expireAt – bevor du Funktionen baust, die auf eine langfristige Gültigkeit dieser URL angewiesen sind, lies den Speicherhinweis weiter unten.

Derselbe Ablauf in Python

import time
import requests

API_KEY = "sk-<your-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_track(prompt: str, lyrics: str = "[Instrumental]") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={"model": "minimax-music-3", "input": {"prompt": prompt, "lyrics": lyrics}},
        timeout=30,
    )
    body = resp.json()
    if resp.status_code != 200 or "error" in body:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]


def wait_for_track(task_id: str, timeout_s: int = 300, interval_s: int = 6) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_track("upbeat synthwave, driving bassline, retro 80s")
    audio_url = wait_for_track(task_id)
    audio = requests.get(audio_url, timeout=60).content
    with open("track.wav", "wb") as f:
        f.write(audio)
    print(f"saved track.wav from task {task_id}")

Parameter, die minimax-music-3 tatsächlich validiert

Das Eingabe-Schema ist strikt – sendest du nicht aufgeführte Felder, lehnt die API die gesamte Anfrage ab, bevor sie in die Warteschlange gelangt:

• prompt (String, erforderlich) – Stil, Stimmung, Instrumentierung. Das bestimmt tatsächlich die Form des Tracks.
• lyrics (String, erforderlich) – immer erforderlich, selbst bei rein instrumentalen Tracks. Übergib "[Instrumental]" als Platzhalter; für Tracks mit Gesang verwende Abschnitts-Tags wie [Verse] / [Chorus].
• callback (Objekt, optional) – {"url": "...", "when": "final"}. Der einzige unterstützte Wert für when ist "final"; jeder andere Wert liefert 400 mit der Fehlermeldung invalid callback.when: only 'final' is supported.

Sendest du irgendetwas außerhalb dieser drei Schlüssel auf oberster Ebene – etwa sample_rate, duration oder einen Tippfehler –, erhältst du:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'sample_rate' not allowed"}

Hinweise für den Produktivbetrieb

• Zwei verschiedene Fehlerformen. Validierungsfehler (fehlende Felder, falsche Enum-Werte, unbekannte Schlüssel) werden auf oberster Ebene als {"code":400,"error_code":"INVALID_REQUEST","message":"..."} zurückgegeben. Authentifizierungs-/Berechtigungsfehler liefern dagegen {"error":{"code":"permission_denied","message":"...","request_id":"..."}} – ein verschachteltes error-Objekt, HTTP 401. Prüfe in deiner Fehlerbehandlung beide Formen; Code, der nur resp["code"] prüft, übersieht den 401-Fall.
• permission_denied bedeutet ein Problem mit dem Schlüssel, nicht mit der Anfrage. Wenn prompt/lyrics vorhanden und vom richtigen Typ sind, du aber weiterhin 401 permission_denied erhältst, ist für diesen API-Schlüssel selbst dieses Modell nicht freigeschaltet – prüfe ihn in der Konsole, statt wiederholt dein JSON durchzulesen.
• Die Speicherung der Ausgabedateien ist temporär. storage: "temp" sowie ein expireAt-Unix-Zeitstempel an jeder Ausgabe – im erfassten Beispiel etwa 7 Tage nach der Erstellung. Lade die Datei sofort herunter, sobald die Aufgabe erfolgreich ist, oder verschiebe sie in deinen eigenen Speicher; speichere temp.hiapi.ai-URLs nicht als dauerhafte Links.
• Verwende für jede Art von Massenverarbeitung Callbacks. Einen Track zu pollen ist in Ordnung; fünfzig Tracks zu pollen bedeutet fünfzig wiederholte Roundtrips. Setze callback.url und when: "final", damit hiapi dir das Ergebnis einmalig zustellt, wenn die Aufgabe tatsächlich abgeschlossen ist.
• Wiederhole vor dem Erhalt der taskId, nicht danach. Ein erneuter Versuch bei einem Netzwerkfehler oder 5xx des initialen POST /v1/tasks ist sicher – zu diesem Zeitpunkt wurde noch nichts erstellt. Sobald du eine taskId hast, erzeugt ein erneutes Einreichen desselben Prompts einen weiteren, unabhängigen Track; ab dann solltest du stattdessen pollen oder auf den Callback warten.

Verwandte Inhalte

• minimax-music-3 Modellseite – aktuelle Preise und Online-Demo-Bereich.
• hiapi-Preise – Tarife für alle Modelle im Katalog.
• hiapi-Dokumentation – vollständige API-Referenz über dieses einzelne Modell hinaus.

Häufige Fragen

Muss ich für rein instrumentale Tracks Liedtexte angeben? Ja – lyrics ist ein Pflichtfeld, unabhängig davon, ob du Gesang möchtest. Übergib "[Instrumental]", und das Modell erzeugt einen Track ohne Gesang.

Kann ich Polling vollständig vermeiden? Ja, setze beim Erstellen der Aufgabe callback: {"url": "https://your-endpoint", "when": "final"}. Wenn die Aufgabe einen Endzustand erreicht, sendet hiapi dieselbe Nutzlast wie bei GET /v1/tasks/:id per POST an deine URL. "final" ist derzeit der einzige unterstützte Wert für when.

Warum erhalte ich "additional properties not allowed"? Das Eingabe-Schema von minimax-music-3 akzeptiert innerhalb von input nur prompt und lyrics (plus callback auf oberster Ebene). Jeder andere Feldname – selbst wenn er bei anderen hiapi-Modellen funktioniert – wird abgelehnt, bevor die Anfrage ausgeführt wird.

Warum gibt ein Schlüssel, der bei anderen Modellen funktioniert, bei diesem Modell 401 zurück? Der Modellzugriff wird pro Schlüssel gewährt. Ein 401 mit error_code: "permission_denied" bedeutet, dass genau diesem Schlüssel die Berechtigung für minimax-music-3 noch nicht erteilt wurde – aktiviere sie in der Konsole; das ist kein Bug in deinem Anfrage-Body.

Wie lange kann ich mit dem Herunterladen der Ausgabedatei warten? Warte nicht – output[0].url ist ein temporärer Link (expireAt liegt in der Praxis etwa eine Woche später). Behandle ihn als einmalige Übergabe: Lade die Datei sofort herunter oder lade sie erneut hoch, sobald die Aufgabe erfolgreich ist.