Come chiamare l'API mirelo-sfx-2.0 tramite HiAPI: curl, Python e polling asincrono

Funzionalità e scenari d'uso di mirelo-sfx-2.0

mirelo-sfx-2.0 è un modello di sintesi di effetti sonori da testo accessibile tramite HiAPI. Gli si fornisce una descrizione in linguaggio naturale — ad esempio "una pesante porta di legno che si apre lentamente cigolando" o "una moneta che cade su un tavolo di marmo" — e genera un breve frammento audio corrispondente al prompt.

Questo è l'endpoint da usare quando serve un sound design generato su richiesta, anziché ottenere licenze da una libreria di campioni:

• Prototipazione di giochi e applicazioni: generare effetti sonori segnaposto o definitivi per interazioni, eventi UI e loop ambientali.
• Post-produzione video e podcast: riempire i vuoti con audio in stile foley senza prenotare uno studio di registrazione.
• Pipeline generative: ottenere prompt da script, storyboard o input dell'utente e allegare il WAV generato all'output.

Il modello dà il meglio di sé quando la descrizione del suono è chiara e la durata è breve. Se serve musica, parlato o audio lungo, si tratta di famiglie di modelli diverse — mirelo-sfx-2.0 è focalizzato sugli effetti sonori discreti.

Poiché la generazione è asincrona, pianifica l'integrazione basata su task anziché su chiamate HTTP bloccanti. Il resto del tutorial costruisce questa integrazione, dalla richiesta curl grezza fino a un client Python che esegue il polling per ottenere il WAV finale.

Prerequisiti e configurazione dell'autenticazione

Prima della prima chiamata, assicurati di avere:

• Un account HiAPI e una chiave API. Puoi creare e gestire le chiavi nella console HiAPI. Tratta la chiave come una password: caricala da variabili d'ambiente o da un gestore di segreti, non inserirla mai nei repository di codice.
• Uno strumento per inviare richieste HTTP. Per questa guida basta curl; gli esempi di codice usano Python 3.8+.
• Un client HTTP in Python. Gli esempi usano requests per semplicità, ma va bene qualsiasi client in grado di inviare JSON e header.

HiAPI usa un unico URL di base e un unico metodo di autenticazione per tutti i modelli, quindi le convenzioni apprese qui valgono anche per gli altri endpoint:

export HIAPI_API_KEY="your-api-key-here"

Ogni richiesta invia la chiave nell'header Authorization:

Authorization: Bearer $HIAPI_API_KEY
Content-Type: application/json

L'identificatore del modello viene passato nel corpo della richiesta tramite "model": "mirelo-sfx-2.0". Non serve installare un SDK separato: se il tuo client HTTP riesce a raggiungere l'URL di base di HiAPI, puoi chiamare il modello.

Un consiglio pratico: salva l'URL di base in una variabile di configurazione anziché codificarlo direttamente nei vari file. Quando passerai da uno script locale a un servizio di staging o produzione, vorrai modificarlo in un solo punto.

Analisi passo passo della richiesta curl

La richiesta di generazione è una chiamata HTTP POST autenticata all'endpoint di creazione task di HiAPI. Ecco la chiamata completa:

curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mirelo-sfx-2.0",
    "input": {
      "prompt": "heavy wooden door creaking open slowly, old house ambience"
    }
  }'

Analisi per parti:

• -X POST — la creazione del task è un'operazione di scrittura. Usare GET su questo percorso non avvia alcun task.
• URL — l'endpoint accetta un nuovo task di generazione. L'URL di base è memorizzato in HIAPI_BASE_URL, così lo stesso comando funziona in qualsiasi ambiente.
• Authorization — il token bearer identifica il tuo account ed è anche la base per la fatturazione. Un header mancante o malformato è la causa più comune di 401.
• Content-Type: application/json — il corpo è JSON; senza questo header il server rifiuterà o analizzerà male il payload.
• model — seleziona mirelo-sfx-2.0. Poiché HiAPI instrada in base a questo campo, puoi cambiare modello senza modificare l'URL.
• input.prompt — la descrizione testuale del suono. Descrizioni concrete e fisiche (materiale, azione, ambiente) producono risultati migliori di quelle astratte.

