Geração de música

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

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

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

Letras opcionais quando o provedor oferece suporte à entrada explícita de letras.

Solicita uma saída somente instrumental quando o provedor oferece suporte.

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

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

Duração desejada em segundos quando o provedor oferece suporte a sugestões de duração.

Sugestão de formato de saída quando o provedor oferece suporte.

Os tempos limite das solicitações aos provedores são apenas uma 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 por padrão 300000ms para as solicitações aos provedores.

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 imediatamente uma resposta de início/tarefa e publica a faixa concluída 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. Uma solicitação correspondente concluída recentemente também é deduplicada por 2 minutos.
• Consulta de status: openclaw tasks list ou openclaw tasks show <taskId> inspeciona os status na fila, em execução e terminais.
• Reativação após a conclusão: o OpenClaw injeta um evento interno de conclusão de volta na mesma sessão para que o próprio modelo possa escrever a mensagem de acompanhamento voltada ao usuário.
• Dica no prompt: interações posteriores do usuário/manuais na mesma sessão recebem uma pequena dica em tempo de execução quando uma tarefa de música já está em andamento, para que o modelo não chame music_generate novamente sem necessidade.
• Fallback sem sessão: contextos diretos/locais sem uma sessão real de agente são executados em linha e retornam o resultado final do áudio na mesma interação.

Ciclo de vida da tarefa

A tarefa de música apresenta os mesmos estados do registro geral de tarefas (consulte Tarefas em segundo plano para ver a máquina de estados completa, incluindo timed_out, cancelled e lost). A maioria das execuções de música passa por:

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 provedores

O OpenClaw tenta os 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 na ordem definida.
4. Detecção automática usando somente os padrões de provedores com autenticação:
   • primeiro, o provedor padrão atual do modelo de texto, se ele também oferecer geração de música;
   • depois, os demais provedores de geração de música registrados, em ordem alfabética por ID de provedor.

Se um provedor falhar, o próximo candidato será tentado automaticamente. Se todos falharem, o erro incluirá os detalhes de cada tentativa.

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

Observações sobre os provedores

Como escolher o caminho certo

• Baseado em 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 fluxo de trabalho personalizado ou de um provedor que não faça parte do recurso compartilhado e incluído de música.

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

Modos de recurso 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 simples legados, como maxInputImages, supportsLyrics e supportsFormat, não são suficientes para indicar suporte à edição. Os provedores devem declarar generate e edit explicitamente para que testes em ambiente real, testes de contrato e a ferramenta compartilhada music_generate possam validar o suporte aos modos de forma determinística.

Testes em ambiente real

Cobertura opcional em ambiente real para os provedores compartilhados incluídos (fal, Google, MiniMax, OpenRouter):

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

Wrapper equivalente do repositório, que executa o mesmo arquivo de teste:

pnpm test:live:media:music

Por padrão, este arquivo de testes em ambiente real usa variáveis de ambiente de provedores já exportadas antes dos perfis de autenticação armazenados e executa a cobertura de generate e de edit declarada quando o provedor habilita o modo de edição. Cobertura atual:

• google: generate e edit
• fal: somente generate
• minimax: somente generate
• openrouter: generate e edit
• comfy: cobertura separada do Comfy em ambiente real, fora da bateria compartilhada de provedores

Cobertura opcional em ambiente real para o caminho de música incluído do ComfyUI:

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

O arquivo de testes do Comfy em ambiente real também abrange fluxos de trabalho de imagem e vídeo do Comfy quando essas seções estão configuradas.

Relacionados

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