Génération de musique

L’outil music_generate permet à l’agent de créer de la musique ou de l’audio via la capacité partagée de génération musicale avec les fournisseurs configurés — ComfyUI, fal, Google, MiniMax et OpenRouter aujourd’hui. Pour les exécutions d’agent adossées à une session, OpenClaw lance la génération musicale comme une tâche en arrière-plan, la suit dans le registre des tâches, puis réveille à nouveau l’agent lorsque la piste est prête afin qu’il puisse prévenir l’utilisateur et joindre l’audio terminé. L’agent de finalisation suit le mode normal de réponse visible de la session : livraison automatique de la réponse finale lorsqu’elle est configurée, ou message(action="send") lorsque la session exige l’outil de message. Si la session demandeuse est inactive ou si son réveil actif échoue, et qu’un fichier audio généré manque encore dans la réponse de finalisation, OpenClaw envoie un repli direct idempotent avec uniquement l’audio manquant.

L’outil partagé intégré n’apparaît que lorsqu’au moins un fournisseur de génération musicale est disponible. Si vous ne voyez pas music_generate dans les outils de votre agent, configurez agents.defaults.musicGenerationModel ou définissez une clé d’API fournisseur.

Démarrage rapide

Adossé à un fournisseur partagé
Workflow ComfyUI

Configurer l’authentification

Définissez une clé d’API pour au moins un fournisseur — par exemple GEMINI_API_KEY ou MINIMAX_API_KEY.

Choisir un modèle par défaut (facultatif)

{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
      },
    },
  },
}

Demander à l’agent

“Generate an upbeat synthpop track about a night drive through a neon city.”L’agent appelle music_generate automatiquement. Aucune liste d’autorisation d’outils n’est nécessaire.

Pour les contextes synchrones directs sans exécution d’agent adossée à une session, l’outil intégré se rabat tout de même sur la génération en ligne et renvoie le chemin du média final dans le résultat de l’outil.

Configurer le workflow

Configurez plugins.entries.comfy.config.music avec un workflow JSON et des nœuds d’invite/de sortie.

Authentification cloud (facultative)

Pour Comfy Cloud, définissez COMFY_API_KEY ou COMFY_CLOUD_API_KEY.

Appeler l’outil

/tool music_generate prompt="Warm ambient synth loop with soft tape texture"

Exemples d’invites :

Generate a cinematic piano track with soft strings and no vocals.

Generate an energetic chiptune loop about launching a rocket at sunrise.

Fournisseurs pris en charge

Fournisseur	Modèle par défaut	Entrées de référence	Contrôles pris en charge	Authentification
ComfyUI	`workflow`	Jusqu’à 1 image	Musique ou audio défini par le workflow	`COMFY_API_KEY`, `COMFY_CLOUD_API_KEY`
fal	`fal-ai/minimax-music/v2.6`	Aucune	`lyrics`, `instrumental`, `durationSeconds`, `format`	`FAL_KEY` ou `FAL_API_KEY`
Google	`lyria-3-clip-preview`	Jusqu’à 10 images	`lyrics`, `instrumental`, `format`	`GEMINI_API_KEY`, `GOOGLE_API_KEY`
MiniMax	`music-2.6`	Aucune	`lyrics`, `instrumental`, `format=mp3`	`MINIMAX_API_KEY` ou OAuth MiniMax
OpenRouter	`google/lyria-3-pro-preview`	Jusqu’à 1 image	`lyrics`, `instrumental`, `durationSeconds`, `format`	`OPENROUTER_API_KEY`

Matrice des capacités

Le contrat de mode explicite utilisé par music_generate, les tests de contrat et le balayage live partagé :

Fournisseur	`generate`	`edit`	Limite de modification	Voies live partagées
ComfyUI	✓	✓	1 image	Hors du balayage partagé ; couvert par `extensions/comfy/comfy.live.test.ts`
fal	✓	—	Aucune	`generate`
Google	✓	✓	10 images	`generate`, `edit`
MiniMax	✓	—	Aucune	`generate`
OpenRouter	✓	✓	1 image	`generate`, `edit`

Utilisez action: "list" pour inspecter les fournisseurs et modèles partagés disponibles à l’exécution :

/tool music_generate action=list

Utilisez action: "status" pour inspecter la tâche musicale active adossée à la session :

/tool music_generate action=status

Exemple de génération directe :

/tool music_generate prompt="Dreamy lo-fi hip hop with vinyl texture and gentle rain" instrumental=true

Paramètres de l’outil

prompt

string

requis

Invite de génération musicale. Obligatoire pour action: "generate".

action

"generate" | "status" | "list"

défaut:"generate"

