---
read_when:
    - Генерація музики або аудіо через агента
    - Налаштування провайдерів і моделей для генерації музики
    - Розуміння параметрів інструмента `music_generate`
sidebarTitle: Music generation
summary: Генеруйте музику через `music_generate` у робочих процесах Google Lyria, MiniMax і ComfyUI
title: Генерація музики
x-i18n:
    generated_at: "2026-04-26T05:36:23Z"
    model: gpt-5.4
    provider: openai
    source_hash: 4eda549dbb93cbfe15e04462e08b7c86ff0718160244e3e5de3b041c62ee81ea
    source_path: tools/music-generation.md
    workflow: 15
---

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

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

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

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

<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 робочого
        процесу та вузлами prompt/output.
      </Step>
      <Step title="Хмарна автентифікація (необов’язково)">
        Для Comfy Cloud встановіть `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY`.
      </Step>
      <Step title="Викличте інструмент">
        ```text
        /tool music_generate prompt="Теплий ембієнтний синт-луп із м’якою текстурою стрічки"
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

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

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

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

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

| Провайдер | Модель за замовчуванням | Еталонні вхідні дані | Підтримувані параметри керування                       | Автентифікація                         |
| --------- | ----------------------- | -------------------- | ------------------------------------------------------ | -------------------------------------- |
| ComfyUI   | `workflow`              | До 1 зображення      | Музика або аудіо, визначені робочим процесом           | `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.6`             | Немає                | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` або MiniMax OAuth    |

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

Явний контракт режимів, який використовують `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
```

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

<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>
<ParamField path="timeoutMs" type="number">Необов’язковий тайм-аут запиту до провайдера в мілісекундах.</ParamField>

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

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

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

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

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

| Стан        | Значення                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `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: ["minimax/music-2.6"],
      },
    },
  },
}
```

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

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

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

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

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

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

<AccordionGroup>
  <Accordion title="ComfyUI">
    Керується робочим процесом і залежить від налаштованого графа та зіставлення вузлів
    для полів prompt/output. Вбудований Plugin `comfy` підключається до
    спільного інструмента `music_generate` через реєстр провайдерів
    генерації музики.
  </Accordion>
  <Accordion title="Google (Lyria 3)">
    Використовує пакетну генерацію Lyria 3. Поточний вбудований потік підтримує
    prompt, необов’язковий текст пісні та необов’язкові еталонні зображення.
  </Accordion>
  <Accordion title="MiniMax">
    Використовує пакетний ендпойнт `music_generation`. Підтримує prompt, необов’язковий
    текст пісні, інструментальний режим, керування тривалістю та вивід у форматі mp3 через
    автентифікацію API-ключем `minimax` або OAuth `minimax-portal`.
  </Accordion>
</AccordionGroup>

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

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

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

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

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

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

## 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`, коли провайдер вмикає режим 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 також охоплює робочі процеси 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)
