Müzik oluşturma

music_generate aracı, ajanın yapılandırılmış sağlayıcılarla paylaşılan müzik üretme yeteneği üzerinden müzik veya ses oluşturmasını sağlar — bugün ComfyUI, fal, Google, MiniMax ve OpenRouter. Oturum destekli ajan çalıştırmaları için OpenClaw müzik üretimini bir arka plan görevi olarak başlatır, görev kayıt defterinde izler, ardından parça hazır olduğunda ajanı yeniden uyandırır; böylece ajan kullanıcıya haber verip tamamlanan sesi ekleyebilir. Tamamlama ajanı, oturumun normal görünür yanıt modunu izler: yapılandırıldığında otomatik son yanıt teslimi veya oturum mesaj aracını gerektiriyorsa message(action="send"). İstek sahibi oturum etkin değilse veya etkin uyandırması başarısız olursa ve oluşturulan sesin bir kısmı tamamlama yanıtında hâlâ eksikse, OpenClaw yalnızca eksik sesi içeren idempotent bir doğrudan geri dönüş gönderir.

Yerleşik paylaşılan araç yalnızca en az bir müzik üretme sağlayıcısı kullanılabilir olduğunda görünür. Ajanınızın araçlarında music_generate görmüyorsanız agents.defaults.musicGenerationModel yapılandırın veya bir sağlayıcı API anahtarı ayarlayın.

Hızlı başlangıç

Shared provider-backed
ComfyUI workflow

Configure auth

En az bir sağlayıcı için bir API anahtarı ayarlayın — örneğin GEMINI_API_KEY veya MINIMAX_API_KEY.

Pick a default model (optional)

{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
      },
    },
  },
}

Ask the agent

“Generate an upbeat synthpop track about a night drive through a neon city.”Ajan music_generate aracını otomatik olarak çağırır. Araç için izin listesi gerekmez.

Oturum destekli ajan çalıştırması olmayan doğrudan eşzamanlı bağlamlarda yerleşik araç yine de satır içi üretime geri döner ve araç sonucunda son medya yolunu döndürür.

Configure the workflow

plugins.entries.comfy.config.music değerini bir iş akışı JSON’u ve prompt/çıktı düğümleriyle yapılandırın.

Cloud auth (optional)

Comfy Cloud için COMFY_API_KEY veya COMFY_CLOUD_API_KEY ayarlayın.

Call the tool

/tool music_generate prompt="Warm ambient synth loop with soft tape texture"

Örnek promptlar:

Generate a cinematic piano track with soft strings and no vocals.

Generate an energetic chiptune loop about launching a rocket at sunrise.

Desteklenen sağlayıcılar

Sağlayıcı	Varsayılan model	Referans girdileri	Desteklenen denetimler	Kimlik doğrulama
ComfyUI	`workflow`	En fazla 1 görüntü	İş akışı tanımlı müzik veya ses	`COMFY_API_KEY`, `COMFY_CLOUD_API_KEY`
fal	`fal-ai/minimax-music/v2.6`	Yok	`lyrics`, `instrumental`, `durationSeconds`, `format`	`FAL_KEY` veya `FAL_API_KEY`
Google	`lyria-3-clip-preview`	En fazla 10 görüntü	`lyrics`, `instrumental`, `format`	`GEMINI_API_KEY`, `GOOGLE_API_KEY`
MiniMax	`music-2.6`	Yok	`lyrics`, `instrumental`, `format=mp3`	`MINIMAX_API_KEY` veya MiniMax OAuth
OpenRouter	`google/lyria-3-pro-preview`	En fazla 1 görüntü	`lyrics`, `instrumental`, `durationSeconds`, `format`	`OPENROUTER_API_KEY`

Yetenek matrisi

music_generate, sözleşme testleri ve paylaşılan canlı tarama tarafından kullanılan açık mod sözleşmesi:

Sağlayıcı	`generate`	`edit`	Düzenleme sınırı	Paylaşılan canlı hatlar
ComfyUI	✓	✓	1 görüntü	Paylaşılan taramada değil; `extensions/comfy/comfy.live.test.ts` kapsar
fal	✓	—	Yok	`generate`
Google	✓	✓	10 görüntü	`generate`, `edit`
MiniMax	✓	—	Yok	`generate`
OpenRouter	✓	✓	1 görüntü	`generate`, `edit`

Çalışma zamanında kullanılabilir paylaşılan sağlayıcıları ve modelleri incelemek için action: "list" kullanın:

/tool music_generate action=list

Etkin oturum destekli müzik görevini incelemek için action: "status" kullanın:

/tool music_generate action=status

Doğrudan üretim örneği:

/tool music_generate prompt="Dreamy lo-fi hip hop with vinyl texture and gentle rain" instrumental=true

Araç parametreleri

prompt

string

gerekli

Müzik üretme promptu. action: "generate" için gereklidir.

action

"generate" | "status" | "list"

