OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Tools

Генерування музики

Інструмент music_generate створює музику або аудіо за допомогою спільної можливості генерації музики на основі ComfyUI, fal, Google, MiniMax і OpenRouter.

Для запусків агента на основі сеансу music_generate запускається як фонове завдання, відстежує перебіг виконання в реєстрі завдань, а потім активує агента, коли композиція готова, щоб він міг повідомити користувача й прикріпити готове аудіо. Агент завершення дотримується контракту видимої відповіді сеансу: автоматична остаточна відповідь, якщо її налаштовано, або message(action="send"), якщо сеанс вимагає використання інструмента повідомлень. Якщо сеанс запитувача неактивний або його не вдається активувати, а згенерованого аудіо все ще немає у відповіді, OpenClaw надсилає ідемпотентну пряму резервну відповідь лише з відсутнім аудіо.

Швидкий початок

На основі спільного провайдера

  • Налаштуйте автентифікацію

    Задайте ключ API принаймні для одного провайдера, наприклад GEMINI_API_KEY або MINIMAX_API_KEY.

  • Виберіть типову модель (необов’язково)

    json5
    {  agents: {    defaults: {      musicGenerationModel: {        primary: "google/lyria-3-clip-preview",      },    },  },}

  • Зверніться до агента

    «Згенеруй енергійну синтпоп-композицію про нічну поїздку неоновим містом».

    Агент автоматично викликає music_generate. Додавати інструмент до списку дозволених не потрібно.

    • Без запуску агента на основі сеансу (у прямих або локальних контекстах) інструмент виконується вбудовано й повертає шлях до готового медіафайлу в тому самому результаті інструмента.

    Робочий процес ComfyUI

  • Налаштуйте робочий процес

    Налаштуйте plugins.entries.comfy.config.music, указавши JSON робочого процесу та вузли запиту й виведення.

  • Хмарна автентифікація (необов’язково)

    Для Comfy Cloud задайте COMFY_API_KEY або COMFY_CLOUD_API_KEY.

  • Викличте інструмент

    text
    /tool music_generate prompt="Warm ambient synth loop with soft tape texture"

    • Приклади запитів:

    text
    Generate a cinematic piano track with soft strings and no vocals.
    text
    Generate an energetic chiptune loop about launching a rocket at sunrise.

    Використовуйте action: "list", щоб переглянути доступні провайдери й моделі, і action: "status", щоб переглянути активне музичне завдання на основі сеансу:

    text
    /tool music_generate action=list/tool music_generate action=status

    Приклад прямої генерації:

    text
    /tool music_generate prompt="Dreamy lo-fi hip hop with vinyl texture and gentle rain" instrumental=true

    Підтримувані провайдери

    Провайдер Типова модель Вхідні референси Підтримувані параметри керування Автентифікація
    ComfyUI workflow До 1 зображення Музика або аудіо, визначені робочим процесом COMFY_API_KEY, COMFY_CLOUD_API_KEY
    fal fal-ai/minimax-music/v2.6 Немає lyrics, instrumental, durationSeconds, format FAL_KEY або FAL_API_KEY
    Google lyria-3-clip-preview До 10 зображень lyrics, instrumental, format GEMINI_API_KEY, GOOGLE_API_KEY
    MiniMax music-2.6 Немає lyrics, instrumental, format (лише mp3) MINIMAX_API_KEY або OAuth MiniMax
    OpenRouter google/lyria-3-pro-preview До 1 зображення lyrics, instrumental, durationSeconds, format OPENROUTER_API_KEY

    MiniMax реєструє два ідентифікатори провайдера, які використовують ті самі моделі: minimax для автентифікації за ключем API та minimax-portal для OAuth. Посилання на моделі відповідають способу автентифікації (minimax/music-2.6 і minimax-portal/music-2.6 відповідно); див. MiniMax.

    fal також надає fal-ai/ace-step/prompt-to-audio (wav, без тексту пісні та без перемикача інструментального режиму) і fal-ai/stable-audio-25/text-to-audio (wav, лише запит) разом зі своєю типовою моделлю на основі MiniMax. Типова модель Google lyria-3-clip-preview виводить лише mp3; lyria-3-pro-preview також підтримує wav. MiniMax також надає music-2.6-free, music-cover і music-cover-free. OpenRouter також надає google/lyria-3-clip-preview.

    Матриця можливостей

    Явний контракт режимів, який використовують music_generate, тести контракту та спільна перевірка наживо:

    Провайдер generate edit Обмеження редагування Спільні канали перевірки наживо
    ComfyUI ✓ ✓ 1 зображення Не входить до спільної перевірки; охоплено extensions/comfy/comfy.live.test.ts
    fal ✓ — Немає generate
    Google ✓ ✓ 10 зображень generate, edit
    MiniMax ✓ — Немає generate
    OpenRouter ✓ ✓ 1 зображення generate, edit

    Параметри інструмента

    promptstringrequired

    Запит для генерації музики. Обов’язковий для action: "generate".

    action"generate" | "status" | "list"default: generate

    "status" повертає поточне завдання сеансу; "list" показує провайдерів.

    modelstring

    Перевизначення провайдера або моделі (наприклад, google/lyria-3-pro-preview, comfy/workflow).

    lyricsstring

    Необов’язковий текст пісні, якщо провайдер підтримує явне введення тексту.

    instrumentalboolean

    Запит на створення лише інструментального аудіо, якщо провайдер це підтримує.

    imagestring

    Шлях або URL одного референсного зображення.

    imagesstring[]

    Кілька референсних зображень (до 10 у провайдерів, які це підтримують).

    durationSecondsnumber

    Цільова тривалість у секундах, якщо провайдер підтримує підказки щодо тривалості.

    format"mp3" | "wav"

    Підказка щодо формату виведення, якщо провайдер це підтримує.

    filenamestring

    Час очікування запитів до провайдера налаштовує лише оператор. OpenClaw використовує agents.defaults.musicGenerationModel.timeoutMs, якщо його налаштовано, збільшує значення менші за 120000ms до 120000ms, а в іншому разі встановлює типовий час очікування запитів до провайдера 300000ms.

    Асинхронна поведінка

    Генерація музики на основі сеансу виконується як фонове завдання:

    • Фонове завдання: music_generate створює фонове завдання, негайно повертає відповідь про запуск і завдання, а згодом публікує готову композицію в наступному повідомленні агента.
    • Запобігання дублюванню: доки завдання має стан queued або running, подальші виклики music_generate у тому самому сеансі повертають стан завдання замість запуску ще однієї генерації. Для явної перевірки використовуйте action: "status". Нещодавно завершений ідентичний запит також дедуплікується протягом 2 хвилин.
    • Перегляд стану: openclaw tasks list або openclaw tasks show <taskId> показує стан завдань у черзі, у процесі виконання та в кінцевому стані.
    • Активація після завершення: OpenClaw додає внутрішню подію завершення назад у той самий сеанс, щоб модель могла самостійно написати подальшу відповідь користувачеві.
    • Підказка в запиті: подальші користувацькі або ручні звернення в тому самому сеансі отримують невелику підказку середовища виконання, якщо музичне завдання вже виконується, щоб модель не викликала music_generate повторно без перевірки.
    • Резервний варіант без сеансу: прямі або локальні контексти без справжнього сеансу агента виконуються вбудовано й повертають готовий аудіорезультат у тому самому зверненні.

    Життєвий цикл завдання

    Музичне завдання має ті самі стани, що й загальний реєстр завдань (повну машину станів, зокрема timed_out, cancelled і lost, див. у розділі Фонові завдання). Більшість завдань генерації музики проходять такі стани:

    Стан Значення
    queued Завдання створено й очікує, доки провайдер його прийме.
    running Провайдер виконує обробку (зазвичай від 30 секунд до 3 хвилин залежно від провайдера й тривалості).
    succeeded Композиція готова; агент активується й публікує її в розмові.
    failed Помилка провайдера або завершення часу очікування; агент активується з подробицями помилки.

    Перевірте стан через CLI:

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

    Конфігурація

    Вибір моделі

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

    Порядок вибору провайдерів

    OpenClaw перебирає провайдерів у такому порядку:

    1. Параметр model із виклику інструмента (якщо агент його вказує).
    2. musicGenerationModel.primary із конфігурації.
    3. Елементи musicGenerationModel.fallbacks по черзі.
    4. Автоматичне виявлення лише за типовими значеннями провайдерів із налаштованою автентифікацією:
      • спочатку поточний типовий провайдер текстової моделі, якщо він також підтримує генерацію музики;
      • решта зареєстрованих провайдерів генерації музики в алфавітному порядку за ідентифікатором провайдера.

    Якщо один провайдер завершує роботу з помилкою, автоматично виконується спроба з наступним кандидатом. Якщо всі спроби невдалі, помилка містить подробиці кожної з них.

    Установіть agents.defaults.mediaGenerationAutoProviderFallback: false, щоб використовувати лише явно задані записи model, primary і fallbacks.

    Примітки щодо провайдерів

    ComfyUI

    Керується робочим процесом і залежить від налаштованого графа та зіставлення вузлів для полів запиту й результату. Вбудований plugin comfy підключається до спільного інструмента music_generate через реєстр провайдерів генерації музики.

    fal

    Використовує кінцеві точки моделей fal через спільний шлях автентифікації провайдера. Вбудований провайдер за замовчуванням використовує fal-ai/minimax-music/v2.6, а також надає fal-ai/ace-step/prompt-to-audio і fal-ai/stable-audio-25/text-to-audio для запитів перетворення текстового запиту на аудіо. Тексти пісень та інструментальний режим підтримуються лише моделлю MiniMax; дві інші моделі підтримують лише текстові запити.

    Google (Lyria 3)

    Використовує пакетну генерацію Lyria 3. Поточний вбудований процес підтримує текстовий запит, необов’язковий текст пісні та необов’язкові еталонні зображення. Модель lyria-3-clip-preview за замовчуванням виводить лише mp3; модель lyria-3-pro-preview також підтримує wav.

    MiniMax

    Використовує пакетну кінцеву точку music_generation. Підтримує текстовий запит, необов’язковий текст пісні, інструментальний режим і виведення у форматі mp3 через автентифікацію за ключем API minimax або OAuth minimax-portal. Також надає моделі music-2.6-free, music-cover і music-cover-free.

    OpenRouter

    Використовує аудіовихід завершень чату OpenRouter з увімкненим потоковим передаванням. Вбудований провайдер за замовчуванням використовує google/lyria-3-pro-preview, а також надає openrouter/google/lyria-3-clip-preview.

    Вибір правильного шляху

    • Через спільного провайдера, якщо потрібні вибір моделі, перемикання на резервного провайдера та вбудований асинхронний процес завдання/стану.
    • Шлях plugin (ComfyUI), якщо потрібен власний граф робочого процесу або провайдер, який не входить до спільної вбудованої можливості генерації музики.

    Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див. ComfyUI. Якщо ви налагоджуєте поведінку спільного провайдера, почніть із fal, Google (Gemini), MiniMax або OpenRouter.

    Режими можливостей провайдера

    Спільний контракт генерації музики підтримує явне оголошення режимів:

    • generate для генерації лише за текстовим запитом.
    • edit, коли запит містить одне або кілька еталонних зображень.

    У нових реалізаціях провайдерів варто надавати перевагу явним блокам режимів:

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

    Застарілих пласких полів, як-от maxInputImages, supportsLyrics і supportsFormat, недостатньо для оголошення підтримки редагування. Провайдери мають явно оголошувати generate і edit, щоб тести в реальному середовищі, контрактні тести та спільний інструмент music_generate могли детерміновано перевіряти підтримку режимів.

    Тести в реальному середовищі

    Необов’язкове тестове покриття в реальному середовищі для спільних вбудованих провайдерів (fal, Google, MiniMax, OpenRouter):

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

    Еквівалентна обгортка репозиторію, яка запускає той самий файл тестів:

    bash
    pnpm test:live:media:music

    За замовчуванням цей файл тестів у реальному середовищі використовує вже експортовані змінні середовища провайдера перед збереженими профілями автентифікації та запускає покриття як generate, так і оголошеного edit, коли провайдер вмикає режим редагування. Поточне покриття:

    • google: generate і edit
    • fal: лише generate
    • minimax: лише generate
    • openrouter: generate і edit
    • comfy: окреме покриття Comfy у реальному середовищі, поза спільним проходом провайдерів

    Необов’язкове тестове покриття в реальному середовищі для вбудованого музичного шляху ComfyUI:

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

    Файл тестів Comfy у реальному середовищі також охоплює робочі процеси зображень і відео, якщо відповідні розділи налаштовано.

    Пов’язані матеріали

    Was this useful?
    On this page

    On this page