So rufen Sie die mirelo-sfx-2.0-API über HiAPI auf: curl, Python und asynchrones Polling

Funktionen und Anwendungsfälle von mirelo-sfx-2.0

mirelo-sfx-2.0 ist ein über HiAPI aufrufbares Text-zu-Soundeffekt-Modell. Sie übergeben ihm eine natürlichsprachliche Beschreibung – etwa „eine schwere Holztür knarzt langsam auf“ oder „eine Münze fällt auf eine Marmorplatte“ – und es erzeugt einen kurzen Audioclip, der zum Prompt passt.

Dies ist der richtige Endpunkt, wenn Sie bedarfsgerechtes Sounddesign benötigen, anstatt Lizenzen aus einer Sample-Bibliothek zu erwerben:

• Prototyping von Spielen und Anwendungen: Platzhalter oder finale Soundeffekte für Interaktionen, UI-Ereignisse und Umgebungsschleifen erzeugen.
• Postproduktion von Video und Podcast: Lücken mit Foley-artigem Audio füllen, ohne ein Tonstudio buchen zu müssen.
• Generative Pipelines: Prompts aus Skripten, Storyboards oder Benutzereingaben beziehen und das erzeugte WAV an die Ausgabe anhängen.

Das Modell liefert die besten Ergebnisse, wenn die Klangbeschreibung klar und die Dauer kurz ist. Wenn Sie Musik, Sprache oder langes Audio benötigen, ist das eine andere Modellfamilie – mirelo-sfx-2.0 ist auf diskrete Soundeffekte spezialisiert.

Da die Generierung asynchron erfolgt, planen Sie die Integration aufgabenbasiert statt als blockierenden HTTP-Aufruf. Der Rest dieses Tutorials baut diese Integration auf, von der rohen curl-Anfrage bis zum Python-Client, der durch Polling das fertige WAV abruft.

Voraussetzungen und Einrichtung der Authentifizierung

Stellen Sie vor dem ersten Aufruf sicher, dass Sie Folgendes haben:

• Ein HiAPI-Konto und einen API-Schlüssel. Sie können Schlüssel in der HiAPI-Konsole erstellen und verwalten. Behandeln Sie den Schlüssel wie ein Passwort: Laden Sie ihn aus einer Umgebungsvariable oder einem Secret-Manager und committen Sie ihn niemals in ein Code-Repository.
• Ein Werkzeug zum Senden von HTTP-Anfragen. Für diese Einführung genügt curl; die Codebeispiele verwenden Python 3.8+.
• Einen HTTP-Client in Python. Die Beispiele verwenden aus Gründen der Einfachheit requests, aber jeder Client, der JSON und Header senden kann, ist geeignet.

HiAPI verwendet für alle Modelle eine einzige Basis-URL und eine einzige Authentifizierungsmethode, sodass die hier erlernten Konventionen auch für andere Endpunkte gelten:

export HIAPI_API_KEY="your-api-key-here"

Jede Anfrage sendet den Schlüssel im Authorization-Header:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

Der Modellbezeichner wird im Request-Body über "model": "mirelo-sfx-2.0" übergeben. Es ist kein separates SDK zu installieren – solange Ihr HTTP-Client die HiAPI-Basis-URL erreichen kann, können Sie das Modell aufrufen.

Ein praktischer Hinweis: Speichern Sie die Basis-URL in einer Konfigurationsvariable, statt sie in verschiedenen Dateien fest zu kodieren. Wenn Sie von lokalen Skripten zu Staging- oder Produktionsdiensten wechseln, möchten Sie sie nur an einer Stelle ändern.

Schrittweise Analyse der curl-Anfrage

Die Generierungsanfrage ist ein authentifizierter HTTP-POST an den HiAPI-Endpunkt zur Aufgabenerstellung. Hier ist der vollständige Aufruf:

curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mirelo-sfx-2.0",
    "input": {
      "prompt": "heavy wooden door creaking open slowly, old house ambience"
    }
  }'

Aufgeschlüsselt nach Teilen:

• -X POST – die Aufgabenerstellung ist eine Schreiboperation. Ein GET auf diesen Pfad startet keine Aufgabe.
• URL – dieser Endpunkt nimmt neue Generierungsaufgaben an. Die Basis-URL ist in HIAPI_BASE_URL gespeichert, sodass derselbe Befehl in jeder Umgebung funktioniert.
• Authorization – das Bearer-Token identifiziert Ihr Konto und ist die Grundlage für die Abrechnung. Ein fehlender oder falsch formatierter Header ist die häufigste Ursache für 401.
• Content-Type: application/json – der Body ist JSON; ohne diesen Header lehnt der Server die Nutzlast ab oder parst sie falsch.
• model – wählt mirelo-sfx-2.0. Da HiAPI anhand dieses Feldes routet, können Sie das Modell wechseln, ohne die URL zu ändern.
• input.prompt – die Textbeschreibung des Klangs. Konkrete, physische Beschreibungen (Material, Aktion, Umgebung) liefern bessere Ergebnisse als abstrakte Beschreibungen.

Eine erfolgreiche Übermittlung gibt kein Audio zurück. Sie gibt ein Aufgabenobjekt mit einem Bezeichner (in der Regel ein id-Feld) zurück, mit dem Sie den Status prüfen. Erfassen Sie diese ID aus der Antwort; sie ist Ihr Schlüssel, um später das WAV abzurufen.

Wenn Sie die Anfragestruktur bestätigen möchten, bevor Sie Code integrieren, führen Sie diesen exakten Befehl zuerst im Terminal aus. Sobald er funktioniert, ist die Übertragung nach Python reine Routine.

Derselbe Aufruf in Python

Die Python-Version behält dieselbe URL, dieselben Header und denselben Body – sie werden lediglich als Dictionaries und Client-Aufrufe ausgedrückt:

import os
import requests

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

