Blog

Tutoriel

Tutoriel API minimax-music-1.5 : curl et Python Requests

Nov 12, 2026
Image de couverture : sur un fond charbon chaleureux, une large bande de lumière ambrée traverse obliquement une fente étroite, complétée par des blocs géométriques sombres et discrets, dans une composition sobre avec des espaces vides.
Sur cette page

Les exigences de minimax-music-1.5 pour les requêtes

Avant d'écrire la première ligne de code, il vaut mieux comprendre précisément ce que contient un appel de génération musicale. Contrairement à la complétion de texte, une requête musicale possède deux entrées créatives aux rôles distincts, plus plusieurs contrôles qui façonnent la sortie.

Vu de haut, une requête minimax-music-1.5 contient :

  • Une description de style ou de prompt — la direction musicale : genre, ambiance, instrumentation, sensation de tempo, caractéristiques de production.
  • Les paroles — lorsque le morceau comporte des voix, le texte réellement chanté. Laissez vide ou omettez ce champ pour une requête purement instrumentale.
  • Le contrôle de structure — par exemple la durée cible du morceau généré, qui limite la longueur de la composition du modèle.
  • L'identifiant du modèle — minimax-music-1.5 — qui permet à la passerelle de router la tâche vers le bon backend.

Le modèle mental à retenir : l'entrée de style indique au modèle à quoi cela doit ressembler, l'entrée de paroles indique au modèle ce qui est chanté. Les deux ne sont pas interchangeables. Si vous glissez une description de genre dans le champ des paroles, vous obtiendrez une sortie chaotique ; si vous laissez les paroles vides tout en demandant un morceau avec voix, le modèle devra improviser. Déterminez dans lequel des deux modes vous vous trouvez avant de commencer.

Deux autres points à intérioriser avant d'écrire du code :

  1. La génération musicale n'est pas instantanée. Produire un morceau fini demande un temps de calcul réel, c'est pourquoi l'API est conçue de manière asynchrone. Vous soumettez une tâche, puis vous récupérez le résultat. Tout tutoriel qui ne montre qu'un seul appel bloquant vous cache la boucle de polling.
  2. La sortie est livrée par référence. Vous recevez une URL vers l'audio généré, et non des octets bruts en ligne. Il faut le télécharger ou le diffuser séparément.

Une fois que vous savez énoncer ces trois choses — la distinction entre style et paroles, le cycle de vie asynchrone, la sortie par URL — le corps de requête réel devient facile à lire.

Configuration initiale sur HiAPI

Trois choses vous sont nécessaires avant le premier appel : une clé API, l'adresse de base de l'interface, et l'habitude de ne pas coder la clé en dur.

Clé API

Créez la clé dans la console de votre compte HiAPI. Traitez-la comme un mot de passe : elle authentifie chaque requête et est liée à l'usage de votre compte. Ne la committez jamais dans un dépôt, ne la collez jamais dans un gist public, et ne l'emballez jamais dans un bundle mobile ou navigateur.

Adresse de base de l'interface

Tous les appels sont envoyés à la passerelle HiAPI, qui expose minimax-music-1.5 derrière une interface unifiée unique. Vous n'avez pas besoin d'identifiants ou de SDK séparés pour chaque modèle — le nom du modèle dans le corps de la requête sélectionne le backend. Consultez la documentation de référence de l'API pour obtenir l'URL de base exacte et le chemin de requête actuel.

Garder la clé hors du code source

Le modèle qui fonctionne du script jetable à la production est la variable d'environnement :

export HIAPI_API_KEY="your-key-here"

Puis lisez-la à l'exécution. En Python, c'est os.environ["HIAPI_API_KEY"] ; dans le shell, c'est $HIAPI_API_KEY. Si vous utilisez un fichier .env en local, ajoutez-le à .gitignore avant le premier commit — pas après. Pour un service déployé, injectez la clé via le gestionnaire de secrets de la plateforme plutôt que de l'embarquer dans l'image.

Faites une vérification rapide avant de construire quoi que ce soit : assurez-vous que le processus que vous allez lancer voit bien la clé (dans le même shell, exécutez echo $HIAPI_API_KEY). La plupart des rapports « échec d'authentification » remontent à une clé exportée dans un terminal et un script lancé dans un autre.

Émettre la première requête fonctionnelle avec curl

Commencez par curl. Il retire toute couche d'abstraction et vous montre exactement ce qui transite sur le réseau. La requête ci-dessous génère un court morceau avec voix ; adaptez les valeurs des champs à votre propre intention.

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 indépendant chaleureux, guitare acoustique fingerstyle, batterie brossée douce, voix intime en proximité",
    "lyrics": "[verse]\nLa lumière du matin sur le sol de la cuisine\n[chorus]\nNous sommes encore là, nous sommes encore là",
    "duration": 30
  }'

