ElevenLabs Music API auf HiAPI: Musikgenerierung mit curl, Python und Prompt-Rezepten

Warum elevenlabs/music-v2.5 über HiAPI aufrufen

Wenn Sie Ihrer Anwendung Musikgenerierung hinzufügen möchten, ist der schnellste Weg oft nicht der sauberste. Das Backend direkt an einen Modellanbieter anzubinden bedeutet, dass Sie selbst für Konto-Einrichtung, Authentifizierungsschema, Retry-Semantik und Anfragestruktur dieses Anbieters verantwortlich sind. Jedes neue Modell bringt eine weitere Gruppe solcher Entscheidungen mit sich, und jedes Experiment hinterlässt einen Integrationszweig.

Der Aufruf von elevenlabs/music-v2.5 über HiAPI verändert die Form dieser Arbeit. Sie benötigen nur eine Basis-URL, einen Authentifizierungs-Header und eine Anfragekonvention, die beim Wechsel zwischen Modellen stabil bleibt. Der Modellbezeichner (elevenlabs/music-v2.5) ist lediglich ein String im Request-Body, sodass der Wechsel zwischen Musikmodellen oder ein Vergleich mit einem zweiten Modell nur eine Zeile ändert, statt ein neues SDK zu importieren.

Für Entwickler, die den Integrationsweg wählen, sind drei praktische Vorteile erwähnenswert:

• Einheitliche Credential-Verwaltung. Schlüsselverwaltung, Rotation und Umgebungstrennung (Entwicklung/Staging/Produktion) sind an einer Stelle zentralisiert, statt sich pro Anbieter zu vervielfachen.
• Portables Anfragemuster. Die folgenden curl- und Python-Snippets stimmen mit dem überein, was Sie bei anderen Modellen auf HiAPI verwenden. Einmal das Muster lernen reicht.
• Nutzung an einer Stelle gebündelt. Musikgenerierung wird nach Ausgabelänge abgerechnet; sie zusammen mit der Nutzung anderer Modelle zu erfassen bedeutet, Kosten in einem einzigen Dashboard zu verfolgen, statt verstreute Rechnungen zu haben.

Der Preis dafür ist, dass Sie eine Abstraktionsschicht durchlaufen, sodass anbieterspezifische Eigenheiten normalisiert werden. Für Erstintegrationen und die meisten Produktionsfälle ist diese Normalisierung genau das, was Sie wollen. Wenn Sie das konkrete Verhalten des Modells verstehen müssen, ist die Detailseite auf der Website die maßgebliche Quelle.

Vorbereitung vor der ersten Musik-Anfrage

Bestätigen Sie vier Dinge, bevor Sie Code schreiben, damit der erste Aufruf Audio zurückgibt und nicht einen 401- oder Validierungsfehler.

1. API-Schlüssel

Sie benötigen einen API-Schlüssel aus Ihrem HiAPI-Konto. Behandeln Sie ihn wie jeden anderen Schlüssel: in einer Umgebungsvariable speichern, niemals in den Quellcode committen und für lokale Entwicklung und Produktion unterschiedliche Schlüssel verwenden, damit Sie einen widerrufen können, ohne den anderen zu beeinträchtigen.

export HIAPI_API_KEY="your_key_here"

2. Basis-URL und Endpoint-Konvention

Alle Modellaufrufe verwenden dieselbe Basis-URL; das Modell wird innerhalb der Anfrage identifiziert, nicht im Pfad. Halten Sie eine Konstante für die Basis-URL im Projekt, damit Sie bei abweichender Umgebung nur eine Stelle ändern müssen.

3. Ein in natürlicher Sprache geschriebener Prompt

elevenlabs/music-v2.5 akzeptiert einen Text-Prompt, der die gewünschte Musik beschreibt. Sie brauchen keine Partitur und keine MIDI-Datei. Ein bis zwei Sätze zu Genre, Instrumentierung, Stimmung und erwarteter Länge reichen für den Anfang. Die folgenden Abschnitte liefern wiederverwendbare Rezepte.

4. Korrekte Erwartungen an die Ausgabe

Musikgenerierung liefert Audio zurück, keine JSON-Partitur. Planen Sie, wie Sie die Antwort-Payload verarbeiten: während der Entwicklung in eine Datei schreiben, in der Produktion streamen oder speichern. Legen Sie vorab fest, wie lang das Stück ungefähr sein soll, denn die Länge beeinflusst sowohl die Anfrage als auch die Abrechnung.

Eine weitere Sache vor der ersten Anfrage: Prüfen Sie im Preisbereich der Website die aktuellen Ratenlimits und Preise für elevenlabs/music-v2.5, statt Annahmen fest in den Code zu schreiben. Preise und Limits ändern sich; Ihre Integration sollte sie als Konfiguration lesen, nicht als in Skripte eingebettete Konstanten.

