---
read_when:
    - Створення музики або аудіо за допомогою агента
    - Налаштування постачальників і моделей для генерування музики
    - Розуміння параметрів інструмента music_generate
sidebarTitle: Music generation
summary: Створюйте музику за допомогою `music_generate` у робочих процесах ComfyUI, fal, Google Lyria, MiniMax та OpenRouter
title: Генерування музики
x-i18n:
    generated_at: "2026-07-12T13:47:30Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 5a540f537141f0d97b264420aae9e986c1f0c3927b8988ebbaf3798b8afd5dd2
    source_path: tools/music-generation.md
    workflow: 16
---

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

<Note>
`music_generate` з’являється лише тоді, коли доступний принаймні один провайдер
генерації музики: явно задана конфігурація `agents.defaults.musicGenerationModel`
або провайдер із налаштованою автентифікацією (наприклад, заданим ключем API).
</Note>

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

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

<Tabs>
  <Tab title="На основі спільного провайдера">
    <Steps>
      <Step title="Налаштуйте автентифікацію">
        Задайте ключ API принаймні для одного провайдера, наприклад
        `GEMINI_API_KEY` або `MINIMAX_API_KEY`.
      </Step>
      <Step title="Виберіть типову модель (необов’язково)">
        ```json5
        {
          agents: {
            defaults: {
              musicGenerationModel: {
                primary: "google/lyria-3-clip-preview",
              },
            },
          },
        }
        ```
      </Step>
      <Step title="Зверніться до агента">
        _«Згенеруй енергійну синтпоп-композицію про нічну поїздку неоновим
        містом»._

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

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

  </Tab>
  <Tab title="Робочий процес ComfyUI">
    <Steps>
      <Step title="Налаштуйте робочий процес">
        Налаштуйте `plugins.entries.comfy.config.music`, указавши JSON робочого
        процесу та вузли запиту й виведення.
      </Step>
      <Step title="Хмарна автентифікація (необов’язково)">
        Для Comfy Cloud задайте `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY`.
      </Step>
      <Step title="Викличте інструмент">
        ```text
        /tool music_generate prompt="Warm ambient synth loop with soft tape texture"
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

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

```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](/uk/providers/minimax#music-generation).

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`                                                      |

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

<ParamField path="prompt" type="string" required>
  Запит для генерації музики. Обов’язковий для `action: "generate"`.
</ParamField>
<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
  `"status"` повертає поточне завдання сеансу; `"list"` показує провайдерів.
</ParamField>
<ParamField path="model" type="string">
  Перевизначення провайдера або моделі (наприклад,
  `google/lyria-3-pro-preview`, `comfy/workflow`).
</ParamField>
<ParamField path="lyrics" type="string">
  Необов’язковий текст пісні, якщо провайдер підтримує явне введення тексту.
</ParamField>
<ParamField path="instrumental" type="boolean">
  Запит на створення лише інструментального аудіо, якщо провайдер це підтримує.
</ParamField>
<ParamField path="image" type="string">
  Шлях або URL одного референсного зображення.
</ParamField>
<ParamField path="images" type="string[]">
  Кілька референсних зображень (до 10 у провайдерів, які це підтримують).
</ParamField>
<ParamField path="durationSeconds" type="number">
  Цільова тривалість у секундах, якщо провайдер підтримує підказки щодо
  тривалості.
</ParamField>
<ParamField path="format" type='"mp3" | "wav"'>
  Підказка щодо формату виведення, якщо провайдер це підтримує.
</ParamField>
<ParamField path="filename" type="string">Підказка щодо назви вихідного файлу.</ParamField>

<Note>
Не всі провайдери підтримують усі параметри. OpenClaw усе одно перевіряє
жорсткі обмеження, як-от кількість вхідних даних, перед надсиланням. Якщо
провайдер підтримує тривалість, але має менше максимальне значення, ніж
запитане, OpenClaw обмежує її найближчим підтримуваним значенням. Справді
непідтримувані необов’язкові підказки ігноруються з попередженням, якщо
вибраний провайдер або модель не може їх виконати. Результати інструмента
повідомляють застосовані налаштування; `details.normalization` фіксує всі
перетворення запитаних значень на застосовані.
</Note>

Час очікування запитів до провайдера налаштовує лише оператор. 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`, див. у розділі
[Фонові завдання](/uk/automation/tasks#task-lifecycle)). Більшість завдань
генерації музики проходять такі стани:

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

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

```bash
openclaw tasks list
openclaw 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`.

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

<AccordionGroup>
  <Accordion title="ComfyUI">
    Керується робочим процесом і залежить від налаштованого графа та зіставлення вузлів
    для полів запиту й результату. Вбудований plugin `comfy` підключається до
    спільного інструмента `music_generate` через реєстр провайдерів
    генерації музики.
  </Accordion>
  <Accordion title="fal">
    Використовує кінцеві точки моделей fal через спільний шлях автентифікації провайдера.
    Вбудований провайдер за замовчуванням використовує `fal-ai/minimax-music/v2.6`, а також надає
    `fal-ai/ace-step/prompt-to-audio` і
    `fal-ai/stable-audio-25/text-to-audio` для запитів перетворення текстового запиту на аудіо.
    Тексти пісень та інструментальний режим підтримуються лише моделлю MiniMax; дві інші
    моделі підтримують лише текстові запити.
  </Accordion>
  <Accordion title="Google (Lyria 3)">
    Використовує пакетну генерацію Lyria 3. Поточний вбудований процес підтримує
    текстовий запит, необов’язковий текст пісні та необов’язкові еталонні зображення. Модель
    `lyria-3-clip-preview` за замовчуванням виводить лише mp3; модель
    `lyria-3-pro-preview` також підтримує wav.
  </Accordion>
  <Accordion title="MiniMax">
    Використовує пакетну кінцеву точку `music_generation`. Підтримує текстовий запит, необов’язковий
    текст пісні, інструментальний режим і виведення у форматі mp3 через автентифікацію за ключем API
    `minimax` або OAuth `minimax-portal`. Також надає моделі `music-2.6-free`,
    `music-cover` і `music-cover-free`.
  </Accordion>
  <Accordion title="OpenRouter">
    Використовує аудіовихід завершень чату OpenRouter з увімкненим потоковим передаванням.
    Вбудований провайдер за замовчуванням використовує `google/lyria-3-pro-preview`, а також надає
    `openrouter/google/lyria-3-clip-preview`.
  </Accordion>
</AccordionGroup>

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

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

Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див.
[ComfyUI](/uk/providers/comfy). Якщо ви налагоджуєте поведінку спільного провайдера,
почніть із [fal](/uk/providers/fal), [Google (Gemini)](/uk/providers/google),
[MiniMax](/uk/providers/minimax) або [OpenRouter](/uk/providers/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 у реальному середовищі також охоплює робочі процеси зображень і відео,
якщо відповідні розділи налаштовано.

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

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