Blog

Guida all'uso

Utilizzo di mureka-9.5/instrumental tramite HiAPI per immagini di prodotto e-commerce

Costruire una pipeline ripetibile da BGM a video di prodotto con l'API audio di HiAPI

Nov 18, 2026
Copertina piatta con campi di colore malva pallido e nero inchiostro divisi da una sottile linea viola, che contrassegna l'immagine di copertina di questa guida.
In questa pagina
BGM puramente strumentale generata con mureka-9.5/instrumental su HiAPI e mixata in un video di prodotto e-commerce di 30 secondi.

Perché le visuali di prodotto necessitano di un livello BGM separato

La maggior parte dei cataloghi e-commerce è assemblata da due linee di produzione separate: una linea visiva che produce immagini statiche e brevi clip dei prodotti, e una linea audio gestita in modo improvvisato, di solito rimandata all'ultimo momento. Il risultato è del tutto prevedibile — decine di SKU che condividono le stesse tre tracce di una library musicale, livelli di volume incoerenti tra le clip e una questione di licenze che nessuno vuole affrontare durante la revisione marketing.

Trattare la musica di sottofondo come un livello separato risolve questi problemi. Invece di applicare l'audio forzatamente al video finito, si genera una traccia per categoria di prodotto, la si salva come asset riutilizzabile e la si mixa al momento del rendering. Questa separazione offre vantaggi concreti:

  • Riutilizzabilità. Una singola traccia può servire tutti gli SKU di una categoria, quindi cento clip di prodotto non richiedono cento generazioni audio.
  • Coerenza. Una traccia fissa significa volume fisso e punti di loop fissi, il che fa sembrare un'intera schermata di video di prodotto un unico brand, non una playlist.
  • Sostituibilità. Se cambia la parte visiva, basta rimixare, senza rigenerare l'audio; se cambia l'audio, la parte visiva resta invariata.
  • Provenienza chiara. Le tracce strumentali generate non presentano problemi di clearing di campioni di terze parti e, se il negozio necessita di varianti, possono essere rigenerate.

È proprio questo il motivo per cui un endpoint di strumentali generative ha un posto nella pipeline di produzione. L'output puramente strumentale significa che nessuna voce compete per l'attenzione con il testo a schermo o la narrazione, e il prompt testuale significa che è possibile descrivere l'atmosfera con il vocabolario già presente nelle linee guida del brand — calmo, minimale, energico, clinico.

Il resto di questa guida costruisce questo livello: genera tracce con mureka-9.5/instrumental tramite HiAPI, poi mixale in brevi video di prodotto in un modo che possa essere eseguito come attività batch, anziché come creazione artistica clip per clip.

Cosa offre mureka-9.5/instrumental

Funzionalmente, mureka-9.5/instrumental è un modello text-to-music che restituisce una traccia puramente strumentale. Non ci sono stem vocali da rimuovere né input di testi da gestire — descrivi la musica che vuoi e ottieni l'audio.

Quando lo si chiama tramite HiAPI, ciò significa che il modello segue lo stesso approccio di integrazione del resto della piattaforma: una credenziale, una famiglia di endpoint e una risposta che puoi archiviare e riutilizzare. Non serve un account separato o un rapporto di fatturazione separato per l'audio; la traccia generata è semplicemente un altro tipo di asset che la pipeline produce oltre a immagini e video.

Alcune caratteristiche sono particolarmente importanti per il caso d'uso e-commerce:

  • Output puramente strumentale. I video di prodotto sono di solito brevi e fruiti con l'audio disattivato. Una traccia senza voce mantiene l'attenzione sul prodotto e non entra in conflitto con i sottotitoli.
  • Atmosfera guidata dal prompt. L'atmosfera a livello di categoria (ad esempio acustica calda per articoli per la casa, percussioni nitide per l'elettronica) può essere codificata in prompt riutilizzabili, anziché selezionare tracce manualmente.
  • Output in forma di asset. Il risultato è un asset audio che puoi archiviare, denominare, versionare e riutilizzare — con lo stesso ciclo di vita dei rendering delle immagini.