Explication ligne par ligne :

  • -X POST — la génération est une opération de création, pas de lecture.
  • Authorization: Bearer $HIAPI_API_KEY — la clé de la section précédente, développée par le shell, donc tant que vous référencez la variable, elle n'apparaît pas dans votre historique.
  • Content-Type: application/json — la passerelle attend du JSON ; omettre cet en-tête est une cause fréquente de réponses 4xx déroutantes.
  • model — fixe la requête sur minimax-music-1.5.
  • prompt — la description de style. Précisez l'instrumentation et l'ambiance plutôt que de vous limiter à un adjectif.
  • lyrics — le texte chanté, avec de légères balises de section comme [verse] et [chorus] pour suggérer la structure. \n est l'échappement du saut de ligne JSON.
  • duration — limite la longueur du morceau généré, en secondes.

Ce qui revient est une référence de tâche, pas de l'audio. Capturez-la :

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

Lire le corps depuis un fichier avec -d @payload.json garde votre historique shell propre et rend le passage à Python trivial — ce fichier est le corps. Examinez la réponse, notez l'identifiant de tâche ou job ainsi que tout champ d'état ; vous aurez besoin de cet identifiant pour récupérer le résultat.

Porter la requête en Python

La version Python doit ressembler à une transcription de l'appel curl, pas à une réécriture. Utilisez requests, lisez la clé depuis les variables d'environnement, et gardez le corps sous forme de dictionnaire pour la lisibilité.

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 indépendant chaleureux, guitare acoustique fingerstyle, batterie brossée douce, voix intime en proximité",
    "lyrics": "[verse]\nLa lumière du matin sur le sol de la cuisine\n[chorus]\nNous sommes encore là, nous sommes encore là",
    "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))

Quelques notes de portage pour éviter les surprises :

  • Utilisez json.dumps avec data=, ou utilisez json=payload. Les deux fonctionnent ; json=payload laisse requests définir le type de contenu à votre place. Si vous passez un dictionnaire directement à data= sans le sérialiser, le serveur recevra un corps encodé en formulaire et le rejettera.
  • Définissez toujours un timeout. Sans cela, une connexion bloquée fera suspendre votre processus indéfiniment. Gardez à l'esprit que ce timeout couvre la soumission, pas la génération — c'est le sujet de la section suivante.
  • Appelez raise_for_status() avant de parser. Cela transforme un 4xx ou 5xx en exception claire, plutôt qu'en un mystérieux KeyError lorsque vous accédez à un champ inexistant.
  • Conservez l'objet réponse. Pour le débogage, afficher response.status_code et response.text vous en dit bien plus qu'une erreur parsée.

Le résultat de ce script est la même référence de tâche que celle produite par curl. Tout ce qui suit la soumission — polling, nouvelle tentative, téléchargement — est identique quelle que soit la langue, ce qui justifie de lui consacrer une section distincte.

Gérer le cycle de vie des tâches asynchrones

L'erreur la plus courante en génération musicale est de la traiter comme une complétion de chat : envoyer, attendre, lire le morceau. L'appel de soumission revient rapidement, mais l'audio n'existe pas encore. Votre code doit boucler.

Trois états

Chaque tâche traverse une petite machine à états :

  1. Soumise (Submitted) — vous avez l'identifiant de tâche, le travail est en file d'attente ou en cours.
  2. Terminée (Finished) — l'audio est prêt, la réponse contient une URL vers celui-ci.
  3. Échouée (Failed) — la génération a été interrompue ; la réponse en explique la raison.

Votre boucle de polling doit distinguer les trois. Un état submitted signifie continuer d'attendre, pas réessayer.

Polling, sans marteler

Une boucle naïve qui lance des vérifications d'état aussi vite que le CPU le permet épuise les limites de débit et ne vous apprend rien de nouveau — le rendu d'un morceau prend des dizaines de secondes, donc des centaines de vérifications par minute sont du gaspillage. Ajoutez 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")

Consultez la documentation de référence de l'API pour obtenir le chemin de polling et les chaînes d'état exacts — considérez les noms ci-dessus comme indicatifs et alignez-les sur les valeurs de la documentation.

Réessayer les bons objets

Les nouvelles tentatives relèvent de deux niveaux distincts, et les confondre entraîne du travail en double. Une nouvelle tentative de transport — l'appel HTTP lui-même échoue à cause d'un 5xx ou d'une réinitialisation de connexion — peut être répétée sans risque pour une requête de polling. Une nouvelle tentative de génération est en revanche une nouvelle soumission, qui coûte un rendu de plus, donc ne la faites que lorsque la tâche signale explicitement un échec, et en limitant le nombre d'essais. Ne relancez jamais une soumission parce que le polling est lent.

Enfin, persistez l'identifiant de tâche dès l'instant où vous le recevez. Si votre processus plante entre la soumission et la fin, cet identifiant est le seul moyen de récupérer le morceau terminé sans payer une nouvelle génération.

Ajuster les entrées de paroles, de style et de durée

Obtenir un morceau exploitable de minimax-music-1.5 repose principalement sur une rédaction consciente des deux champs textuels. Quelques habitudes déterminent si la sortie est générique ou si c'est vraiment quelque chose que vous publieriez.

Écrire le prompt de style comme un brief de producteur

