So verwendest du die MiniMax Music API (minimax-music-1.5): curl, Python und lauffähige Anfragen

Diese Anleitung zeigt, wie du minimax-music-1.5 über die einheitliche Task-API von hiapi verwendest, um mit einem Stil-Prompt und Songtexten einen vollständigen Song zu erzeugen – inklusive Gesang, Instrumenten und Songstruktur. Alle folgenden Inhalte wurden gegen den echten Endpunkt verifiziert und können direkt kopiert, eingefügt und ausgeführt werden.

Was du baust und was du vorbereiten musst

Ziel: eine Textbeschreibung des Musikstils und deine Songtexte einreichen und eine herunterladbare Audiospur erhalten.

Du brauchst nur eines: einen hiapi API-Schlüssel. Hole ihn dir aus deinem Dashboard – er beginnt mit sk-. Alle folgenden Beispiele gehen davon aus, dass er in einer Umgebungsvariable gespeichert ist:

export HIAPI_KEY="sk-your-key-here"

Die Musikgenerierung auf hiapi nutzt dieselbe asynchrone Task-Schnittstelle wie alle anderen Modelle: POST /v1/tasks erstellt einen Task, danach entweder GET /v1/tasks/<taskId> abfragen oder einen Callback erhalten, wenn der Task abgeschlossen ist.

Eingabe-Schema (verifiziert)

minimax-music-1.5 akzeptiert in input die folgenden Felder – jedes andere Feld wird mit 400 abgelehnt:

Feld	Erforderlich	Typ	Einschränkung
prompt	Ja	string	10–300 Zeichen. Beschreibt Genre, Stimmung, Instrumentierung und Gesangsstil.
lyrics	Ja	string	10–600 Zeichen. Die zu singenden Texte; unterstützt Abschnitts-Tags wie [Verse] und [Chorus].
sample_rate	Nein	integer	Einer von 16000, 24000, 32000, 44100.
bitrate	Nein	integer	Einer von 32000, 64000, 128000, 256000.

Zwei mudah zu übersehende Fallstricke:

1. prompt und lyrics sind beide erforderlich. prompt steuert, wie es klingt; lyrics steuern, was gesungen wird. Fehlt eines davon, erhältst du invalid input: ... missing required field.
2. Das Schema ist streng. Felder, die du von anderen Musik-APIs erwarten könntest – duration, seed, format, instrumental – werden nicht akzeptiert. Sendest du sie, wird additional properties ... not allowed zurückgegeben.

Minimales lauffähiges Beispiel: curl

Task erstellen:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-1.5",
    "input": {
      "prompt": "Uplifting acoustic pop, warm female vocals, gentle guitar and light percussion",
      "lyrics": "[Verse]\nMorning light on a quiet street\nCoffee steam and a steady beat\n[Chorus]\nWe keep on going, we find our way\nOne small step at a time, every day",
      "sample_rate": 44100,
      "bitrate": 256000
    }
  }'

Bei erfolgreicher Erstellung wird eine Task-ID zurückgegeben:

{"code": 200, "data": {"taskId": "task_abc123..."}}

Dann abfragen (pollen), bis der Task einen Endzustand erreicht:

curl https://api.hiapi.ai/v1/tasks/task_abc123 \
  -H "Authorization: Bearer $HIAPI_KEY"

Während der Task läuft, siehst du einen nicht-finalen status; bei Abschluss wechselt status zu success und die Audio-URL erscheint in output:

{
  "code": 200,
  "data": {
    "taskId": "task_abc123",
    "status": "success",
    "output": [{"url": "https://.../track.mp3"}]
  }
}

Lade die Datei so schnell wie möglich herunter – die Output-URL ist zeitlich begrenzt; behandle sie als Abholfenster und nicht als dauerhaften Speicher:

curl -o track.mp3 "https://.../track.mp3"

Vollständiges Python-Skript: einreichen, pollen, herunterladen

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_KEY']}",
    "Content-Type": "application/json",
}

def create_task() -> str:
    payload = {
        "model": "minimax-music-1.5",
        "input": {
            "prompt": ("Uplifting acoustic pop, warm female vocals, "
                       "gentle guitar and light percussion"),
            "lyrics": ("[Verse]\nMorning light on a quiet street\n"
                       "Coffee steam and a steady beat\n"
                       "[Chorus]\nWe keep on going, we find our way\n"
                       "One small step at a time, every day"),
            "sample_rate": 44100,
            "bitrate": 256000,
        },
    }
    r = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    data = r.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = (r.json().get("data") or {})
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

def download(url: str, path: str = "track.mp3") -> str:
    r = requests.get(url, timeout=120)
    r.raise_for_status()
    with open(path, "wb") as f:
        f.write(r.content)
    return path

if __name__ == "__main__":
    task_id = create_task()
    print(f"submitted: {task_id}")
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    print(f"done, downloading: {url}")
    print(f"saved to {download(url)}")

Führe es mit python3 make_song.py aus. Das Skript reicht den Task ein, fragt alle 5 Sekunden ab und speichert die fertige Spur lokal.

Produktionsmuster

