--- read_when: - Создание музыки или аудио с помощью агента - Настройка провайдеров и моделей для генерации музыки - Понимание параметров инструмента music_generate sidebarTitle: Music generation summary: Создание музыки с помощью music_generate в рабочих процессах ComfyUI, fal, Google Lyria, MiniMax и OpenRouter title: Генерация музыки x-i18n: generated_at: "2026-07-13T18:50:19Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 24 provider: openai source_hash: 5a540f537141f0d97b264420aae9e986c1f0c3927b8988ebbaf3798b8afd5dd2 source_path: tools/music-generation.md workflow: 16 --- Инструмент `music_generate` создаёт музыку или аудио с помощью общей возможности генерации музыки на базе ComfyUI, fal, Google, MiniMax и OpenRouter. `music_generate` отображается, только когда доступен хотя бы один провайдер генерации музыки: явно заданная конфигурация `agents.defaults.musicGenerationModel` или провайдер с настроенной аутентификацией (например, с заданным ключом API). При запусках агента с поддержкой сеанса `music_generate` запускается как фоновая задача, отслеживает ход выполнения в журнале задач, а затем пробуждает агента, когда трек готов, чтобы тот мог сообщить пользователю и прикрепить готовое аудио. Агент завершения следует контракту видимого ответа сеанса: автоматически отправляет итоговый ответ, если это настроено, либо использует `message(action="send")`, когда сеанс требует применения инструмента сообщений. Если сеанс инициатора неактивен или его не удаётся пробудить, а созданное аудио по-прежнему отсутствует в ответе, OpenClaw идемпотентно отправляет напрямую только недостающее аудио. ## Быстрый старт Задайте ключ API хотя бы для одного провайдера — например, `GEMINI_API_KEY` или `MINIMAX_API_KEY`. ```json5 { agents: { defaults: { musicGenerationModel: { primary: "google/lyria-3-clip-preview", }, }, }, } ``` _«Создай энергичный синти-поп-трек о ночной поездке по неоновому городу»._ Агент автоматически вызывает `music_generate`. Добавлять инструмент в список разрешённых не требуется. Без запуска агента с поддержкой сеанса (в прямом или локальном контексте) инструмент выполняется синхронно и возвращает путь к готовому медиафайлу в том же результате инструмента. Настройте `plugins.entries.comfy.config.music`, указав JSON рабочего процесса и узлы запроса и вывода. Для Comfy Cloud задайте `COMFY_API_KEY` или `COMFY_CLOUD_API_KEY`. ```text /tool music_generate prompt="Тёплый эмбиентный синтезаторный цикл с мягкой плёночной текстурой" ``` Примеры запросов: ```text Создай кинематографичный фортепианный трек с мягкими струнными без вокала. ``` ```text Создай энергичный чиптюн-цикл о запуске ракеты на рассвете. ``` Используйте `action: "list"` для просмотра доступных провайдеров и моделей, а `action: "status"` — для просмотра активной музыкальной задачи с поддержкой сеанса: ```text /tool music_generate action=list /tool music_generate action=status ``` Пример прямой генерации: ```text /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](/ru/providers/minimax#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` | ## Параметры инструмента Запрос на генерацию музыки. Обязателен для `action: "generate"`. `"status"` возвращает текущую задачу сеанса; `"list"` просматривает провайдеров. Переопределение провайдера или модели (например, `google/lyria-3-pro-preview`, `comfy/workflow`). Необязательный текст песни, если провайдер поддерживает его явную передачу. Запросить только инструментальный результат, если провайдер это поддерживает. Путь или URL одного референсного изображения. Несколько референсных изображений (до 10 у поддерживающих провайдеров). Целевая длительность в секундах, если провайдер поддерживает указание длительности. Предпочтительный формат вывода, если провайдер его поддерживает. Предпочтительное имя выходного файла. Не все провайдеры поддерживают все параметры. 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 ` показывает состояние в очереди, выполнения и завершения. - **Пробуждение после завершения:** OpenClaw внедряет внутреннее событие завершения обратно в тот же сеанс, чтобы модель могла самостоятельно написать последующий ответ пользователю. - **Подсказка в запросе:** последующие пользовательские или ручные обращения в том же сеансе получают небольшую подсказку среды выполнения, если музыкальная задача уже выполняется, чтобы модель не вызывала `music_generate` повторно вслепую. - **Резервный вариант без сеанса:** прямые или локальные контексты без настоящего сеанса агента выполняются синхронно и возвращают итоговое аудио в том же обращении. ### Жизненный цикл задачи Музыкальная задача использует те же состояния, что и общий реестр задач (полную схему состояний, включая `timed_out`, `cancelled` и `lost`, см. в разделе [Фоновые задачи](/ru/automation/tasks#task-lifecycle)). Большинство музыкальных задач проходит следующие состояния: | Состояние | Значение | | ----------- | ---------------------------------------------------------------------------------------------- | | `queued` | Задача создана и ожидает принятия провайдером. | | `running` | Провайдер выполняет обработку (обычно от 30 секунд до 3 минут в зависимости от провайдера и длительности). | | `succeeded` | Трек готов; агент пробуждается и публикует его в беседе. | | `failed` | Ошибка или тайм-аут провайдера; агент пробуждается с подробностями ошибки. | Проверьте состояние через CLI: ```bash openclaw tasks list openclaw tasks show openclaw tasks cancel ``` ## Конфигурация ### Выбор модели ```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`. ## Примечания о провайдерах Управляется рабочим процессом и зависит от настроенного графа и сопоставления узлов с полями промпта и вывода. Встроенный плагин `comfy` подключается к общему инструменту `music_generate` через реестр провайдеров генерации музыки. Использует конечные точки моделей fal через общий механизм аутентификации провайдеров. Встроенный провайдер по умолчанию использует `fal-ai/minimax-music/v2.6`, а также предоставляет `fal-ai/ace-step/prompt-to-audio` и `fal-ai/stable-audio-25/text-to-audio` для запросов преобразования промпта в аудио. Тексты песен и инструментальный режим поддерживаются только моделью MiniMax; две другие модели работают только с промптами. Использует пакетную генерацию Lyria 3. Текущий встроенный процесс поддерживает промпт, необязательный текст песни и необязательные эталонные изображения. Модель `lyria-3-clip-preview`, используемая по умолчанию, выводит только mp3; модель `lyria-3-pro-preview` также поддерживает wav. Использует пакетную конечную точку `music_generation`. Поддерживает промпт, необязательный текст песни, инструментальный режим и вывод mp3 с аутентификацией либо по API-ключу `minimax`, либо через OAuth `minimax-portal`. Также предоставляет модели `music-2.6-free`, `music-cover` и `music-cover-free`. Использует аудиовывод завершений чата OpenRouter с включённой потоковой передачей. Встроенный провайдер по умолчанию использует `google/lyria-3-pro-preview`, а также предоставляет `openrouter/google/lyria-3-clip-preview`. ## Выбор подходящего пути - **На основе общего провайдера** — если вам нужны выбор модели, переключение на резервного провайдера и встроенный асинхронный процесс задач и статусов. - **Путь плагина (ComfyUI)** — если вам нужен пользовательский граф рабочего процесса или провайдер, который не входит в общую встроенную возможность генерации музыки. Если вы отлаживаете поведение, специфичное для ComfyUI, см. [ComfyUI](/ru/providers/comfy). Если вы отлаживаете поведение общего провайдера, начните с [fal](/ru/providers/fal), [Google (Gemini)](/ru/providers/google), [MiniMax](/ru/providers/minimax) или [OpenRouter](/ru/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 в реальной среде также охватывает рабочие процессы с изображениями и видео, если соответствующие разделы настроены. ## Связанные материалы - [Фоновые задачи](/ru/automation/tasks) — отслеживание задач для отсоединённых запусков `music_generate` - [ComfyUI](/ru/providers/comfy) - [Справочник по конфигурации](/ru/gateway/config-agents#agent-defaults) — конфигурация `musicGenerationModel` - [Google (Gemini)](/ru/providers/google) - [MiniMax](/ru/providers/minimax) - [Модели](/ru/concepts/models) — настройка моделей и переключение на резервную модель - [Обзор инструментов](/ru/tools)