varsayılan:"generate"

"status" geçerli oturum görevini döndürür; "list" sağlayıcıları inceler.

model

string

Sağlayıcı/model geçersiz kılması (örn. google/lyria-3-pro-preview, comfy/workflow).

lyrics

string

Sağlayıcı açık şarkı sözü girdisini desteklediğinde isteğe bağlı şarkı sözleri.

instrumental

boolean

Sağlayıcı desteklediğinde yalnızca enstrümantal çıktı isteyin.

image

string

Tek referans görüntü yolu veya URL.

images

string[]

Birden çok referans görüntüsü (destekleyen sağlayıcılarda en fazla 10).

durationSeconds

number

Sağlayıcı süre ipuçlarını desteklediğinde saniye cinsinden hedef süre.

format

"mp3" | "wav"

Sağlayıcı desteklediğinde çıktı biçimi ipucu.

filename

string

Çıktı dosya adı ipucu.

Tüm sağlayıcılar tüm parametreleri desteklemez. OpenClaw yine de gönderimden önce girdi sayısı gibi katı sınırları doğrular. Bir sağlayıcı süreyi destekliyor ancak istenen değerden daha kısa bir maksimum kullanıyorsa OpenClaw en yakın desteklenen süreye sınırlar. Seçilen sağlayıcı veya model gerçekten desteklenmeyen isteğe bağlı ipuçlarını yerine getiremiyorsa bunlar bir uyarıyla yok sayılır. Araç sonuçları uygulanan ayarları bildirir; details.normalization istenenden uygulanana yapılan tüm eşlemeleri yakalar.

Sağlayıcı istek zaman aşımları yalnızca operatör yapılandırmasıdır. OpenClaw yapılandırıldığında agents.defaults.musicGenerationModel.timeoutMs kullanır, 120000ms altındaki değerleri 120000ms değerine yükseltir ve aksi halde sağlayıcı istekleri için varsayılan olarak 300000ms kullanır.

Eşzamansız davranış

Oturum destekli müzik üretimi arka plan görevi olarak çalışır:

Arka plan görevi: music_generate bir arka plan görevi oluşturur, hemen başlatıldı/görev yanıtı döndürür ve tamamlanan parçayı daha sonra takip eden bir ajan mesajında gönderir.
Yinelenmeyi önleme: bir görev queued veya running durumundayken aynı oturumdaki sonraki music_generate çağrıları yeni bir üretim başlatmak yerine görev durumunu döndürür. Açıkça kontrol etmek için action: "status" kullanın.
Durum arama: openclaw tasks list veya openclaw tasks show <taskId> kuyruğa alınmış, çalışan ve terminal durumları inceler.
Tamamlama uyandırması: OpenClaw, modelin kullanıcıya yönelik takip mesajını kendisi yazabilmesi için aynı oturuma dahili bir tamamlama olayı enjekte eder.
Prompt ipucu: aynı oturumdaki sonraki kullanıcı/manuel turlar, bir müzik görevi zaten devam ediyorsa küçük bir çalışma zamanı ipucu alır; böylece model körlemesine tekrar music_generate çağırmaz.
Oturumsuz geri dönüş: gerçek bir ajan oturumu olmayan doğrudan/yerel bağlamlar satır içi çalışır ve son ses sonucunu aynı turda döndürür.

Görev yaşam döngüsü

Durum	Anlamı
`queued`	Görev oluşturuldu, sağlayıcının kabul etmesini bekliyor.
`running`	Sağlayıcı işliyor (sağlayıcıya ve süreye bağlı olarak genellikle 30 saniye ila 3 dakika).
`succeeded`	Parça hazır; ajan uyanır ve bunu konuşmaya gönderir.
`failed`	Sağlayıcı hatası veya zaman aşımı; ajan hata ayrıntılarıyla uyanır.

CLI’dan durumu kontrol edin:

openclaw tasks list
openclaw tasks show <taskId>
openclaw tasks cancel <taskId>

Yapılandırma

Model seçimi

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

Sağlayıcı seçimi sırası

OpenClaw sağlayıcıları şu sırayla dener:

Araç çağrısından gelen model parametresi (ajan bir tane belirtiyorsa).
Yapılandırmadan musicGenerationModel.primary.
Sırayla musicGenerationModel.fallbacks.
Yalnızca kimlik doğrulama destekli sağlayıcı varsayılanlarını kullanarak otomatik algılama:
- önce geçerli varsayılan sağlayıcı;
- ardından sağlayıcı kimliği sırasına göre kalan kayıtlı müzik üretme sağlayıcıları.

Bir sağlayıcı başarısız olursa sıradaki aday otomatik olarak denenir. Tümü başarısız olursa hata her denemeden ayrıntılar içerir. Yalnızca açık model, primary ve fallbacks girdilerini kullanmak için agents.defaults.mediaGenerationAutoProviderFallback: false ayarlayın.

Sağlayıcı notları