La pagina del modello mureka-9.5/instrumental è il luogo autorevole in cui consultare i campi di richiesta correnti, le opzioni supportate e la struttura della risposta prima di scrivere il codice client. Questa guida resta deliberatamente a livello di pipeline: i nomi dei campi e le opzioni disponibili evolvono continuamente, e la tua integrazione dovrebbe basarsi sul contratto documentato, non su ipotesi copiate da un post di blog.

Una nota sull'ambito: la BGM strumentale è solo un livello, non l'intera traccia audio. Se il video di prodotto necessita di una voce fuori campo o di un set di effetti sonori, questi sono aspetti separati che vanno composti sopra il letto musicale, e non richiesti a questo endpoint.

Progettare prompt e specifiche delle tracce per categoria di prodotto

La modalità di errore più comune nell'audio generativo è un prompt privo di struttura che produce qualcosa di tecnicamente conforme ma non in linea con il brand. Risolvi il problema definendo un piccolo set di profili di categoria prima di effettuare la chiamata API.

Creare profili di categoria, non prompt per singolo SKU

Raggruppa il catalogo in un set gestibile di categorie audio — di solito da cinque a quindici per un negozio di medie dimensioni. Per ogni categoria, annota atmosfera, indicazioni sugli strumenti, intervallo di tempo e cosa evitare. Il profilo è un documento che tutto il team può revisionare e che corrisponde uno a uno a un template di prompt:

Letto musicale strumentale per video di prodotto {category}.
Atmosfera: {mood}. Strumentazione: {instruments}.
Tempo: {tempo_range}. Mantieni l'arrangiamento uniforme e adatto al loop.
Nessuna voce. Nessun calo improvviso di intensità.

Specificare in funzione del montaggio, non solo dell'atmosfera

Il prompt dovrebbe codificare come verrà usata la traccia. Due dettagli ripagano in seguito:

  • Energia uniforme. Le clip di prodotto sono brevi; una traccia che impiega i primi dieci secondi per costruire lascia la clip quasi senza musica. Richiedi un arrangiamento costante.
  • Adatta al loop. Se prevedi di ripetere la traccia per riempire clip più lunghe, richiedi un suono stabile e ripetitivo, senza cambi di tonalità netti. Ripetere una traccia progettata per questo è molto più semplice che fare crossfade su una traccia qualsiasi.

Decidere in anticipo la durata della traccia

La durata della traccia è una decisione di specifica, non un ripensamento. Due strategie funzionano:

  1. Corrispondere alla durata nominale della clip e rifilare leggermente. Adatta quando tutte le clip di una categoria hanno la stessa durata.
  2. Generare un letto più lungo per categoria e ripeterlo o ritagliarlo in base alla clip. Adatta quando le durate variano e vuoi utilizzare un unico asset riutilizzabile.

Per cataloghi di grandi dimensioni, la seconda è di solito più economica in termini di impegno operativo, ma solo se hai progettato per il loop.

Annotare le specifiche

Metti ogni profilo insieme al template di prompt nel controllo di versione, indicando categoria, template e durata prevista della traccia. Quando qualcuno chiede perché una clip di utensili da cucina suona in un certo modo, la risposta è un file, non la memoria.

Effettuare la chiamata API tramite HiAPI

La chiamata stessa è la parte più piccola della pipeline. Configurala in modo che tutto ciò che la circonda — assemblaggio del prompt, denominazione degli asset, archiviazione — sia deterministico.

Configurazione delle credenziali e del client

Archivia la chiave HiAPI in una variabile d'ambiente e caricala in un unico punto del client. Non spargere le credenziali tra vari script.

export HIAPI_API_KEY="your_key_here"

Inserisci l'URL di base e la chiave in un piccolo modulo condiviso, in modo che ogni attività — un test singolo o un batch completo — utilizzi la stessa configurazione.

Assemblare la richiesta dal profilo

Non scrivere i prompt a mano nel codice; carica il profilo di categoria, renderizza il template di prompt e costruisci la richiesta da lì. La richiesta dovrebbe contenere:

  • il prompt renderizzato,
  • le caratteristiche della traccia target definite dal profilo,
  • e gli identificatori necessari per tracciare l'attività in seguito (categoria, versione del profilo).