Der erste Aufruf mit curl

Beginnen Sie mit curl, weil es jede Schicht zwischen Ihnen und der HTTP-Anfrage entfernt. Wenn der curl-Aufruf funktioniert, ist jeder Fehler in Ihrer Anwendung ein Problem Ihrer Anwendung, nicht der API.

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/music-v2.5",
    "messages": [
      {
        "role": "user",
        "content": "Instrumental lo-fi hip hop, warm vinyl texture, mellow electric piano, soft brushed drums, 80 BPM, relaxed late-night mood, about 30 seconds."
      }
    ]
  }'

Die einzelnen Teile bewirken Folgendes:

• -sS hält die Fortschrittsausgabe still, zeigt aber weiterhin Fehler an. Nützlich, wenn Sie die Ausgabe in eine Datei umleiten.
• Die URL ist der einheitliche Endpoint. Beachten Sie, dass der Modellname nicht im Pfad, sondern im Request-Body erscheint.
• Authorization: Bearer $HIAPI_API_KEY liest den Schlüssel aus der Umgebung, sodass er nicht im Klartext in der Shell-Historie bleibt. Unter Windows setzen Sie die Variable entsprechend mit set oder der PowerShell-Syntax $env:.
• Content-Type: application/json ist erforderlich; dieser Endpoint akzeptiert keine Formular-Kodierung.
• model ist der exakte Bezeichner elevenlabs/music-v2.5. Ein Tippfehler hier erzeugt einen Modell-nicht-gefunden-Fehler statt eines allgemeinen Fehlers, was beim Debuggen hilft.
• messages übergibt Ihren Prompt als Inhalt der Benutzernachricht. Legen Sie den Prompt in eine Nachricht; lange, strukturierte Prompts funktionieren besser als über mehrere Nachrichten verteilte.

Der Response-Body enthält das generierte Audio sowie Metadaten zur Anfrage. Leiten Sie während der Entwicklung die Ausgabe in eine Datei um, damit Sie das Ergebnis sofort anhören können:

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json -o response.json

Die Payload in request.json zu legen und mit -d @request.json zu lesen, ist eine Angewohnheit, die Sie sich früh zulegen sollten. Sie macht Anfragen vergleichbar, überprüfbar und leicht wiederholbar, wenn Sie jeweils nur einen Parameter ändern.

Den Aufruf in Python wiederholen

Sobald der curl-Aufruf Audio zurückgibt, portieren Sie ihn nach Python. Das Ziel ist nicht nur ein lauffähiges Skript, sondern eine Funktion, die aus einer Task-Queue, einem API-Handler oder einem Notebook aufgerufen werden kann, ohne dass Copy-Paste-Abweichungen entstehen.

import json
import os
import urllib.request

BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
MODEL = "elevenlabs/music-v2.5"

def generate_music(prompt: str, timeout: int = 120) -> dict:
    """Sendet einen Musik-Prompt über HiAPI an elevenlabs/music-v2.5."""
    api_key = os.environ.get("HIAPI_API_KEY")
    if not api_key:
        raise RuntimeError("HIAPI_API_KEY is not set")

    payload = {
        "model": MODEL,
        "messages": [{"role": "user", "content": prompt}],
    }

    request = urllib.request.Request(
        BASE_URL,
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request, timeout=timeout) as response:
        return json.loads(response.read().decode("utf-8"))

if __name__ == "__main__":
    result = generate_music(
        "Cinematic orchestral swell, strings and low brass, hopeful build, "
        "no percussion, about 20 seconds."
    )
    print(json.dumps(result, indent=2)[:500])

Wenn die Funktion wächst, lohnt es sich, einige Entscheidungen beizubehalten:

• Standardbibliothek bevorzugen. urllib vermeidet Abhängigkeitsänderungen im Tutorial. Wenn Ihr Projekt bereits requests oder httpx nutzt, ist die Umstellung mechanisch: übergeben Sie json=payload, headers=headers und timeout.
• Timeouts sind Pflicht. Musikgenerierung dauert länger als Chat-Completions. Setzen Sie explizite Timeouts und verlassen Sie sich nicht auf Standardwerte. Wählen Sie einen Wert, der länger ist als die erwartete Generierungszeit Ihres längsten angeforderten Stücks.
• Den Schlüssel zum Aufrufzeitpunkt lesen, nicht beim Import, damit dasselbe Modul lokal und in Containern funktioniert, in denen die Umgebung zur Laufzeit injiziert wird.
• Strukturierte Daten zurückgeben, statt Strings zu drucken. Der Aufrufer entscheidet, ob Audio auf die Festplatte geschrieben, in Objektspeicher hochgeladen oder an den Client weitergeleitet wird.

