Tutorial

So verwendest du lyria-3-pro über die hiapi API: curl, Python und lauffähige Anfragebeispiele

Aug 25, 2026

lyria-3-pro ist ein Musikgenerierungsmodell, das über die hiapi API bereitgestellt wird: Sende eine Textaufforderung und erhalte einen vollständigen Track. Dieser Leitfaden führt dich durch den tatsächlichen Anfrageablauf, der eine taskId zurückgibt, erklärt das vollständige (sehr knappe) Eingabe-Schema und die Produktionsdetails, die du benötigst, sobald du dich von einmaligen Tests löst.

Was du vorbereiten musst

Einen hiapi API-Schlüssel. Erhältlich im Dashboard – der Schlüssel beginnt mit sk-.
curl oder Pythons requests. Kein SDK erforderlich; hiapi verwendet Standard-REST.

lyria-3-pro läuft auf der einheitlichen asynchronen Aufgaben-API von hiapi: Du POSTest eine Aufgabe, erhältst sofort eine taskId zurück und fragst dann das Ergebnis ab oder empfängst einen Callback, sobald der Track bereit ist.

Minimales lauffähiges Beispiel

1. Aufgabe 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-pro",
    "input": {
      "prompt": "Warm lo-fi piano loop with soft vinyl crackle, relaxed tempo, calm evening mood"
    }
  }'

Eine normale Antwort kehrt sofort zurück, bevor der Track tatsächlich fertig gerendert ist:

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

2. Ergebnis abfragen

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

Warte einige Sekunden vor der ersten Abfrage und prüfe danach alle 3–5 Sekunden. status durchläuft Zwischenzustände wie archiving und erreicht schließlich einen Endzustand:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M0T17T7RERV481QJC3DRZCRS",
    "model": "lyria-3-pro",
    "status": "success",
    "created": 1787580115,
    "completed": 1787580157,
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M0T17T7RERV481QJC3DRZCRS-0.mp3",
        "expireAt": 1788184956
      }
    ]
  }
}

Lade output[0].url so bald wie möglich herunter – die standardmäßige temp-Speicherebene läuft nach etwa 7 Tagen ab (expireAt ist ein Unix-Zeitstempel). Im Fehlerfall ist status gleich fail, und data.error enthält { code, message } statt output.

3. Dieselbe Anfrage in Python

import time
import requests

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

payload = {
    "model": "lyria-3-pro",
    "input": {
        "prompt": "Warm lo-fi piano loop with soft vinyl crackle, relaxed tempo, calm evening mood",
    },
}

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

while True:
    time.sleep(3)
    detail = requests.get(f"https://api.hiapi.ai/v1/tasks/{task_id}", headers=HEADERS).json()
    status = detail["data"]["status"]
    if status == "success":
        print(detail["data"]["output"][0]["url"])
        break
    if status == "fail":
        raise RuntimeError(detail["data"]["error"])

Vollständiges Eingabe-Schema

input akzeptiert genau zwei Felder – alles außerhalb dieser Liste wird mit 400 INVALID_REQUEST abgelehnt:

Feld	Typ	Erforderlich	Beschreibung
`prompt`	string	Ja	Beschreibt Genre, Instrumentierung, Stimmung und Tempo – je konkreter, desto konsistenter das Ergebnis.
`seed`	integer	Nein	Mindestwert `0`. Verwende denselben Seed mit demselben Prompt, um reproduzierbarere Ergebnisse zu erhalten.

prompt ist erforderlich – lässt du es weg, wird die Aufgabe gar nicht erst erstellt:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: prompt: missing required field \"prompt\""}

Sende irgendein anderes Feld – duration, negative_prompt, sample_count oder ähnliche Felder, die manche anderen Musikmodelle akzeptieren –, wird die Anfrage direkt abgelehnt:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'negative_prompt' not allowed"}

Die Dauer des Ausgabe-Tracks wird vom Modell selbst festgelegt; es gibt keinen duration-Parameter, um sie zu konfigurieren.

Hinweise für die Produktion

Callbacks statt Polling. Übergib außer bei schnellen Tests ein callback auf oberster Ebene, statt in einer Schleife zu pollen:

{
  "model": "lyria-3-pro",
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" },
  "input": { "prompt": "..." }
}

Wenn die Aufgabe einen Endzustand erreicht (success oder fail), sendet hiapi einmalig ein POST an callback.url – es ist nicht nötig, eine Polling-Schleife offen zu halten. Behalte das Polling dennoch als Fallback bei, falls die Callback-Zustellung fehlschlägt.

Idempotenz. Falls der Aufrufer dieselbe Anfrage wiederholen könnte, sende den Header Idempotency-Key (maximal 255 Byte) – Wiederholungen mit demselben Key im selben Konto geben die ursprüngliche taskId zurück, statt einen doppelten Track zu erstellen (und zu berechnen).

Ausgaben länger als 7 Tage aufbewahren. Der Ausgabespeicher ist standardmäßig temp (etwa 7 Tage). Setze bei der Erstellung "storage": "persistent" auf oberster Ebene, um den Track langfristig zu behalten (Abrechnung nach Größe), oder stufe temp-Ausgaben später hoch.

Fehlerbehandlung. Fehlerhafte oder nicht autorisierte Schlüssel geben HTTP 401 zurück:

{"error":{"code":"permission_denied","message":"This API key cannot use the selected model. Please check permissions or use another key.","type":"hiapi_error"}}

Fehlerhaft formatierte Eingaben geben 400 mit error_code: INVALID_REQUEST zurück (wie oben gezeigt); unzureichendes Guthaben gibt 402 zurück; ein Content-Type, der nicht JSON ist, gibt 415 zurück. Bei zeitweise auftretenden 503-Fehlern versuche es mit Backoff erneut – das bedeutet, dass die Plattform vorübergehend nicht verfügbar ist, nicht dass deine Anfrage fehlerhaft war.

Die Preise für lyria-3-pro (und alle anderen Modelle auf der Plattform) sind auf der hiapi-Preisseite aufgeführt und nicht hier fest hinterlegt, da sich die Tarife ändern können.

Häufige Fragen

Kann ich die Dauer des generierten Tracks festlegen? Nein. Das input-Schema von lyria-3-pro akzeptiert nur prompt und seed – es gibt kein duration-Feld, die Trackdauer bestimmt das Modell selbst.

Unterstützt lyria-3-pro negative Prompts oder Style-Referenzaudio? Nein. Anders als einige andere Modelle auf der Plattform ist das Schema von lyria-3-pro strikt auf prompt und seed beschränkt; das Senden von negative_prompt oder einem beliebigen Referenzaudio-Feld gibt 400 INVALID_REQUEST zurück.

In welchem Format liegen die Ausgabedateien vor? MP3, zurückgegeben als output[0].url mit type gleich "audio". Diese URL ist ein temporärer Link und läuft gemäß output[0].expireAt ab, sofern nicht "storage": "persistent" gesetzt ist.

Wie erhalte ich reproduzierbare Ergebnisse? Verwende denselben prompt und übergib denselben seed (nicht negative ganze Zahl). Ohne seed kann jeder Aufruf unterschiedliche Ergebnisse liefern.

Was ist der schnellste Weg, eine Anfrage zu debuggen, die ständig 400 zurückgibt? Lies die message – sie nennt das konkrete fehlende oder ungültige Feld. Das Schema ist streng: Felder zu senden, die dieses Modell nicht akzeptiert (etwa duration, das andere Musikmodelle auf der Plattform durchaus akzeptieren), gibt 400 mit dem Fehler "additional properties not allowed" zurück.