Callbacks statt Polling verwenden

Für alles, was über ein schnelles Skript hinausgeht, registriere einen Callback, damit hiapi das Ergebnis an dich pusht, sobald der Task einen Endzustand erreicht. Füge ein Top-Level-callback-Objekt hinzu (es ist auf derselben Ebene wie model, nicht innerhalb von input):

{
  "model": "minimax-music-1.5",
  "input": {"prompt": "...", "lyrics": "..."},
  "callback": {"url": "https://your.domain.example/hiapi/callback", "when": "final"}
}

Nur "when": "final" wird unterstützt – du erhältst ein POST, wenn der Task erfolgreich ist oder fehlschlägt, keine inkrementellen Fortschrittsereignisse. Polling eignet sich für Entwicklung und einmalige Aufgaben; Callbacks sind besser, wenn du große Mengen an Spuren generierst oder hinter einer Warteschlange läufst, weil du keine offene Schleife aufrechterhalten musst und keine Ratenbegrenzungen durch hochfrequentes Polling auslöst. Wenn ein Callback nie ankommt, gehe die Checkliste in Warum dein hiapi-Task-Callback nicht ausgelöst wird durch.

Idempotenz und Wiederholungen

Die Task-Erstellung selbst ist nicht idempotent: Ein erneuter Versuch eines zeitlich überschrittenen POST /v1/tasks kann zwei Tasks erzeugen (und doppelt berechnet werden). Speichere die taskId sofort nach Rückkehr des Erstellungsaufrufs und stelle sie bei einem Neustart durch Abfragen dieser ID wieder her, statt blind erneut einzureichen. Wenn ein Task hängen zu bleiben scheint, beende und erstelle ihn nicht sofort neu – siehe hiapi /v1/tasks: Task hängt oder läuft in ein Timeout, um zu unterscheiden, ob ein Task langsam oder tot ist.

Fehlerbehandlung

Zwei Arten von Fehlern zeigen sich unterschiedlich:

• Fehler auf Anfrageebene werden synchron zurückgegeben. Ein ungültiger oder nicht autorisierter Schlüssel gibt einen permission_denied-Fehler zurück ("This API key cannot use the selected model..."), zusammen mit einer request_id, die du dem Support nennen kannst. Schemaverstöße geben 400 INVALID_REQUEST mit einer präzisen Meldung zurück, z. B. prompt: minLength: got 1, want 10.
• Fehler auf Task-Ebene erscheinen im Polling-/Callback-Ergebnis als status: "fail" mit error.code und error.message – der Erstellungsaufruf war erfolgreich, aber die Generierung ist fehlgeschlagen. Diese Fehler gehören in deine Wiederholungslogik.

Validiere die Längen clientseitig vor dem Senden: prompt maximal 300 Zeichen, lyrics maximal 600 Zeichen; die API lehnt zu lange Eingaben ab, statt sie abzuschneiden.

Preise und Limits

MiniMax Music 1.5 wird pro generierter Spur nach Nutzung abgerechnet – die aktuellen Tarife findest du auf der hiapi-Preisseite und der minimax-music-1.5-Modellseite, wo du das Modell im Playground auch testen kannst, bevor du eine Zeile Code schreibst.

Häufige Fragen

Welche Eingabefelder akzeptiert minimax-music-1.5?

Genau vier: prompt (erforderlich, 10–300 Zeichen), lyrics (erforderlich, 10–600 Zeichen), sample_rate (optional, 16000/24000/32000/44100) und bitrate (optional, 32000/64000/128000/256000). Jedes andere Feld wird mit additional properties not allowed abgelehnt.

Kann ich die Songstruktur steuern?

Ja – verwende in lyrics Abschnitts-Tags wie [Verse] und [Chorus], um die Struktur zu organisieren. Das Modell nutzt diese Tags, um das Arrangement zu formen. Der gesamte Lyrics-String (inklusive Tags) muss innerhalb des Limits von 600 Zeichen bleiben.

Kann ich rein instrumentale Musik erzeugen?

Das Eingabe-Schema hat keinen Schalter für Instrumentalmusik. Dieser Endpunkt ist textgetrieben, beschreibe also im prompt die Instrumentierung und Stimmung, die du möchtest; für rein instrumentale Anwendungsfälle siehe die Modellseite für die aktuelle Funktionsliste.

Wie bekomme ich die Audiodatei?

Wenn der Task-Status success ist, enthält data.output[0].url den Download-Link. Hole ihn sofort und speichere die Bytes selbst – Output-URLs laufen ab.

Soll ich pollen oder einen Callback verwenden?

Für Entwicklung und einzelne Tasks nutze Polling (5 Sekunden Intervall sind ausreichend). In der Produktion verwende callback mit when: "final", damit du keine Verbindung offen halten musst – besonders wenn du Spuren in großen Mengen generierst.

Warum erhalte ich permission_denied?

Dein Schlüssel ist ungültig oder hat keinen Zugriff auf dieses Modell. Überprüfe den Schlüssel im Dashboard und stelle sicher, dass du ihn im Format Authorization: Bearer sk-... sendest.