Prima di finalizzare il payload della richiesta, verifica i campi esatti di richiesta di mureka-9.5/instrumental sulla pagina del modello e ancora il codice alla struttura descritta in quella documentazione.

Trattare la risposta come un asset, non come un valore

La chiamata di generazione restituisce un asset audio e un identificatore. Due abitudini lo mantengono gestibile:

  • Persistenza immediata. Scarica nel tuo storage con un nome chiave deterministico, ad esempio bgm/{category}/{profile_version}/{job_id}.wav. Non affidarti alla stabilità di un URL remoto.
  • Registrazione dei metadati. Archivia il prompt, la versione del profilo, l'identificatore dell'attività e la durata restituita insieme al file. Quando una traccia deve essere rigenerata, puoi riprodurre esattamente la stessa richiesta.

Classificare i fallimenti come ritentabili o non ritentabili

Distingui i fallimenti temporanei (retry con backoff) dai problemi della richiesta stessa (campi non validi, prompt rifiutato), che fallirebbero allo stesso modo se ritentati. Un'attività batch che ritenta cento volte un payload malformato è molto peggio di un fallimento rapido che segnala il profilo problematico.

Mixare la traccia nel video di prodotto

Il mixing è dove si guadagna o si perde la maggior parte della qualità percepita. Un audio che inizia bruscamente, salta al punto di loop o è più forte delle altre clip del negozio appare sciatto anche se la traccia in sé è buona.

Abbinare deliberatamente le durate

Prima del rendering, confronta la durata della clip e quella della traccia:

  • Traccia più lunga della clip: ritaglia dalla fine, non dall'inizio. Iniziare dal centro elimina l'intro e spesso cade su una sezione instabile.
  • Traccia più corta della clip: ripeti, ma solo sulla regione progettata per il loop. Usa un breve crossfade sulla giunzione per evitare click udibili.
  • Più o meno uguali: aggiungi comunque un breve fade in/out nell'ultimo secondo, così l'audio non inizia o finisce bruscamente.

Controllare il volume come impostazione della pipeline

Il volume dovrebbe essere un target fisso applicato a ogni asset, non una decisione di missaggio clip per clip. Normalizza il letto musicale a un livello coerente prima del mixing e abbassalo leggermente in presenza di voce fuori campo, così la narrazione resta chiara. Poiché normalizzi una sola volta la traccia sorgente, ogni clip derivata eredita la stessa baseline.

Completare il mixing con un'unica operazione deterministica

Un comando che prende la clip e la traccia e produce il file finale rende la pipeline riproducibile:

ffmpeg -i clip.mp4 -stream_loop -1 -i bgm.wav \
  -filter_complex "[0:a]anull[a0];[1:a]afade=t=in:st=0:d=0.5,afade=t=out:st=9.5:d=0.5[a1];[a0][a1]amix=inputs=2:duration=first" \
  -shortest -c:v copy -c:a aac out.mp4

Adatta la catena di filtri alle tue durate effettive e alla presenza o meno di audio nella clip, ma mantieni questa forma: un comando, un output, con parametri guidati dalle specifiche dell'attività, non digitati a mano.

Conservare gli asset sorgente

Archivia separatamente la traccia generata e il video mixato. Il video è un prodotto derivato; la traccia è l'elemento riutilizzabile. Rigenerare un video da una traccia archiviata è veloce; rigenerare una traccia che hai sovrascritto non lo è.

Elaborazione batch su tutti gli SKU, senza modifiche manuali

Passare da una clip all'intero catalogo è principalmente un problema di dati. Se i passaggi per ogni clip sono parametrizzati, il livello batch è sottile.

Attività guidate da un manifest

Descrivi il lavoro come dati — una riga per output — includendo SKU, percorso della clip, categoria e versione del profilo. Il runner legge il manifest, risolve la categoria in una traccia (generando solo se la cache non ha un riscontro) ed esegue il rendering del video. Nessun passaggio dovrebbe richiedere la selezione manuale di una traccia.

