Generación de música

Solicitud de generación de música. Obligatoria para action: "generate".

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

Sustitución del proveedor/modelo (p. ej., google/lyria-3-pro-preview, comfy/workflow).

Letras opcionales cuando el proveedor admite una entrada explícita de letras.

Solicita una salida exclusivamente instrumental cuando el proveedor la 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.mediaModels.music.timeoutMs cuando está configurado, eleva los valores inferiores a 120000ms hasta 120000ms y, en los demás casos, establece de forma predeterminada las solicitudes a proveedores en 300000ms.

Comportamiento asíncrono

La generación de música respaldada por una 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/tarea y publica posteriormente la pista terminada en un mensaje de seguimiento del agente.
• Prevención de duplicados: mientras una tarea está en 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. Una solicitud coincidente completada recientemente también se desduplica durante 2 minutos.
• Consulta de estado: openclaw tasks list o openclaw tasks show <taskId> consulta los estados en cola, en ejecución y terminales.
• Reactivación al finalizar: OpenClaw vuelve a inyectar 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 de la solicitud: los turnos posteriores del usuario o manuales de la misma sesión reciben una pequeña indicación en tiempo de ejecución cuando ya hay una tarea de música en curso, para que el modelo no vuelva a llamar a music_generate a ciegas.
• Alternativa sin sesión: los contextos directos/locales sin una sesión real del agente se ejecutan en línea y devuelven el resultado final del audio en el mismo turno.

Ciclo de vida de las tareas

La tarea de música 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 de música 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. Parámetro model de la llamada a la herramienta (si el agente especifica uno).
2. musicGenerationModel.primary de la configuración.
3. 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;
   • los demás proveedores de generación de música registrados, ordenados alfabéticamente por identificador del proveedor.

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

La alternativa automática entre proveedores autenticados siempre está habilitada. Un valor model por llamada sigue siendo determinante.

Notas sobre los proveedores

Elección de la ruta adecuada

• Con respaldo de proveedor compartido cuando se requiera selección de modelos, conmutación por error entre proveedores y el flujo asíncrono integrado de tareas y estados.
• Ruta del Plugin (ComfyUI) cuando se necesite un grafo de flujo de trabajo personalizado o un proveedor que no forme parte de la capacidad compartida incluida de generación de música.

Para depurar comportamientos específicos de ComfyUI, consulte ComfyUI. Para depurar comportamientos de proveedores compartidos, comience con fal, Google (Gemini), MiniMax u OpenRouter.

Modos de capacidad de proveedores

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

• generate para la generación basada únicamente en 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 manera 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

Contenedor equivalente del repositorio, que ejecuta el mismo archivo de prueba:

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 de edit declarada cuando el proveedor activa 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 de Comfy independiente, no incluida en el barrido de proveedores compartidos

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

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 abarca 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 independientes 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