# Générer une chanson avec une API IA : du prompt au MP3

> Tutoriel complet pour générer une chanson avec l'API Tchavi : prompt contre paroles, job asynchrone, polling, erreurs avant facturation et coût réel.

- Published: 2026-11-04
- Author: Gael — fondateur de Tchavi
- Canonical: https://tchavi.com/fr/blog/generer-une-chanson-avec-une-api-ia

---


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/generations`** est asynchrone : il répond `202` avec un `id` de 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-cover` reprend 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 `prompt` porte la direction musicale** — tonalité, tempo, instruments, voix, ambiance. **Les `lyrics` portent les mots** — avec des repères `[Couplet]` / `[Refrain]`. Confondre les deux donne un résultat vague.
- Tu interroges `GET /v1/jobs/:id` jusqu'à `completed` ou `failed`. Un job terminé répond avec `output.audio_url` — et non `video_url`, réservé à la vidéo.
- Trois combinaisons sont refusées avec un `400`, avant toute facturation : une reprise sans `source_audio_url`, un `source_audio_url` envoyé à un générateur, et `instrumental` avec `lyrics`.
- 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` :

```bash
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 :

```json
{
  "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](https://tchavi.com/fr/docs/jobs). En cURL, une boucle simple :

```bash
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 :

```json
{
  "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 :

```bash
npm install @tchavi/sdk
```

```javascript
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) :

```javascript
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 :

<MusicDemo track="song" />

## 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 :

```bash
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.

<MusicDemo track="cover" />

## 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](https://tchavi.com/fr/docs/music-generation) et celle des [jobs asynchrones](https://tchavi.com/fr/docs/jobs).
- Les deux modèles ont leur propre page, avec une démo : [`minimax-music-2.6`](https://tchavi.com/fr/m/minimax/minimax-music-2.6) et [`minimax-music-cover`](https://tchavi.com/fr/m/minimax/minimax-music-cover).
- Le [catalogue musique](https://tchavi.com/fr/models/music) 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](https://tchavi.com/fr/register?next=%2Fdashboard%2Fbilling%3Famount%3D1000%26currency%3DXOF%26from%3Dblog-musique-api)

> _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](https://tchavi.com/fr/docs/payments)). Plus de guides sur [le blog](https://tchavi.com/fr/blog). Pour suivre les prochains : [LinkedIn](https://www.linkedin.com/company/tchavi) et [X](https://x.com/tchaviai)._