Tutoriale
Tutorial API minimax-music-1.5: curl e Python Requests
In questa pagina
Requisiti delle richieste a minimax-music-1.5
Prima di scrivere la prima riga di codice, è meglio capire bene cosa comprende una chiamata di generazione musicale. A differenza del completamento di testo, una richiesta musicale ha due input creativi con ruoli distinti, più alcuni controlli che modellano l'output.
A livello alto, una richiesta a minimax-music-1.5 comprende:
- Descrizione dello stile o del prompt — la direzione musicale: genere, mood, arrangiamento strumentale, percezione del tempo, caratteristiche di produzione.
- Testo — quando il brano è vocale, il testo effettivamente cantato. Per le richieste puramente strumentali, lascialo vuoto o ometti questo campo.
- Controllo della struttura — ad esempio la durata target del brano generato, che limita la lunghezza della composizione del modello.
- Identificatore del modello —
minimax-music-1.5— che consente al gateway di instradare il task al backend corretto.
Il modello mentale da tenere a mente: l'input di stile dice al modello come deve suonare, l'input del testo gli dice cosa viene cantato. I due non sono intercambiabili. Se infili una descrizione di genere nel campo del testo otterrai output confusi; se lasci il testo vuoto ma chiedi un brano vocale, il modello dovrà inventarselo. Prima di iniziare, stabilisci in quale dei due modi ti trovi.
Ci sono altri due punti da interiorizzare prima di scrivere codice:
- La generazione musicale non è istantanea. Generare un brano finito richiede tempo di calcolo reale, quindi l'API è asincrona per progettazione. Invii un task, poi recuperi il risultato. Qualsiasi tutorial che mostri solo una chiamata bloccante ti sta nascondendo il ciclo di polling.
- L'output viene consegnato tramite riferimento. Ricevi un URL dell'audio generato, non byte grezzi inline. Devi scaricarlo o trasmetterlo separatamente.
Una volta che sai spiegare chiaramente queste tre cose — la differenza tra stile e testo, il ciclo di vita asincrono, l'output basato su URL — il corpo effettivo della richiesta diventa facile da leggere.
Configurazione iniziale su HiAPI
Prima della prima chiamata ti servono tre cose: una chiave API, l'indirizzo base dell'interfaccia e l'abitudine di non codificare la chiave nel codice.
Chiave API
Crea la chiave nella console del tuo account HiAPI. Trattala come una password: autentica ogni richiesta ed è legata al consumo del tuo account. Non salvarla mai nel repository, non incollarla mai in un gist pubblico e non inserirla mai nel bundle di un'app mobile o browser.
Indirizzo base dell'interfaccia
Tutte le chiamate vanno al gateway HiAPI, che espone minimax-music-1.5 dietro un'unica interfaccia unificata. Non ti servono credenziali o SDK separati per ogni modello — il nome del modello nel corpo della richiesta seleziona il backend. Consulta la documentazione di riferimento dell'API per l'URL base esatto e il percorso attuale della richiesta.
Tenere la chiave fuori dal codice sorgente
Il pattern che vale dagli script temporanei alla produzione è la variabile d'ambiente:
export HIAPI_API_KEY="your-key-here"
Poi leggila a runtime. In Python è os.environ["HIAPI_API_KEY"]; nella shell è $HIAPI_API_KEY. Se usi localmente un file .env, aggiungilo a .gitignore prima del primo commit — non dopo. Per i servizi in deployment, inietta la chiave tramite il gestore dei segreti della piattaforma, non inserirla nell'immagine.
Fai un controllo rapido prima di costruire qualsiasi cosa: verifica che il processo che stai per avviare veda la chiave (esegui echo $HIAPI_API_KEY nella stessa shell). La maggior parte delle segnalazioni di “autenticazione fallita” risale all'aver esportato la chiave in un terminale e aver eseguito lo script in un altro.
Inviare la prima richiesta funzionante con curl
Inizia con curl. Rimuove ogni livello di astrazione e ti mostra esattamente cosa viaggia sulla rete. La richiesta seguente genera un breve brano vocale; adatta i valori dei campi alle tue intenzioni.
curl -X POST "$HIAPI_BASE_URL/minimax-music-1.5" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-music-1.5",
"prompt": "folk indie caldo, chitarra acustica fingerstyle, spazzolato leggero, voce intima ravvicinata",
"lyrics": "[verse]\nLa luce del mattino sul pavimento della cucina\n[chorus]\nSiamo ancora qui, siamo ancora qui",
"duration": 30
}'
Riga per riga:
-X POST— la generazione è un'operazione di creazione, non di lettura.Authorization: Bearer $HIAPI_API_KEY— la chiave della sezione precedente, espansa dalla shell, quindi finché usi la variabile non appare nella cronologia.Content-Type: application/json— il gateway si aspetta JSON; omettere questo header è una causa comune di risposte 4xx confuse.model— fissa la richiesta a minimax-music-1.5.prompt— descrizione dello stile. Specifica arrangiamento strumentale e mood, non un solo aggettivo.lyrics— il testo cantato, con tag leggeri di sezione come[verse]e[chorus]per suggerire la struttura. L'escape\nè l'a capo di JSON.duration— limita in secondi la lunghezza del brano generato.
La risposta è un riferimento al task, non l'audio. Catturalo:
curl -s -X POST "$HIAPI_BASE_URL/minimax-music-1.5" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @payload.json | tee job.json
Usare -d @payload.json per leggere il corpo da file mantiene pulita la cronologia della shell e rende il passaggio a Python semplicissimo — quel file è il corpo della richiesta. Esamina la risposta, annota l'identificatore del task o job e qualsiasi campo di stato; ti servirà quell'identificatore per recuperare il risultato.
Portare la richiesta in Python
La versione Python dovrebbe sembrare una trascrizione della chiamata curl, non una riscrittura. Usa requests, leggi la chiave dall'ambiente e mantieni il corpo come dizionario per leggibilità.
import os
import json
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]
payload = {
"model": "minimax-music-1.5",
"prompt": "folk indie caldo, chitarra acustica fingerstyle, spazzolato leggero, voce intima ravvicinata",
"lyrics": "[verse]\nLa luce del mattino sul pavimento della cucina\n[chorus]\nSiamo ancora qui, siamo ancora qui",
"duration": 30,
}
response = requests.post(
f"{BASE_URL}/minimax-music-1.5",
headers={
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
},
data=json.dumps(payload),
timeout=60,
)
response.raise_for_status()
job = response.json()
print(json.dumps(job, indent=2))
Alcune note di porting per evitare sorprese:
- Usa
json.dumpscondata=, oppurejson=payload. Entrambi funzionano;json=payloadfa impostare arequestsil tipo di contenuto. Se passi un dizionario direttamente adata=senza serializzarlo, il server riceverà un corpo con codifica form e lo rifiuterà. - Imposta sempre un
timeout. Altrimenti una connessione bloccata farà restare il processo appeso all'infinito. Ricorda che questo timeout copre l'invio, non la generazione — quello è il problema della sezione successiva. - Chiama
raise_for_status()prima di fare il parsing. Trasforma un 4xx o 5xx in un'eccezione chiara, invece di un misteriosoKeyErrorquando accedi a un campo inesistente. - Conserva l'oggetto response. In debug, stampare
response.status_codeeresponse.textti dice molto più dell'errore già interpretato.
Il risultato di questo script è lo stesso riferimento al task prodotto da curl. Tutto ciò che segue l'invio — polling, retry, download — è identico in qualsiasi linguaggio, ed è proprio per questo che merita una sezione a parte.
Gestire il ciclo di vita dei task asincroni
L'errore più comune nella generazione musicale è trattarla come un completamento chat: invia, aspetta, leggi il brano. La chiamata di invio torna rapidamente, ma l'audio non esiste ancora. Il tuo codice deve chiudere il ciclo.
I tre stati
Ogni task attraversa una piccola macchina a stati:
- Inviato (Submitted) — hai ottenuto l'identificatore del task, il lavoro è in coda o in esecuzione.
- Completato (Finished) — l'audio è pronto, la risposta contiene l'URL che vi punta.
- Fallito (Failed) — la generazione è stata interrotta; la risposta ne spiega il motivo.
Il tuo ciclo di polling deve distinguere tutti e tre gli stati. Lo stato submitted significa continuare ad attendere, non riprovare.
Fai polling, non martellare
Un ciclo ingenuo che effettua controlli di stato alla massima velocità consentita dalla CPU consuma i limiti di frequenza senza dirti nulla di nuovo — il rendering di un brano richiede decine di secondi, quindi centinaia di controlli al minuto sono puro spreco. Aggiungi un backoff:
import time
def wait_for_job(job_id, base_url, api_key, interval=2.0, max_wait=300):
deadline = time.time() + max_wait
while time.time() < deadline:
r = requests.get(
f"{base_url}/jobs/{job_id}",
headers={"Authorization": f"Bearer {api_key}"},
timeout=30,
)
r.raise_for_status()
data = r.json()
status = data.get("status")
if status == "finished":
return data
if status == "failed":
raise RuntimeError(f"job failed: {data}")
time.sleep(interval)
raise TimeoutError(f"job {job_id} not finished after {max_wait}s")
Consulta la documentazione di riferimento dell'API per il percorso esatto di polling e le stringhe di stato — considera i nomi sopra come illustrativi e allineali ai valori della documentazione.
Riprova l'oggetto giusto
I retry appartengono a due livelli diversi, e confonderli porta a lavoro duplicato. Retry di trasporto — la chiamata HTTP stessa fallisce per un 5xx o un reset di connessione — è ripetibile in sicurezza per le richieste di polling. Retry di generazione è invece un nuovo invio, che costa un altro rendering, quindi fallo solo quando il task riporta esplicitamente un fallimento e con un limite di tentativi. Non riprovare mai l'invio solo perché il polling è lento.
Infine, rendi persistente l'identificatore del task nel momento stesso in cui lo ricevi. Se il tuo processo va in crash tra l'invio e il completamento, quell'identificatore è l'unico modo per recuperare il brano completato senza pagare una nuova generazione.
Regolare testo, stile e durata
Ottenere un brano utilizzabile da minimax-music-1.5 dipende soprattutto dallo scrivere i due campi di testo con intenzione. Alcune abitudini determinano se l'output è generico o qualcosa che pubblicheresti davvero.
Scrivere il prompt di stile come un briefing del produttore
Una singola parola di genere lascia al modello troppa libertà. Sovrapponi dimensioni concrete:
- Genere ed epoca — “trip hop di fine anni '90” è meglio di “elettronica”.
- Arrangiamento strumentale — nomina gli strumenti solisti e la sezione ritmica.
- Mood ed energia — “malinconico ma con spinta” crea una tensione che un solo aggettivo non può esprimere.
- Caratteristiche di produzione — “lo-fi, saturazione nastro, stereo ampio” guidano il mix.
Mantieniti su una o due frasi. I prompt a paragrafi lunghi tendono a diluire invece che a rifinire.
Organizzare la struttura del testo con i tag
Marcatori di sezione leggeri — [verse], [chorus], [bridge] — danno al modello una mappa e producono di solito una struttura di canzone più chiara rispetto a un blocco unico senza marcatori. Mantieni ogni riga abbastanza corta da essere cantata; una riga di dodici parole raramente si adatta a una melodia. Per i brani strumentali, ometti del tutto lyrics invece di inviare una stringa vuota contenente testo di stile.
Far corrispondere la durata al materiale
La durata limita la composizione. Una durata breve con un testo completo verso-ritornello-verso costringe a comprimere e finisce per suonare affrettato; una durata lunga con due righe di testo invita alla ripetizione. Decidi prima la forma del brano, poi imposta una durata coerente. Se ti serve un lavoro più lungo, espandi il testo invece di allungare il tempo sperando che funzioni.
Iterare con piccole modifiche
Quando un brano è vicino ma non giusto, cambia un solo input alla volta — l'arrangiamento nel prompt, o una parola sul tempo, o quella riga di testo che non funziona. Cambiare tutto insieme ti impedisce di sapere quale campo ha portato il miglioramento. Conserva il tuo miglior corpo di richiesta in un file e ramifica da lì.
Diagnosticare gli errori comuni
La maggior parte dei fallimenti ricade in poche categorie riconoscibili. Abbina il sintomo, applica la correzione e vai avanti.
Fallimenti di autenticazione
Sintomo: 401 o 403, con messaggio relativo alle credenziali.
- Verifica che l'header sia
Authorization: Bearer <key>— la parolaBearere lo spazio sono obbligatori. - Controlla che la variabile d'ambiente sia effettivamente impostata nel processo che effettua la richiesta. Una chiave esportata in una shell non arriva a un cron job o a un container Docker.
- Controlla spazi o a capo extra copiati insieme alla chiave.
Corpo della richiesta malformato
Sintomo: 400, con messaggio di validazione.
- Invia
Content-Type: application/json. La mancanza di questo header fa interpretare male al server un corpo di richiesta del tutto corretto. - Se usi
requests, passajson=payloadoppuredata=json.dumps(payload). Passare il dizionario grezzo adata=lo codifica come form. - Valida nomi e tipi dei campi rispetto alla documentazione di riferimento dell'API:
modeldeve essere esattamenteminimax-music-1.5,durationè un intero, gli a capo del testo vanno correttamente escapati come\nin JSON. - Nel dubbio, usa
curl -d @payload.jsonper isolare se il corpo stesso è valido prima di coinvolgere Python.
Timeout ed errori di connessione
Sintomo: la richiesta si blocca o viene lanciato un errore di connessione.
- Imposta un
timeoutesplicito per ogni chiamata. Il timeout di invio deve essere abbastanza ampio da coprire il ritardo di coda, ma non è il tempo di rendering. - Non impostare il timeout di polling uguale al
max_waitcomplessivo; un singolo controllo di stato lento non deve interrompere un task ancora in esecuzione. - Se l'invio va ripetutamente in timeout mentre il polling riesce, il tuo corpo potrebbe essere troppo grande — riduci il testo.
Errori di polling
Sintomo: continui a fare polling ma non vedi mai finished, oppure stai interrogando la risorsa sbagliata.
- Verifica di usare l'identificatore del task dalla risposta di invio, non l'ID della richiesta o un header di correlazione.
- Considera
submitted/runningcome “continua ad attendere” e non “riprova l'invio”. Invii ripetuti producono un secondo brano. - Aggiungi un backoff. Il polling aggressivo provoca limiti di frequenza, che sembrano fallimenti ma sono autoinflitti.
- Se il task riporta
failed, leggi il messaggio prima di reinviare — tag di testo non validi o durata fuori intervallo falliscono allo stesso modo ogni volta.
Quando sei bloccato, torna alla chiamata curl grezza con -v per vedere la riga di stato e gli header effettivi. Questo passo elimina la maggior parte delle ambiguità più in fretta di qualsiasi quantità di debug Python.
Articoli correlati
Vedi tutti gli articoli →-
Tutoriale
Guida pratica a gpt-6.2-sol: 5 utilizzi ad alto valore dei modelli testuali nel business
-
Tutoriale
Guida pratica a gpt-6.2-astra: integrazione e punti chiave per 5 scenari testuali ad alto valore
Checklist dal punto di vista dello sviluppatore, dalla selezione degli scenari all'implementazione ingegneristica
-
Tutoriale
Scenari pratici di Tripo H3.1: 5 utilizzi ad alto valore e punti di implementazione
Da text-to-3D alla ricostruzione multi-view: scegliere modalità e parametri giusti per ogni scenario di business