Guides médias
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, mv, 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 :
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 et incluent mv avec une version officielle du modèle Suno, comme chirp-v4. Pour les flux uniquement de paroles, envoyez action: "LYRICS" avec un modèle dont le détails du modèle documente la génération de paroles et omettez mv. 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 détails du modèle.
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-v4",
"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 diagnostic privées dans les champs 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é.
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 à interroger, 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 de polling terminée peut inclure les champs média finaux :
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "completed",
"audio_url": "https://cdn.example.com/music/abc123.mp3",
"video_url": "https://cdn.example.com/music/abc123.mp4",
"stream_audio_url": "https://cdn.example.com/music/abc123-stream.mp3",
"image_url": "https://cdn.example.com/music/cover.jpg",
"title": "Morning Static",
"lyrics": "[Verse 1]\n..."
}Les champs média finaux sont absents jusqu'à ce que status soit completed. Les tâches échouées renvoient status: "failed" avec error.
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-10spour les tâches longues, puis arrêtez surcompletedoufailed. - Ne pas afficher de lecteur final tant que la tâche n'est pas
completedet qu'unaudio_urlexiste. - 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_idstocké 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 détails du modèle 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 |
| 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 & Tarification | Facturation & Tarification |