Guides médias
Génération de musique
Créez des chansons ou des paroles et attendez que l'audio soit terminé
La génération de musique est asynchrone. POST /v1/music/generations renvoie un ID de tâche, un statut et généralement une poll_url. Interrogez GET /v1/tasks/{id} avec cet ID jusqu'à ce que la tâche soit completed (terminée) ou failed (échouée).
Choisir ce qu'il faut créer
| Ce qu'il faut créer | Champs clés | Notes |
|---|---|---|
| Chanson complète ou instrumentale | model, mv, prompt, optionnel title, tags, action: "MUSIC" | À utiliser lorsque l'utilisateur attend l'audio final |
| Paroles uniquement | model, prompt, action: "LYRICS" | À utiliser uniquement avec les modèles qui exposent la génération de paroles |
| Continuer un clip existant | model, mv, prompt, continue_clip_id, optionnel continue_at | Conservez l'ID du clip précédent |
| Couvrir ou étendre votre propre audio | model, mv, prompt, audio_url, optionnel audio_operation | audio_url doit être une URL publique. audio_operation est upload-cover par défaut ; upload-extend nécessite également continue_at |
| Ajouter une instrumentale, remplacer une section ou séparer des pistes | audio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation, ou advanced-split | Chaque opération possède ses propres champs requis ; voir Créer de la musique |
Obtenez la liste actuelle des modèles de musique à partir de :
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
-H "Authorization: Bearer sk-your-api-key"L'exemple ci-dessous utilise suno-music avec mv: "chirp-v6". D'autres modèles de musique, tels que stable-audio-3, utilisent des champs différents comme duration et output_format ; lisez d'abord les détails du modèle. Pour les paroles uniquement, choisissez un modèle qui documente la génération de paroles, envoyez action: "LYRICS" et omettez mv.
Créer une tâche de musique
curl https://api.tokenlab.sh/v1/music/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "suno-music",
"mv": "chirp-v6",
"prompt": "An upbeat synth-pop track with warm vocals and a clean chorus",
"title": "Morning Static",
"tags": "synth-pop, upbeat",
"action": "MUSIC"
}'Les prompts, titres et tags peuvent apparaître dans l'historique de votre produit. N'y placez jamais de clés API, d'URL privées ou de données de diagnostic.
Obtenir l'audio terminé
Appelez GET /v1/tasks/{id} avec l' id ou le task_id renvoyé.
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"Forme de la réponse
La réponse de création est un enregistrement de tâche, pas l'audio final :
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "pending",
"created": 1706000000,
"model": "suno-music"
}Une réponse d'interrogation terminée peut inclure les champs multimédias finaux :
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "completed",
"audio_url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"video_url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"image_url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"title": "Morning Static",
"lyrics": "[Verse 1]\n...",
"media_retention": {
"days": 30,
"items": [
{
"url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"kind": "audio",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"kind": "video",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"kind": "image",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
}
]
}
}Les champs multimédias finaux sont absents tant que le status n'est pas completed. Les tâches échouées renvoient status: "failed" avec une error.
Les statuts sont pending, processing, completed et failed. Une tâche terminée peut inclure audio_url, video_url, title, lyrics et d'autres métadonnées. Les URL multimédias sont des URL TokenLab qui restent valides pendant 30 jours ; téléchargez ou enregistrez tout résultat dont vous avez besoin plus longtemps.
Afficher le bon état
- Affichez un état en attente immédiatement après la création de la tâche.
- Interrogez toutes les
5-10spour les tâches longues, puis arrêtez-vous surcompletedoufailed. - N'affichez pas de lecteur final tant que la tâche n'est pas
completedet qu'uneaudio_urlexiste. - Pour les tâches de paroles uniquement, rendez 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_idstocké au lieu de créer une nouvelle tâche.
Enregistrements de facturation
Les tâches de musique peuvent réserver un montant estimé lors de leur création. Le montant final est enregistré après l'achèvement ou l'échec. Enregistrez request_id, task_id, le modèle, le point de terminaison et billing_transaction_id lorsqu'ils apparaissent ; utilisez les enregistrements d'utilisation de l'API de gestion pour la facturation finale.
Erreurs courantes
| Symptôme | Cause probable | Solution |
|---|---|---|
| Tâche créée mais pas de lecteur | La tâche est toujours en attente ou terminée sans audio_url | Continuez à interroger jusqu'à l'état terminal, puis gérez l'absence de sortie comme un échec de travail utilisateur |
| Chansons en double après rafraîchissement | L'interface utilisateur a recréé la tâche au lieu de la reprendre | Persistez et réutilisez le task_id |
| La tâche de paroles ne renvoie pas d'audio | action: "LYRICS" est uniquement textuel | Séparez les chemins d'interface utilisateur pour les paroles et la musique |
| Paramètre non pris en charge | Le modèle sélectionné n'accepte pas le champ | Supprimez-le ou choisissez un modèle qui le documente |
Référence API
| Sujet | Référence |
|---|---|
| Créer de la musique | Créer de la musique |
| Obtenir le statut de la musique | Obtenir le statut de la musique |
| Obtenir le statut de la tâche | Obtenir le statut de la tâche |
| Lister les modèles | Lister les modèles |
| Facturation et tarification | Facturation et tarification |