Come usare lyria-3.5 tramite l'API hiapi: curl, Python e una richiesta funzionante

lyria-3.5 è il modello di generazione musicale da testo di hiapi: invia una descrizione musicale, un testo o entrambi e ottieni una traccia completa—con titolo, guida al ritmo e controllo della durata opzionali. Questa guida spiega in dettaglio lo schema di input, una richiesta che restituisce una traccia reale e i dettagli necessari per passare dal test una tantum alla produzione.

Cosa ti serve

• Una chiave API hiapi. Ottienila dalla dashboard—la chiave inizia con sk-.
• curl o requests di Python. Nessun SDK necessario; hiapi usa puro REST.

lyria-3.5 funziona sull'API unificata per attività asincrone di hiapi: invii un'attività con POST, ricevi immediatamente un taskId, poi esegui il polling del risultato o ricevi una callback quando la traccia è pronta.

Schema di input completo

lyria-3.5 accetta molto più di un semplice prompt. A parte il fatto che devi fornire almeno uno tra prompt e lyrics, tutti gli altri campi sono opzionali:

Campo	Tipo	Descrizione
prompt	string	Genere, strumenti, atmosfera, voce, struttura del brano. Fornisci prompt o lyrics.
lyrics	string	Una frase per riga. Le etichette di sezione—[Intro], [Verse], [Chorus], [Bridge], [Outro]—vanno su una riga ciascuna, seguite dal testo. Per le strofe ripetute usa [Verse 1], [Verse 2].
title	string	Titolo del brano generato.
bpm	string	Guida al ritmo, deve essere una stringa numerica, ad esempio "90".
length	integer	Durata richiesta in secondi, 1–240. Serve a orientare la lunghezza; la durata effettiva può variare. Se omesso, non viene specificata.
seed	string	Seed come stringa numerica, ad esempio "00123". Anche con lo stesso seed non è garantito ottenere un audio identico.

Due avvertenze preliminari: bpm e seed sono stringhe, non numeri—invia "90", non 90, altrimenti l'API restituisce 400 (got number, want string). Inoltre lo schema è rigoroso: qualsiasi campo non presente nella tabella sopra (duration, style, genre, negative_prompt, ecc.) restituisce 400 con additional properties '...' not allowed.

Esempio minimo funzionante

1. Crea l'attività

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
    }
  }'

Una risposta normale viene restituita immediatamente, prima che la traccia sia effettivamente renderizzata:

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

2. Esegui il polling del risultato

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

Attendi qualche secondo prima del primo polling, poi controlla ogni 3–5 secondi. status passerà prima da handling e poi allo stato finale. Ecco la risposta reale della richiesta sopra dopo circa 100 secondi:

{
  "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
      }
    ]
  }
}

Nota che il formato contenitore dell'output può variare da richiesta a richiesta (qui .m4a; altri modelli musicali su hiapi restituiscono .mp3)—leggi output[0].type/URL invece di codificare l'estensione. Scarica output[0].url in tempo: il livello di archiviazione predefinito temp scade dopo circa 7 giorni (expireAt è un timestamp Unix). In caso di errore, status è fail e data.error contiene { code, message } al posto di output.

3. Invia una richiesta guidata dai lyrics con 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.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"])

A seconda che tu voglia una traccia strumentale o vocale, sostituisci lyrics con prompt (o invia entrambi).

Note per la produzione

• Usa le callback invece del polling. Aggiungi un oggetto callback di primo livello: {"url": "https://yourapp.com/hook", "when": "final"}. when accetta solo "final"—ricevi una chiamata quando l'attività raggiunge lo stato finale, non aggiornamenti di avanzamento.
• Idempotenza. L'API delle attività non accetta chiavi di idempotenza fornite dal client, quindi previeni i problemi di retry a livello applicativo: salva subito il taskId ricevuto e controlla lo stato dell'attività prima di riprovare, per evitare richieste duplicate.
• Errori. Una chiave API mancante o non valida restituisce HTTP 401 e error_code: "permission_denied". Una violazione dello schema restituisce HTTP 400 e error_code: "INVALID_REQUEST", con il messaggio che indica il campo problematico—utile per individuare un duration di troppo o un bpm numerico prima della produzione.
• Archiviazione. Dopo un polling riuscito o una callback, trasferisci subito output[0].url nel tuo archivio; non fare affidamento sul livello temp oltre il suo expireAt.

Letture correlate

• Tutorial dell'API lyria-3-pro—un altro modello Lyria di hiapi; se non ti servono lyrics o controllo del ritmo, il suo schema è più semplice e richiede solo un prompt.
• Guida all'API MiniMax Music—un altro modello di generazione musicale da testo su hiapi, con il proprio set di opzioni per lyrics e campionamento.
• Riferimento del modello lyria-3.5—la documentazione autorevole dei parametri.
• Prezzi di hiapi—le tariffe attuali per ciascun modello.

FAQ

Devo inviare sia prompt sia lyrics?No—l'API richiede solo almeno uno dei due. Inviando solo prompt ottieni una traccia strumentale, solo lyrics una traccia completamente guidata dai lyrics, oppure inviali entrambi.

Quale formato audio restituisce lyria-3.5?Varia da richiesta a richiesta—controlla output[0].type e l'estensione dell'URL, non dare per scontato .mp3 o .m4a.

Posso forzare un ritmo preciso?bpm è indicativo, non un vincolo rigido, e deve essere inviato come stringa ("90", non 90).

Quanto può essere lunga la traccia generata?length accetta da 1 a 240 secondi, ma serve solo a orientare il modello e non garantisce la durata esatta—controlla la durata effettiva del file restituito.

Lo stesso seed mi dà due volte la stessa traccia?No. seed è una stringa numerica che serve a regolare finemente la generazione, ma la documentazione di hiapi afferma esplicitamente che l'audio non è garantito identico.

Cosa succede se invio un campo non riconosciuto, come genre o duration?Lo schema è rigoroso—ricevi un 400 con additional properties '<field>' not allowed, invece di vedere il campo ignorato silenziosamente.