Générer une chanson par API tient en un seul appel : POST /v1/music/generations, avec un prompt et, si tu veux des paroles précises, un champ lyrics. La réponse n'est pas le fichier audio — c'est un job, qui se termine quelques dizaines de secondes plus tard avec un MP3 à récupérer. Ce guide part d'un fichier vide et arrive à un morceau fini : le code exact en cURL et en Node.js, les deux modèles disponibles, ce qui distingue le prompt des paroles, les erreurs que l'API renvoie avant de te facturer quoi que ce soit, et le prix réel.
En bref
POST /v1/music/generationsest asynchrone : il répond202avec unidde job, pendant que le morceau se fabrique en arrière-plan.- Deux modèles :
minimax-music-2.6écrit et interprète une chanson à partir d'une description (329,242 crédits, environ 110 F) ;minimax-music-coverreprend un morceau que tu fournis (658,484 crédits, environ 219 F). Facturation forfaitaire au morceau, jusqu'à cinq minutes, sans paramètre de durée. - Le
promptporte la direction musicale — tonalité, tempo, instruments, voix, ambiance. Leslyricsportent les mots — avec des repères[Couplet]/[Refrain]. Confondre les deux donne un résultat vague. - Tu interroges
GET /v1/jobs/:idjusqu'àcompletedoufailed. Un job terminé répond avecoutput.audio_url— et nonvideo_url, réservé à la vidéo. - Trois combinaisons sont refusées avec un
400, avant toute facturation : une reprise sanssource_audio_url, unsource_audio_urlenvoyé à un générateur, etinstrumentalaveclyrics. - Sur nos essais, la chanson a pris 65,9 s à générer pour un morceau de 1 min 10 ; la reprise, 76,4 s pour 1 min 06.
Le premier appel : écrire une chanson
Crée une clé dans ton tableau de bord, puis envoie un prompt :
curl -X POST https://tchavi.com/api/v1/music/generations \
-H "Authorization: Bearer $TCHAVI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-music-2.6",
"prompt": "Afrobeats mid-tempo, 100 BPM, tonalité de Do majeur, guitare highlife, basse ronde, voix féminine chaude, ambiance de retrouvailles joyeuses"
}'
La réponse arrive tout de suite, bien avant que le morceau existe :
{
"id": "0f3c1a2b-...",
"object": "music.generation",
"status": "pending",
"model": "minimax-music-2.6",
"created_at": "2026-11-05T09:12:03.000Z",
"tchavi": {
"credits_used": 329.242,
"credits_remaining": 4821.5
}
}
credits_used est débité à la soumission, pas à la fin du job. Si le job échoue, ce montant est remboursé intégralement — ton code n'a rien de particulier à faire pour ça.
Suivre le job jusqu'au fichier fini
L'id renvoyé se poll sur l'endpoint des jobs asynchrones. En cURL, une boucle simple :
JOB_ID="0f3c1a2b-..."
while true; do
STATUS=$(curl -s https://tchavi.com/api/v1/jobs/$JOB_ID \
-H "Authorization: Bearer $TCHAVI_API_KEY")
echo "$STATUS" | grep -o '"status":"[a-z]*"'
case "$STATUS" in
*'"status":"completed"'*|*'"status":"failed"'*) break ;;
esac
sleep 5
done
echo "$STATUS"
Un job terminé répond avec le fichier :
{
"id": "0f3c1a2b-...",
"status": "completed",
"model": "minimax-music-2.6",
"type": "MUSIC",
"output": {
"audio_url": "https://cdn.tchavi.com/.../track.mp3",
"file_size_mb": 1.7,
"url_expires_at": "2026-11-06T09:14:51.000Z"
}
}
C'est output.audio_url, pas output.video_url — ce dernier champ appartient aux jobs vidéo, pas à la musique. output.url_expires_at donne la date limite pour télécharger le fichier : passé ce délai, le lien signé ne fonctionne plus.
Avec le SDK Node.js (à venir)
Les deux appels cURL ci-dessus suffisent pour écrire une chanson et récupérer le fichier dès aujourd'hui : c'est le chemin qui fonctionne maintenant. Le SDK @tchavi/sdk ne sait pas encore faire ça : la méthode client.music.generations arrive avec une prochaine version, pas encore publiée. Le code ci-dessous montre à quoi ressemblera cette intégration une fois le SDK mis à jour — ne l'installe pas en t'attendant à ce qu'elle marche tout de suite :
npm install @tchavi/sdk
import Tchavi from '@tchavi/sdk';
const client = new Tchavi({ apiKey: process.env.TCHAVI_API_KEY });
const submission = await client.music.generations.create({
model: 'minimax-music-2.6',
prompt:
'Afrobeats mid-tempo, 100 BPM, tonalité de Do majeur, guitare highlife, basse ronde, voix féminine chaude',
});
console.log(submission.id, submission.tchavi.credits_used);
let job = await client.jobs.retrieve(submission.id);
while (job.status !== 'completed' && job.status !== 'failed') {
await new Promise((r) => setTimeout(r, 5000));
job = await client.jobs.retrieve(submission.id);
}
console.log(job.status, job.output?.audio_url);
Ou, plus court, le helper qui fait les deux en un appel (il attend 10 minutes par défaut, le temps qu'une chanson complète se fabrique) :
const job = await client.music.generations.createAndWait({
model: 'minimax-music-2.6',
prompt: 'Afrobeats mid-tempo, 100 BPM, guitare highlife, basse ronde, voix féminine chaude',
});
console.log(job.status, job.output?.audio_url);
Une fois publié, le SDK devrait valider prompt et model avant même d'envoyer la requête, et refuser localement un instrumental combiné à des lyrics — tu obtiendrais l'erreur tout de suite, sans aller-retour réseau. En attendant, les deux vérifications se font déjà côté serveur avec les appels cURL montrés plus haut.
Voici ce que ces deux appels produisent — une chanson écrite, chantée et mixée par le modèle, à partir du prompt et des paroles ci-dessous :
Prompt : A minor, 102 BPM, afrobeats with highlife guitar, round bass and log drum, female lead with a small backing choir, bright and hopeful, the energy of a market opening at dawn
minimax-music-2.6 · 329,242 crédits · 1:10 · généré en 65,9 s
Le prompt et les paroles : deux rôles, pas un seul
C'est le point qui change le résultat le plus : le prompt et les lyrics ne se recouvrent pas.
Le prompt décrit la musique elle-même : genre, tempo en BPM, tonalité, instruments, type de voix, ambiance. Un prompt qui ne donne que l'ambiance — « une chanson joyeuse sur l'amitié » — laisse le modèle deviner le tempo et la tonalité, et le résultat varie plus d'un essai à l'autre. Un prompt qui précise le tempo et la tonalité donne quelque chose de plus prévisible à chaque appel.
Les lyrics portent les mots et la structure du morceau, avec des repères de section :
[Couplet]
On s'est perdus de vue à Cotonou
Et on s'est retrouvés par hasard, dans la foule
[Refrain]
Reviens, reviens, la ville t'a gardé une place
Reviens, reviens, rien n'a vraiment changé de face
Omets lyrics et minimax-music-2.6 écrit ses propres paroles à partir du prompt. Envoie instrumental: true pour ne pas avoir de voix du tout — mais jamais en même temps que lyrics : l'un demande l'absence de voix, l'autre fournit des mots à chanter, l'API refuse la contradiction avant de lancer le job.
Reprendre un morceau existant : minimax-music-cover
minimax-music-cover garde la mélodie d'un morceau que tu fournis et change tout ce qui l'entoure — genre, voix, instruments, arrangement. Il exige source_audio_url, un MP3 ou un WAV accessible publiquement :
curl -X POST https://tchavi.com/api/v1/music/generations \
-H "Authorization: Bearer $TCHAVI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "minimax-music-cover",
"prompt": "Version acoustique douce, voix féminine, guitare nylon",
"source_audio_url": "https://example.com/ma-maquette.mp3"
}'
Deux fois le prix du modèle qui écrit une chanson depuis zéro : 658,484 crédits, environ 219 F, toujours au forfait par morceau.
La reprise ci-dessous part de la chanson que tu viens d'entendre, pas d'un enregistrement de quelqu'un d'autre : même mélodie, arrangement acoustique.
Prompt : Gentle acoustic cover, nylon guitar and brushed percussion, warm female vocal, slower tempo, intimate studio feel
minimax-music-cover · 658,484 crédits · 1:06 · généré en 76,4 s
Les erreurs avant la facturation
Trois combinaisons sont refusées avec un 400, avant tout débit de crédits :
| Cas | Réponse |
|---|---|
minimax-music-cover sans source_audio_url | 400 bad_request — le modèle n'a rien à reprendre |
source_audio_url envoyé à minimax-music-2.6 | 400 bad_request — un générateur n'en a pas besoin |
instrumental: true avec lyrics rempli | 400 bad_request — les deux se contredisent |
prompt ou model absent | 400 bad_request (ou rejeté localement par le SDK) |
Aucune de ces erreurs ne te coûte un crédit. Si en revanche un job démarre et échoue plus tard — côté modèle — les crédits débités à la soumission sont remboursés intégralement ; tu le vois dans tchavi.credits_refunded sur le job.
Ce que ça coûte
| Modèle | Ce qu'il fait | Crédits par morceau | Prix en F |
|---|---|---|---|
minimax-music-2.6 | Écrit et interprète une chanson, jusqu'à 5 min | 329,242 | environ 110 F |
minimax-music-cover | Reprend un morceau fourni, dans le style décrit | 658,484 | environ 219 F |
C'est un forfait par morceau, pas par seconde : une chanson de trente secondes et une de cinq minutes coûtent le même prix. Avec 3 crédits pour 1 F, une recharge de 1 000 F (3 000 crédits) couvre environ 9 chansons avec minimax-music-2.6, ou environ 4 reprises avec minimax-music-cover.
Les 50 crédits offerts à la vérification de l'e-mail ne suffisent pas pour un morceau : il en faut 329,242 au minimum. Il faut recharger ton compte avant de tester la musique — le coût d'un essai reste faible, mais il n'est pas gratuit.
Ce qu'on a mesuré
Deux essais, pas un benchmark :
minimax-music-2.6: 65,9 secondes de génération pour un morceau de 1 min 10.minimax-music-cover: 76,4 secondes de génération pour un morceau de 1 min 06.
Le temps de génération ne dépend pas de la longueur du morceau produit : les deux tournent autour d'une minute, que le résultat fasse une minute ou cinq.
Comment l'essayer
- Lis la documentation de génération musicale et celle des jobs asynchrones.
- Les deux modèles ont leur propre page, avec une démo :
minimax-music-2.6etminimax-music-cover. - Le catalogue musique liste les deux côte à côte.
FAQ
Peut-on choisir la durée du morceau ?
Non. Il n'y a pas de paramètre de durée : le modèle décide, dans la limite de cinq minutes, et le prix ne change pas selon ce qu'il produit.
Que se passe-t-il si lyrics est vide mais présent ?
Envoie le champ seulement si tu as des paroles à donner. Une chaîne vide n'est pas traitée comme une absence de paroles.
Peut-on tester la musique avec les crédits gratuits de l'inscription ?
Non. Les 50 crédits offerts à la vérification de l'e-mail ne couvrent pas un morceau : il en faut 329,242 pour minimax-music-2.6. Une recharge est nécessaire avant le premier essai.
Le job peut-il être interrogé indéfiniment ?
Oui, GET /v1/jobs/:id reste disponible après la fin du job, tant que le fichier n'a pas expiré. output.url_expires_at donne la date limite pour télécharger le MP3.
Le SDK gère-t-il la reprise de morceau ?
Pas encore sur npm : client.music.generations arrive avec une prochaine version du SDK. En attendant, appelle directement POST /v1/music/generations avec model: "minimax-music-cover" et un source_audio_url, comme montré plus haut.
crée ton compte et recharge 1 000 F
Cet article fait partie de la série « Construire un SaaS IA depuis l'Afrique francophone ». Tchavi est une passerelle d'API IA compatible OpenAI : une seule clé donne accès à plus de 100 modèles de texte, d'image, d'audio et de vidéo, et tu la paies en mobile money, sans carte bancaire (pays et opérateurs). Plus de guides sur le blog. Pour suivre les prochains : LinkedIn et X.