English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Tools

Генерація музики

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

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

Швидкий старт

Shared provider-backed

  • Configure auth

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

  • Pick a default model (optional)

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

  • Ask the agent

    "Згенеруй бадьорий синтпоп-трек про нічну поїздку крізь неонове місто."

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

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

    ComfyUI workflow

  • Configure the workflow

    Налаштуйте plugins.entries.comfy.config.music за допомогою workflow JSON і вузлів prompt/output.

  • Cloud auth (optional)

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

  • Call the tool

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

    • Приклади prompt:

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

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

    Провайдер Модель за замовчуванням Вхідні референси Підтримувані елементи керування Автентифікація
    ComfyUI workflow До 1 зображення Музика або аудіо, визначені workflow 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 або MiniMax OAuth
    OpenRouter google/lyria-3-pro-preview До 1 зображення lyrics, instrumental, durationSeconds, format OPENROUTER_API_KEY

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

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

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

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

    text
    /tool music_generate action=list

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

    text
    /tool music_generate action=status

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

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

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

    promptstringrequired

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

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

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

    modelstring

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

    lyricsstring

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

    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", щоб перевірити явно.
    • Перегляд статусу: openclaw tasks list або openclaw tasks show <taskId> показує статус queued, running і термінальний статус.
    • Пробудження після завершення: OpenClaw вводить внутрішню подію завершення назад у ту саму сесію, щоб модель сама могла написати наступну відповідь для користувача.
    • Підказка prompt: подальші користувацькі/ручні ходи в тій самій сесії отримують невелику runtime-підказку, коли завдання генерації музики вже виконується, щоб модель не викликала music_generate наосліп знову.
    • Резервний варіант без сесії: прямі/локальні контексти без реальної сесії агента виконуються вбудовано й повертають фінальний аудіорезультат у тому самому ході.

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

    Стан Значення
    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. Автовиявлення лише за замовчуваннями провайдера з налаштованою автентифікацією:
      • спочатку поточний провайдер за замовчуванням;
      • решта зареєстрованих провайдерів генерації музики в порядку provider-id.

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

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

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

    ComfyUI

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

    fal

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

    Google (Lyria 3)

    Використовує пакетну генерацію Lyria 3. Поточний вбудований потік підтримує prompt, необов’язковий текст lyrics і необов’язкові референсні зображення.

    MiniMax

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

    OpenRouter

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

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

    • Спільний шлях із підтримкою провайдерів — коли потрібні вибір моделі, перемикання між провайдерами у разі збою та вбудований асинхронний потік завдання/статусу.
    • Шлях Plugin (ComfyUI) — коли потрібен власний граф workflow або провайдер, який не входить до спільної вбудованої можливості генерації музики.

    Якщо ви налагоджуєте поведінку, специфічну для 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, щоб live-тести, контрактні тести та спільний інструмент music_generate могли детерміновано перевіряти підтримку режимів.

    Live-тести

    Опціональне live-покриття для спільних вбудованих провайдерів:

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

    Обгортка репозиторію:

    bash
    pnpm test:live:media music

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

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

    Опціональне live-покриття для вбудованого музичного шляху ComfyUI:

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

    Live-файл Comfy також покриває робочі процеси зображень і відео comfy, коли ці розділи налаштовані.

    Пов’язане

    Was this useful?
    On this page

    On this page