​

Geração de música

​

Início rápido

​

Geração compartilhada com provedores

1. Defina uma chave de API para pelo menos um provedor, por exemplo GEMINI_API_KEY ou MINIMAX_API_KEY.
2. Opcionalmente, defina seu modelo preferido:

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

3. Peça ao agente: “Generate an upbeat synthpop track about a night drive through a neon city.”

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

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

​

Geração com Comfy orientada por workflow

1. Configure models.providers.comfy.music com um JSON de workflow e nós de prompt/saída.
2. Se você usa Comfy Cloud, defina COMFY_API_KEY ou COMFY_CLOUD_API_KEY.
3. Peça música ao agente ou chame a ferramenta diretamente.

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

​

Suporte compartilhado a provedores empacotados

​

Matriz de capacidades declaradas

/tool music_generate action=list

/tool music_generate action=status

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

​

Parâmetros da ferramenta embutida

​

Comportamento assíncrono para o caminho compartilhado com provedores

• Execuções de agente com sessão associada: music_generate cria uma tarefa em segundo plano, retorna imediatamente uma resposta de tarefa iniciada/em execução e publica a faixa finalizada depois em uma mensagem de follow-up do agente.
• Prevenção de duplicatas: enquanto essa tarefa em segundo plano ainda estiver queued ou running, chamadas posteriores de music_generate na mesma sessão retornam o status da tarefa em vez de iniciar outra geração.
• Consulta de status: use action: "status" para inspecionar a tarefa de música ativa associada à sessão sem iniciar uma nova.
• Rastreamento de tarefas: use openclaw tasks list ou openclaw tasks show <taskId> para inspecionar status em fila, em execução e final para a geração.
• Despertar na conclusão: o OpenClaw injeta um evento interno de conclusão de volta na mesma sessão para que o modelo possa escrever por conta própria o follow-up voltado ao usuário.
• Dica de prompt: turnos posteriores do usuário/manuais na mesma sessão recebem uma pequena dica de runtime quando uma tarefa de música já está em andamento para que o modelo não chame music_generate cegamente de novo.
• Fallback sem sessão: contextos diretos/locais sem uma sessão real de agente ainda executam inline e retornam o resultado final de áudio no mesmo turno.

​

Ciclo de vida da tarefa

1. queued — tarefa criada, aguardando o provedor aceitá-la.
2. running — o provedor está processando (normalmente entre 30 segundos e 3 minutos, dependendo do provedor e da duração).
3. succeeded — a faixa está pronta; o agente desperta e a publica na conversa.
4. failed — erro do provedor ou timeout; o agente desperta com detalhes do erro.

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

​

Configuração

​

Seleção de modelo

{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
        fallbacks: ["minimax/music-2.5+"],
      },
    },
  },
}

​

Ordem de seleção de provedor

1. Parâmetro model da chamada da ferramenta, se o agente especificar um
2. musicGenerationModel.primary da configuração
3. musicGenerationModel.fallbacks em ordem
4. Auto-detecção usando apenas padrões de provedor respaldados por auth:
   • primeiro o provedor padrão atual
   • os demais provedores registrados de geração de música em ordem de id do provedor

​

Observações sobre provedores

• O Google usa geração em lote do Lyria 3. O fluxo empacotado atual oferece suporte a prompt, texto opcional de letra e imagens de referência opcionais.
• O MiniMax usa o endpoint em lote music_generation. O fluxo empacotado atual oferece suporte a prompt, letras opcionais, modo instrumental, orientação de duração e saída mp3.
• O suporte a ComfyUI é orientado por workflow e depende do grafo configurado, além do mapeamento de nós para campos de prompt/saída.

​

Modos de capacidade do provedor

• generate para geração somente por prompt
• edit quando a solicitação inclui uma ou mais imagens de referência

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

​

Escolhendo o caminho certo

• Use o caminho compartilhado com provedores quando quiser seleção de modelo, failover entre provedores e o fluxo embutido de tarefa/status assíncronos.
• Use um caminho de plugin como ComfyUI quando precisar de um grafo de workflow personalizado ou de um provedor que não faça parte da capacidade compartilhada empacotada de música.
• Se estiver depurando comportamento específico do ComfyUI, consulte ComfyUI. Se estiver depurando comportamento de provedor compartilhado, comece por Google (Gemini) ou MiniMax.

​

Testes live

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

pnpm test:live:media music

• google: generate mais edit
• minimax: somente generate
• comfy: cobertura live separada do Comfy, não a varredura compartilhada de provedores

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

​

Relacionado

• Tarefas em segundo plano - rastreamento de tarefas para execuções destacadas de music_generate
• Referência de configuração - configuração de musicGenerationModel
• ComfyUI
• Google (Gemini)
• MiniMax
• Modelos - configuração de modelo e failover
• Visão geral das ferramentas