API minimax-music-3 : guide curl et Python

Générer un morceau avec minimax-music-3 sur hiapi ne demande qu'un appel POST /v1/tasks suivi d'un polling — exactement le même schéma de tâche asynchrone que celui utilisé par tous les modèles de la plateforme. Ce guide documente de vraies requêtes et réponses (création de tâche, polling et URL audio finale), de sorte que le code ci-dessous peut être copié et exécuté tel quel, et non simplement à titre d'illustration.

Ce dont vous avez besoin

1. Une clé API hiapi — créez-la dans la console. Chaque requête l'envoie sous forme de jeton Bearer.
2. C'est tout. Contrairement aux modèles image-vers-vidéo ou image-vers-image, minimax-music-3 n'accepte aucun fichier ni URL en entrée — il génère uniquement à partir de texte.

Requête minimale fonctionnelle (curl)

Créer la tâche :

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

Réponse :

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

Interroger la tâche jusqu'à son achèvement :

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

Pendant l'exécution de la tâche, status passe successivement par handling → archiving, puis finit par devenir success (ou failed). Lors de nos tests, un morceau a mis environ deux minutes et demie entre la soumission et success. La réponse une fois terminée est la suivante :

{
  "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 correspond au fichier WAV. Faites attention à expireAt — avant de concevoir une fonctionnalité qui dépend de la validité à long terme de cette URL, lisez la note ci-dessous sur le stockage.

Le même flux en 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}")

Les paramètres réellement validés par minimax-music-3

Le schéma d'entrée est strict — si vous envoyez un champ non répertorié, l'API rejette l'ensemble de la requête avant même qu'elle n'entre en file d'attente :

• prompt (chaîne, obligatoire) — style, ambiance, instrumentation. C'est en pratique ce qui détermine la forme du morceau.
• lyrics (chaîne, obligatoire) — toujours obligatoire, même pour un morceau purement instrumental. Passez "[Instrumental]" comme valeur de remplissage ; pour les morceaux avec chant, utilisez des balises de section telles que [Verse] / [Chorus].
• callback (objet, facultatif) — {"url": "...", "when": "final"}. La seule valeur prise en charge pour when est "final" ; toute autre valeur renvoie un 400 avec le message invalid callback.when: only 'final' is supported.

Envoyez quoi que ce soit en dehors de ces trois clés de premier niveau — comme sample_rate, duration ou une faute de frappe — et vous obtiendrez :

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

Points d'attention pour la production

• Deux formats d'erreur distincts. Les erreurs de validation (champ manquant, valeur d'énumération invalide, clé inconnue) renvoient au niveau supérieur {"code":400,"error_code":"INVALID_REQUEST","message":"..."}. Les erreurs d'authentification/permission renvoient en revanche {"error":{"code":"permission_denied","message":"...","request_id":"..."}} — un objet error imbriqué, avec un code HTTP 401. Vérifiez ces deux formats dans votre gestion des erreurs ; un code qui ne teste que resp["code"] laissera passer les cas 401.
• permission_denied signale un problème de clé, pas de requête. Si prompt/lyrics sont présents et du bon type, mais que vous recevez quand même un 401 permission_denied, cela signifie que la clé API elle-même n'a pas ce modèle activé — vérifiez-la dans la console plutôt que de relire votre JSON en boucle.
• Le stockage des fichiers de sortie est temporaire. storage: "temp" ainsi qu'un horodatage Unix expireAt sur chaque sortie — dans l'exemple capturé, environ 7 jours après la création. Dès qu'une tâche réussit, téléchargez le fichier immédiatement ou poussez-le vers votre propre stockage ; ne conservez pas les URL temp.hiapi.ai comme des liens permanents.
• Pour toute tâche en lot, utilisez un callback. Interroger un morceau ne pose pas de problème ; en interroger cinquante, c'est cinquante allers-retours répétés. Configurez callback.url et when: "final" pour que hiapi vous pousse le résultat en une seule fois lorsque la tâche est réellement terminée.
• Réessayez avant d'obtenir le taskId, pas après. Réessayer en cas d'erreur réseau ou de 5xx sur le POST /v1/tasks initial est sans risque — rien n'a encore été créé à ce stade. Une fois que vous avez le taskId, resoumettre le même prompt crée un autre morceau sans rapport ; à ce stade, interrogez plutôt la tâche ou attendez le callback.

Pour aller plus loin

• Page du modèle minimax-music-3 — tarifs actuels et zone de démonstration en ligne.
• Tarifs hiapi — les taux de tous les modèles du catalogue.
• Documentation hiapi — la référence API complète, au-delà de ce seul modèle.

Questions fréquentes

Faut-il fournir des paroles pour un morceau purement instrumental ? Oui — que vous vouliez ou non des voix, lyrics est un champ obligatoire. Passez "[Instrumental]" et le modèle générera un morceau sans chant.

Peut-on éviter complètement le polling ? Oui, en définissant callback: {"url": "https://your-endpoint", "when": "final"} lors de la création de la tâche. Lorsque la tâche atteint un état terminal, hiapi envoie en POST à votre URL la même charge utile que GET /v1/tasks/:id. "final" est actuellement la seule valeur prise en charge pour when.

Pourquoi est-ce que je reçois « additional properties not allowed » ? Le schéma d'entrée de minimax-music-3 n'accepte que prompt et lyrics dans input (plus callback au niveau supérieur). Tout autre nom de champ — même s'il fonctionne sur d'autres modèles hiapi — sera rejeté avant l'exécution de la requête.

Pourquoi une clé qui fonctionne sur d'autres modèles renvoie-t-elle un 401 sur ce modèle ? L'accès aux modèles est accordé clé par clé. Un retour 401 avec error_code: "permission_denied" signifie que cette clé précise n'a pas encore obtenu les droits sur minimax-music-3 — activez-les dans la console, ce n'est pas un bug de votre corps de requête.

Combien de temps puis-je attendre avant de télécharger le fichier de sortie ? N'attendez pas — output[0].url est un lien temporaire (en pratique, expireAt correspond à environ une semaine plus tard). Considérez-le comme une transmission à usage unique : téléchargez ou re-téléversez immédiatement après le succès de la tâche.