API ElevenLabs Music su HiAPI: generare musica con curl, Python e ricette di prompt

Perché chiamare elevenlabs/music-v2.5 tramite HiAPI

Se devi aggiungere la generazione musicale a un prodotto, il percorso più veloce spesso non è quello più pulito. Collegare il backend direttamente al fornitore del modello significa doverti occupare personalmente della configurazione dell'account del fornitore, dello schema di autenticazione, della semantica dei retry e della struttura delle richieste. Ogni nuovo modello adottato aggiunge un altro insieme di queste decisioni, e ogni esperimento lascia un ramo di integrazione.

Chiamare elevenlabs/music-v2.5 tramite HiAPI cambia la forma di questo lavoro. Ti servono solo un URL di base, un header di autenticazione e una convenzione di richiesta che resta stabile quando passi da un modello all'altro. L'identificatore del modello (elevenlabs/music-v2.5) è solo una stringa nel corpo della richiesta, quindi passare da un modello musicale all'altro, o provarne un secondo per confronto, richiede una sola riga di modifica invece di importare un nuovo SDK.

Per gli sviluppatori che scelgono come integrarsi, ci sono tre vantaggi concreti da considerare:

• Un'unica superficie di gestione delle credenziali. La gestione delle chiavi, la rotazione e l'isolamento degli ambienti (sviluppo/staging/produzione) sono centralizzati in un solo punto, invece di moltiplicarsi per fornitore.
• Pattern di richiesta portabili. Gli snippet curl e Python qui sotto sono coerenti con quelli che usi per gli altri modelli su HiAPI. Basta imparare il pattern una volta.
• Utilizzo concentrato in un unico punto. La generazione musicale viene fatturata in base alla durata dell'output; tenerla insieme agli utilizzi degli altri modelli significa monitorare i costi in un'unica dashboard invece di affrontare fatture sparse.

Il prezzo da pagare è passare attraverso un livello di astrazione, quindi le particolarità specifiche del fornitore vengono normalizzate. Per la prima integrazione e per la maggior parte dei casi d'uso in produzione, questa normalizzazione è proprio ciò che desideri. Quando devi capire il comportamento specifico del modello, la pagina di dettaglio sul sito è la fonte autorevole.

Preparativi prima della prima richiesta musicale

Verifica quattro cose prima di scrivere codice, così la prima chiamata restituirà audio invece di un 401 o di un errore di validazione.

1. Chiave API

Devi ottenere una chiave API dal tuo account HiAPI. Trattala come qualsiasi altra chiave: conservala in una variabile d'ambiente, non inserirla mai nel codice sorgente e usa chiavi diverse per lo sviluppo locale e la produzione, così puoi revocarne una senza influire sull'altra.

export HIAPI_API_KEY="your_key_here"

2. URL di base e convenzione dell'endpoint

Tutte le chiamate ai modelli passano dallo stesso URL di base, e il modello viene identificato all'interno della richiesta, non nel percorso. Mantieni una costante per l'URL di base nel progetto, così se il tuo ambiente è diverso devi modificare un solo punto.

3. Un prompt scritto in linguaggio naturale

elevenlabs/music-v2.5 accetta un prompt testuale che descrive la musica che desideri. Non hai bisogno di spartiti o file MIDI. Una o due frasi che specifichino genere, organico strumentale, mood e durata prevista sono sufficienti per iniziare. Le sezioni successive forniscono ricette riutilizzabili.

4. Aspettative corrette sull'output

La generazione musicale restituisce audio, non uno spartito JSON. Pianifica come gestire il payload della risposta: scrivi su file durante lo sviluppo, esegui streaming o archivia in produzione. Decidi in anticipo quanto dovrebbe essere lungo il brano, perché la durata influisce sia sulla richiesta sia sulla fatturazione.

Un'ultima cosa prima della prima richiesta: controlla i limiti di frequenza e i prezzi attuali di elevenlabs/music-v2.5 nel pannello dei prezzi del sito, invece di codificare ipotesi nel codice. Prezzi e limiti cambiano, e la tua integrazione dovrebbe leggerli come configurazione, non come costanti incorporate nello script.

Effettuare la prima chiamata con curl

Inizia con curl, perché rimuove ogni livello tra te e la richiesta HTTP. Se la chiamata curl funziona, qualsiasi errore nell'applicazione è un problema dell'applicazione, non dell'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."
      }
    ]
  }'

Ecco cosa fa ciascuna parte:

