Come si usa l'API di Mirelo SFX 2.0? Genera il tuo primo effetto sonoro in 5 minuti

TL;DR

• Cos'è: un modello text-to-SFX che trasforma una descrizione in un WAV da 1 a 30 secondi (PCM 16-bit / 48 kHz / mono). Apri la pagina del modello Mirelo SFX 2.0 e scrivi una frase per ascoltare un'anteprima. Mirelo SFX 2.0 è ora disponibile su HiAPI, e i nuovi utenti che si registrano ricevono 200 crediti.
• Quanto costa: la fatturazione è basata sui secondi di output, $0.0215 al secondo (43 crediti), con un minimo di 1 secondo; 5 secondi costano $0.1075, 30 secondi $0.645.
• Come chiamarlo al volo: nella pagina del modello inserisci la descrizione, scegli la durata e invia; per integrarlo nel tuo prodotto usa POST /v1/tasks, imposta model su mirelo-sfx-2.0, e in input metti solo prompt e duration.

Cos'è Mirelo SFX 2.0

L'input ha solo due campi: prompt e duration. La descrizione va da 1 a 2.000 caratteri: specifica sorgente sonora, materiale, azione, distanza e ambiente, poi aggiungi attacco e coda; duration è un numero intero di secondi da 1 a 30, con default 5. L'output è sempre un singolo WAV, PCM 16-bit, 48 kHz, mono, senza opzioni di formato.

Gestisce solo singoli effetti sonori e ambienti: una richiesta produce un evento sonoro, non genera brani musicali, voci o dialoghi. Che si tratti di aggiungere un punto d'impatto a un montaggio, un suono di feedback UI a un gioco o un rumore di fondo di una notte piovosa a un video breve, è il suo mestiere.

Questo colpo di martello nel sito viene consegnato in 1 secondo, a $0.0215. Il transiente e la lunga risonanza metallica stanno tutti in questo secondo:

Ascolta: colpo di martello su trave d'acciaio, WAV da 1 secondo

A single heavy hammer strike on a steel beam in a large empty warehouse, sharp transient, long metallic ring, close perspective.

Genera con questo prompt → Il link precompila solo la descrizione; dopo averlo aperto, imposta duration su 1 secondo per ottenere questo risultato.

Ascolta anche un caso di ambiente da 10 secondi, stesso modello e stessi campi:

Ascolta: notte di pioggia su tetto metallico, WAV da 10 secondi

Prova online: 4 passi per ascoltare il primo risultato

1. Apri la pagina del modello Mirelo SFX 2.0; registrandoti ricevi 200 crediti.
2. Incolla nella casella della descrizione la descrizione del colpo di martello qui sopra, oppure sostituiscila con il suono che vuoi tu.
3. Imposta duration su 1–3 secondi per ascoltare prima attacco e coda.
4. Fai clic su invia: nel player esce il WAV, che puoi scaricare direttamente.

Non saltare il passo 3. La stessa descrizione con 1 secondo e con 10 secondi dà due cose diverse; provare prima corto e poi lungo ti risparmia i soldi di rigenerazioni ripetute.

Integrazione API: 4 passi per farla funzionare

1. Crea una API Key nella console.
2. POST https://api.hiapi.ai/v1/tasks, con model impostato su mirelo-sfx-2.0 e in input inserisci prompt e duration.
3. Prendi il taskId restituito, attendi la notifica del callback oppure esegui polling su GET /v1/tasks/{taskId}.
4. Quando status diventa success, prendi da output la voce con type uguale a audio e usa il suo url per scaricare il WAV.

curl eseguibile

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mirelo-sfx-2.0",
    "input": {
      "prompt": "A single heavy hammer strike on a steel beam in a large empty warehouse, sharp transient, long metallic ring, close perspective.",
      "duration": 1
    }
  }'

L'ID del task nella risposta sta in data.taskId:

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

Usa questo ID per controllare lo stato:

curl -s https://api.hiapi.ai/v1/tasks/YOUR_TASK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

data.status passa per queued, handling, success o fail. In caso di successo, cerca in data.output la voce con type uguale a audio.

Versione Python: creazione, polling e download in un unico script

import requests
import time

BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

payload = {
    "model": "mirelo-sfx-2.0",
    "input": {
        "prompt": "A single heavy hammer strike on a steel beam in a large empty warehouse, sharp transient, long metallic ring, close perspective.",
        "duration": 1,
    },
}

task_id = requests.post(BASE, headers=HEADERS, json=payload, timeout=30).json()["data"]["taskId"]

