API minimax-music-3: guida con curl e Python

Con hiapi, generare un brano con minimax-music-3 richiede solo una chiamata POST /v1/tasks più il polling: esattamente lo stesso pattern di attività asincrona utilizzato da tutti i modelli della piattaforma. Questa guida documenta richieste e risposte reali (creazione dell'attività, polling e URL audio finale), quindi il codice riportato di seguito è copiabile ed eseguibile, non solo illustrativo.

Cosa ti serve

1. Una chiave API hiapi — creala nella console. Viene inviata come token Bearer a ogni richiesta.
2. Tutto qui. A differenza dei modelli di generazione video da immagine o immagine da immagine, minimax-music-3 non accetta alcun file o URL in input: genera esclusivamente dal testo.

Richiesta minima funzionante (curl)

Crea l'attività:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-3",
    "input": {
      "prompt": "chill lofi hip hop beat, mellow piano, soft drums",
      "lyrics": "[Instrumental]"
    }
  }'

Risposta:

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

Esegui il polling dell'attività fino al completamento:

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55 \
  -H "Authorization: Bearer sk-<your-key>"

Durante l'esecuzione, status passa da handling a archiving e infine a success (oppure failed). Nei test, un brano ha impiegato circa due minuti e mezzo dalla sottomissione a success. La risposta al completamento è la seguente:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55",
    "status": "success",
    "model": "minimax-music-3",
    "created": 1787018905,
    "completed": 1787019051,
    "storage": "temp",
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M09A11R6WEC2JDQ8RK6E7N55-0.wav",
        "artifactId": "78585",
        "expireAt": 1787623851
      }
    ]
  },
  "message": "success"
}

output[0].url è il file WAV. Fai attenzione a expireAt: prima di costruire qualsiasi funzionalità che si basi sulla validità a lungo termine di questo URL, leggi la nota sull'archiviazione riportata di seguito.

Lo stesso flusso in Python

import time
import requests

API_KEY = "sk-<your-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_track(prompt: str, lyrics: str = "[Instrumental]") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={"model": "minimax-music-3", "input": {"prompt": prompt, "lyrics": lyrics}},
        timeout=30,
    )
    body = resp.json()
    if resp.status_code != 200 or "error" in body:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]


def wait_for_track(task_id: str, timeout_s: int = 300, interval_s: int = 6) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_track("upbeat synthwave, driving bassline, retro 80s")
    audio_url = wait_for_track(task_id)
    audio = requests.get(audio_url, timeout=60).content
    with open("track.wav", "wb") as f:
        f.write(audio)
    print(f"saved track.wav from task {task_id}")

Parametri effettivamente validati da minimax-music-3

Lo schema di input è rigoroso: se invii campi non elencati, l'API rifiuta l'intera richiesta prima ancora di metterla in coda:

• prompt (stringa, obbligatorio) — stile, atmosfera, strumentazione. È ciò che determina di fatto la forma del brano.
• lyrics (stringa, obbligatorio) — sempre obbligatorio, anche per brani puramente strumentali. Passa "[Instrumental]" come segnaposto; per brani con parti cantate, usa tag di sezione come [Verse] / [Chorus].
• callback (oggetto, facoltativo) — {"url": "...", "when": "final"}. L'unico valore supportato per when è "final"; qualsiasi altro valore restituisce 400 con il messaggio invalid callback.when: only 'final' is supported.

Se invii qualcosa al di fuori di queste tre chiavi di primo livello — come sample_rate, duration o un refuso — otterrai:

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'sample_rate' not allowed"}

Considerazioni per la produzione

• Due forme di errore diverse. Gli errori di validazione (campi mancanti, valori di enumerazione errati, chiavi sconosciute) restituiscono al livello superiore {"code":400,"error_code":"INVALID_REQUEST","message":"..."}. Gli errori di autenticazione/autorizzazione restituiscono invece {"error":{"code":"permission_denied","message":"...","request_id":"..."}} — un oggetto error annidato, con HTTP 401. Controlla entrambe le forme nella tua gestione degli errori; un codice che verifica solo resp["code"] non intercetta il caso 401.
• permission_denied indica un problema della chiave, non della richiesta. Se prompt/lyrics sono presenti e del tipo corretto ma ricevi comunque un 401 permission_denied, significa che la chiave API stessa non ha questo modello abilitato: controllala nella console invece di rileggere il tuo JSON.
• L'archiviazione dei file di output è temporanea. storage: "temp" e un timestamp Unix expireAt su ogni output — nell'esempio catturato, circa 7 giorni dopo la creazione. Scarica subito il file o trasferiscilo nel tuo storage non appena l'attività ha successo; non conservare gli URL temp.hiapi.ai come se fossero link permanenti.
• Per qualsiasi attività in batch, usa i callback. Fare polling per un brano va bene; farlo per cinquanta brani significa cinquanta andata e ritorno ripetuti. Imposta callback.url e when: "final" per far sì che hiapi ti invii il risultato in un'unica notifica quando l'attività è davvero completata.
• Riprova prima di ottenere il taskId, non dopo. Riprovare in caso di errore di rete o 5xx sulla POST /v1/tasks iniziale è sicuro: a quel punto non è ancora stato creato nulla. Una volta ottenuto il taskId, reinviare lo stesso prompt crea un altro brano non correlato: in quel caso esegui il polling o attendi il callback.

Contenuti correlati

• Pagina del modello minimax-music-3 — prezzi attuali e area di prova online.
• Prezzi di hiapi — tariffe per tutti i modelli del catalogo.
• Documentazione di hiapi — riferimento API completo, oltre a questo singolo modello.

Domande frequenti

Devo fornire i testi per un brano puramente strumentale? Sì: indipendentemente dal fatto che tu voglia le voci, lyrics è un campo obbligatorio. Passa "[Instrumental]" e il modello genererà un brano senza parti cantate.

Posso evitare del tutto il polling? Sì, impostando callback: {"url": "https://your-endpoint", "when": "final"} al momento della creazione dell'attività. Quando l'attività raggiunge lo stato finale, hiapi invierà via POST al tuo URL lo stesso payload di GET /v1/tasks/:id. Al momento "final" è l'unico valore supportato per when.

Perché ricevo "additional properties not allowed"? Lo schema di input di minimax-music-3 accetta all'interno di input solo prompt e lyrics (più callback al livello superiore). Qualsiasi altro nome di campo — anche se funziona su altri modelli hiapi — viene rifiutato prima che la richiesta venga eseguita.

Perché una chiave che funziona su altri modelli restituisce 401 su questo modello? L'accesso ai modelli è concesso per chiave. Un 401 con error_code: "permission_denied" significa che a quella specifica chiave non è ancora stata concessa l'autorizzazione per minimax-music-3: abilitala nella console, non è un bug nel tuo corpo della richiesta.

Quanto posso aspettare prima di scaricare il file di output? Non aspettare: output[0].url è un link temporaneo (in pratica expireAt scade dopo circa una settimana). Trattalo come un passaggio usa e getta: scarica o ricarica subito dopo il successo dell'attività.