• -sS mantiene silenzioso l'output di avanzamento ma mostra comunque gli errori. Utile quando incolli l'output in un file.
• L'URL è l'endpoint unificato. Nota che il nome del modello non appare nel percorso, ma nel corpo della richiesta.
• Authorization: Bearer $HIAPI_API_KEY legge la chiave dall'ambiente, così non resta in chiaro nella cronologia della shell. Su Windows, imposta la variabile di conseguenza con set o con la sintassi $env: di PowerShell.
• Content-Type: application/json è obbligatorio; l'endpoint non accetta la codifica di form.
• model è l'identificatore esatto elevenlabs/music-v2.5. Un errore di battitura qui genera un errore di modello non trovato, non un errore generico, il che è utile per il debug.
• messages passa il tuo prompt come contenuto del messaggio utente. Inserisci il prompt in un unico messaggio; i prompt lunghi e strutturati funzionano meglio che se suddivisi in più messaggi.

Il corpo della risposta contiene l'audio generato e i metadati sulla richiesta. Durante lo sviluppo, reindirizza l'output su un file, così puoi ascoltare subito il risultato:

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

Mettere il payload in request.json e leggerlo con -d @request.json è un'abitudine da acquisire il prima possibile. Rende la richiesta confrontabile, verificabile e facile da ripetere modificando un solo parametro alla volta.

Ripetere la chiamata in Python

Una volta che la chiamata curl restituisce audio, portala in Python. L'obiettivo non è solo uno script funzionante, ma una funzione che possa essere chiamata da una coda di task, da un handler API o da un notebook senza divergenze dovute al copia-incolla.

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:
    """Invia un prompt musicale a elevenlabs/music-v2.5 tramite HiAPI."""
    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])

Man mano che la funzione cresce, ci sono alcune decisioni che vale la pena mantenere:

• Preferisci la libreria standard. urllib evita variazioni di dipendenze nel tutorial. Se il tuo progetto usa già requests o httpx, la conversione è meccanica: passa json=payload, headers=headers e timeout.
• Il timeout è obbligatorio. La generazione musicale richiede più tempo delle completamenti chat. Imposta un timeout esplicito e non affidarti ai valori predefiniti. Scegli un valore più lungo del tempo di generazione previsto per il brano più lungo che richiedi.
• Leggi la chiave al momento della chiamata, non all'importazione, così lo stesso modulo funziona sia in locale sia in container in cui l'ambiente viene iniettato a runtime.
• Restituisci dati strutturati, non stringhe stampate. Sarà il chiamante a decidere se scrivere l'audio su disco, caricarlo su object storage o inoltrarlo al client.

Prima di costruire qualsiasi cosa su di essi, verifica che la funzione Python e la chiamata curl producano risultati equivalenti per lo stesso prompt. Questa coerenza è la tua baseline di regressione.

Ricette di prompt per stile, mood e durata

I prompt musicali funzionano meglio quando rispondono in ordine a tre domande: quale genere e organico strumentale, quale tono emotivo, quanto lungo. I prompt vaghi producono output generici; i prompt troppo lunghi diluiscono i descrittori importanti. L'obiettivo è una frase densa, o tre brevi proposizioni.

Usali come punti di partenza pronti da copiare e incollare, modificando una sola dimensione alla volta.

Ricette guidate dallo stile

• 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.

Ricette guidate dal mood

• 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.

Ricette guidate dalla durata

La durata dovrebbe essere indicata nel prompt come obiettivo esplicito e dovrebbe essere coerente con l'arrangiamento. Una richiesta di 15 secondi con un'introduzione lenta e una lunga coda verrà troncata bruscamente.

• ... 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.

Esempio combinato

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

Quando l'output non corrisponde alle aspettative

Modifica una sola variabile per tentativo, così capisci esattamente cosa ha cambiato il risultato.

• Troppo generico: sostituisci le parole emotive con organico strumentale e tempo specifici. "Energetic" è meno incisivo di "driving 16th-note bass at 128 BPM".
• Troppo pieno o disordinato: rimuovi esplicitamente strumenti (no drums, no vocals, sparse arrangement) invece di aggiungere altri descrittori positivi.
• La lunghezza non è giusta: se il brano si interrompe bruscamente, chiedi un obiettivo più breve e una conclusione esplicita; se sembra affrettato, riduci il numero di sezioni richieste.
• Deriva di stile: sposta genere e organico strumentale all'inizio del prompt. I token iniziali hanno un peso maggiore.

Mantieni nel repository un piccolo file di prompt che documenti le ricette efficaci. Questo file vale più di qualsiasi singolo brano generato, perché trasforma la scrittura dei prompt in un artefatto ingegneristico riproducibile.

Errori comuni e come risolverli

La maggior parte delle prime integrazioni fallisce in pochi modi prevedibili. Esamina questa lista prima di iniziare a fare ipotesi.

