Come usare lyria-3-pro tramite l'API hiapi: curl, Python ed esempi di richiesta eseguibili

lyria-3-pro è un modello di generazione musicale disponibile tramite l'API hiapi: invia un prompt testuale e ottieni una traccia audio completa. Questa guida ti accompagna attraverso il flusso di richiesta che restituisce davvero un taskId, illustra lo schema di input completo (molto breve) e i dettagli di produzione di cui hai bisogno una volta superato il test occasionale.

Cosa ti serve

• Una chiave API hiapi. Disponibile dalla console: la chiave inizia con sk-.
• curl o requests di Python. Nessun SDK necessario; hiapi usa REST standard.

lyria-3-pro funziona sull'API unificata dei task asincroni di hiapi: esegui un POST di un task, ricevi immediatamente un taskId, quindi interroga il risultato o ricevi un callback quando la traccia è pronta.

Esempio minimo eseguibile

1. Crea il task

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

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

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

2. Interroga il risultato

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

Attendi qualche secondo prima della prima interrogazione, poi controlla ogni 3–5 secondi. Lo status attraversa stati intermedi come archiving e infine raggiunge uno stato terminale:

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

Scarica output[0].url il prima possibile: il livello di archiviazione predefinito temp scade dopo circa 7 giorni (expireAt è un timestamp Unix). In caso di errore, lo status è fail e data.error contiene { code, message } invece di output.

3. La stessa richiesta 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"])

Schema di input completo

input accetta esattamente due campi: qualsiasi altro contenuto al di fuori di questo elenco viene rifiutato con 400 INVALID_REQUEST:

Campo	Tipo	Obbligatorio	Descrizione
prompt	string	Sì	Descrive genere, strumentazione, atmosfera e tempo: più è specifico, più i risultati sono coerenti.
seed	integer	No	Valore minimo 0. Riutilizzando lo stesso seed con lo stesso prompt si ottengono risultati più riproducibili.

prompt è obbligatorio: se lo ometti, il task non viene nemmeno creato:

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

Inviando qualsiasi altro campo, come duration, negative_prompt, sample_count e campi simili accettati da altri modelli musicali, la richiesta viene rifiutata direttamente:

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

La durata della traccia di output è fissata dal modello stesso; non esiste un parametro duration per configurarla.

Considerazioni per la produzione

Il callback è preferibile al polling. Oltre ai test rapidi, passa un callback di primo livello invece di interrogare in un ciclo:

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

Quando il task raggiunge uno stato terminale (success o fail), hiapi invia un POST a callback.url: non è necessario mantenere attivo un ciclo di polling. Conserva comunque il polling come fallback, nel caso la consegna del callback fallisca.

Idempotenza. Se il chiamante potrebbe ripetere la stessa richiesta, invia l'header Idempotency-Key (massimo 255 byte): i tentativi ripetuti con la stessa chiave sullo stesso account restituiscono il taskId originale, senza creare (e fatturare) tracce duplicate.

Conserva l'output oltre 7 giorni. L'archiviazione dell'output è predefinita su temp (circa 7 giorni). Imposta "storage": "persistent" al momento della creazione per conservare la traccia a lungo termine (fatturato in base alla dimensione), oppure promuovi successivamente un output temp.

Gestione degli errori. Una chiave errata o non autorizzata restituisce HTTP 401:

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

Un input malformato restituisce 400 con error_code: INVALID_REQUEST (come mostrato sopra); saldo insufficiente restituisce 402; un Content-Type non JSON restituisce 415. In caso di 503 intermittenti, riprova con un backoff: indica che la piattaforma è temporaneamente non disponibile, non che la tua richiesta sia errata.

I prezzi di lyria-3-pro (e di tutti gli altri modelli della piattaforma) sono elencati nella pagina dei prezzi hiapi, non codificati qui, poiché le tariffe possono cambiare.

Risorse correlate

• Riferimento del modello lyria-3-pro: prezzi e playground per questo modello.
• Crea task / Ottieni dettagli task (API asincrona unificata): il contratto di richiesta/risposta condiviso da ogni modello su hiapi.
• API minimax-music-3: guida curl e Python: un altro modello text-to-music, utile per confrontare gli stili di output.
• Come usare l'API MiniMax Music (minimax-music-1.5): un modello di generazione musicale MiniMax precedente, adatto per confronti costo/qualità.

Domande frequenti

È possibile impostare la durata della traccia generata? No. Lo schema input di lyria-3-pro accetta solo prompt e seed: non esiste un campo duration, la durata della traccia è determinata dal modello stesso.

lyria-3-pro supporta prompt negativi o audio di riferimento per lo stile? No. A differenza di alcuni altri modelli della piattaforma, lo schema di lyria-3-pro è rigorosamente limitato a prompt e seed; inviare negative_prompt o qualsiasi campo di audio di riferimento restituisce 400 INVALID_REQUEST.

In che formato è il file di output? MP3, restituito in output[0].url, con type uguale a "audio". L'URL è un link temporaneo e scade secondo output[0].expireAt, a meno che non si imposti "storage": "persistent".

Come si ottengono risultati riproducibili? Usa lo stesso prompt e passa lo stesso seed (intero non negativo). Se ometti seed, ogni chiamata può produrre risultati diversi.

Qual è il modo più rapido per fare debug di una richiesta che restituisce sempre 400? Leggi il message: indica il campo specifico mancante o non valido. Lo schema è rigoroso: inviare campi non accettati da questo modello (ad esempio duration, che altri modelli musicali della piattaforma accettano davvero) restituisce 400 con l'errore "additional properties not allowed".