So verwendest du lyria-3.5 über die hiapi API: curl, Python und eine funktionierende Anfrage

lyria-3.5 ist hiapis Text-zu-Musik-Modell: Sende eine Musikbeschreibung, Liedtexte oder beides und erhalte einen fertigen Track – optional mit Titel, Tempo-Vorgabe und Längensteuerung. Dieser Leitfaden erklärt das vollständige Eingabe-Schema, eine Anfrage, die einen echten Track zurückgibt, und alle Details, die du für den Produktivbetrieb nach einem einmaligen Test benötigst.

Was du vorbereiten musst

• Einen hiapi API-Key. Erhältlich im Dashboard – der Key beginnt mit sk-.
• curl oder Pythons requests. Kein SDK erforderlich; hiapi nutzt reines REST.

lyria-3.5 läuft auf hiapis einheitlicher asynchroner Task-API: Du reichst einen Task per POST ein, erhältst sofort eine taskId und fragst dann das Ergebnis ab oder empfängst einen Callback, sobald der Track fertig ist.

Das vollständige Eingabe-Schema

lyria-3.5 akzeptiert weit mehr als nur einen nackten Prompt. Abgesehen davon, dass du mindestens eines von prompt oder lyrics angeben musst, sind alle Felder optional:

Feld	Typ	Beschreibung
prompt	string	Genre, Instrumente, Stimmung, Gesang, Songstruktur. Gib prompt oder lyrics an.
lyrics	string	Eine Zeile pro Zeile. Abschnitts-Tags – [Intro], [Verse], [Chorus], [Bridge], [Outro] – stehen jeweils auf einer eigenen Zeile, gefolgt von den Liedtexten. Wiederholte Abschnitte werden mit [Verse 1], [Verse 2] nummeriert.
title	string	Titel des generierten Songs.
bpm	string	Tempo-Vorgabe, muss ein numerischer String sein, z. B. "90".
length	integer	Gewünschte Dauer in Sekunden, 1–240. Dient als Längenvorgabe; die tatsächliche Dauer kann abweichen. Wenn weggelassen, wird nichts vorgegeben.
seed	string	Numerischer String als Seed, z. B. "00123". Selbst mit demselben Seed ist keine identische Audioausgabe garantiert.

Zwei Dinge vorab: bpm und seed sind Strings, keine Zahlen – sende "90", nicht 90, sonst gibt die API einen 400-Fehler zurück (got number, want string). Außerdem ist das Schema strikt: Jedes Feld, das nicht in der Tabelle steht (duration, style, genre, negative_prompt usw.), führt zu einem 400-Fehler mit additional properties '...' not allowed.

Minimales funktionierendes Beispiel

1. Task erstellen

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "lyria-3.5",
    "input": {
      "prompt": "Warm instrumental indie folk, fingerpicked acoustic guitar, soft brushed drums, quiet morning",
      "bpm": "90",
      "length": 30
    }
  }'

Eine erfolgreiche Antwort kommt sofort zurück, noch bevor der Track tatsächlich gerendert ist:

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

2. Ergebnis abfragen

curl "https://api.hiapi.ai/v1/tasks/tk-hiapi-01M2HCSKAP77MTH1ANKQXE1DT2" \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

Warte vor der ersten Abfrage einige Sekunden und prüfe danach alle 3–5 Sekunden. status durchläuft zunächst handling und geht dann in einen Endzustand über. Hier ist die tatsächliche Antwort auf die obige Anfrage etwa 100 Sekunden später:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M2HCSKAP77MTH1ANKQXE1DT2",
    "model": "lyria-3.5",
    "status": "success",
    "created": 1789437730,
    "completed": 1789437829,
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M2HCSKAP77MTH1ANKQXE1DT2-0.m4a",
        "expireAt": 1790042629
      }
    ]
  }
}

Beachte, dass das Ausgabe-Containerformat je nach Anfrage variieren kann (hier .m4a; andere Musikmodelle auf hiapi liefern .mp3) – lies output[0].type/URL aus, statt die Dateiendung fest zu verdrahten. Lade output[0].url rechtzeitig herunter: Die standardmäßige temp-Speicherebene läuft nach etwa 7 Tagen ab (expireAt ist ein Unix-Zeitstempel). Im Fehlerfall ist status fail und data.error enthält { code, message } statt output.

