---
read_when:
    - Генерування музики або аудіо через агента
    - Налаштування провайдерів і моделей для генерування музики
    - Розуміння параметрів інструмента music_generate
summary: Генерування музики зі спільними провайдерами, зокрема плагінами на основі workflow
title: Генерування музики
x-i18n:
    generated_at: "2026-04-23T23:28:46Z"
    model: gpt-5.4
    provider: openai
    source_hash: 6010ee365e4b48b62eb20f3769aae4e409cb651fe7d5946b8c832f0fb120a1e4
    source_path: tools/music-generation.md
    workflow: 15
---

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

Для сесій агента на основі спільних провайдерів OpenClaw запускає генерування музики як
фонове завдання, відстежує його в журналі завдань, а потім знову пробуджує агента, коли
трек готовий, щоб агент міг опублікувати готове аудіо назад в
оригінальний канал.

<Note>
Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерування музики. Якщо ви не бачите `music_generate` в інструментах свого агента, налаштуйте `agents.defaults.musicGenerationModel` або задайте API-ключ провайдера.
</Note>

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

### Генерування на основі спільного провайдера

1. Задайте API-ключ щонайменше для одного провайдера, наприклад `GEMINI_API_KEY` або
   `MINIMAX_API_KEY`.
2. За потреби задайте бажану модель:

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

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

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

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

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

```text
Згенеруй кінематографічний фортепіанний трек із м’якими струнними без вокалу.
```

```text
Згенеруй енергійний chiptune-луп про запуск ракети на світанку.
```

### Генерування Comfy на основі workflow

Вбудований Plugin `comfy` підключається до спільного інструмента `music_generate` через
реєстр провайдерів генерування музики.

1. Налаштуйте `models.providers.comfy.music` із JSON workflow та
   вузлами prompt/output.
2. Якщо ви використовуєте Comfy Cloud, задайте `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY`.
3. Попросіть агента створити музику або викличте інструмент безпосередньо.

Приклад:

```text
/tool music_generate prompt="Теплий ambient synth loop із м’якою текстурою плівки"
```

## Підтримка вбудованих спільних провайдерів

| Провайдер | Типова модель         | Еталонні входи   | Підтримувані керувальні параметри                        | 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`                    |

### Матриця оголошених можливостей

Це явний контракт режимів, який використовують `music_generate`, контрактні тести
та спільний live sweep.

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

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

```text
/tool music_generate action=list
```

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

```text
/tool music_generate action=status
```

Приклад прямого генерування:

```text
/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   | Бажана тривалість у секундах, якщо провайдер підтримує підказки тривалості                        |
| `timeoutMs`      | number   | Необов’язковий тайм-аут запиту до провайдера в мілісекундах                                       |
| `format`         | string   | Підказка щодо вихідного формату (`mp3` або `wav`), якщо провайдер це підтримує                    |
| `filename`       | string   | Підказка щодо назви вихідного файла                                                                |

Не всі провайдери підтримують усі параметри. OpenClaw усе одно перевіряє жорсткі обмеження,
як-от кількість входів, до надсилання. Коли провайдер підтримує тривалість, але
використовує коротший максимум, ніж запитане значення, OpenClaw автоматично обмежує
його до найближчої підтримуваної тривалості. Справді непідтримувані необов’язкові підказки ігноруються
з попередженням, коли вибраний провайдер або модель не можуть їх застосувати.

Результати інструмента повідомляють про застосовані налаштування. Коли OpenClaw обмежує тривалість під час fallback між провайдерами, повернене `durationSeconds` відображає надіслане значення, а `details.normalization.durationSeconds` показує зіставлення між запитаним і застосованим значенням.

## Асинхронна поведінка для шляху на основі спільного провайдера

