Génération de Musique

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

Démarrage

Guides essentiels

Guides médias

Génération de Musique

Choisissez le Flux de Travail

Créer une Tâche de Musique

Interroger pour la Complétion

Forme de la réponse

Gestion de l’Interface Utilisateur et de l’État

Facturation et Rapprochement

Erreurs Courantes

Référence API

​Choisissez le Flux de Travail

​Créer une Tâche de Musique

​Interroger pour la Complétion

​Forme de la réponse

​Gestion de l’Interface Utilisateur et de l’État

​Facturation et Rapprochement

​Erreurs Courantes

​Référence API

Choisissez le Flux de Travail

Créer une Tâche de Musique

Interroger pour la Complétion

Forme de la réponse

Gestion de l’Interface Utilisateur et de l’État

Facturation et Rapprochement

Erreurs Courantes

Référence API