"status" renvoie la tâche de session actuelle ; "list" inspecte les fournisseurs.

model

string

Remplacement du fournisseur/modèle (par ex. google/lyria-3-pro-preview, comfy/workflow).

lyrics

string

Paroles facultatives lorsque le fournisseur prend en charge une entrée explicite de paroles.

instrumental

boolean

Demande une sortie uniquement instrumentale lorsque le fournisseur la prend en charge.

image

string

Chemin ou URL d’une seule image de référence.

images

string[]

Plusieurs images de référence (jusqu’à 10 chez les fournisseurs compatibles).

durationSeconds

number

Durée cible en secondes lorsque le fournisseur prend en charge les indications de durée.

format

"mp3" | "wav"

Indication de format de sortie lorsque le fournisseur la prend en charge.

filename

string

Indication de nom de fichier de sortie.

Tous les fournisseurs ne prennent pas en charge tous les paramètres. OpenClaw valide tout de même les limites strictes, comme le nombre d’entrées, avant l’envoi. Lorsqu’un fournisseur prend en charge la durée mais utilise un maximum inférieur à la valeur demandée, OpenClaw ramène la durée à la valeur prise en charge la plus proche. Les indications facultatives réellement non prises en charge sont ignorées avec un avertissement lorsque le fournisseur ou le modèle sélectionné ne peut pas les respecter. Les résultats de l’outil indiquent les paramètres appliqués ; details.normalization capture tout mappage entre valeur demandée et valeur appliquée.

Les délais d’expiration des requêtes fournisseur relèvent uniquement de la configuration opérateur. OpenClaw utilise agents.defaults.musicGenerationModel.timeoutMs lorsqu’il est configuré, relève les valeurs inférieures à 120000ms à 120000ms, et sinon définit par défaut les requêtes fournisseur à 300000ms.

Comportement asynchrone

La génération musicale adossée à une session s’exécute comme une tâche en arrière-plan :

Tâche en arrière-plan : music_generate crée une tâche en arrière-plan, renvoie immédiatement une réponse démarrée/tâche, et publie la piste terminée plus tard dans un message d’agent de suivi.
Prévention des doublons : tant qu’une tâche est queued ou running, les appels music_generate ultérieurs dans la même session renvoient l’état de la tâche au lieu de lancer une autre génération. Utilisez action: "status" pour vérifier explicitement.
Consultation de l’état : openclaw tasks list ou openclaw tasks show <taskId> inspecte les états en file d’attente, en cours d’exécution et terminaux.
Réveil de finalisation : OpenClaw injecte un événement interne de finalisation dans la même session afin que le modèle puisse rédiger lui-même le suivi visible par l’utilisateur.
Indication d’invite : les tours utilisateur/manuels ultérieurs dans la même session reçoivent une petite indication d’exécution lorsqu’une tâche musicale est déjà en cours, afin que le modèle ne rappelle pas aveuglément music_generate.
Repli sans session : les contextes directs/locaux sans véritable session d’agent s’exécutent en ligne et renvoient le résultat audio final dans le même tour.

Cycle de vie des tâches

État	Signification
`queued`	Tâche créée, en attente d’acceptation par le fournisseur.
`running`	Le fournisseur traite la demande (généralement de 30 secondes à 3 minutes selon le fournisseur et la durée).
`succeeded`	Piste prête ; l’agent se réveille et la publie dans la conversation.
`failed`	Erreur fournisseur ou délai d’expiration ; l’agent se réveille avec les détails de l’erreur.

Vérifiez l’état depuis la CLI :

openclaw tasks list
openclaw tasks show <taskId>
openclaw tasks cancel <taskId>

Configuration

Sélection du modèle

{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
        fallbacks: ["fal/fal-ai/minimax-music/v2.6", "minimax/music-2.6"],
      },
    },
  },
}

Ordre de sélection des fournisseurs

OpenClaw essaie les fournisseurs dans cet ordre :

Paramètre model de l’appel d’outil (si l’agent en précise un).
musicGenerationModel.primary depuis la configuration.
musicGenerationModel.fallbacks dans l’ordre.
Détection automatique utilisant uniquement les valeurs par défaut des fournisseurs avec authentification :
- fournisseur par défaut actuel en premier ;
- fournisseurs de génération musicale enregistrés restants, par ordre d’identifiant de fournisseur.

Si un fournisseur échoue, le candidat suivant est essayé automatiquement. Si tous échouent, l’erreur inclut les détails de chaque tentative. Définissez agents.defaults.mediaGenerationAutoProviderFallback: false pour utiliser uniquement les entrées explicites model, primary et fallbacks.

Notes sur les fournisseurs

ComfyUI

