Generowanie muzyki

Monit generowania muzyki. Wymagany dla action: "generate".

"status" zwraca bieżące zadanie sesji; "list" wyświetla dostawców.

Nadpisanie dostawcy/modelu (np. google/lyria-3-pro-preview, comfy/workflow).

Opcjonalny tekst utworu, gdy dostawca obsługuje jawne przekazywanie tekstu.

Żądanie wyjścia wyłącznie instrumentalnego, gdy dostawca je obsługuje.

Ścieżka lub adres URL pojedynczego obrazu referencyjnego.

Wiele obrazów referencyjnych (do 10 u obsługujących je dostawców).

Docelowy czas trwania w sekundach, gdy dostawca obsługuje wskazówki dotyczące czasu trwania.

Wskazówka dotycząca formatu wyjściowego, gdy dostawca go obsługuje.

Limity czasu żądań do dostawcy są wyłącznie konfiguracją operatora. OpenClaw używa agents.defaults.musicGenerationModel.timeoutMs, gdy ta wartość jest skonfigurowana, podnosi wartości poniżej 120000ms do 120000ms, a w pozostałych przypadkach domyślnie ustawia limit żądań do dostawcy na 300000ms.

Działanie asynchroniczne

Generowanie muzyki oparte na sesji działa jako zadanie w tle:

• Zadanie w tle: music_generate tworzy zadanie w tle, natychmiast zwraca odpowiedź o rozpoczęciu wraz z informacjami o zadaniu, a później publikuje gotowy utwór w kolejnej wiadomości agenta.
• Zapobieganie duplikatom: gdy zadanie ma stan queued lub running, kolejne wywołania music_generate w tej samej sesji zwracają stan zadania zamiast rozpoczynać następne generowanie. Użyj action: "status", aby sprawdzić go jawnie. Niedawno ukończone pasujące żądanie jest również deduplikowane przez 2 minuty.
• Sprawdzanie stanu: openclaw tasks list lub openclaw tasks show <taskId> pozwala sprawdzić stan oczekujący, aktywny i końcowy.
• Wybudzenie po zakończeniu: OpenClaw wprowadza wewnętrzne zdarzenie zakończenia z powrotem do tej samej sesji, aby model mógł samodzielnie napisać dalszą odpowiedź przeznaczoną dla użytkownika.
• Wskazówka w monicie: kolejne tury użytkownika lub ręczne w tej samej sesji otrzymują krótką wskazówkę środowiska wykonawczego, gdy zadanie muzyczne jest już w toku, dzięki czemu model nie wywołuje ponownie music_generate bez sprawdzenia.
• Tryb awaryjny bez sesji: konteksty bezpośrednie/lokalne bez rzeczywistej sesji agenta działają synchronicznie i zwracają końcowy wynik dźwiękowy w tej samej turze.

Cykl życia zadania

Zadanie muzyczne udostępnia te same stany co ogólny rejestr zadań (pełny automat stanów, w tym timed_out, cancelled i lost, opisano w sekcji Zadania w tle). Większość zadań muzycznych przechodzi przez następujące stany:

Sprawdź stan z poziomu CLI:

openclaw tasks listopenclaw tasks show <taskId>openclaw tasks cancel <taskId>

Konfiguracja

Wybór modelu

{  agents: {    defaults: {      musicGenerationModel: {        primary: "google/lyria-3-clip-preview",        fallbacks: ["fal/fal-ai/minimax-music/v2.6", "minimax/music-2.6"],      },    },  },}

Kolejność wyboru dostawcy

OpenClaw próbuje dostawców w następującej kolejności:

1. Parametr model z wywołania narzędzia (jeśli agent go określi).
2. musicGenerationModel.primary z konfiguracji.
3. Wpisy musicGenerationModel.fallbacks w podanej kolejności.
4. Automatyczne wykrywanie wyłącznie na podstawie domyślnych dostawców z uwierzytelnianiem:
   • najpierw bieżący domyślny dostawca modelu tekstowego, jeśli oferuje również generowanie muzyki;
   • pozostali zarejestrowani dostawcy generowania muzyki, alfabetycznie według identyfikatora dostawcy.

Jeśli dostawca zawiedzie, automatycznie podejmowana jest próba użycia następnego kandydata. Jeśli wszystkie próby się nie powiodą, błąd zawiera szczegóły każdej z nich.

Ustaw agents.defaults.mediaGenerationAutoProviderFallback: false, aby używać wyłącznie jawnych wpisów model, primary i fallbacks.

Uwagi dotyczące dostawców

Wybór właściwej ścieżki

• Współdzielona ścieżka oparta na dostawcy, gdy potrzebujesz wyboru modelu, przełączania awaryjnego między dostawcami i wbudowanego asynchronicznego przepływu zadań i statusów.
• Ścieżka pluginu (ComfyUI), gdy potrzebujesz niestandardowego grafu przepływu pracy lub dostawcy, który nie jest częścią współdzielonej, dołączonej funkcji muzycznej.

Jeśli debugujesz zachowanie specyficzne dla ComfyUI, zobacz ComfyUI. Jeśli debugujesz zachowanie współdzielonego dostawcy, zacznij od fal, Google (Gemini), MiniMax lub OpenRouter.

Tryby możliwości dostawcy

Współdzielony kontrakt generowania muzyki obsługuje jawne deklaracje trybów:

• generate do generowania wyłącznie na podstawie polecenia.
• edit, gdy żądanie zawiera co najmniej jeden obraz referencyjny.

Nowe implementacje dostawców powinny preferować jawne bloki trybów:

capabilities: {  generate: {    maxTracks: 1,    supportsLyrics: true,    supportsFormat: true,  },  edit: {    enabled: true,    maxTracks: 1,    maxInputImages: 1,    supportsFormat: true,  },}

Starsze płaskie pola, takie jak maxInputImages, supportsLyrics i supportsFormat, nie wystarczają do zadeklarowania obsługi edycji. Dostawcy powinni jawnie deklarować generate i edit, aby testy na żywo, testy kontraktowe oraz współdzielone narzędzie music_generate mogły deterministycznie weryfikować obsługę trybów.

Testy na żywo

Opcjonalne testy na żywo współdzielonych, dołączonych dostawców (fal, Google, MiniMax, OpenRouter):

OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts

Równoważne repozytoryjne polecenie opakowujące, które uruchamia ten sam plik testowy:

pnpm test:live:media:music

Ten plik testów na żywo domyślnie używa już wyeksportowanych zmiennych środowiskowych dostawcy przed zapisanymi profilami uwierzytelniania i uruchamia testy zarówno dla generate, jak i zadeklarowanego edit, gdy dostawca włącza tryb edycji. Obecny zakres:

• google: generate oraz edit
• fal: tylko generate
• minimax: tylko generate
• openrouter: generate oraz edit
• comfy: oddzielne testy Comfy na żywo, poza współdzielonym zestawem testów dostawców

Opcjonalne testy na żywo dołączonej ścieżki muzycznej ComfyUI:

OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts

Plik testów Comfy na żywo obejmuje również przepływy pracy obrazów i filmów Comfy, gdy odpowiednie sekcje są skonfigurowane.

Powiązane

• Zadania w tle — śledzenie zadań dla odłączonych uruchomień music_generate
• ComfyUI
• Dokumentacja konfiguracji — konfiguracja musicGenerationModel
• Google (Gemini)
• MiniMax
• Modele — konfiguracja modeli i przełączanie awaryjne
• Przegląd narzędzi