Come usare la MiniMax Music API (minimax-music-1.5): curl, Python e richieste eseguibili

Questa guida spiega come usare minimax-music-1.5 sull'API unificata delle attività di hiapi per generare una canzone completa — con voce, strumenti e struttura del brano — a partire da un prompt di stile e da un testo. Tutti i contenuti seguenti sono stati verificati sull'endpoint reale e possono essere copiati, incollati ed eseguiti direttamente.

Cosa costruirai e cosa ti serve

Obiettivo: inviare una descrizione testuale dello stile musicale e il tuo testo, per ottenere una traccia audio scaricabile.

Ti serve una sola cosa: una chiave API hiapi. Ottienila dalla tua dashboard — inizia con sk-. Tutti gli esempi seguenti presuppongono che sia salvata in una variabile d'ambiente:

export HIAPI_KEY="sk-your-key-here"

La generazione musicale su hiapi usa la stessa interfaccia asincrona a task di tutti gli altri modelli: POST /v1/tasks crea il task, poi puoi fare polling su GET /v1/tasks/<taskId> oppure ricevere un callback al completamento del task.

Schema di input (verificato)

minimax-music-1.5 accetta i seguenti campi in input — qualsiasi altro campo viene rifiutato con 400:

Campo	Obbligatorio	Tipo	Vincoli
prompt	Sì	string	10–300 caratteri. Descrive genere, atmosfera, strumentazione e stile vocale.
lyrics	Sì	string	10–600 caratteri. Il testo da cantare; supporta tag di sezione come [Verse] e [Chorus].
sample_rate	No	integer	Uno tra 16000, 24000, 32000, 44100.
bitrate	No	integer	Uno tra 32000, 64000, 128000, 256000.

Due punti in cui è facile inciampare:

1. prompt e lyrics sono entrambi obbligatori. Il prompt controlla come suona; lyrics controlla cosa viene cantato. Se ne manca uno si ottiene invalid input: ... missing required field.
2. Lo schema è rigoroso. Campi che potresti aspettarti da altre API musicali — duration, seed, format, instrumental — non sono accettati. Inviarli restituisce additional properties ... not allowed.

Esempio minimo eseguibile: curl

Crea il task:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-1.5",
    "input": {
      "prompt": "Uplifting acoustic pop, warm female vocals, gentle guitar and light percussion",
      "lyrics": "[Verse]\nMorning light on a quiet street\nCoffee steam and a steady beat\n[Chorus]\nWe keep on going, we find our way\nOne small step at a time, every day",
      "sample_rate": 44100,
      "bitrate": 256000
    }
  }'

La creazione riuscita restituisce un id del task:

{"code": 200, "data": {"taskId": "task_abc123..."}}

Poi fai polling finché il task non raggiunge lo stato finale:

curl https://api.hiapi.ai/v1/tasks/task_abc123 \
  -H "Authorization: Bearer $HIAPI_KEY"

Mentre il task è in esecuzione vedrai uno status non finale; al completamento status diventa success e l'URL audio compare in output:

{
  "code": 200,
  "data": {
    "taskId": "task_abc123",
    "status": "success",
    "output": [{"url": "https://.../track.mp3"}]
  }
}

Scarica il file il prima possibile — gli URL di output hanno una scadenza e vanno trattati come una finestra di ritiro, non come archiviazione permanente:

curl -o track.mp3 "https://.../track.mp3"

Script Python completo: invio, polling, download

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_KEY']}",
    "Content-Type": "application/json",
}

def create_task() -> str:
    payload = {
        "model": "minimax-music-1.5",
        "input": {
            "prompt": ("Uplifting acoustic pop, warm female vocals, "
                       "gentle guitar and light percussion"),
            "lyrics": ("[Verse]\nMorning light on a quiet street\n"
                       "Coffee steam and a steady beat\n"
                       "[Chorus]\nWe keep on going, we find our way\n"
                       "One small step at a time, every day"),
            "sample_rate": 44100,
            "bitrate": 256000,
        },
    }
    r = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    data = r.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = (r.json().get("data") or {})
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

def download(url: str, path: str = "track.mp3") -> str:
    r = requests.get(url, timeout=120)
    r.raise_for_status()
    with open(path, "wb") as f:
        f.write(r.content)
    return path

if __name__ == "__main__":
    task_id = create_task()
    print(f"submitted: {task_id}")
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    print(f"done, downloading: {url}")
    print(f"saved to {download(url)}")

