---
read_when:
    - Генерація музики або аудіо через агента
    - Налаштування провайдерів і моделей для генерації музики
    - Розуміння параметрів інструмента music_generate
summary: Генеруйте музику за допомогою спільних провайдерів, зокрема плагінів на основі workflow
title: Генерація музики
x-i18n:
    generated_at: "2026-04-06T22:52:33Z"
    model: gpt-5.4
    provider: openai
    source_hash: ce8da8dfc188efe8593ca5cbec0927dd1d18d2861a1a828df89c8541ccf1cb25
    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`. Додавати інструмент до allow-list не потрібно.

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

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

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

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

### Генерація через Comfy на основі workflow

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

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

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

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

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

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

Кожен запит `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. Автовиявлення лише з використанням стандартних налаштувань провайдера на основі авторизації:
   - спочатку поточний провайдер за замовчуванням
   - решта зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів

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

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

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

- Google використовує пакетну генерацію Lyria 3. Поточний вбудований потік підтримує
  prompt, необов’язковий текст пісні та необов’язкові опорні зображення.
- MiniMax використовує пакетний endpoint `music_generation`. Поточний вбудований потік
  підтримує prompt, необов’язковий текст пісні, інструментальний режим, керування тривалістю та
  вивід у форматі 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` могли детерміновано перевіряти підтримку режимів.

## Як вибрати правильний шлях

- Використовуйте шлях на основі спільного провайдера, якщо вам потрібні вибір моделі, перемикання між провайдерами у разі збоїв і вбудований асинхронний потік завдань/статусу.
- Використовуйте шлях через плагін, наприклад 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`, за замовчуванням надає перевагу API-ключам із live/env над збереженими профілями авторизації та запускає покриття і для `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) - конфігурація моделей і перемикання при збоях
- [Огляд інструментів](/uk/tools)
