Tutorial

So verwenden Sie mureka-9.5/instrumental über die HiAPI API: curl- und Python-Leitfaden

Nov 3, 2026

Die Funktionen von mureka-9.5/instrumental auf HiAPI

mureka-9.5/instrumental ist ein Text-zu-Musik-Endpunkt auf HiAPI, speziell für rein instrumentale Ausgaben optimiert – Hintergrundmusik, Loops, Untermalungsmusik und Soundtracks. Sie beschreiben den Track mit einem Prompt, reichen einen einzelnen Auftrag ein, und HiAPI liefert eine fertige Audiodatei zurück, die Sie herunterladen und in Spiele, Videoschnitte, Podcasts oder Produktdemos einbauen können.

Das Wort instrumental (instrumental) ist der Schlüssel. Der Endpunkt richtet sich an Musik ohne gesangliche Hauptstimme und eignet sich daher für Szenarien, in denen Erzählstimme oder Dialog klar verständlich bleiben müssen. Wenn Sie Gesangsstücke mit Songtexten benötigen, ist das ein anderes Thema; wenn Sie eine saubere Hintergrundmusik unter einer Vertonung benötigen, ist dies das richtige Werkzeug.

Wählen Sie diesen Endpunkt, wenn:

Sie generierte Hintergrundmusik (BGM) wünschen und nicht aus einer Musikbibliothek auswählen möchten.
Sie schnell und programmatisch große Mengen an Varianten erzeugen müssen statt einer einzelnen maßgeschneiderten Auftragsproduktion.
Ihre Pipeline bereits HTTP verwendet und Sie Musik wie jeden anderen Ressourcengenerierungsschritt behandeln möchten.
Ihnen eine vorhersehbare Request-Form wichtig ist: einreichen, abfragen, herunterladen.

Wie bei anderen Musikgenerierungs-Endpunkten ist die Arbeit asynchron. Nach dem Einreichen erhalten Sie eine Aufgabe, die Sie verfolgen müssen, bis die Audiodatei erzeugt ist. Wenn Sie Ihren Code von Anfang an darauf auslegen, ist der Rest der Integration Routine.

Wo er im Produkt passt

Typische Nutzer sind Content-Pipelines, die Tracks auf Abruf benötigen: ein Video-Renderer, der unter jedes Segment eine Musikspur legen möchte, ein Spiel, das Ambient-Loops braucht, oder ein Prototyping-Tool, mit dem Nutzer eine Stimmung eingeben und das Ergebnis hören. Da der Endpunkt textgesteuert ist, können Sie Prompts aus vorhandenen Metadaten – Genre, Rhythmik, Stimmung und erwartete Dauer – templateartig erzeugen und beim Rendern generieren.

Behandeln Sie jede Anfrage als einen Generierungsauftrag mit eigenem Lebenszyklus. Dieser Rahmen hält Ihre Retry-Logik, Protokollierung und Kostenabrechnung solide.

Vorbereitung vor dem Senden der Anfrage

Bevor der erste Aufruf erfolgreich ist, müssen einige Bedingungen erfüllt sein. Keine davon ist kompliziert, aber eine zu übersehen ist die häufigste Ursache für einen fehlgeschlagenen ersten Request.

Anmeldedaten

Sie benötigen einen HiAPI API-Schlüssel. Behandeln Sie ihn als Geheimnis: Laden Sie ihn aus einer Umgebungsvariable wie HIAPI_API_KEY, kodieren Sie ihn niemals fest in Skripte, die Sie einreichen, und rotieren Sie ihn, falls er kompromittiert wurde. Der Schlüssel wird über den Header Authorization als Bearer-Token gesendet.

export HIAPI_API_KEY="your_api_key_here"

Endpunkt und Transport

Sie rufen das Modell mureka-9.5/instrumental über die einheitliche HiAPI API auf. Die Basis-URL ist der HiAPI API-Host; der Modellbezeichner wird gemäß der für diesen Endpunkt dokumentierten HiAPI-Konvention im Request-Payload oder Pfad platziert. Verwenden Sie HTTPS, senden Sie Content-Type: application/json und senden Sie einen JSON-Body.

Raten Sie keine Parameternamen. HiAPI dokumentiert die Felder, die dieses Modell akzeptiert; alles außerhalb dieser Menge wird im besten Fall ignoriert, im schlimmsten Fall abgelehnt. Wenn ein Feld, das Sie möchten, nicht dokumentiert ist, ist es nicht Teil des Vertrags – bauen Sie auf dem auf, was vorhanden ist.