Cache delle tracce per categoria e versione del profilo

Le tracce sono la parte costosa e riutilizzabile. Imposta la chiave di cache sulla categoria più la versione del profilo, più eventuali opzioni che influenzano il prompt, e riutilizzala su ogni SKU di quella categoria. Quando modifichi un profilo, incrementa il suo numero di versione, così le vecchie tracce non vengono riutilizzate silenziosamente con nuove visuali.

Trattare il re-rendering come percorso normale

Le visuali cambiano più spesso dell'audio. Quando le immagini di prodotto vengono aggiornate, il comportamento atteso è: mantieni la traccia, rimixa il video. Progetta il manifest in modo che una modifica alla clip reimposti solo l'artefatto video, mentre la cache delle tracce resta calda. Il re-rendering dovrebbe essere economico, banale e sicuro da eseguire in batch.

Fallire a livello di voce, non di batch

Il runner batch dovrebbe elaborare ogni riga che può e segnalare i fallimenti con SKU, versione del profilo e motivo. Una clip difettosa non dovrebbe interrompere un'attività di migliaia di righe, e un riepilogo finale ti dice quali profili o input richiedono attenzione.

Rendere il runner idempotente

Chiavi di output deterministiche significano che rieseguire un batch sovrascrive gli stessi artefatti anziché creare duplicati. Questa proprietà rende il runner qualcosa che può essere pianificato in sicurezza — ad esempio ogni notte sui nuovi SKU — senza supervisione manuale.

Controlli di qualità prima della pubblicazione

Prima che gli asset vadano online, esegui una breve checklist fissa. Automatizza ciò che puoi e trasforma il resto in un passaggio di revisione con un responsabile chiaro.

Controlli automatizzati

  • Corrispondenza delle durate. La lunghezza dell'audio del video mixato è uguale a quella della clip entro una tolleranza ridotta.
  • Coerenza del volume. Campiona i livelli audio dell'intero batch e segnala gli outlier — una traccia normalizzata diversamente spicca nella griglia.
  • Giunzioni del loop. Controlla la regione di giunzione delle tracce in loop; click o salti di livello dovrebbero far fallire il controllo.
  • Presenza dei fade. Verifica che i fade in e out siano effettivamente applicati.
  • Integrità dei file. Verifica che ogni output sia decodificabile e che il codec corrisponda a quanto previsto dal negozio.

Controlli manuali

  • Aderenza al brand. Ascolta una clip rappresentativa per ogni categoria. La generazione è non deterministica; un profilo che di solito funziona può occasionalmente produrre una traccia fuori brand. Rigenera e aggiorna la cache di quella categoria.
  • Leggibilità del testo. Verifica che la musica non copra il testo a schermo o la voce fuori campo, soprattutto sugli altoparlanti del telefono.
  • Inizio e fine. Guarda i primi e gli ultimi secondi di alcune clip — è lì che l'audio brusco si nota di più.

Cosa fare se qualcosa va storto

Indaga dall'artefatto verso l'esterno. Se il video è sbagliato ma la traccia è corretta, il problema è nel passaggio di mixing o nel manifest. Se la traccia è sbagliata, controlla il prompt renderizzato e la versione del profilo prima di richiamare il modello. Quando la richiesta stessa fallisce o restituisce una struttura inattesa, consulta la pagina del modello mureka-9.5/instrumental per il contratto corrente, poi verifica le tue credenziali e il payload rispetto ad esso.

Esegui questi controlli come parte del batch, non come audit separato. Una pipeline che verifica i propri output è la chiave che rende ripetibile l'intero approccio.

Una volta che profili, cache delle tracce e controlli sono in atto, aggiungere una nuova categoria di prodotto è solo una piccola modifica revisionabile, non un nuovo progetto di produzione — ed è esattamente questo lo scopo di costruire il livello BGM separatamente.

Inizia a creare con artefatti IA persistenti

Ottieni la tua chiave API e chiama modelli di immagini, video e audio tramite un'unica API basata sui task.

Leggi la documentazione API