3. Eine textbasierte Anfrage mit Python senden

import time
import requests

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

payload = {
    "model": "lyria-3.5",
    "input": {
        "title": "Carry the Morning",
        "lyrics": (
            "[Verse 1]\n"
            "Light through the window, coffee still warm\n"
            "[Chorus]\n"
            "Carry the morning, carry it slow\n"
        ),
        "bpm": "96",
        "length": 45,
    },
}

create = requests.post("https://api.hiapi.ai/v1/tasks", headers=HEADERS, json=payload)
task_id = create.json()["data"]["taskId"]

status = None
while status not in ("success", "fail"):
    time.sleep(4)
    poll = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS).json()
    status = poll["data"]["status"]

if status == "success":
    print(poll["data"]["output"][0]["url"])
else:
    print(poll["data"]["error"])

Je nachdem, ob du reine Instrumentalmusik oder einen Gesangstrack möchtest, ersetze lyrics durch prompt (oder sende beides).

Hinweise für den Produktivbetrieb

• Callbacks statt Polling. Ergänze ein callback-Objekt auf oberster Ebene: {"url": "https://yourapp.com/hook", "when": "final"}. when akzeptiert nur "final" – du erhältst einen Aufruf, wenn der Task einen Endzustand erreicht, nicht bei Fortschrittsupdates.
• Idempotenz. Die Task-API akzeptiert keinen vom Client bereitgestellten Idempotenz-Key, daher musst du Wiederholungsprobleme auf Anwendungsebene verhindern: Speichere die taskId sofort nach Erhalt und prüfe den Task-Status vor einem erneuten Versuch, um doppelte Anfragen zu vermeiden.
• Fehler. Ein fehlender oder ungültiger API-Key führt zu HTTP 401 und error_code: "permission_denied". Ein Verstoß gegen das Schema führt zu HTTP 400 und error_code: "INVALID_REQUEST", wobei die Meldung das betroffene Feld benennt – das hilft, überflüssige duration oder einen numerischen bpm vor dem Produktivgang zu erkennen.
• Speicherung. Nach erfolgreichem Polling oder Callback übertrage output[0].url sofort in deinen eigenen Speicher; verlasse dich nicht über expireAt hinaus auf die temp-Ebene.

Weiterführende Lektüre

• lyria-3-pro API-Tutorial – ein weiteres Lyria-Modell auf hiapi; wenn du keine Liedtexte oder Tempo-Steuerung benötigst, ist sein Schema einfacher und braucht nur einen Prompt.
• MiniMax Music API-Leitfaden – ein weiteres Text-zu-Musik-Modell auf hiapi mit eigenen Optionen für Liedtexte und Sampling.
• lyria-3.5 Modellreferenz – die maßgebliche Parameterdokumentation.
• hiapi Preise – aktuelle Tarife der einzelnen Modelle.

FAQ

Muss ich prompt und lyrics gleichzeitig senden?Nein – die API verlangt nur, dass mindestens eines von beiden bereitgestellt wird. Nur prompt ergibt einen rein instrumentalen Track, nur lyrics ergibt einen vollständig durch den Text gesteuerten Track, oder sende beides zusammen.

Welches Audioformat gibt lyria-3.5 zurück?Das variiert je nach Anfrage – prüfe output[0].type und die Dateiendung der URL, gehe nicht von .mp3 oder .m4a aus.

Kann ich ein exaktes Tempo erzwingen?bpm ist eine Vorgabe, keine harte Beschränkung, und muss als String gesendet werden ("90", nicht 90).

Wie lang können die generierten Tracks sein?length akzeptiert 1–240 Sekunden, lenkt das Modell aber nur, statt eine exakte Dauer zu garantieren – prüfe die tatsächliche Laufzeit der zurückgegebenen Datei.

Bekomme ich mit demselben seed zweimal denselben Track?Nein. seed ist ein numerischer String, der die Generierung feinjustiert, aber die hiapi-Dokumentation stellt ausdrücklich klar, dass keine identische Audioausgabe garantiert wird.

Was passiert, wenn ich ein nicht erkanntes Feld wie genre oder duration sende?Das Schema ist strikt – du erhältst einen 400-Fehler mit additional properties '<field>' not allowed, statt dass das Feld stillschweigend ignoriert wird.