ComfyUI

İş akışı güdümlüdür ve prompt/çıktı alanları için yapılandırılmış grafiğe ve düğüm eşlemesine bağlıdır. Paketlenen comfy Plugin’i, müzik üretme sağlayıcı kayıt defteri üzerinden paylaşılan music_generate aracına bağlanır.

fal

Paylaşılan sağlayıcı kimlik doğrulama yolu üzerinden fal model uç noktalarını kullanır. Paketlenen sağlayıcı varsayılan olarak fal-ai/minimax-music/v2.6 kullanır ve prompttan sese istekleri için ayrıca fal-ai/ace-step/prompt-to-audio ve fal-ai/stable-audio-25/text-to-audio sunar.

Google (Lyria 3)

Lyria 3 toplu üretimini kullanır. Geçerli paketlenmiş akış promptu, isteğe bağlı şarkı sözü metnini ve isteğe bağlı referans görüntülerini destekler.

MiniMax

Toplu music_generation uç noktasını kullanır. Promptu, isteğe bağlı şarkı sözlerini, enstrümantal modu ve minimax API anahtarı kimlik doğrulaması veya minimax-portal OAuth üzerinden mp3 çıktısını destekler.

OpenRouter

Akış etkinleştirilmiş OpenRouter sohbet tamamlama ses çıktısını kullanır. Paketlenen sağlayıcı varsayılan olarak google/lyria-3-pro-preview kullanır ve ayrıca openrouter/google/lyria-3-clip-preview sunar.

Doğru yolu seçme

Paylaşılan sağlayıcı destekli: model seçimi, sağlayıcı yük devretmesi ve yerleşik eşzamansız görev/durum akışını istediğinizde.
Plugin yolu (ComfyUI): özel bir iş akışı grafiğine veya paylaşılan paketlenmiş müzik yeteneğinin parçası olmayan bir sağlayıcıya ihtiyacınız olduğunda.

ComfyUI’ye özgü davranışı hata ayıklıyorsanız bkz. ComfyUI. Paylaşılan sağlayıcı davranışını hata ayıklıyorsanız fal, Google (Gemini), MiniMax veya OpenRouter ile başlayın.

Sağlayıcı yetenek modları

Paylaşılan müzik üretimi sözleşmesi açık mod bildirimlerini destekler:

Yalnızca istemle üretim için generate.
İstek bir veya daha fazla referans görseli içerdiğinde edit.

Yeni sağlayıcı uygulamaları açık mod bloklarını tercih etmelidir:

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

maxInputImages, supportsLyrics ve supportsFormat gibi eski düz alanlar, düzenleme desteğini duyurmak için yeterli değildir. Sağlayıcılar generate ve edit değerlerini açıkça bildirmelidir; böylece canlı testler, sözleşme testleri ve paylaşılan music_generate aracı mod desteğini deterministik olarak doğrulayabilir.

Canlı testler

Paylaşılan paketli sağlayıcılar için isteğe bağlı canlı kapsam:

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

Depo sarmalayıcısı:

pnpm test:live:media music

Bu canlı dosya varsayılan olarak saklanan kimlik doğrulama profillerinden önce zaten dışa aktarılmış sağlayıcı ortam değişkenlerini kullanır ve sağlayıcı düzenleme modunu etkinleştirdiğinde hem generate hem de bildirilen edit kapsamını çalıştırır. Bugünkü kapsam:

google: generate ve edit
fal: yalnızca generate
minimax: yalnızca generate
openrouter: generate ve edit
comfy: paylaşılan sağlayıcı taraması değil, ayrı Comfy canlı kapsamı

Paketli ComfyUI müzik yolu için isteğe bağlı canlı kapsam:

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

Comfy canlı dosyası, bu bölümler yapılandırıldığında comfy görsel ve video iş akışlarını da kapsar.

İlgili

Arka plan görevleri — ayrılmış music_generate çalıştırmaları için görev takibi
ComfyUI
Yapılandırma başvurusu — musicGenerationModel yapılandırması
Google (Gemini)
MiniMax
Modeller — model yapılandırması ve yük devretme
Araçlara genel bakış

​Hızlı başlangıç

​Desteklenen sağlayıcılar

​Yetenek matrisi

​Araç parametreleri

​Eşzamansız davranış

​Görev yaşam döngüsü

​Yapılandırma

​Model seçimi

​Sağlayıcı seçimi sırası

​Sağlayıcı notları

​Doğru yolu seçme

​Sağlayıcı yetenek modları

​Canlı testler

​İlgili

Hızlı başlangıç

Desteklenen sağlayıcılar

Yetenek matrisi

Araç parametreleri

Eşzamansız davranış

Görev yaşam döngüsü

Yapılandırma

Model seçimi

Sağlayıcı seçimi sırası

Sağlayıcı notları

Doğru yolu seçme

Sağlayıcı yetenek modları

Canlı testler

İlgili