while True:
    data = requests.get(f"{BASE}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if data["status"] in ("success", "fail"):
        break
    time.sleep(2)

if data["status"] == "success":
    audio_url = next(item["url"] for item in data["output"] if item["type"] == "audio")
    with open("effect.wav", "wb") as f:
        f.write(requests.get(audio_url, timeout=60).content)
    print("saved effect.wav")
else:
    print(data.get("error"))

I task di effetti sonori sono molto più brevi di quelli video: un intervallo di polling di 2 secondi basta, non serve aspettare 3 secondi pieni.

Come scrivere la descrizione: cinque elementi

Non ci sono parametri aggiuntivi: prompt è l'intera superficie di controllo. Scrivilo seguendo questi cinque punti e colpisci al primo tentativo:

Elemento	Cosa scrivere	Frase corrispondente nell'esempio
Sorgente sonora	Quale oggetto produce il suono	a heavy hammer strike
Materiale	Il materiale del corpo che suona	on a steel beam
Azione	Come suona e con quale intensità	single, heavy
Distanza e ambiente	Dove si trova l'ascoltatore e quanto è grande lo spazio	in a large empty warehouse, close perspective
Attacco e coda	Quanto è rapido l'inizio e quanto dura la fine	sharp transient, long metallic ring

Se non sei sicuro di una dimensione, omettila; non scrivere aggettivi come "circa" o "cinematografico": ogni sostantivo concreto nella descrizione finisce nel suono. Vale la pena tenere una frase finale come "no music and no voices", che esclude in un colpo solo gli strati indesiderati.

Come scegliere la durata

Prima usa 1–3 secondi per verificare che timbro, attacco e coda siano giusti; poi, a versione definitiva, porta duration alla lunghezza target. La stessa descrizione con 3 secondi e con 10 secondi produce una densità di eventi diversa: la versione breve serve a sondare la direzione, quella lunga a ottenere il prodotto finito, ed è molto più economico che lanciare subito 30 secondi.

• Impatti, UI, clic → 1–3 secondi.
• Ambienti, rumore di fondo, atmosfera di una stanza → 10–30 secondi.
• Se devi rispettare la durata di un'inquadratura → inserisci direttamente il numero intero di secondi dell'inquadratura; il modello consegna la durata che gli dai.

4 cose da tenere presenti prima del lancio in produzione

1. Aggiungi il polling come rete di sicurezza al callback. Aggiungi al corpo della richiesta "callback": {"url": "https://yourapp.com/webhook", "when": "final"}: quando il task raggiunge lo stato finale ricevi una notifica; le notifiche possono perdersi, quindi affianca un GET /v1/tasks/{taskId} periodico come compensazione.
2. Sii idempotente per taskId. Sia success che fail sono stati finali; lo stesso taskId può ricevere più notifiche, quindi prima di elaborare controlla a database e deduplica.
3. I link ai prodotti scadono. Il url in output è un indirizzo temporaneo: appena lo ottieni, trasferiscilo nel tuo storage, non usarlo come CDN a lungo termine.
4. Una descrizione racconta un solo evento. Impatto più caduta di schegge, pioggia più tuono più abbaiare di cane: separali in più richieste generate singolarmente e sovrapponili in post-produzione; è più controllabile che stiparli in una sola frase.

Domande frequenti

Mirelo SFX 2.0 può generare brani musicali o voci? No. Gestisce solo singoli effetti sonori e ambienti, con una durata massima di 30 secondi. Per la musica usa un modello musicale, per la voce fuori campo un modello vocale.

Cosa succede se non compilo duration? Genera 5 secondi e addebita $0.1075. Per altre lunghezze scrivilo esplicitamente, come numero intero da 1 a 30.

Posso scegliere MP3 o stereo in output? No, è sempre un singolo WAV, PCM 16-bit, 48 kHz, mono. Per altri formati converti in post-produzione.

Quanto può essere lunga la descrizione? 2.000 caratteri, abbastanza per inserire una specifica sonora completa.

Lancia subito il tuo primo risultato

Copia la descrizione del colpo di martello qui sopra, apri la pagina del modello Mirelo SFX 2.0, imposta duration su 1 secondo e ascolta un impatto completo per $0.0215. Una volta verificato il risultato, inserisci gli stessi due campi nel curl qui sopra e integralo nel tuo flusso di lavoro. Per tutti i parametri consulta la documentazione di integrazione.

Letture correlate: Prezzi di Mirelo SFX 2.0 · vs ElevenLabs Sound Effects v2 · 4 prompt reali per effetti sonori