Come usare mureka-9.5/instrumental tramite l'API HiAPI: guida con curl e Python

Cosa fa mureka-9.5/instrumental su HiAPI

mureka-9.5/instrumental è un endpoint di generazione musicale da testo su HiAPI, ottimizzato specificamente per output puramente strumentali: musica di sottofondo, loop, tappeti sonori e colonne sonore. Descrivi il brano con un prompt, invii un singolo task e HiAPI restituisce una risorsa audio completa che puoi scaricare e inserire in giochi, montaggi video, podcast o presentazioni di prodotto.

La parola chiave è instrumental (strumentale). L'endpoint è pensato per musica senza performance vocale principale, quindi è adatto a scenari in cui la voce fuori campo o i dialoghi devono restare chiari e comprensibili. Se ti servono brani cantati con testo, è un'altra questione; se ti serve un tappeto musicale pulito sotto una voce fuori campo, questo è lo strumento giusto.

Scegli questo endpoint quando:

• Vuoi generare musica di sottofondo (BGM) invece di attingere a una libreria musicale.
• Hai bisogno di generare rapidamente e programmaticamente molte varianti, invece di una singola commissione personalizzata.
• La tua pipeline usa già HTTP e vuoi trattare la musica come qualsiasi altro passo di generazione di risorse.
• Ti interessa una forma di richiesta prevedibile: invio, polling, download.

Come gli altri endpoint di generazione musicale, il lavoro è asincrono. Dopo l'invio ottieni un task che devi monitorare fino alla generazione dell'audio. Progetta il codice tenendo conto di questo fin dall'inizio e il resto dell'integrazione sarà routine.

Dove si colloca nel prodotto

L'utente tipico è una pipeline di contenuti che necessita di brani on demand: un renderer video che vuole un tappeto musicale sotto ogni clip, un gioco che desidera loop ambientali, o uno strumento di prototyping che fa inserire all'utente un'emozione e restituisce un risultato. Poiché l'endpoint è guidato dal testo, puoi templatizzare il prompt usando i metadati che già possiedi — genere, andamento ritmico, atmosfera e durata prevista — e generare al momento del rendering.

Tratta ogni richiesta come un task di generazione con un proprio ciclo di vita. Questa impostazione mantiene ragionevoli la logica di retry, il logging e la contabilizzazione dei costi.

Prepararsi prima di inviare la richiesta

Prima che la prima chiamata riesca vanno soddisfatte alcune condizioni. Nessuna è complicata, ma trascurarne una è la causa più comune del fallimento della prima richiesta.

Credenziali

Ti serve una chiave API HiAPI. Trattala come un segreto: caricala da una variabile d'ambiente come HIAPI_API_KEY, non codificarla mai direttamente negli script che commetti, e ruotala se viene esposta. La chiave viene inviata come token bearer tramite l'header Authorization.

export HIAPI_API_KEY="your_api_key_here"

Endpoint e trasporto

Chiami il modello mureka-9.5/instrumental tramite l'API unificata di HiAPI. L'URL di base è l'host dell'API HiAPI; l'identificatore del modello va nel payload della richiesta o nel percorso secondo la convenzione documentata da HiAPI per questo endpoint. Usa HTTPS, invia Content-Type: application/json e invia un corpo JSON.

Non indovinare i nomi dei parametri. HiAPI documenta i campi accettati da questo modello; qualunque cosa fuori da quell'insieme, nel migliore dei casi viene ignorata, nel peggiore rifiutata. Se il campo che vorresti non è documentato, non fa parte del contratto: costruisci su ciò che è disponibile.

Cosa preparare

• Un prompt che descrive la musica: genere, strumentazione, atmosfera, andamento ritmico e uso previsto.
• Le opzioni di durata o varianti documentate ed esposte dal modello.
• Un posto dove memorizzare l'identificatore del task e, in seguito, l'URL di download.
• Accesso di rete dall'ambiente in cui gira il codice all'host HiAPI.

Una nota sui tempi

La generazione non è immediata. Imposta timeout del client generosi e metti in conto il polling. Un approccio sincrono — inviare la richiesta e bloccarsi finché l'audio non ritorna nella stessa risposta — porta a codice instabile.

Una richiesta curl funzionante

Parti da curl. Elimina ogni livello tra te e l'HTTP, così se qualcosa non va lo vedi subito.

La chiamata

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mureka-9.5/instrumental",
    "input": {
      "prompt": "strumentale lo-fi hip hop caldo, pianoforte elettrico morbido, leggero crepitio di vinile, 80 bpm rilassati, nessuna voce"
    }
  }'