Bestätigen Sie, bevor Sie irgendetwas darauf aufbauen, dass die Python-Funktion und der curl-Aufruf für denselben Prompt äquivalente Ergebnisse liefern. Diese Konsistenz ist Ihre Regressionsbasis.

Prompt-Rezepte für Stil, Stimmung und Länge

Musik-Prompts funktionieren am besten, wenn sie drei Fragen in Reihenfolge beantworten: welches Genre und welche Instrumentierung, welche emotionale Tonalität, wie lang. Vage Prompts erzeugen generische Ausgaben; überlange Prompts verwässern die wichtigen Deskriptoren. Ziel ist ein dichter Satz oder drei kurze Teilsätze.

Verwenden Sie diese als direkt kopierbare Ausgangspunkte und ändern Sie jeweils nur eine Dimension.

Stilzentrierte Rezepte

• Solo piano, felt hammers, close-miked, slow arpeggios in the style of a modern film score.
• Upbeat synthwave, analog bass, gated reverb drums, arpeggiated lead, 120 BPM.
• Acoustic folk ensemble, fingerpicked guitar, upright bass, light tambourine, organic room sound.
• Ambient drone, layered pads, no rhythm section, slowly evolving texture.

Stimmungszentrierte Rezepte

• Warm and nostalgic, like a summer evening, major key, gentle dynamics.
• Tense and minimal, low pulsing bass, sparse percussion, unresolved harmony.
• Playful and bright, staccato strings, bouncy rhythm, light-hearted.
• Melancholic and spacious, reverb-heavy, sparse piano, slow tempo.

Längenzentrierte Rezepte

Die Länge sollte als klares Ziel im Prompt stehen und mit dem Arrangement übereinstimmen. Eine 15-Sekunden-Anfrage mit langsamem Aufbau und langem Ausklang wird hart abgeschnitten.

• ... about 15 seconds, short intro, no outro, ends cleanly.
• ... about 30 seconds, one clear section, loopable ending.
• ... about 60 seconds, intro, main section, and a natural fade.

Kombiniertes Beispiel

Lo-fi hip hop for focus, dusty vinyl crackle, soft electric piano, brushed drums, 80 BPM, calm and unhurried, about 30 seconds, loopable.

Wenn die Ausgabe nicht den Erwartungen entspricht

Ändern Sie pro Versuch nur eine Variable, damit Sie erkennen, was das Ergebnis tatsächlich verändert hat.

• Zu generisch: Ersetzen Sie Stimmungswörter durch konkrete Instrumentierung und Tempo. „Energetic“ ist schwächer als „driving 16th-note bass at 128 BPM“.
• Zu geschäftig oder unübersichtlich: Entfernen Sie Instrumente explizit (no drums, no vocals, sparse arrangement), statt weitere positive Deskriptoren hinzuzufügen.
• Länge fühlt sich falsch an: Wenn das Stück abrupt endet, fordern Sie ein kürzeres Ziel und ein klares Ende an; wenn es sich gehetzt anfühlt, reduzieren Sie die Anzahl der angeforderten Abschnitte.
• Stildrift: Verschieben Sie Genre und Instrumentierung an den Anfang des Prompts. Frühere Tokens haben mehr Gewicht.

Halten Sie eine kleine Prompt-Datei im Repository, die funktionierende Rezepte dokumentiert. Diese Datei ist wertvoller als jedes einzelne generierte Stück, weil sie das Schreiben von Prompts zu einem reproduzierbaren Engineering-Artefakt macht.

Häufige Fehler und ihre Behebung

Die meisten Erstintegrationen scheitern auf wenige vorhersehbare Arten. Gehen Sie diese Checkliste durch, bevor Sie zu raten beginnen.

Authentifizierungsfehler

401 bedeutet fast immer einen falsch formatierten Header oder einen fehlenden Schlüssel in der Prozessumgebung. Prüfen Sie auf überflüssige Leerzeichen nach Bearer, ob der Schlüssel aus der falschen .env-Datei geladen wurde oder ob das export in einer anderen Session als das Skript ausgeführt wurde. Geben Sie die Schlüssellänge aus (nicht den Schlüssel selbst), um zu bestätigen, dass er befüllt ist.

Modellbezeichner stimmt nicht

Modell-nicht-gefunden- oder Validierungsfehler bedeuten meist, dass der model-String keine exakte Übereinstimmung ist. elevenlabs/music-v2.5 ist groß-/kleinschreibungssensitiv und enthält einen Schrägstrich. Wenn Sie ihn aus einem Chat-Fenster kopiert haben, prüfen Sie auf typografische Anführungszeichen oder Zeilenumbruchreste.

Fehlerhaft formatierter Request-Body