Piloté par workflow et dépend du graphe configuré ainsi que du mappage des nœuds pour les champs d’invite/de sortie. Le Plugin comfy intégré se branche sur l’outil partagé music_generate via le registre des fournisseurs de génération musicale.

fal

Utilise les points de terminaison de modèles fal via le chemin d’authentification partagé des fournisseurs. Le fournisseur intégré utilise par défaut fal-ai/minimax-music/v2.6 et expose également fal-ai/ace-step/prompt-to-audio et fal-ai/stable-audio-25/text-to-audio pour les requêtes de conversion d’invite en audio.

Google (Lyria 3)

Utilise la génération par lots Lyria 3. Le flux intégré actuel prend en charge l’invite, le texte de paroles facultatif et les images de référence facultatives.

MiniMax

Utilise le point de terminaison par lots music_generation. Prend en charge l’invite, les paroles facultatives, le mode instrumental et la sortie mp3 via l’authentification par clé d’API minimax ou OAuth minimax-portal.

OpenRouter

Utilise la sortie audio des complétions de chat OpenRouter avec le streaming activé. Le fournisseur intégré utilise par défaut google/lyria-3-pro-preview et expose également openrouter/google/lyria-3-clip-preview.

Choisir le bon chemin

Adossé à un fournisseur partagé lorsque vous voulez la sélection de modèle, le basculement entre fournisseurs et le flux intégré asynchrone de tâche/état.
Chemin Plugin (ComfyUI) lorsque vous avez besoin d’un graphe de workflow personnalisé ou d’un fournisseur qui ne fait pas partie de la capacité musicale partagée intégrée.

Si vous déboguez un comportement spécifique à ComfyUI, consultez ComfyUI. Si vous déboguez un comportement partagé de fournisseur, commencez par fal, Google (Gemini), MiniMax ou OpenRouter.

Modes de capacité du fournisseur

Le contrat partagé de génération musicale prend en charge les déclarations de mode explicites :

generate pour la génération à partir d’un prompt uniquement.
edit lorsque la requête inclut une ou plusieurs images de référence.

Les nouvelles implémentations de fournisseurs doivent privilégier les blocs de mode explicites :

capabilities: {
  generate: {
    maxTracks: 1,
    supportsLyrics: true,
    supportsFormat: true,
  },
  edit: {
    enabled: true,
    maxTracks: 1,
    maxInputImages: 1,
    supportsFormat: true,
  },
}

Les anciens champs plats tels que maxInputImages, supportsLyrics et supportsFormat ne suffisent pas à annoncer la prise en charge de l’édition. Les fournisseurs doivent déclarer generate et edit explicitement afin que les tests en conditions réelles, les tests de contrat et l’outil partagé music_generate puissent valider la prise en charge des modes de manière déterministe.

Tests en conditions réelles

Couverture en conditions réelles optionnelle pour les fournisseurs groupés partagés :

OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts

Wrapper du dépôt :

pnpm test:live:media music

Ce fichier en conditions réelles utilise par défaut les variables d’environnement de fournisseur déjà exportées avant les profils d’authentification stockés, et exécute la couverture generate ainsi que la couverture edit déclarée lorsque le fournisseur active le mode d’édition. Couverture actuelle :

google : generate plus edit
fal : generate uniquement
minimax : generate uniquement
openrouter : generate plus edit
comfy : couverture Comfy en conditions réelles distincte, pas le balayage partagé des fournisseurs

Couverture en conditions réelles optionnelle pour le chemin musical ComfyUI groupé :

OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts

Le fichier Comfy en conditions réelles couvre aussi les workflows d’image et de vidéo comfy lorsque ces sections sont configurées.

Connexe

Tâches en arrière-plan — suivi des tâches pour les exécutions détachées de music_generate
ComfyUI
Référence de configuration — configuration musicGenerationModel
Google (Gemini)
MiniMax
Modèles — configuration des modèles et basculement
Vue d’ensemble des outils

​Démarrage rapide

​Fournisseurs pris en charge

​Matrice des capacités

​Paramètres de l’outil

​Comportement asynchrone

​Cycle de vie des tâches

​Configuration

​Sélection du modèle

​Ordre de sélection des fournisseurs

​Notes sur les fournisseurs

​Choisir le bon chemin

​Modes de capacité du fournisseur

​Tests en conditions réelles

​Connexe

Démarrage rapide

Fournisseurs pris en charge

Matrice des capacités

Paramètres de l’outil

Comportement asynchrone

Cycle de vie des tâches

Configuration

Sélection du modèle

Ordre de sélection des fournisseurs

Notes sur les fournisseurs

Choisir le bon chemin

Modes de capacité du fournisseur

Tests en conditions réelles

Connexe