TokenLab

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éerChamps clésNotes
Chanson complète ou instrumentalemodel, mv, prompt, optionnel title, tags, action: "MUSIC"À utiliser lorsque l'utilisateur attend l'audio final
Paroles uniquementmodel, prompt, action: "LYRICS"À utiliser uniquement avec les modèles qui exposent la génération de paroles
Continuer un clip existantmodel, mv, prompt, continue_clip_id, optionnel continue_atConservez l'ID du clip précédent
Couvrir ou étendre votre propre audiomodel, mv, prompt, audio_url, optionnel audio_operationaudio_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 pistesaudio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation, ou advanced-splitChaque 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-10s pour les tâches longues, puis arrêtez-vous sur completed ou failed.
  • N'affichez pas de lecteur final tant que la tâche n'est pas completed et qu'une audio_url existe.
  • 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_id stocké 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ômeCause probableSolution
Tâche créée mais pas de lecteurLa tâche est toujours en attente ou terminée sans audio_urlContinuez à interroger jusqu'à l'état terminal, puis gérez l'absence de sortie comme un échec de travail utilisateur
Chansons en double après rafraîchissementL'interface utilisateur a recréé la tâche au lieu de la reprendrePersistez et réutilisez le task_id
La tâche de paroles ne renvoie pas d'audioaction: "LYRICS" est uniquement textuelSéparez les chemins d'interface utilisateur pour les paroles et la musique
Paramètre non pris en chargeLe modèle sélectionné n'accepte pas le champSupprimez-le ou choisissez un modèle qui le documente

Référence API

SujetRéférence
Créer de la musiqueCréer de la musique
Obtenir le statut de la musiqueObtenir le statut de la musique
Obtenir le statut de la tâcheObtenir le statut de la tâche
Lister les modèlesLister les modèles
Facturation et tarificationFacturation et tarification

Sur cette page