> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Génération de Musique

> Créez des tâches de musique ou de paroles, interrogez pour l'audio final et stockez les sorties musicales visibles par l'utilisateur en toute sécurité.

La génération de musique est asynchrone. `POST /v1/music/generations` crée une tâche publique TokenLab et renvoie `id` / `task_id`, `status`, et généralement `poll_url`. Votre application doit stocker cette identité de tâche, afficher la progression et interroger jusqu'à un statut terminal.

## Choisissez le Flux de Travail

| Flux de travail                   | Champs clés                                                     | Remarques                                                                           |
| --------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Chanson complète ou instrumentale | `model`, `prompt`, `title` optionnel, `tags`, `action: "MUSIC"` | À utiliser lorsque l'utilisateur s'attend à un audio final                          |
| Paroles uniquement                | `model`, `prompt`, `action: "LYRICS"`                           | À utiliser uniquement avec des modèles qui exposent la génération de paroles        |
| Continuer un clip existant        | `continue_clip_id`, `continue_at` optionnel                     | Stockez l'identité du clip/tâche publique précédente avant d'offrir la continuation |

Interrogez le catalogue de modèles actuel avant d'expédier une liste de modèles codée en dur :

```bash theme={null}
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
  -H "Authorization: Bearer sk-your-api-key"
```

Les exemples publics actuels utilisent `suno_music` pour la génération de musique. Pour les flux uniquement de paroles, envoyez `action: "LYRICS"` avec un modèle dont le contrat public documente la génération de paroles. Traitez les ID de modèle comme des ID publics TokenLab, et non comme une garantie que les champs spécifiques au fournisseur sont des champs de contrat public.

## Créer une Tâche de Musique

```bash theme={null}
curl https://api.tokenlab.sh/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno_music",
    "prompt": "Une piste synth-pop entraînante avec des voix chaleureuses et un refrain clair",
    "title": "Morning Static",
    "tags": "synth-pop, entraînant",
    "action": "MUSIC"
  }'
```

Gardez les prompts, titres et tags visibles par l'utilisateur et sûrs à stocker. Ne placez pas de clés API, d'URLs privées ou d'informations de routage internes dans aucun champ de prompt.

## Interroger pour la Complétion

Utilisez d'abord `poll_url`. Si votre client a besoin d'une route fixe, appelez `GET /v1/tasks/{id}` avec le `id` ou `task_id` retourné.

```bash theme={null}
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"
```

Les statuts publics attendus sont `pending`, `processing`, `completed`, et `failed`. Une tâche de musique complétée peut inclure `audio_url`, `video_url`, `title`, `lyrics`, et des métadonnées normalisées. Stockez les URLs finales dans votre propre base de données afin que l'utilisateur puisse rouvrir le résultat sans redémarrer la génération.

## Gestion de l'Interface Utilisateur et de l'État

* Affichez un état en attente immédiatement après la création de la tâche.
* Interrogez toutes les `5-10s` pour les tâches longues, puis arrêtez sur `completed` ou `failed`.
* Ne pas afficher de lecteur final tant que la tâche n'est pas `completed` et qu'un `audio_url` existe.
* Pour les tâches uniquement de paroles, affichez la sortie texte séparément des tâches audio afin que les utilisateurs comprennent ce qu'ils achètent.
* Lors d'un rafraîchissement, reprenez à partir du `task_id` stocké au lieu de créer une nouvelle tâche.

## Facturation et Rapprochement

Les tâches de musique peuvent réserver un montant estimé au moment de la création et se régler après que le statut terminal soit connu. Stockez `request_id`, `task_id`, modèle, point de terminaison, et `billing_transaction_id` lorsqu'il apparaît. Utilisez les enregistrements d'utilisation de l'API de gestion pour le rapprochement au lieu des ID de tâche du fournisseur.

## Erreurs Courantes

| Symptôme                                   | Cause probable                                                 | Solution                                                                                                                |
| ------------------------------------------ | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Tâche créée mais pas de lecteur            | La tâche est toujours en attente ou complétée sans `audio_url` | Continuez à interroger jusqu'à un statut terminal, puis traitez la sortie manquante comme un travail utilisateur échoué |
| Chansons dupliquées après rafraîchissement | L'interface utilisateur a recréé la tâche au lieu de reprendre | Persistez et réutilisez `task_id`                                                                                       |
| La tâche de paroles ne renvoie pas d'audio | `action: "LYRICS"` est uniquement textuel                      | Séparez les chemins UI de paroles et de musique                                                                         |
| Paramètre non pris en charge               | Le champ n'est pas dans le contrat public du modèle            | Supprimez les champs spécifiques au fournisseur ou choisissez un modèle qui les documente                               |

## Référence API

| Sujet                           | Référence                                                                   |
| ------------------------------- | --------------------------------------------------------------------------- |
| Créer de la Musique             | [Créer de la Musique](/fr/api-reference/music/create-music)                 |
| Obtenir le Statut de la Musique | [Obtenir le Statut de la Musique](/fr/api-reference/music/get-music-status) |
| Obtenir le Statut de la Tâche   | [Obtenir le Statut de la Tâche](/fr/api-reference/tasks/get-task-status)    |
| Lister les Modèles              | [Lister les Modèles](/fr/api-reference/models/list-models)                  |
| Facturation & Tarification      | [Facturation & Tarification](/fr/guides/billing)                            |