Wenn curl funktioniert, Python aber nicht, liegt der Unterschied fast immer in der Serialisierung. Ein Python-Dict direkt dort zu übergeben, wo ein JSON-String erwartet wird, doppelte Kodierung mit json.dumps oder ein fehlender Content-Type: application/json erzeugen serverseitige Parse-Fehler, die nichts mit der eigentlichen Ursache zu tun zu haben scheinen. Protokollieren Sie den exakten Request-Body, den Ihr Code sendet, und vergleichen Sie ihn zeichenweise mit der funktionierenden curl-Payload.

Timeouts bei längeren Stücken

Längere Längen erfordern längere Generierungszeiten. Ein Client-Timeout, das für Chat-Anfragen passt, schneidet längere Musik-Anfragen ab. Erhöhen Sie das Timeout gezielt für diesen Endpoint und fügen Sie Retries mit Backoff nur bei Verbindungsfehlern hinzu; wiederholen Sie niemals blind eine Anfrage, die möglicherweise bereits Ausgabe erzeugt und abgerechnet wurde.

Prompt-Länge und -Inhalt

Extrem lange Prompts oder Prompts mit Anweisungen zur API selbst erzeugen oft schlechtere Musik. Lassen Sie den Prompt nur von Musik handeln. Wenn ein Prompt, der gestern funktioniert hat, nicht mehr funktioniert, reduzieren Sie ihn auf das Gerüst Stil/Stimmung/Länge und bauen Sie ihn dann wieder auf.

Die Antwort als Text behandeln

Dieser Endpoint gibt Audiodaten zurück, keinen lesbaren Transkriptionstext. Den rohen Response-Body in eine .txt-Datei zu schreiben und sich dann zu wundern, warum er nicht abspielbar ist, ist ein häufiger Fehler am ersten Tag. Speichern Sie mit der richtigen Audio-Endung und prüfen Sie, ob die Datei in einem Player geöffnet werden kann, bevor Sie weiter bauen.

Wenn ein Fehler wirklich unklar ist, reproduzieren Sie ihn mit der kleinstmöglichen curl-Anfrage. So lässt sich isolieren, ob das Problem im API-Vertrag oder in Ihrem Code liegt.

Vom Testaufruf zum reproduzierbaren Workflow

Ein erfolgreicher Testaufruf ist der Ausgangspunkt, nicht die Integration. Nutzen Sie diese Checkliste, um daraus etwas zu machen, worauf sich das Team verlassen kann.

• Konfiguration externalisieren. Basis-URL, Modellbezeichner, Timeouts und Standard-Längenziele gehören in die Konfiguration, nicht in verstreute String-Literale. Umgebungsspezifische Werte kommen aus der Umgebung.
• Client zentralisieren. Eine Funktion oder eine leichte Client-Klasse ist für die Anfrage verantwortlich. Kein Modul sollte selbstständig HTTP-Aufrufe an den Musik-Endpoint bauen, sonst gehen Header und Fehlerbehandlung auseinander.
• Fehler nach Kategorie behandeln. Unterscheiden Sie Authentifizierung, Validierung, Timeout und Serverfehler. Wiederholen Sie nur transiente Fehler, mit Backoff und Obergrenze. Wiederholen Sie niemals Anfragen, die möglicherweise bereits Ausgabe erzeugt und abgerechnet wurden.
• Audio korrekt speichern. Schreiben Sie in Objektspeicher mit deterministischen Schlüsseln, legen Sie den Prompt zum generierten Asset und protokollieren Sie den Modellbezeichner. Das spätere Reproduzieren von Ergebnissen hängt davon ab, genau zu wissen, was damals angefordert wurde.
• Länge als erstklassigen Parameter verfolgen. Da die Abrechnung der Ausgabelänge folgt, machen Sie das Ziellänge in Prompt-Templates explizit und protokollieren Sie sie pro Anfrage, damit Kostenberichte mit der Nutzung übereinstimmen.
• Prompt-Bibliothek aufbauen. Nehmen Sie validierte Rezepte in die Versionskontrolle auf und notieren Sie kurz den Zweck jedes Rezepts. Neue Teammitglieder starten mit funktionierenden Prompts statt mit Raten.
• Synchronen und asynchronen Pfad trennen. Generierung kann langsam sein. Bei benutzergerichteten Funktionen: Job einreichen, Anfrage persistieren und einen Worker das Modell aufrufen lassen. Der HTTP-Handler sollte nicht während der gesamten Generierung offen bleiben.
• Mit einem Smoke-Test verifizieren. Ein Test, der einen festen kurzen Prompt sendet und prüft, dass das Audio-Response-Format korrekt ist, erkennt Credential- und Vertragsdrift frühzeitig.

Wenn Sie bereit sind, tiefer in Parameter und Limits einzusteigen, ist die Modellseite von elevenlabs/music-v2.5 auf HiAPI der Ort, an dem Sie die aktuellen Fähigkeiten prüfen, bevor Sie Annahmen fest verdrahten.