Was Sie vorbereiten sollten

Einen Prompt, der die Musik beschreibt: Genre, Instrumentierung, Stimmung, Rhythmik und Verwendungszweck.
Die dokumentierten Dauer- oder Variantenoptionen, die das Modell offenlegt.
Einen Ort zur Speicherung der Aufgabenkennung und später der Download-URL.
Netzwerkzugriff von dem Ort, an dem Ihr Code läuft, zum HiAPI-Host.

Ein Hinweis zur Zeit

Die Generierung ist nicht sofort. Setzen Sie Client-Timeouts großzügig und rechnen Sie mit Polling. Synchrones Denken – Anfrage senden und blockieren, bis die Audiodatei in derselben Antwort zurückkommt – führt zu instabilem Code.

Eine funktionierende curl-Anfrage

Beginnen Sie mit curl. Es entfernt jede Schicht zwischen Ihnen und der HTTP-Kommunikation, sodass Sie Probleme sofort sehen.

Der Aufruf

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mureka-9.5/instrumental",
    "input": {
      "prompt": "warm lo-fi hip hop instrumental, mellow electric piano, soft vinyl crackle, relaxed 80 bpm, no vocals"
    }
  }'

Legen Sie zuerst die beiden Umgebungsvariablen fest, damit außer dem von Ihnen gewählten Inhalt keine sensiblen Informationen im Klartext in der Shell-Historie verbleiben:

export HIAPI_BASE_URL="https://api.hiapi.ai/v1/..."   # verwenden Sie den für diesen Endpunkt dokumentierten Pfad
export HIAPI_API_KEY="your_api_key_here"

Was die einzelnen Teile tun

-X POST — Einreichen ist ein Erstellungsvorgang.
-H "Authorization: Bearer ..." — Authentifiziert den Aufruf mit Ihrem Konto.
-H "Content-Type: application/json" — Teilt dem Server mit, dass der Body JSON ist; ohne diesen Header lehnen viele Server den Body direkt ab.
-d '{...}' — Der JSON-Payload. Das Feld model gibt den Endpunkt an; das Objekt input enthält Ihren Prompt und weitere dokumentierte Felder.
-sS — Unterdrückt den Fortschritt, zeigt aber weiterhin Fehler an. Nützlich in Skripten.

Die Antwort lesen

Die Antwort ist JSON. Sie suchen eine Aufgaben- oder Jobkennung und ein Statusfeld. Formatieren Sie sie zur Prüfung hübsch:

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | jq .

Bewahren Sie die Kennung auf. Sie ist das Handle für jede spätere Statusprüfung. Analysieren Sie nicht den gesamten Antwort-Body in Ihre Anwendung; extrahieren Sie Aufgaben-ID und Status und speichern Sie die Rohantwort zur Fehlersuche.

Wenn Sie einen Nicht-2xx-Status erhalten, lesen Sie den Body – HiAPI gibt strukturierte Fehlermeldungen zurück, die in der Regel das problematische Feld benennen.

Die gleiche Anfrage in Python

Die Python-Version entspricht exakt dem curl-Aufruf: gleiche Header, gleicher JSON-Body. Verwenden Sie der Einfachheit halber requests oder die Standardbibliothek, wenn Sie keine Abhängigkeiten wünschen.

Mit requests

import os
import requests

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