def create_sfx_task(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/v1/tasks",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "mirelo-sfx-2.0",
            "input": {"prompt": prompt},
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["id"]

Die Unterschiede zur Shell-Version:

• Umgebungszugriff – os.environ ersetzt die Shell-Expansion, sodass der Schlüssel niemals im Quellcode erscheint.
• json= statt -d – requests serialisiert das Dictionary für Sie und setzt den Inhaltstyp. Sie können den manuellen Header weglassen, ihn aber auch behalten.
• raise_for_status() – wandelt Nicht-2xx-Antworten in Ausnahmen um; hier gehört die Fehlerbehandlung hin.
• timeout – ein Client-Timeout verhindert, dass hängende Verbindungen Ihren Worker blockieren. Die Aufgabenerstellung ist schnell; die lange Wartezeit entsteht beim Polling.

Der Rückgabewert ist die Aufgaben-ID. Speichern Sie sie – sie ist Ihr einziger Handle für diese Generierung. An diesem Punkt treffen Python- und curl-Pfad zusammen: Beide benötigen einen Polling-Schritt, bevor das Audio existiert.

Da der Body nur Daten enthält, können Sie den Prompt parametrisieren und eine Liste von Beschreibungen durchlaufen, um Soundeffekte in Stapeln zu erzeugen, wobei Sie für jeden Prompt eine Aufgabe erstellen und die IDs sammeln.

Umgang mit asynchronen Aufgaben und Polling der Ergebnisse

Die Klangerzeugung braucht Zeit – Sekunden, nicht Millisekunden – daher modelliert HiAPI sie als Aufgabe. Der Erstellungsaufruf gibt sofort eine ID zurück; ein zweiter Endpunkt meldet, ob die Aufgabe noch läuft, abgeschlossen oder fehlgeschlagen ist.

Die typische Schleife ist:

1. Aufgabe erstellen und ID erfassen.
2. Mit dieser ID den Aufgabenstatus-Endpunkt abfragen.
3. Wenn der Status noch in Bearbeitung ist, kurz warten und erneut abfragen.
4. Wenn der Status Erfolg meldet, die Ausgabe aus der Antwort lesen.
5. Wenn der Status Fehler meldet, abbrechen und einen Fehler auslösen.

In Python:

import time

def wait_for_task(task_id: str, timeout_s: int = 300) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/v1/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        status = task.get("status")
        if status == "succeeded":
            return task
        if status == "failed":
            raise RuntimeError(task.get("error", "task failed"))

        time.sleep(2)

    raise TimeoutError(f"task {task_id} did not finish in time")

Einige Punkte verdienen besondere Beachtung:

• Polling-Intervall. Zwei Sekunden sind ein sinnvoller Standard für Soundeffekte. Eine enge Schleife verschwendet Kontingent und kann Ratenlimits auslösen, ohne dass Ergebnisse schneller eintreffen.
• Gesamtfrist. Setzen Sie der Schleife immer eine Obergrenze. Eine hängende Aufgabe sollte Ihren Job fehlschlagen lassen, nicht den Worker für immer blockieren.
• Statuswerte. Behandeln Sie unbekannte Statuswerte als „noch in Bearbeitung“, statt Erfolg anzunehmen, und verzweigen Sie explizit auf Erfolgs- und Fehlerstatus.
• Webhooks (falls verfügbar). Wenn Ihr HiAPI-Konto Abschluss-Callbacks unterstützt, bevorzugen Sie diese im serverseitigen Produktionscode gegenüber Polling; für Skripte und Prototypen bleibt Polling die einfachste Option.

Speichern Sie die Aufgaben-ID zusammen mit dem Prompt in Ihrer eigenen Datenbank, damit Sie später erneut versuchen, prüfen oder Ausgaben abrufen können, ohne neu zu generieren.

Lesen der zurückgegebenen WAV-Antwort

Wenn eine Aufgabe Erfolg meldet, enthält die Antwort das erzeugte Audio. Je nach Endpunktversion kann die Ausgabe als WAV-Datei-URL oder als eingebettete Audiodaten erscheinen; behandeln Sie beide Fälle als „speicherbare Bytes“.

Ein erfolgreiches Aufgabenobjekt trägt die Ausgabe unter Feldern wie output, üblicherweise zusammen mit Metadaten wie Modellname, ursprünglichem Prompt und Zeitinformationen. Das Audio selbst ist ein standardmäßiger WAV-Container, was bedeutet, dass Sie es jeder Audio-Bibliothek übergeben können, ohne einen benutzerdefinierten Decoder zu benötigen.

So persistieren Sie ein URL-basiertes Ergebnis:

result = wait_for_task(task_id)
audio_url = result["output"]["audio_url"]

wav_bytes = requests.get(audio_url, timeout=60).content
with open(f"{task_id}.wav", "wb") as f:
    f.write(wav_bytes)

Wenn das Audio als dekodierte Daten ankommt, dekodieren Sie es vor dem Schreiben mit base64:

import base64

wav_bytes = base64.b64decode(result["output"]["audio_base64"])
with open(f"{task_id}.wav", "wb") as f:
    f.write(wav_bytes)

Sobald Sie die Bytes haben:

• Header validieren. WAV-Dateien beginnen mit dem RIFF-Magic. Die Prüfung der ersten vier Bytes fängt abgeschnittene Downloads ab, bevor sie im Speicher landen.
• Dauerhafte Speicherung. Schreiben Sie in den Objektspeicher und speichern Sie den Schlüssel zusammen mit der Aufgaben-ID in der Datenbank. Behandeln Sie erzeugtes Audio als cachebares Artefakt, nicht als temporäre Antwort.
• Abspielen oder verarbeiten. Standardwerkzeuge – wave, soundfile oder jeder Audioplayer – öffnen die Datei direkt. Anschließend können Sie Stille zuschneiden, die Lautheit normalisieren oder für die Auslieferung in andere Formate konvertieren.

Da die Datei ein gewöhnliches WAV ist, erfordert die Anbindung an einen Web-Endpunkt oder eine Asset-Pipeline einer Spiel-Engine keine besondere Behandlung.

Häufige Fehlerquellen und ihre Behebung

Die meisten Integrationsprobleme lassen sich in einige vorhersehbare Kategorien einordnen.

Authentifizierungsfehler (401 / 403)

401 bedeutet fast immer, dass der Authorization-Header fehlt, falsch formatiert ist oder aus einer leeren Umgebungsvariable gebaut wurde. Vergewissern Sie sich, dass HIAPI_API_KEY in der Shell exportiert ist, in der der Prozess läuft – nicht nur im Editor – und dass der Header als Bearer <key> mit genau einem Leerzeichen dazwischen gelesen wird. 403 bedeutet in der Regel, dass der Schlüssel gültig ist, aber keinen Zugriff auf das Modell hat; prüfen Sie die Modellberechtigungen Ihres Kontos.

Fehlerhafte Nutzlast (400 / 422)

Die häufigste Ursache ist ein Request-Body, der kein gültiges JSON ist – unpaarige Anführungszeichen im curl-Befehl sind ein typisches Beispiel. Validieren Sie vor dem Senden mit einem JSON-Prüfer. Die zweithäufigste Ursache ist ein fehlendes model-Feld oder eine falsch verschachtelte Prompt-Ebene; das Modell erwartet input.prompt, nicht ein prompt auf oberster Ebene. Prüfen Sie schließlich, dass der Prompt nicht leer ist und innerhalb der in der Modelldokumentation angegebenen Längengrenzen liegt.

Zu häufiges Polling

Eine enge while-Schleife ohne Sleep erzeugt eine Flut von Statusanfragen, kann Ratenlimits auslösen und die Aufgabe, auf die Sie warten, verlangsamen. Verwenden Sie ein festes Intervall von ein bis zwei Sekunden, fügen Sie Jitter hinzu, wenn Sie mehrere Jobs parallel ausführen, und erzwingen Sie stets eine maximale Wartezeit.

Erstellung als Abschluss missverstehen

Die Erstellungsantwort sieht wie ein Erfolg aus und gibt 200 zurück, enthält aber kein Audio. Wenn Ihr Code sofort das output-Feld liest, schlägt er fehl oder schreibt eine leere Datei. Durchlaufen Sie immer den Status-Endpunkt, bevor Sie auf Ergebnisse zugreifen.

Stille Timeouts und Wiederholungen

Wiederholungen bei Netzwerk-Timeouts während der Aufgabenerstellung sind sicher, aber ein erneuter Aufruf der Erstellung nach einem Timeout, bei dem die Aufgabe tatsächlich erfolgreich war, erzeugt doppelte Jobs. Verwenden Sie Idempotenzschlüssel, falls der Endpunkt sie unterstützt; andernfalls listen Sie vor einer Wiederholung die letzten Aufgaben auf, um dies abzugleichen.

Randfälle bei Disk und Speicher

Öffnen Sie die Datei beim Schreiben von WAV-Bytes im Binärmodus ("wb"). Der Textmodus beschädigt den Dateiheader. Wenn Sie Ausgaben nach Prompt-Namen speichern, überschreiben sich zwei Aufgaben mit demselben Prompt gegenseitig – verwenden Sie die Aufgaben-ID als Dateischlüssel.

Mit diesen Schutzmaßnahmen ist die mirelo-sfx-2.0-Integration eine kurze Pipeline: erstellen, pollen, persistieren. Beginnen Sie mit dem curl-Aufruf, portieren Sie nach Python und betrachten Sie die Aufgaben-ID als Ihre Single Source of Truth.