Eseguilo con python3 make_song.py. Lo script invia il task, fa polling ogni 5 secondi e salva localmente la traccia completata.

Modalità per la produzione

Usare i callback invece del polling

Per qualsiasi uso che vada oltre un semplice script, registra un callback per far sì che hiapi ti invii il risultato quando il task raggiunge lo stato finale. Aggiungi un oggetto callback di primo livello (allo stesso livello di model, non dentro input):

{
  "model": "minimax-music-1.5",
  "input": {"prompt": "...", "lyrics": "..."},
  "callback": {"url": "https://your.domain.example/hiapi/callback", "when": "final"}
}

È supportato solo "when": "final" — riceverai una POST una sola volta al successo o al fallimento del task, non eventi di avanzamento incrementali. Il polling è adatto allo sviluppo e ai task una tantum; i callback sono preferibili quando devi generare molte tracce o quando operi in coda, perché non devi mantenere un ciclo aperto né rischi di attivare limiti di frequenza con polling ad alta frequenza. Se il callback non arriva mai, segui la checklist in Perché il tuo callback dei task hiapi non si attiva.

Idempotenza e retry

La creazione del task non è di per sé idempotente: riprovare un POST /v1/tasks andato in timeout può creare due task (e generare due addebiti). Persisti il taskId non appena la chiamata di creazione restituisce un risultato e, al riavvio, riprendi facendo polling su quell'id invece di inviare di nuovo alla cieca. Se un task sembra bloccato, non terminarlo e ricrearlo subito — vedi hiapi /v1/tasks quando un task si blocca o va in timeout per capire come distinguere un task lento da un task morto.

Gestione degli errori

Due tipi di errore si comportano diversamente:

• Errori a livello di richiesta restituiti in modo sincrono. Una chiave errata o non autorizzata restituisce l'errore permission_denied ("This API key cannot use the selected model..."), con un request_id da citare al supporto. Le violazioni dello schema restituiscono 400 INVALID_REQUEST con un messaggio preciso, ad esempio prompt: minLength: got 1, want 10.
• Errori a livello di task compaiono nel risultato del polling/callback come status: "fail", con error.code e error.message — la chiamata di creazione è riuscita, ma la generazione non è riuscita. Sono questi gli errori che devono entrare nella logica di retry.

Convalida le lunghezze sul client prima dell'invio: prompt massimo 300 caratteri, lyrics massimo 600 caratteri; l'API rifiuta gli input troppo lunghi invece di troncarli.

Prezzi e limiti

MiniMax Music 1.5 viene fatturato per traccia generata, con prezzi a consumo — consulta le tariffe attuali nella pagina dei prezzi di hiapi e nella pagina del modello minimax-music-1.5, dove puoi anche provare il modello nel playground prima di scrivere qualsiasi codice.

Domande frequenti

Quali campi di input accetta minimax-music-1.5?

Esattamente quattro: prompt (obbligatorio, 10–300 caratteri), lyrics (obbligatorio, 10–600 caratteri), sample_rate (opzionale, 16000/24000/32000/44100) e bitrate (opzionale, 32000/64000/128000/256000). Qualsiasi altro campo viene rifiutato con additional properties not allowed.

È possibile controllare la struttura del brano?

Sì — usa tag di sezione come [Verse] e [Chorus] in lyrics per organizzare la struttura. Il modello usa questi tag per modellare l'arrangiamento. L'intera stringa dei lyrics (tag inclusi) deve restare entro il limite di 600 caratteri.

È possibile generare musica puramente strumentale?

Lo schema di input non ha un interruttore per la modalità strumentale. L'endpoint è guidato dai lyrics, quindi descrivi nel prompt la strumentazione e l'atmosfera che desideri; per i casi d'uso puramente strumentali consulta la pagina del modello per l'elenco aggiornato delle capacità.

Come si ottiene il file audio?

Quando lo stato del task è success, il link per il download è in data.output[0].url. Scaricalo subito e archivia i byte per conto tuo — gli URL di output scadono.

Conviene fare polling o usare i callback?

Per lo sviluppo e per singoli task usa il polling (un intervallo di 5 secondi è sufficiente). In produzione usa il callback con when: "final" per evitare di mantenere aperte le connessioni — soprattutto quando generi tracce in batch.

Perché ricevo permission_denied?

La tua chiave non è valida oppure non ha accesso a quel modello. Verifica la chiave nella dashboard e assicurati di inviarla come Authorization: Bearer sk-....