Генерація музики
Інструмент music_generate дає агенту змогу створювати музику або аудіо через
спільну можливість генерації музики з налаштованими провайдерами, такими як Google,
MiniMax і налаштований через workflow ComfyUI.
Для сеансів агента на основі спільного провайдера OpenClaw запускає генерацію музики як
фонове завдання, відстежує її в журналі завдань, а потім знову пробуджує агента, коли
трек готовий, щоб агент міг опублікувати готове аудіо назад у
початковий канал.
Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації музики. Якщо ви не бачите music_generate серед інструментів вашого агента, налаштуйте agents.defaults.musicGenerationModel або вкажіть API-ключ провайдера.
Швидкий старт
Генерація на основі спільного провайдера
- Установіть API-ключ принаймні для одного провайдера, наприклад
GEMINI_API_KEY або
MINIMAX_API_KEY.
- За потреби встановіть бажану модель:
{
agents: {
defaults: {
musicGenerationModel: {
primary: "google/lyria-3-clip-preview",
},
},
},
}
- Попросіть агента: “Згенеруй енергійний synthpop-трек про нічну поїздку
крізь неонове місто.”
Агент викликає music_generate автоматично. Додавати інструмент до списку дозволених не потрібно.
Для прямих синхронних контекстів без запуску агента на основі сеансу вбудований
інструмент усе одно повертається до вбудованої генерації та повертає фінальний шлях до медіафайлу в результаті інструмента.
Приклади запитів:
Згенеруй кінематографічний фортепіанний трек із м’якими струнними та без вокалу.
Згенеруй енергійну chiptune-петлю про запуск ракети на світанку.
Генерація Comfy на основі workflow
Вбудований плагін comfy підключається до спільного інструмента music_generate через
реєстр провайдерів генерації музики.
- Налаштуйте
models.providers.comfy.music за допомогою JSON workflow та
вузлів prompt/output.
- Якщо ви використовуєте Comfy Cloud, установіть
COMFY_API_KEY або COMFY_CLOUD_API_KEY.
- Попросіть агента створити музику або викличте інструмент безпосередньо.
Приклад:
/tool music_generate prompt="Тепла ембієнтна synth-петля з м’якою текстурою стрічки"
Підтримка спільних вбудованих провайдерів
| Провайдер | Модель за замовчуванням | Еталонні входи | Підтримувані елементи керування | API-ключ |
|---|
| ComfyUI | workflow | До 1 зображення | Визначена workflow музика або аудіо | COMFY_API_KEY, COMFY_CLOUD_API_KEY |
| Google | lyria-3-clip-preview | До 10 зображень | lyrics, instrumental, format | GEMINI_API_KEY, GOOGLE_API_KEY |
| MiniMax | music-2.5+ | Немає | lyrics, instrumental, durationSeconds, format=mp3 | MINIMAX_API_KEY |
action: "list", щоб переглянути доступні спільні провайдери та моделі
під час виконання:
/tool music_generate action=list
action: "status", щоб переглянути активне завдання музики на основі сеансу:
/tool music_generate action=status
/tool music_generate prompt="Мрійливий lo-fi hip hop із вініловою текстурою та ніжним дощем" instrumental=true
Параметри вбудованого інструмента
| Параметр | Тип | Опис |
|---|
prompt | string | Запит на генерацію музики (обов’язковий для action: "generate") |
action | string | "generate" (за замовчуванням), "status" для поточного завдання сеансу або "list" для перегляду провайдерів |
model | string | Перевизначення провайдера/моделі, наприклад google/lyria-3-pro-preview або comfy/workflow |
lyrics | string | Необов’язковий текст пісні, якщо провайдер підтримує явне введення тексту |
instrumental | boolean | Запит лише на інструментальний результат, якщо провайдер це підтримує |
image | string | Шлях або URL одного еталонного зображення |
images | string[] | Кілька еталонних зображень (до 10) |
durationSeconds | number | Цільова тривалість у секундах, якщо провайдер підтримує підказки щодо тривалості |
format | string | Підказка щодо формату виводу (mp3 або wav), якщо провайдер це підтримує |
filename | string | Підказка щодо імені вихідного файлу |
Асинхронна поведінка для шляху на основі спільного провайдера
- Запуски агента на основі сеансу:
music_generate створює фонове завдання, негайно повертає відповідь started/task і публікує готовий трек пізніше в наступному повідомленні агента.
- Запобігання дублюванню: поки це фонове завдання все ще має стан
queued або running, наступні виклики music_generate у тому самому сеансі повертають стан завдання замість запуску нової генерації.
- Перегляд стану: використовуйте
action: "status", щоб переглянути активне музичне завдання на основі сеансу без запуску нового.
- Відстеження завдань: використовуйте
openclaw tasks list або openclaw tasks show <taskId>, щоб переглядати статуси queued, running і terminal для генерації.
- Пробудження після завершення: OpenClaw впроваджує внутрішню подію завершення назад у той самий сеанс, щоб модель могла самостійно написати користувацьке подальше повідомлення.
- Підказка в prompt: пізніші користувацькі/ручні ходи в тому самому сеансі отримують невелику підказку часу виконання, коли завдання музики вже виконується, щоб модель не викликала
music_generate знову бездумно.
- Режим без сеансу: прямі/локальні контексти без реального сеансу агента все одно виконуються вбудовано й повертають фінальний результат аудіо в тому самому ході.
Налаштування
Вибір моделі
{
agents: {
defaults: {
musicGenerationModel: {
primary: "google/lyria-3-clip-preview",
fallbacks: ["minimax/music-2.5+"],
},
},
},
}
Порядок вибору провайдера
Під час генерації музики OpenClaw намагається використати провайдерів у такому порядку:
- параметр
model із виклику інструмента, якщо агент його вказує
musicGenerationModel.primary із конфігураціїmusicGenerationModel.fallbacks у заданому порядку- Автовиявлення з використанням лише стандартних значень провайдерів на основі auth:
- спочатку поточний провайдер за замовчуванням
- решта зареєстрованих провайдерів генерації музики в порядку provider-id
Якщо провайдер завершується помилкою, автоматично пробується наступний кандидат. Якщо всі завершуються помилкою,
помилка містить подробиці кожної спроби.
Примітки щодо провайдерів
- Google використовує пакетну генерацію Lyria 3. Поточний вбудований потік підтримує
prompt, необов’язковий текст lyrics і необов’язкові еталонні зображення.
- MiniMax використовує пакетний endpoint
music_generation. Поточний вбудований потік
підтримує prompt, необов’язкові lyrics, інструментальний режим, керування тривалістю та
вивід у mp3.
- Підтримка ComfyUI керується workflow і залежить від налаштованого графа та
зіставлення вузлів для полів prompt/output.
Вибір правильного шляху
- Використовуйте шлях на основі спільного провайдера, якщо вам потрібні вибір моделі, відмовостійке перемикання між провайдерами та вбудований асинхронний потік завдань/стану.
- Використовуйте шлях плагіна, наприклад ComfyUI, якщо вам потрібен власний граф workflow або провайдер, який не входить до спільної вбудованої можливості музики.
- Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див. ComfyUI. Якщо ви налагоджуєте поведінку спільного провайдера, почніть із Google (Gemini) або MiniMax.
Живі тести
Добровільне live-покриття для спільних вбудованих провайдерів:
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
Пов’язане
