> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

Инструмент `music_generate` создаёт музыку или аудио с помощью общей
возможности генерации музыки на базе ComfyUI, fal, Google, MiniMax и
OpenRouter.

> [!NOTE]
>
> `music_generate` отображается, только когда доступен хотя бы один провайдер
> генерации музыки: явно заданная конфигурация `agents.defaults.musicGenerationModel` или
> провайдер с настроенной аутентификацией (например, с заданным ключом API).

При запусках агента с поддержкой сеанса `music_generate` запускается как фоновая
задача, отслеживает ход выполнения в журнале задач, а затем пробуждает агента,
когда трек готов, чтобы тот мог сообщить пользователю и прикрепить готовое аудио.
Агент завершения следует контракту видимого ответа сеанса: автоматически
отправляет итоговый ответ, если это настроено, либо использует
`message(action="send")`, когда сеанс требует применения инструмента сообщений.
Если сеанс инициатора неактивен или его не удаётся пробудить, а созданное аудио
по-прежнему отсутствует в ответе, OpenClaw идемпотентно отправляет напрямую
только недостающее аудио.

## Быстрый старт

> [tab] Общий провайдер
>
> **1. Настройте аутентификацию**
>
> Задайте ключ API хотя бы для одного провайдера — например,
> `GEMINI_API_KEY` или `MINIMAX_API_KEY`.
>
> **2. Выберите модель по умолчанию (необязательно)**
>
> ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
> {
>   agents: {
>     defaults: {
>       musicGenerationModel: {
>         primary: "google/lyria-3-clip-preview",
>       },
>     },
>   },
> }
> ```
>
> **3. Обратитесь к агенту**
>
> *«Создай энергичный синти-поп-трек о ночной поездке по
> неоновому городу».*
>
> Агент автоматически вызывает `music_generate`. Добавлять инструмент
> в список разрешённых не требуется.
>
> Без запуска агента с поддержкой сеанса (в прямом или локальном контексте)
> инструмент выполняется синхронно и возвращает путь к готовому медиафайлу
> в том же результате инструмента.

> [tab] Рабочий процесс ComfyUI
>
> **1. Настройте рабочий процесс**
>
> Настройте `plugins.entries.comfy.config.music`, указав JSON рабочего процесса
> и узлы запроса и вывода.
>
> **2. Облачная аутентификация (необязательно)**
>
> Для Comfy Cloud задайте `COMFY_API_KEY` или `COMFY_CLOUD_API_KEY`.
>
> **3. Вызовите инструмент**
>
> ```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
> /tool music_generate prompt="Тёплый эмбиентный синтезаторный цикл с мягкой плёночной текстурой"
> ```

Примеры запросов:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
Создай кинематографичный фортепианный трек с мягкими струнными без вокала.
```

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
Создай энергичный чиптюн-цикл о запуске ракеты на рассвете.
```

Используйте `action: "list"` для просмотра доступных провайдеров и моделей,
а `action: "status"` — для просмотра активной музыкальной задачи с поддержкой
сеанса:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
/tool music_generate action=list
/tool music_generate action=status
```

Пример прямой генерации:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
/tool music_generate prompt="Мечтательный lo-fi-хип-хоп с виниловой текстурой и лёгким дождём" 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` или MiniMax OAuth |
| 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](https://docs2.openclaw.ai/ru/providers/minimax.md#music-generation).

Помимо модели по умолчанию на базе MiniMax, fal также предоставляет
`fal-ai/ace-step/prompt-to-audio` (wav, без текста песни и без переключателя инструментального
режима) и `fal-ai/stable-audio-25/text-to-audio` (wav, только запрос). Модель 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` |

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

**prompt** `string` *required*

Запрос на генерацию музыки. Обязателен для `action: "generate"`.

