Comment utiliser l'API MiniMax Music (minimax-music-1.5) : curl, Python et requêtes exécutables

Ce guide explique comment utiliser minimax-music-1.5 sur l'API de tâches unifiée de hiapi pour générer une chanson complète — voix, instruments et structure — à partir d'un prompt de style et de paroles. Tout ce qui suit a été vérifié sur le point de terminaison réel : vous pouvez copier, coller et exécuter.

Ce que vous allez construire et ce dont vous avez besoin

Objectif : soumettre une description textuelle du style musical et vos paroles, puis obtenir une piste audio téléchargeable.

Vous n'avez besoin que d'une chose : une clé API hiapi. Récupérez-la depuis votre tableau de bord — elle commence par sk-. Tous les exemples ci-dessous supposent qu'elle est stockée dans une variable d'environnement :

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

Sur hiapi, la génération musicale utilise la même interface de tâches asynchrone que tous les autres modèles : POST /v1/tasks crée la tâche, puis vous interrogez GET /v1/tasks/<taskId> ou recevez un callback à la fin de la tâche.

Schéma d'entrée (vérifié)

minimax-music-1.5 accepte les champs suivants dans input — tout autre champ est rejeté avec un code 400 :

Champ	Obligatoire	Type	Contrainte
prompt	Oui	string	10 à 300 caractères. Décrit le genre, l'ambiance, l'instrumentation et le style vocal.
lyrics	Oui	string	10 à 600 caractères. Les paroles à chanter ; les balises de section comme [Verse] et [Chorus] sont prises en charge.
sample_rate	Non	integer	Parmi 16000, 24000, 32000, 44100.
bitrate	Non	integer	Parmi 32000, 64000, 128000, 256000.

Deux pièges fréquents :

1. prompt et lyrics sont tous deux obligatoires. Le prompt détermine le rendu sonore ; les paroles déterminent ce qui est chanté. L'absence de l'un ou de l'autre renvoie invalid input: ... missing required field.
2. Le schéma est strict. Des champs que vous pourriez attendre d'autres API musicales — duration, seed, format, instrumental — ne sont pas acceptés. Les envoyer renvoie additional properties ... not allowed.

Exemple minimal exécutable : curl

Créer la tâche :

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
    }
  }'

Une création réussie renvoie un identifiant de tâche :

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

Interrogez ensuite jusqu'à ce que la tâche atteigne un état terminal :

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

Tant que la tâche s'exécute, vous voyez un status non terminal ; une fois terminée, status passe à success et l'URL audio apparaît dans output :

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

Téléchargez le fichier dès que possible — l'URL de sortie est limitée dans le temps : considérez-la comme une fenêtre de récupération et non comme un stockage permanent :

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

Script Python complet : soumission, interrogation, téléchargement

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)}")

Exécutez-le avec python3 make_song.py. Le script soumet la tâche, interroge toutes les 5 secondes et enregistre la piste terminée localement.

Modes de production

Utiliser un callback au lieu de l'interrogation

Pour tout usage allant au-delà d'un script rapide, enregistrez un callback afin que hiapi vous transmette le résultat lorsque la tâche atteint un état terminal. Ajoutez un objet callback de premier niveau (au même niveau que model, pas à l'intérieur de input) :

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

Seul "when": "final" est pris en charge — vous recevez un POST unique lorsque la tâche réussit ou échoue, et non des événements de progression incrémentale. L'interrogation convient au développement et aux tâches ponctuelles ; les callbacks sont préférables pour générer de nombreuses pistes ou lorsque vous êtes derrière une file d'attente, car vous n'avez pas à maintenir une boucle ouverte et vous évitez les limitations de débit dues à une interrogation trop fréquente. Si le callback n'arrive jamais, parcourez la checklist de Pourquoi votre callback de tâche hiapi ne se déclenche pas.

Idempotence et nouvelles tentatives

La création de tâche n'est pas idempotente : réessayer un POST /v1/tasks expiré peut créer deux tâches (et entraîner deux facturations). Persistez le taskId dès le retour de l'appel de création, et en cas de redémarrage, reprenez en interrogeant cet identifiant plutôt qu'en resoumettant à l'aveugle. Si une tâche semble bloquée, ne l'arrêtez pas et ne la recréez pas immédiatement — consultez Quand une tâche hiapi /v1/tasks se bloque ou expire pour savoir distinguer une tâche lente d'une tâche morte.

Gestion des erreurs

Les deux types d'échec se manifestent différemment :

• Les erreurs au niveau de la requête sont renvoyées de manière synchrone. Une clé erronée ou non autorisée renvoie une erreur permission_denied ("This API key cannot use the selected model..."), accompagnée d'un request_id à transmettre au support. Une violation du schéma renvoie 400 INVALID_REQUEST avec un message précis, par exemple prompt: minLength: got 1, want 10.
• Les échecs au niveau de la tâche apparaissent dans le résultat d'interrogation/callback sous la forme status: "fail", avec error.code et error.message — l'appel de création a réussi, mais la génération a échoué. Ce sont ces échecs qui doivent entrer dans votre logique de nouvelle tentative.

Validez les longueurs côté client avant soumission : prompt 300 caractères maximum, lyrics 600 caractères maximum ; l'API rejette les entrées trop longues au lieu de les tronquer.

Tarification et limites

MiniMax Music 1.5 est facturé à la piste générée, selon une tarification à l'usage — consultez les tarifs actuels sur la page de tarification hiapi et la page du modèle minimax-music-1.5, où vous pouvez également essayer le modèle dans le playground avant d'écrire la moindre ligne de code.

Questions fréquentes

Quels champs d'entrée minimax-music-1.5 accepte-t-il ?

Exactement quatre : prompt (obligatoire, 10 à 300 caractères), lyrics (obligatoire, 10 à 600 caractères), sample_rate (facultatif, 16000/24000/32000/44100) et bitrate (facultatif, 32000/64000/128000/256000). Tout autre champ est rejeté avec additional properties not allowed.

Peut-on contrôler la structure de la chanson ?

Oui — utilisez des balises de section comme [Verse] et [Chorus] dans lyrics pour structurer le morceau. Le modèle s'appuie sur ces balises pour façonner l'arrangement. La chaîne de paroles complète (balises comprises) doit rester dans la limite de 600 caractères.

Peut-on générer de la musique purement instrumentale ?

Le schéma d'entrée ne propose pas d'option instrumentale. Ce point de terminaison est piloté par les paroles ; décrivez donc l'instrumentation et l'ambiance souhaitées dans prompt ; pour les cas d'usage purement instrumentaux, consultez la page du modèle pour connaître les capacités actuelles.

Comment obtenir le fichier audio ?

Lorsque le statut de la tâche est success, le lien de téléchargement se trouve dans data.output[0].url. Récupérez-le immédiatement et stockez les octets vous-même — les URL de sortie expirent.

Faut-il interroger ou utiliser un callback ?

Pour le développement et les tâches uniques, utilisez l'interrogation (un intervalle de 5 secondes suffit). En production, utilisez un callback avec when: "final" pour éviter de garder une connexion ouverte — surtout lorsque vous générez des pistes en lot.

Pourquoi est-ce que je reçois permission_denied ?

Votre clé est invalide ou n'a pas accès à ce modèle. Vérifiez la clé dans le tableau de bord et assurez-vous de l'envoyer sous la forme Authorization: Bearer sk-....