Generación de música

Instrucción para generar música. Es obligatoria para action: "generate".

"status" devuelve la tarea actual de la sesión; "list" consulta los proveedores.

Sustitución del proveedor o modelo (por ejemplo, google/lyria-3-pro-preview, comfy/workflow).

Letra opcional cuando el proveedor admite una entrada explícita de letra.

Solicita una salida exclusivamente instrumental cuando el proveedor lo admite.

Ruta o URL de una única imagen de referencia.

Varias imágenes de referencia (hasta 10 en los proveedores compatibles).

Duración objetivo en segundos cuando el proveedor admite indicaciones de duración.

Indicación del formato de salida cuando el proveedor lo admite.

Los tiempos de espera de las solicitudes a proveedores son exclusivamente una configuración del operador. OpenClaw utiliza agents.defaults.musicGenerationModel.timeoutMs cuando está configurado, eleva los valores inferiores a 120000ms hasta 120000ms y, en caso contrario, establece de forma predeterminada un tiempo de espera de 300000ms para las solicitudes a proveedores.

Comportamiento asíncrono

La generación de música respaldada por sesión se ejecuta como una tarea en segundo plano:

• Tarea en segundo plano: music_generate crea una tarea en segundo plano, devuelve inmediatamente una respuesta de inicio o de tarea y publica posteriormente la pista terminada en un mensaje de seguimiento del agente.
• Prevención de duplicados: mientras una tarea está en estado queued o running, las llamadas posteriores a music_generate en la misma sesión devuelven el estado de la tarea en lugar de iniciar otra generación. Use action: "status" para comprobarlo explícitamente. También se elimina la duplicación de una solicitud coincidente completada recientemente durante 2 minutos.
• Consulta de estado: openclaw tasks list u openclaw tasks show <taskId> consulta los estados en cola, en ejecución y terminales.
• Reactivación al finalizar: OpenClaw inyecta un evento interno de finalización en la misma sesión para que el propio modelo pueda redactar el seguimiento dirigido al usuario.
• Indicación en la instrucción: los turnos posteriores del usuario o manuales en la misma sesión reciben una breve indicación en tiempo de ejecución cuando ya hay una tarea musical en curso, para evitar que el modelo vuelva a llamar a music_generate sin comprobarlo.
• Respaldo sin sesión: los contextos directos o locales sin una sesión real de agente se ejecutan en línea y devuelven el resultado final de audio en el mismo turno.

Ciclo de vida de la tarea

La tarea musical presenta los mismos estados que el registro general de tareas (consulte Tareas en segundo plano para ver la máquina de estados completa, incluidos timed_out, cancelled y lost). La mayoría de las ejecuciones musicales pasan por:

Compruebe el estado desde la CLI:

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

Configuración

Selección del modelo

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

Orden de selección de proveedores

OpenClaw prueba los proveedores en este orden:

1. El parámetro model de la llamada a la herramienta (si el agente especifica uno).
2. musicGenerationModel.primary de la configuración.
3. Los valores de musicGenerationModel.fallbacks, en orden.
4. Detección automática utilizando únicamente los valores predeterminados de proveedores respaldados por autenticación:
   • primero, el proveedor predeterminado actual del modelo de texto, si también ofrece generación de música;
   • después, los demás proveedores de generación de música registrados, ordenados alfabéticamente por identificador de proveedor.

Si un proveedor falla, se prueba automáticamente el siguiente candidato. Si todos fallan, el error incluye los detalles de cada intento.

Establezca agents.defaults.mediaGenerationAutoProviderFallback: false para usar únicamente las entradas explícitas model, primary y fallbacks.

Notas sobre los proveedores

Elegir la ruta adecuada

• Respaldada por proveedores compartidos cuando se necesita selección de modelos, conmutación por error entre proveedores y el flujo integrado de tareas asíncronas y estados.
• Ruta de Plugin (ComfyUI) cuando se necesita un grafo de flujo de trabajo personalizado o un proveedor que no forma parte de la capacidad musical compartida incluida.

Si está depurando un comportamiento específico de ComfyUI, consulte ComfyUI. Si está depurando el comportamiento de proveedores compartidos, comience por fal, Google (Gemini), MiniMax u OpenRouter.

Modos de capacidad de los proveedores

El contrato compartido de generación de música admite declaraciones explícitas de modos:

• generate para la generación solo a partir de indicaciones.
• edit cuando la solicitud incluye una o más imágenes de referencia.

Las nuevas implementaciones de proveedores deben preferir bloques de modo explícitos:

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

Los campos planos heredados como maxInputImages, supportsLyrics y supportsFormat no bastan para anunciar la compatibilidad con la edición. Los proveedores deben declarar generate y edit explícitamente para que las pruebas en vivo, las pruebas de contrato y la herramienta compartida music_generate puedan validar la compatibilidad con los modos de forma determinista.

Pruebas en vivo

Cobertura en vivo opcional para los proveedores compartidos incluidos (fal, Google, MiniMax, OpenRouter):

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

Comando equivalente del repositorio, que ejecuta el mismo archivo de pruebas:

pnpm test:live:media:music

De forma predeterminada, este archivo de pruebas en vivo usa las variables de entorno de proveedores ya exportadas antes que los perfiles de autenticación almacenados, y ejecuta tanto la cobertura de generate como la declarada para edit cuando el proveedor habilita el modo de edición. Cobertura actual:

• google: generate más edit
• fal: solo generate
• minimax: solo generate
• openrouter: generate más edit
• comfy: cobertura en vivo independiente de Comfy, no incluida en el recorrido de proveedores compartidos

Cobertura en vivo opcional para la ruta de música de ComfyUI incluida:

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

El archivo de pruebas en vivo de Comfy también cubre los flujos de trabajo de imágenes y vídeos de comfy cuando esas secciones están configuradas.

Temas relacionados

• Tareas en segundo plano — seguimiento de tareas para ejecuciones desacopladas de music_generate
• ComfyUI
• Referencia de configuración — configuración de musicGenerationModel
• Google (Gemini)
• MiniMax
• Modelos — configuración y conmutación por error de modelos
• Descripción general de las herramientas