Un invio riuscito non restituisce l'audio. Restituisce un oggetto task con un identificatore (di solito il campo id) che usi per controllare lo stato. Cattura quell'ID dalla risposta: è l'indizio che ti permetterà di recuperare il WAV in seguito.

Se vuoi verificare la struttura della richiesta prima di scrivere codice, esegui prima questo comando esatto nel terminale. Una volta che funziona, convertirlo in Python è un'operazione meccanica.

La stessa chiamata in Python

La versione Python mantiene lo stesso URL, gli stessi header e lo stesso corpo — semplicemente li rappresenta come dizionari e chiamate del client:

import os
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]

def create_sfx_task(prompt: str) -> str:
    response = requests.post(
        f"{BASE_URL}/v1/tasks",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": "mirelo-sfx-2.0",
            "input": {"prompt": prompt},
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["id"]

Differenze rispetto alla versione shell:

• Accesso all'ambiente — os.environ sostituisce l'espansione della shell, così la chiave non appare mai nel codice sorgente.
• json= al posto di -d — requests serializza il dizionario e imposta il content type per te. Puoi rimuovere l'header manuale, anche se lasciarlo non fa male.
• raise_for_status() — trasforma le risposte non 2xx in eccezioni; è qui che va gestita la gestione degli errori.
• timeout — il timeout del client evita che connessioni bloccate sospendano il tuo processo di lavoro. La creazione del task è rapida; l'attesa lunga avviene durante il polling.

Il valore restituito è l'ID del task. Salvalo — è il tuo unico handle per quella generazione. A questo punto i percorsi Python e curl convergono: entrambi richiedono il passo di polling prima che l'audio esista.

Poiché il corpo della richiesta è solo dati, puoi parametrizzare il prompt e iterare su un elenco di descrizioni per generare effetti sonori in batch, creando un task per ogni prompt e raccogliendo gli ID.

Gestire i task asincroni ed eseguire il polling dei risultati

La generazione audio richiede tempo — secondi, non millisecondi — quindi HiAPI la modella come un task. La chiamata di creazione restituisce immediatamente un ID; un secondo endpoint segnala se quel task è ancora in esecuzione, è completato o è fallito.

Il ciclo tipico è:

1. Creare il task e catturare l'ID.
2. Eseguire il polling dell'endpoint di stato del task con quell'ID.
3. Se lo stato è ancora in elaborazione, attendere brevemente e interrogare di nuovo.
4. Quando lo stato segnala successo, leggere l'output dalla risposta.
5. Se lo stato segnala un fallimento, interrompere e sollevare un errore.

In Python:

import time

def wait_for_task(task_id: str, timeout_s: int = 300) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        response = requests.get(
            f"{BASE_URL}/v1/tasks/{task_id}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=30,
        )
        response.raise_for_status()
        task = response.json()

        status = task.get("status")
        if status == "succeeded":
            return task
        if status == "failed":
            raise RuntimeError(task.get("error", "task failed"))

        time.sleep(2)

    raise TimeoutError(f"task {task_id} did not finish in time")

Alcuni punti meritano una nota specifica:

• Intervallo di polling. Due secondi sono un valore predefinito ragionevole per gli effetti sonori. Un polling in ciclo stretto spreca quota e può attivare limiti di frequenza, senza far arrivare il risultato più velocemente.
• Scadenza complessiva. Imposta sempre un limite superiore per il ciclo. Un task bloccato deve far fallire il tuo job, non sospendere il processo per sempre.
• Valori di stato. Tratta i valori di stato sconosciuti come "ancora in elaborazione" anziché presumere il successo, e ramifica esplicitamente sugli stati di successo e fallimento.
• Webhook (se disponibili). Se il tuo account HiAPI supporta callback di completamento, preferiscile al polling nel codice di produzione lato server; per script e prototipi il polling resta l'opzione più semplice.

Salva l'ID del task insieme al prompt nel tuo database, così potrai in seguito ritentare, verificare o recuperare l'output senza rigenerarlo.

Leggere la risposta WAV restituita

Quando il task segnala successo, la risposta contiene l'audio generato. A seconda della versione dell'endpoint, l'output può apparire come URL di un file WAV o come dati audio inline; tratta entrambi i casi come "byte memorizzabili".

L'oggetto task riuscito porta l'output sotto un campo come output, di solito con metadati quali nome del modello, prompt originale e informazioni temporali. L'audio stesso è un contenitore WAV standard, il che significa che puoi passarlo a qualsiasi libreria audio senza decoder personalizzati.

Per rendere persistente un risultato basato su URL:

result = wait_for_task(task_id)
audio_url = result["output"]["audio_url"]

wav_bytes = requests.get(audio_url, timeout=60).content
with open(f"{task_id}.wav", "wb") as f:
    f.write(wav_bytes)

Se l'audio arriva come dati decodificati, decodifica in base64 prima di scrivere:

import base64

wav_bytes = base64.b64decode(result["output"]["audio_base64"])
with open(f"{task_id}.wav", "wb") as f:
    f.write(wav_bytes)

Una volta ottenuti i byte:

• Verifica l'intestazione. I file WAV iniziano con il magic number RIFF. Controllare i primi quattro byte intercetta download troncati prima che raggiungano l'archivio.
• Archiviazione persistente. Scrivi nello storage a oggetti e salva la chiave nel database insieme all'ID del task. Tratta l'audio generato come un artefatto memorizzabile in cache, non come una risposta temporanea.
• Riproduzione o elaborazione. Strumenti standard — wave, soundfile o qualsiasi lettore audio — aprono il file direttamente. Puoi poi tagliare il silenzio, normalizzare il volume o convertire in un altro formato per la consegna.

Poiché il file è un normale WAV, collegarlo a un endpoint Web o a una pipeline di asset per motori di gioco non richiede trattamenti speciali.

Punti di errore comuni e come risolverli

La maggior parte dei problemi di integrazione rientra in alcune categorie prevedibili.

Errori di autenticazione (401 / 403)

Un 401 significa quasi sempre che l'header Authorization è mancante, malformato o costruito da una variabile d'ambiente vuota. Verifica che HIAPI_API_KEY sia esportata nella shell in cui gira il processo — non solo nell'editor — e che l'header sia Bearer <key>, con un solo spazio in mezzo. Un 403 di solito significa che la chiave è valida ma non ha accesso a quel modello; controlla i permessi del modello del tuo account.

Payload malformati (400 / 422)

La causa più comune è un corpo della richiesta non JSON valido — le virgolette non bilanciate nel comando curl sono l'esempio tipico. Verifica con un validatore JSON prima di inviare. La seconda causa più comune è il campo model mancante o il prompt annidato a un livello errato; il modello si aspetta input.prompt, non un prompt di primo livello. Infine, verifica che il prompt non sia vuoto e che la sua lunghezza rientri nei limiti specificati nella documentazione del modello.

Polling troppo frequente

Un ciclo while stretto senza sleep genera un gran numero di richieste di stato, può attivare limiti di frequenza e rallenta il task che stai aspettando. Usa un intervallo fisso di uno o due secondi, aggiungi jitter quando esegui più job in parallelo e imponi sempre un tempo massimo di attesa.

Scambiare la creazione per il completamento

La risposta di creazione sembra un successo e restituisce 200, ma non contiene l'audio. Se il codice legge subito il campo output, fallirà o scriverà un file vuoto. Passa sempre dall'endpoint di stato prima di toccare il risultato.

Timeout silenziosi e retry

Riprovare in caso di timeout di rete durante la creazione del task è sicuro, ma riprovare la chiamata di creazione dopo un timeout di una chiamata in realtà già riuscita produce job duplicati. Se l'endpoint supporta chiavi di idempotenza, usale; altrimenti elenca i task recenti per verifica prima di riprovare.

Casi limite di disco e archiviazione

Quando scrivi i byte WAV, apri il file in modalità binaria ("wb"). La modalità testo corrompe l'intestazione del file. Se archivi gli output con il nome del prompt, due task con lo stesso prompt si sovrascriveranno a vicenda — usa l'ID del task come chiave del file.

Con queste protezioni, l'integrazione di mirelo-sfx-2.0 è una breve pipeline: creare, eseguire il polling, rendere persistente. Inizia dalla chiamata curl, passa a Python e usa l'ID del task come fonte di verità.