Errori di autenticazione

Un 401 indica quasi sempre un header malformato o una chiave mancante nell'ambiente del processo. Controlla se ci sono spazi indesiderati dopo Bearer, se la chiave è stata caricata dal file .env sbagliato o se export è stato eseguito in una sessione diversa da quella che esegue lo script. Stampa la lunghezza della chiave (non la chiave stessa) per confermare che sia popolata.

Identificatore del modello non corrispondente

Un errore di modello non trovato o di validazione di solito significa che la stringa model non è una corrispondenza esatta. elevenlabs/music-v2.5 distingue maiuscole e minuscole e contiene una barra. Se l'hai copiato da una finestra di chat, controlla la presenza di virgolette tipografiche o residui di ritorno a capo.

Corpo della richiesta malformato

Se curl funziona ma Python no, la differenza è quasi sempre un problema di serializzazione. Passare un dict Python dove è attesa una stringa JSON, codificare due volte con json.dumps o dimenticare Content-Type: application/json produce tutti errori di parsing lato server che sembrano non avere relazione con la vera causa. Registra il corpo esatto della richiesta inviato dal codice e confrontalo carattere per carattere con il payload curl funzionante.

Timeout per brani più lunghi

Durate maggiori richiedono tempi di generazione più lunghi. Un timeout client adatto a una richiesta chat troncherà le richieste musicali più lunghe. Aumenta il timeout specificamente per questo endpoint e aggiungi retry con backoff solo per errori a livello di connessione, mai ripetere ciecamente richieste che potrebbero essere già state fatturate.

Lunghezza e contenuto del prompt

Prompt estremamente lunghi, o prompt che contengono istruzioni sull'API stessa, tendono a produrre musica peggiore. Mantieni il prompt solo sulla musica. Se un prompt che funzionava ieri smette di funzionare, riducilo allo scheletro stile/mood/durata e poi ricostruiscilo.

Trattare la risposta come testo

L'endpoint restituisce dati audio, non testo trascritto leggibile. Scrivere il corpo grezzo della risposta in un file .txt e poi chiedersi perché non si riesce a riprodurlo è un errore comune del primo giorno. Salva con l'estensione audio corretta e verifica che il file si apra nel lettore prima di costruire ulteriormente.

Quando l'errore non è chiaro, riproducilo con la più piccola richiesta curl possibile. Questo isola se il problema è nel contratto dell'API o nel tuo codice.

Da chiamata di test a workflow ripetibile

Una chiamata di test riuscita è un punto di partenza, non un'integrazione. Usa questa lista per trasformarla in qualcosa su cui il team possa fare affidamento.

• Configurazione esterna. URL di base, identificatore del modello, timeout e obiettivi di durata predefiniti vanno nella configurazione, non in stringhe letterali sparse. I valori specifici dell'ambiente provengono dall'ambiente.
• Client centralizzato. Una singola funzione o una classe client leggera gestisce le richieste. Nessun modulo dovrebbe costruire da solo chiamate HTTP all'endpoint musicale, altrimenti si creano divergenze su header e gestione degli errori.
• Gestisci gli errori per categoria. Distingui tra autenticazione, validazione, timeout ed errori del server. Ripeti solo gli errori transitori, con backoff e un limite massimo. Non ripetere mai richieste che potrebbero aver già prodotto output e essere state fatturate.
• Archivia l'audio correttamente. Scrivi su object storage con chiavi deterministiche, conserva il prompt insieme all'asset generato e registra l'identificatore del modello. Riprodurre un risultato in seguito dipende dal sapere esattamente cosa era stato richiesto.
• Traccia la durata come parametro di primo livello. Poiché la fatturazione segue la durata dell'output, indica la durata obiettivo esplicitamente nei template di prompt e registrala per richiesta, così il report dei costi è allineato all'utilizzo.
• Crea una libreria di prompt. Metti le ricette validate sotto controllo di versione con una breve nota sullo scopo di ciascuna. I nuovi membri del team partono da prompt funzionanti invece di tirare a indovinare.
• Separa i percorsi sincroni e asincroni. La generazione può essere lenta. Per le funzionalità rivolte all'utente, invia un job, persisti la richiesta e lascia che un worker chiami il modello. L'handler HTTP non dovrebbe restare aperto per tutta la durata della generazione.
• Verifica con uno smoke test. Un test che invia un breve prompt fisso e verifica che la risposta audio abbia il formato corretto individua presto le derive di credenziali e di contratto.

Quando sei pronto ad approfondire parametri e limiti, la pagina del modello elevenlabs/music-v2.5 su HiAPI è il posto dove controllare le capacità attuali prima di codificare ipotesi.