Imposta prima le due variabili d'ambiente, così nessuna informazione sensibile resta in chiaro nella cronologia della shell oltre al contenuto che scegli:

export HIAPI_BASE_URL="https://api.hiapi.ai/v1/..."   # 使用该端点有文档记录的路径
export HIAPI_API_KEY="your_api_key_here"

Cosa fa ogni parte

• -X POST — l'invio è un'operazione di creazione.
• -H "Authorization: Bearer ..." — autentica la chiamata con il tuo account.
• -H "Content-Type: application/json" — dice al server che il corpo è JSON; se lo ometti, molti server rifiutano direttamente il corpo.
• -d '{...}' — il payload JSON. Il campo model specifica l'endpoint; l'oggetto input contiene il prompt e gli altri campi documentati.
• -sS — modalità silenziosa per l'avanzamento, ma mostra comunque gli errori. Utile negli script.

Leggere la risposta

La risposta è JSON. Devi cercare un identificatore di task o job e un campo di stato. Stampala in modo leggibile per ispezionarla:

curl -sS -X POST "$HIAPI_BASE_URL" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | jq .

Conserva l'identificatore. È il riferimento per ogni successiva verifica di stato. Non analizzare l'intero corpo della risposta nella tua applicazione; estrai l'ID del task e lo stato, e memorizza la risposta grezza per il debug.

Se ottieni uno stato diverso da 2xx, leggi il corpo: HiAPI restituisce messaggi di errore strutturati che di solito indicano il campo problematico.

La stessa richiesta in Python

La versione Python corrisponde esattamente alla chiamata curl: stessi header, stesso corpo JSON. Usa requests per semplicità, oppure la libreria standard se vuoi zero dipendenze.

Con requests

import os
import requests

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

