Geração de música

Prompt de geração de música. Obrigatório para action: "generate".

"status" retorna a tarefa atual da sessão; "list" inspeciona provedores.

Substituição de provedor/modelo (por exemplo, google/lyria-3-pro-preview, comfy/workflow).

Letra opcional quando o provedor oferece suporte a entrada explícita de letra.

Solicita saída apenas instrumental quando o provedor oferece suporte.

Caminho ou URL de uma única imagem de referência.

Várias imagens de referência (até 10 em provedores compatíveis).

Duração-alvo em segundos quando o provedor oferece suporte a dicas de duração.

Dica de formato de saída quando o provedor oferece suporte.

Tempos limite de solicitação de provedor são apenas configuração do operador. O OpenClaw usa agents.defaults.musicGenerationModel.timeoutMs quando configurado, eleva valores abaixo de 120000ms para 120000ms e, caso contrário, usa como padrão 300000ms para solicitações de provedor.

Comportamento assíncrono

A geração de música com sessão é executada como uma tarefa em segundo plano:

• Tarefa em segundo plano: music_generate cria uma tarefa em segundo plano, retorna uma resposta iniciada/de tarefa imediatamente e publica a faixa finalizada depois em uma mensagem de acompanhamento do agente.
• Prevenção de duplicatas: enquanto uma tarefa 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. Use action: "status" para verificar explicitamente.
• Consulta de status: openclaw tasks list ou openclaw tasks show <taskId> inspeciona status em fila, em execução e terminal.
• Ativação de conclusão: o OpenClaw injeta um evento interno de conclusão de volta na mesma sessão para que o modelo possa escrever o acompanhamento voltado ao usuário por conta própria.
• Dica de prompt: turnos posteriores de 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 novamente às cegas.
• Fallback sem sessão: contextos diretos/locais sem uma sessão real de agente são executados inline e retornam o resultado final de áudio no mesmo turno.

Ciclo de vida da tarefa

Verifique o status pela CLI:

openclaw tasks listopenclaw tasks show <taskId>openclaw tasks cancel <taskId>

Configuração

Seleção de modelo

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

Ordem de seleção de provedor

O OpenClaw tenta provedores nesta ordem:

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. Detecção automática usando apenas padrões de provedor com autenticação:
   • provedor padrão atual primeiro;
   • provedores restantes de geração de música registrados em ordem de ID de provedor.

Se um provedor falhar, o próximo candidato é tentado automaticamente. Se todos falharem, o erro inclui detalhes de cada tentativa.

Defina agents.defaults.mediaGenerationAutoProviderFallback: false para usar apenas entradas explícitas de model, primary e fallbacks.

Observações sobre provedores

Escolhendo o caminho certo

• Com provedor compartilhado quando você quer seleção de modelo, failover de provedor e o fluxo assíncrono integrado de tarefa/status.
• Caminho de Plugin (ComfyUI) quando você precisa de um grafo de workflow personalizado ou de um provedor que não faz parte da capacidade compartilhada integrada de música.

Se você estiver depurando um comportamento específico do ComfyUI, consulte ComfyUI. Se você estiver depurando um comportamento compartilhado de provedor, comece com fal, Google (Gemini), MiniMax ou OpenRouter.

Modos de capacidade do provedor

O contrato compartilhado de geração de música oferece suporte a declarações explícitas de modo:

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

Novas implementações de provedores devem preferir blocos de modo explícitos:

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

Campos planos legados como maxInputImages, supportsLyrics e supportsFormat não são suficientes para anunciar suporte a edição. Provedores devem declarar generate e edit explicitamente para que testes live, testes de contrato e a ferramenta compartilhada music_generate possam validar o suporte a modos de forma determinística.

Testes live

Cobertura live opcional para os provedores compartilhados incluídos:

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

Wrapper do repo:

pnpm test:live:media music

Esse arquivo live usa, por padrão, as variáveis de ambiente de provedor já exportadas antes dos perfis de autenticação armazenados, e executa a cobertura de generate e de edit declarado quando o provedor habilita o modo de edição. Cobertura atual:

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

Cobertura live opcional para o caminho de música ComfyUI incluído:

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

O arquivo live do Comfy também cobre fluxos de trabalho de imagem e vídeo do comfy quando essas seções estão configuradas.

Relacionados

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