payload = {
    "model": "mureka-9.5/instrumental",
    "input": {
        "prompt": (
            "warm lo-fi hip hop instrumental, mellow electric piano, "
            "soft vinyl crackle, relaxed 80 bpm, no vocals"
        )
    },
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

resp = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
resp.raise_for_status()
data = resp.json()
job_id = data["id"]          # use the documented field name
print("submitted:", job_id, data.get("status"))

Mit der Standardbibliothek

Wenn Sie keine Abhängigkeit hinzufügen können:

import json, os, urllib.request

req = urllib.request.Request(
    os.environ["HIAPI_BASE_URL"],
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(req, timeout=30) as r:
    data = json.load(r)

Praktische Gewohnheiten

Verwenden Sie timeout=30 nur beim Einreichen. Polling benötigt eine eigene Schleife und ein eigenes Timeout.
Rufen Sie raise_for_status() vor dem Parsen auf. Ein Fehlerantwort-Body ist keine Aufgabe.
Kapseln Sie die Extraktion der Aufgaben-ID in eine kleine Hilfsfunktion, damit eine Feldnamenänderung nur eine Zeile Korrektur erfordert.
Protokollieren Sie niemals den API-Schlüssel; protokollieren Sie stattdessen Aufgaben-ID und Status.
Halten Sie den Payload als Dictionary im Code, serialisieren Sie ihn einmal, damit Tests darauf prüfen können.

Asynchrone Aufgaben und Polling behandeln

Das Einreichen ist der erste Schritt. Die Generierung erfolgt serverseitig und wird später abgeschlossen, daher fragen Sie den Status-Endpunkt ab, bis die Aufgabe einen Endzustand meldet.

Die Form der Schleife

Aufgabe einreichen, ID erfassen.
Kurz warten.
Status für diese ID abfragen.
Wenn der Status „in Warteschlange“ oder „in Bearbeitung“ ist, mit Backoff warten und wiederholen.
Wenn der Status ein Erfolgsstatus ist, die Ausgabe lesen.
Wenn der Status ein Fehlerstatus ist, den Fehler protokollieren und abbrechen – nicht blind wiederholen.

Eine robuste Implementierung

import time, random, requests

def wait_for_job(job_id, base_status_url, headers,
                 timeout_s=600, initial_delay=2.0, max_delay=30.0):
    deadline = time.monotonic() + timeout_s
    delay = initial_delay

    while time.monotonic() < deadline:
        r = requests.get(f"{base_status_url}/{job_id}", headers=headers, timeout=30)
        r.raise_for_status()
        status = r.json()["status"]

        if status in ("succeeded", "completed", "success"):
            return r.json()
        if status in ("failed", "error", "cancelled"):
            raise RuntimeError(f"job {job_id} ended as {status}: {r.text}")

        time.sleep(delay + random.uniform(0, 0.5))   # jitter
        delay = min(delay * 1.5, max_delay)          # exponential backoff

    raise TimeoutError(f"job {job_id} did not finish in {timeout_s}s")

Warum jedes Detail wichtig ist

Jitter verhindert synchrone Wiederholungen, wenn mehrere Aufgaben parallel laufen.
Backoff verhindert, dass der Status-Endpunkt während des Renderns von Tracks überlastet wird.
Deadline verwandelt endloses Hängen in eine saubere Ausnahme, die die Pipeline verarbeiten kann.
Endzustandsprüfungen sollten den in der HiAPI-Dokumentation aufgeführten Status-Strings entsprechen. Bestätigen Sie diese anhand der API-Referenz, statt Vermutungen zu vertrauen.
Wiederholungen sollten bei transienten Netzwerkfehlern (Timeouts, 5xx) erfolgen, nicht bei Aufgaben, die bereits wegen Validierungsfehlern fehlgeschlagen sind.

Betriebshinweise

Persistieren Sie die job_id, bevor Sie mit dem Polling beginnen. Wenn Ihr Prozess abstürzt, können Sie das Polling wieder aufnehmen, statt für eine zweite Generierung zu bezahlen. Protokollieren Sie Statusübergänge mit Zeitstempel, damit Sie sehen, wo die Zeit verbracht wird. Wenn Sie viele Aufgaben ausführen, pollen Sie eine kleine Anzahl parallel über eine Warteschlange, statt für jede Aufgabe einen Request-Thread zu blockieren.

Die instrumentale Ausgabe abrufen und herunterladen

Der Instrumentalmodus wird durch Ihre Anfrage ausgedrückt; der Endpunkt ist auf solche Ausgaben spezialisiert. In der Praxis verstärkt die Prompt-Formulierung dies: Benennen Sie Instrumente, beschreiben Sie die Stimmung und erklären Sie, dass keine Vocals gewünscht sind. Prompts, die Gesangslinien verlangen, widersprechen dem Zweck des Endpunkts.

Wo die Audiodatei erscheint

Wenn die Aufgabe den Erfolgsstatus erreicht, trägt die Statusantwort das Ergebnis. Erwarten Sie, dass die Audiodatei als separat abrufbare URL geliefert wird, nicht als Base64 im Status-JSON. Lesen Sie die Antwort und extrahieren Sie die Download-URL aus dem dokumentierten Ausgabefeld.

result = wait_for_job(job_id, status_url, headers)
# Prüfen Sie die ersten Male sorgfältig das Ergebnis und pinnen Sie dann das Feld.
audio_url = result["output"]["audio_url"]   # bestätigen Sie den Feldnamen in der API-Referenz

with requests.get(audio_url, stream=True, timeout=60) as r:
    r.raise_for_status()
    with open(f"{job_id}.mp3", "wb") as f:
        for chunk in r.iter_content(chunk_size=65536):
            f.write(chunk)

Download-Gewohnheiten

Streamen Sie auf die Festplatte. Musikdateien sind groß; sie vollständig in den Speicher zu laden, ist vermeidbarer Stress.
Prüfen Sie den Inhaltstyp. Speichern Sie die Datei mit der vom Antworttyp nahegelegten Erweiterung, nicht mit einer fest kodierten.
Behandeln Sie die URL als temporär. Laden Sie zeitnah herunter oder persistieren Sie die URL nur, wenn die Dokumentation sie als stabil ausweist. Kopieren Sie die Bytes in Ihren eigenen Speicher zur dauerhaften Aufbewahrung.
Laden Sie nur einmal herunter. Ein Download in einer Wiederholungsschleife ohne Abschlussmarker erzeugt leicht partielle Dateien. Schreiben Sie unter einem temporären Namen und benennen Sie nach Erfolg um.
Protokollieren Sie die Herkunft. Speichern Sie Aufgaben-ID und Prompt zusammen mit der Datei. Wenn Sie später eine Variante benötigen, haben Sie die exakten Eingaben.

Häufige Fehlerpunkte und Lösungen

Die meisten Probleme bei der ersten Integration fallen in eine kurze Liste. Hier ist die Checkliste.

401 / 403 — Authentifizierung. Der Header ist falsch, der Schlüssel fehlt, oder die Umgebungsvariable wird zu einem leeren String aufgelöst. Vergewissern Sie sich, dass der Schlüssel in derselben Shell oder demselben Prozess gesetzt ist, in dem der Code läuft, und dass der Header exakt Authorization: Bearer <key> lautet.

400 — Fehlerhaft formatierter Payload. Fehlendes model, ein Tippfehler in mureka-9.5/instrumental, ungültiges JSON oder ein vom Endpunkt nicht akzeptiertes Feld. Senden Sie den Body zuerst mit curl, um den Payload vom Code zu isolieren. Validieren Sie JSON vor dem Senden; nachgestellte Kommas sind ein Klassiker.

415 oder Fehler mit leerem Body — Inhaltstyp. Content-Type: application/json muss vorhanden sein. Manche HTTP-Clients setzen es automatisch, wenn Sie json= übergeben, aber nicht alle.

Polling-Timeout. Ihre Deadline ist zu kurz, Ihr Backoff zu aggressiv, oder die Aufgabe ist tatsächlich fehlgeschlagen und Sie haben sie als noch laufend eingestuft. Prüfen Sie die exakten Status-Strings anhand der Dokumentation und geben Sie bei der Fehlersuche jeden Statusübergang aus.

Fehlende Download-URL. Sie haben das falsche Feld gelesen oder die Antwort gelesen, bevor die Aufgabe den Endzustand Erfolg erreicht hatte. Protokollieren Sie einmal einen vollständigen Erfolgspayload, bestätigen Sie den Pfad der Audio-URL und pinnen Sie ihn dann.

Doppelte Generierung. Ihr Poller ist abgestürzt und etwas hat erneut eingereicht. Persistieren Sie die Aufgaben-ID vor dem Polling und prüfen Sie auf vorhandene Aufgaben, bevor Sie eine neue einreichen.

Ratenbegrenzung. Warten Sie bei 429-Antworten mit Jitter und Backoff und reihen Sie Arbeit ein, statt aus vielen Threads gleichzeitig zu feuern.

Arbeiten Sie sie in dieser Reihenfolge ab – Authentifizierung, Payload, Inhaltstyp, Polling, Ausgabe – und Sie finden die Ursache in der Regel auf Anhieb. Sobald der curl-Aufruf und seine Python-Entsprechung beide durchgängig erfolgreich sind, tut der Endpunkt, was Sie verlangen: Er verwandelt Prompts in instrumentale Tracks und liefert Ihnen eine Download-URL.