payload = {
    "model": "mureka-9.5/instrumental",
    "input": {
        "prompt": (
            "strumentale lo-fi hip hop caldo, pianoforte elettrico morbido, "
            "leggero crepitio di vinile, 80 bpm rilassati, nessuna voce"
        )
    },
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

resp = requests.post(BASE_URL, json=payload, headers=headers, timeout=30)
resp.raise_for_status()
data = resp.json()
job_id = data["id"]          # use the documented field name
print("submitted:", job_id, data.get("status"))

Con la libreria standard

Se non puoi aggiungere dipendenze:

import json, os, urllib.request

req = urllib.request.Request(
    os.environ["HIAPI_BASE_URL"],
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(req, timeout=30) as r:
    data = json.load(r)

Abitudini utili

• Usa timeout=30 solo per l'invio. Il polling richiede il proprio ciclo e i propri timeout.
• Chiama raise_for_status() prima di analizzare la risposta. Un corpo di errore non è un task.
• Racchiudi l'estrazione dell'ID del task in una piccola funzione di supporto, così un cambio di nome del campo richiede una sola riga.
• Non registrare mai la chiave API; registra invece l'ID del task e lo stato.
• Mantieni il payload come dizionario nel codice, serializzalo una volta sola, così i test possono fare asserzioni su di esso.

Gestire task asincroni e polling

L'invio è solo il primo passo. La generazione avviene lato server e si completa più tardi, quindi esegui polling sull'endpoint di stato finché il task non riporta uno stato terminale.

La forma del ciclo

1. Invia il task e cattura l'ID.
2. Attendi brevemente.
3. Interroga lo stato per quell'ID.
4. Se lo stato è in coda o in elaborazione, applica un backoff e ripeti.
5. Se lo stato è di successo, leggi l'output.
6. Se lo stato è di fallimento, registra l'errore e fermati: non riprovare alla cieca.

Un'implementazione affidabile

import time, random, requests

def wait_for_job(job_id, base_status_url, headers,
                 timeout_s=600, initial_delay=2.0, max_delay=30.0):
    deadline = time.monotonic() + timeout_s
    delay = initial_delay

    while time.monotonic() < deadline:
        r = requests.get(f"{base_status_url}/{job_id}", headers=headers, timeout=30)
        r.raise_for_status()
        status = r.json()["status"]

        if status in ("succeeded", "completed", "success"):
            return r.json()
        if status in ("failed", "error", "cancelled"):
            raise RuntimeError(f"job {job_id} ended as {status}: {r.text}")

        time.sleep(delay + random.uniform(0, 0.5))   # jitter
        delay = min(delay * 1.5, max_delay)          # exponential backoff

    raise TimeoutError(f"job {job_id} did not finish in {timeout_s}s")

Perché ogni dettaglio conta

• Jitter evita retry sincronizzati quando molti task girano in parallelo.
• Backoff evita di martellare l'endpoint di stato mentre il brano viene renderizzato.
• Scadenza trasforma un blocco infinito in un'eccezione pulita che la pipeline può gestire.
• Controllo degli stati terminali deve corrispondere alle stringhe di stato documentate da HiAPI. Verificale con il riferimento API invece di fidarti di supposizioni.
• Retry vanno applicati agli errori di rete transitori (timeout, 5xx), non a un task già fallito per un errore di validazione.

Suggerimenti operativi

Persisti il job_id prima di iniziare il polling. Se il processo muore, puoi riprendere il polling invece di pagare per una seconda generazione. Registra le transizioni di stato con timestamp, così vedi dove va il tempo. Se esegui molti task, esegui il polling di pochi task in parallelo tramite una coda, invece di bloccare un thread di richiesta per ogni task.

Ottenere l'output strumentale e scaricarlo

La modalità strumentale è espressa dalla tua richiesta: l'endpoint è dedicato a questo tipo di output. In pratica la formulazione del prompt lo rafforza: nomina gli strumenti, descrivi l'atmosfera e dichiara che non ci sono voci. Un prompt che chiede linee vocali va contro lo scopo dell'endpoint.

Dove compare l'audio

Quando il task raggiunge uno stato di successo, la risposta di stato trasporta il risultato. Aspettati che l'audio venga consegnato come URL da scaricare separatamente, non come base64 nel JSON di stato. Leggi la risposta ed estrai l'URL di download dal campo di output documentato.

result = wait_for_job(job_id, status_url, headers)
# 前几次仔细检查结果，然后固定该字段。
audio_url = result["output"]["audio_url"]   # 在 API 参考中确认字段名

with requests.get(audio_url, stream=True, timeout=60) as r:
    r.raise_for_status()
    with open(f"{job_id}.mp3", "wb") as f:
        for chunk in r.iter_content(chunk_size=65536):
            f.write(chunk)

Abitudini di download

• Scrivi su disco in streaming. I file musicali sono grandi; caricarli interamente in memoria è uno stress evitabile.
• Controlla il tipo di contenuto. Salva il file con l'estensione suggerita dalla risposta, non con un'estensione codificata a mano.
• Considera l'URL temporaneo. Scarica subito, oppure persisti l'URL solo se la documentazione lo indica come stabile. Copia i byte nel tuo storage per una conservazione duratura.
• Scarica una sola volta. Scaricare in un ciclo di retry senza un marcatore di completamento crea facilmente file parziali. Scrivi con un nome temporaneo e rinomina dopo il successo.
• Registra la provenienza. Conserva l'ID del task e il prompt insieme al file. Quando in futuro ti servirà una variante, avrai gli input esatti.

Punti di fallimento comuni e rimedi

La maggior parte dei problemi di prima integrazione rientra in una lista breve. Ecco la checklist.

401 / 403 — autenticazione. L'header è sbagliato, la chiave manca, oppure la variabile d'ambiente si risolve in una stringa vuota. Verifica che la chiave sia impostata nella stessa shell o nello stesso processo che esegue il codice, e che l'header sia esattamente Authorization: Bearer <key>.

400 — payload malformato. Manca model, c'è un errore di battitura in mureka-9.5/instrumental, JSON non valido, o un campo che l'endpoint non accetta. Prima invia il corpo con curl per isolare il payload dal codice. Valida il JSON prima di inviarlo; le virgole finali sono il classico problema.

415 o errore di corpo vuoto — content type. Deve essere presente Content-Type: application/json. Alcuni client HTTP lo impostano da soli quando passi json=, ma non tutti.

Timeout del polling. La tua scadenza è troppo corta, il backoff è troppo aggressivo, oppure il task è effettivamente fallito e tu lo hai classificato come ancora in esecuzione. Verifica le stringhe di stato esatte con la documentazione e stampa ogni transizione di stato durante il debug.

URL di download mancante. Hai letto il campo sbagliato, oppure hai letto la risposta prima che il task raggiungesse lo stato terminale di successo. Registra una volta un payload di successo completo, conferma il percorso dell'URL audio, poi fissalo.

Generazioni duplicate. Il tuo poller è andato in crash e qualcosa ha reinviato. Persisti l'ID del task prima del polling e controlla i task esistenti prima di inviarne uno nuovo.

Rate limit. Applica backoff con jitter alle risposte 429 e accoda il lavoro, invece di scatenare richieste simultanee da molti thread.

Affrontali in quest'ordine — autenticazione, payload, content type, polling, output — e di solito troverai la causa al primo colpo. Una volta che la chiamata curl e la sua gemella Python riescono end-to-end, l'endpoint sta facendo ciò che gli chiedi: trasformare un prompt in un brano strumentale e consegnarti un URL di download.