**action** `"generate" | "status" | "list"` (default: 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** `"mp3" | "wav"`

Предпочтительный формат вывода, если провайдер его поддерживает.

**filename** `string`

Предпочтительное имя выходного файла.

> [!NOTE]
>
> Не все провайдеры поддерживают все параметры. OpenClaw всё равно проверяет
> строгие ограничения, например количество входных данных, до отправки запроса.
> Если провайдер поддерживает длительность, но его максимальное значение меньше
> запрошенного, OpenClaw ограничивает значение ближайшей поддерживаемой
> длительностью. Действительно неподдерживаемые необязательные указания
> игнорируются с предупреждением, если выбранный провайдер или модель не может
> их выполнить. Результаты инструмента содержат применённые настройки;
> `details.normalization` фиксирует все сопоставления запрошенных и применённых
> значений.

Тайм-ауты запросов к провайдеру настраиваются только оператором. 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`, см. в разделе
[Фоновые задачи](https://docs2.openclaw.ai/ru/automation/tasks.md#task-lifecycle)). Большинство музыкальных
задач проходит следующие состояния:

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

Проверьте состояние через CLI:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw tasks list
openclaw tasks show <taskId>
openclaw tasks cancel <taskId>
```

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

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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`.

## Примечания о провайдерах

> [accordion] ComfyUI
>
> Управляется рабочим процессом и зависит от настроенного графа и сопоставления узлов
> с полями промпта и вывода. Встроенный плагин `comfy` подключается к
> общему инструменту `music_generate` через реестр провайдеров
> генерации музыки.

> [accordion] 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] Google (Lyria 3)
>
> Использует пакетную генерацию Lyria 3. Текущий встроенный процесс поддерживает
> промпт, необязательный текст песни и необязательные эталонные изображения. Модель
> `lyria-3-clip-preview`, используемая по умолчанию, выводит только mp3; модель
> `lyria-3-pro-preview` также поддерживает wav.

> [accordion] MiniMax
>
> Использует пакетную конечную точку `music_generation`. Поддерживает промпт, необязательный
> текст песни, инструментальный режим и вывод mp3 с аутентификацией либо по API-ключу `minimax`,
> либо через OAuth `minimax-portal`. Также предоставляет модели `music-2.6-free`,
> `music-cover` и `music-cover-free`.

> [accordion] OpenRouter
>
> Использует аудиовывод завершений чата OpenRouter с включённой потоковой передачей. Встроенный
> провайдер по умолчанию использует `google/lyria-3-pro-preview`, а также предоставляет
> `openrouter/google/lyria-3-clip-preview`.

## Выбор подходящего пути

* **На основе общего провайдера** — если вам нужны выбор модели, переключение
  на резервного провайдера и встроенный асинхронный процесс задач и статусов.
* **Путь плагина (ComfyUI)** — если вам нужен пользовательский граф рабочего процесса или
  провайдер, который не входит в общую встроенную возможность генерации музыки.

Если вы отлаживаете поведение, специфичное для ComfyUI, см.
[ComfyUI](https://docs2.openclaw.ai/ru/providers/comfy.md). Если вы отлаживаете поведение общего провайдера,
начните с [fal](https://docs2.openclaw.ai/ru/providers/fal.md), [Google (Gemini)](https://docs2.openclaw.ai/ru/providers/google.md),
[MiniMax](https://docs2.openclaw.ai/ru/providers/minimax.md) или [OpenRouter](https://docs2.openclaw.ai/ru/providers/openrouter.md).

## Режимы возможностей провайдеров

Общий контракт генерации музыки поддерживает явные объявления режимов:

* `generate` для генерации только по промпту.
* `edit`, когда запрос содержит одно или несколько эталонных изображений.

В новых реализациях провайдеров следует отдавать предпочтение явным блокам режимов:

```typescript theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
```

Эквивалентная обёртка репозитория, запускающая тот же тестовый файл:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
pnpm test:live:media:music
```

Этот файл тестов в реальной среде по умолчанию использует уже экспортированные переменные окружения провайдера
раньше сохранённых профилей аутентификации и выполняет тестирование как `generate`, так и объявленного `edit`,
когда провайдер включает режим редактирования. Текущее покрытие:

* `google`: `generate` и `edit`
* `fal`: только `generate`
* `minimax`: только `generate`
* `openrouter`: `generate` и `edit`
* `comfy`: отдельное тестирование Comfy в реальной среде, не входящее в общую проверку провайдеров

Опциональное тестирование в реальной среде для встроенного пути генерации музыки ComfyUI:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```

Файл тестов Comfy в реальной среде также охватывает рабочие процессы с изображениями и видео,
если соответствующие разделы настроены.

## Связанные материалы

* [Фоновые задачи](https://docs2.openclaw.ai/ru/automation/tasks.md) — отслеживание задач для отсоединённых запусков `music_generate`
* [ComfyUI](https://docs2.openclaw.ai/ru/providers/comfy.md)
* [Справочник по конфигурации](https://docs2.openclaw.ai/ru/gateway/config-agents.md#agent-defaults) — конфигурация `musicGenerationModel`
* [Google (Gemini)](https://docs2.openclaw.ai/ru/providers/google.md)
* [MiniMax](https://docs2.openclaw.ai/ru/providers/minimax.md)
* [Модели](https://docs2.openclaw.ai/ru/concepts/models.md) — настройка моделей и переключение на резервную модель
* [Обзор инструментов](https://docs2.openclaw.ai/ru/tools.md)