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.

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

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InRpbWVvdXRNcyIgdHlwZT0ibnVtYmVyIg Timeout opcional da solicitação ao provedor em milissegundos. Quando omitido, o OpenClaw usa agents.defaults.musicGenerationModel.timeoutMs se configurado. Valores abaixo de 10000ms são elevados para 10000ms e informados no resultado da ferramenta. OPENCLAW_DOCS_MARKER:paramClose:

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 de iniciada/tarefa imediatamente e publica a faixa finalizada posteriormente em uma mensagem de acompanhamento do agente.
• Prevenção de duplicatas: enquanto uma tarefa está queued ou running, chamadas music_generate posteriores 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.
• Despertar 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: ["minimax/music-2.6"],      },    },  },}

Ordem de seleção de provedores

O OpenClaw tenta os provedores nesta ordem:

1. Parâmetro model da chamada de 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 provedores com autenticação:
   • provedor padrão atual primeiro;
   • demais provedores de geração de música registrados em ordem de provider-id.

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 de 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 do recurso compartilhado incluído de música.

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

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 apenas por prompt.
• edit quando a solicitação inclui uma ou mais imagens de referência.

Novas implementações de provedor 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 flat 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 deterministicamente.

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 repositório:

pnpm test:live:media music

Este arquivo live carrega variáveis de ambiente de provedor ausentes de ~/.profile, prefere chaves de API live/env a perfis de autenticação armazenados por padrão e executa tanto a cobertura de generate quanto a de edit declarada quando o provedor habilita o modo de edição. Cobertura hoje:

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

Ative a cobertura live 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.

Relacionado

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