Un seul mot de genre laisse trop de liberté au modèle. Empilez des dimensions concrètes :

  • Genre et époque — « trip hop de la fin des années 90 » vaut mieux que « électronique ».
  • Instrumentation — nommez les instruments principaux et la section rythmique.
  • Ambiance et énergie — « mélancolique mais entraînant » crée une tension qu'un seul adjectif ne peut exprimer.
  • Caractéristiques de production — « lo-fi, saturation de bande, stéréo large » oriente le mixage.

Tenez-vous-en à une ou deux phrases. Les prompts en longs paragraphes ont tendance à diluer plutôt qu'affiner.

Structurer les paroles avec des balises

De légers marqueurs de section — [verse], [chorus], [bridge] — donnent au modèle une feuille de route et produisent généralement une structure de chanson plus claire qu'un bloc de texte sans balises. Gardez chaque ligne assez courte pour être chantée ; une ligne de douze mots s'accorde rarement à une mélodie. Pour un morceau instrumental, omettez complètement lyrics plutôt que d'envoyer une chaîne vide contenant du texte de style.

Faire correspondre la durée au matériau

La durée limite la composition. Une courte durée avec des paroles complètes verse-chorus-verse force la compression et sonne précipitée ; une longue durée avec deux lignes de paroles invite la répétition. Décidez d'abord de la forme de la chanson, puis définissez la durée qui lui convient. Si vous avez besoin d'une pièce plus longue, développez les paroles plutôt que d'allonger la durée en espérant que ça marche.

Itérer par petits changements

Quand un morceau est proche mais pas tout à fait juste, ne modifiez qu'une seule entrée à la fois — l'instrumentation dans le prompt, ou le mot de tempo, ou la ligne de paroles qui ne fonctionne pas. Tout changer en même temps vous empêche de savoir quel champ a apporté l'amélioration. Conservez votre meilleur corps de requête dans un fichier et partez de là par branches.

Diagnostiquer les erreurs courantes

La plupart des échecs tombent dans quelques catégories reconnaissables. Identifiez le symptôme, appliquez le correctif, avancez.

Échecs d'authentification

Symptôme : 401 ou 403, avec un message lié aux identifiants.

  • Vérifiez que l'en-tête est Authorization: Bearer <key> — le mot Bearer et l'espace sont obligatoires.
  • Vérifiez que la variable d'environnement est bien définie dans le processus qui émet la requête. Une clé exportée dans un shell n'atteint pas une tâche cron ni un conteneur Docker.
  • Vérifiez les espaces ou retours à la ligne superflus copiés avec la clé.

Corps de requête mal formé

Symptôme : 400, avec un message de validation.

  • Envoyez Content-Type: application/json. L'absence de cet en-tête fait mal interpréter par le serveur un corps pourtant parfaitement correct.
  • Si vous utilisez requests, passez json=payload ou data=json.dumps(payload). Passer un dictionnaire brut à data= l'encode en formulaire.
  • Validez les noms et types de champs avec la documentation de référence de l'API : model doit valoir exactement minimax-music-1.5, duration est un entier, et les sauts de ligne des paroles doivent être correctement échappés en \n dans le JSON.
  • En cas de doute, utilisez curl -d @payload.json pour isoler si le corps lui-même est valide avant d'impliquer Python.

Délais d'attente et erreurs de connexion

Symptôme : la requête se bloque ou lève une erreur de connexion.

  • Définissez un timeout explicite pour chaque appel. Le timeout de soumission doit être assez large pour couvrir la latence de file d'attente, mais ce n'est pas le temps de rendu.
  • Ne réglez pas votre timeout de polling égal au max_wait global ; une seule vérification d'état lente ne doit pas interrompre une tâche toujours en cours.
  • Si la soumission expire à répétition alors que le polling réussit, votre corps est probablement trop volumineux — réduisez les paroles.

Erreurs de polling

Symptôme : vous interrogez sans cesse sans jamais voir finished, ou vous interrogez la mauvaise ressource.

  • Vérifiez que vous utilisez l'identifiant de tâche issu de la réponse de soumission, et non pas l'identifiant de requête ou un en-tête de corrélation.
  • Traitez submitted/running comme « continuez d'attendre » et non comme « réessayez la soumission ». Une soumission répétée génère un second morceau.
  • Ajoutez un backoff. Un polling agressif attire les limites de débit, ce qui ressemble à un échec mais est en réalité auto-infligé.
  • Si la tâche signale failed, lisez le message avant de resoumettre — une balise de paroles invalide ou une durée hors limites échouera de la même manière à chaque fois.

En cas de blocage, revenez à l'appel curl brut avec -v pour voir la ligne de statut et les en-têtes réels. Cette étape dissipe la plupart des ambiguïtés plus vite que n'importe quel débogage Python.

Articles similaires

Voir tous les articles →

Commencez avec des artefacts IA persistants

Obtenez votre clé API et appelez des modèles d'image, de vidéo et d'audio via une API unique basée sur les tasks.

Lire la documentation de l'API