- Запуски агента з підтримкою сесії: `music_generate` створює фонове завдання, негайно повертає відповідь started/task і пізніше публікує готовий трек у наступному повідомленні агента.
- Запобігання дублюванню: поки це фонове завдання має стан `queued` або `running`, наступні виклики `music_generate` у тій самій сесії повертають стан завдання замість запуску нового генерування.
- Перевірка стану: використовуйте `action: "status"`, щоб перевірити активне завдання генерування музики з підтримкою сесії без запуску нового.
- Відстеження завдань: використовуйте `openclaw tasks list` або `openclaw tasks show <taskId>`, щоб переглядати стани queued, running і terminal для генерування.
- Пробудження після завершення: OpenClaw вставляє внутрішню подію завершення назад у ту саму сесію, щоб модель могла сама написати користувацьке наступне повідомлення.
- Підказка в prompt: наступні користувацькі/ручні ходи в тій самій сесії отримують невелику підказку під час виконання, коли завдання музики вже виконується, щоб модель не викликала `music_generate` повторно всліпу.
- Fallback без сесії: прямі/локальні контексти без реальної сесії агента все одно виконуються вбудовано та повертають фінальний результат аудіо в тому самому ході.

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

Кожен запит `music_generate` проходить через чотири стани:

1. **queued** -- завдання створено, очікує, поки провайдер його прийме.
2. **running** -- провайдер виконує обробку (зазвичай від 30 секунд до 3 хвилин залежно від провайдера та тривалості).
3. **succeeded** -- трек готовий; агент пробуджується та публікує його в розмову.
4. **failed** -- помилка провайдера або тайм-аут; агент пробуджується з деталями помилки.

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

```bash
openclaw tasks list
openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```

Запобігання дублюванню: якщо для поточної сесії вже є музичне завдання у стані `queued` або `running`, `music_generate` повертає стан наявного завдання замість запуску нового. Використовуйте `action: "status"`, щоб явно перевірити стан без запуску нового генерування.

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

### Вибір моделі

```json5
{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
        fallbacks: ["minimax/music-2.5+"],
      },
    },
  },
}
```

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

Під час генерування музики OpenClaw намагається використовувати провайдерів у такому порядку:

1. параметр `model` із виклику інструмента, якщо агент його задає
2. `musicGenerationModel.primary` із конфігурації
3. `musicGenerationModel.fallbacks` по черзі
4. автовизначення з використанням лише типових значень провайдера на основі auth:
   - спочатку поточний типовий провайдер
   - потім інші зареєстровані провайдери генерування музики в порядку ідентифікаторів провайдерів

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

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

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

- Google використовує пакетне генерування Lyria 3. Поточний вбудований потік підтримує
  prompt, необов’язковий текст lyrics і необов’язкові еталонні зображення.
- MiniMax використовує пакетний ендпойнт `music_generation`. Поточний вбудований потік
  підтримує prompt, необов’язкові lyrics, інструментальний режим, керування тривалістю та
  вихід у форматі mp3.
- Підтримка ComfyUI керується workflow і залежить від налаштованого графа та
  зіставлення вузлів для полів prompt/output.

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

Контракт спільного генерування музики тепер підтримує явні оголошення режимів:

- `generate` для генерування лише за prompt
- `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` могли детерміновано перевіряти підтримку режимів.

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

- Використовуйте шлях на основі спільного провайдера, коли вам потрібні вибір моделі, fallback між провайдерами та вбудований асинхронний потік завдання/стану.
- Використовуйте шлях через Plugin, такий як ComfyUI, коли вам потрібен користувацький граф workflow або провайдер, який не входить до спільної вбудованої можливості генерування музики.
- Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див. [ComfyUI](/uk/providers/comfy). Якщо ви налагоджуєте поведінку спільного провайдера, почніть із [Google (Gemini)](/uk/providers/google) або [MiniMax](/uk/providers/minimax).

## Live-тести

Покриття live-тестами за згодою для спільних вбудованих провайдерів:

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

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

```bash
pnpm test:live:media music
```

Цей live-файл завантажує відсутні змінні середовища провайдера з `~/.profile`, типово віддає
перевагу live/env API-ключам перед збереженими профілями auth і запускає покриття
і для `generate`, і для оголошеного `edit`, коли провайдер вмикає режим редагування.

Наразі це означає:

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

Покриття live-тестами за згодою для вбудованого музичного шляху ComfyUI:

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

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

## Пов’язане

- [Фонові завдання](/uk/automation/tasks) - відстеження завдань для відокремлених запусків `music_generate`
- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) - конфігурація `musicGenerationModel`
- [ComfyUI](/uk/providers/comfy)
- [Google (Gemini)](/uk/providers/google)
- [MiniMax](/uk/providers/minimax)
- [Моделі](/uk/concepts/models) - конфігурація моделей і fallback
- [Огляд інструментів](/uk/tools)
