تولید موسیقی

درخواست تولید موسیقی. برای action: "generate" الزامی است.

"status" وظیفه فعلی نشست را بازمی‌گرداند؛ "list" ارائه‌دهندگان را بررسی می‌کند.

جایگزینی ارائه‌دهنده/مدل (برای مثال google/lyria-3-pro-preview، comfy/workflow).

متن ترانه اختیاری، هنگامی که ارائه‌دهنده از ورودی صریح متن ترانه پشتیبانی کند.

درخواست خروجی فقط بی‌کلام، هنگامی که ارائه‌دهنده از آن پشتیبانی کند.

مسیر یا نشانی وب یک تصویر مرجع.

چند تصویر مرجع (در ارائه‌دهندگان پشتیبان، حداکثر ۱۰ تصویر).

مدت هدف برحسب ثانیه، هنگامی که ارائه‌دهنده از راهنمای مدت پشتیبانی کند.

راهنمای قالب خروجی، هنگامی که ارائه‌دهنده از آن پشتیبانی کند.

مهلت زمانی درخواست ارائه‌دهنده فقط در پیکربندی اپراتور تعیین می‌شود. OpenClaw در صورت پیکربندی از agents.defaults.musicGenerationModel.timeoutMs استفاده می‌کند، مقادیر کمتر از 120000ms را به 120000ms افزایش می‌دهد و در غیر این صورت، مهلت پیش‌فرض درخواست‌های ارائه‌دهنده را 300000ms قرار می‌دهد.

رفتار ناهمگام

تولید موسیقی مبتنی بر نشست به‌صورت یک وظیفه پس‌زمینه اجرا می‌شود:

• وظیفه پس‌زمینه: music_generate یک وظیفه پس‌زمینه ایجاد می‌کند، پاسخ آغازشده/وظیفه را بی‌درنگ بازمی‌گرداند و قطعه نهایی را بعداً در یک پیام پیگیری عامل ارسال می‌کند.
• جلوگیری از تکرار: تا زمانی که وظیفه‌ای در حالت queued یا running باشد، فراخوانی‌های بعدی music_generate در همان نشست، به‌جای آغاز تولیدی دیگر، وضعیت وظیفه را بازمی‌گردانند. برای بررسی صریح از action: "status" استفاده کنید. درخواست منطبق و به‌تازگی تکمیل‌شده نیز تا ۲ دقیقه تکرارزدایی می‌شود.
• جست‌وجوی وضعیت: openclaw tasks list یا openclaw tasks show <taskId> وضعیت‌های در صف، در حال اجرا و پایانی را بررسی می‌کند.
• بیدارسازی پس از تکمیل: OpenClaw یک رویداد تکمیل داخلی را دوباره به همان نشست تزریق می‌کند تا مدل بتواند خودش پیام پیگیری قابل‌مشاهده برای کاربر را بنویسد.
• راهنمای درخواست: نوبت‌های بعدی کاربر/دستی در همان نشست، هنگامی که وظیفه موسیقی از قبل در حال اجراست، یک راهنمای کوچک زمان اجرا دریافت می‌کنند تا مدل دوباره کورکورانه music_generate را فراخوانی نکند.
• جایگزین بدون نشست: زمینه‌های مستقیم/محلی بدون نشست واقعی عامل، به‌صورت درون‌خطی اجرا می‌شوند و نتیجه نهایی صدا را در همان نوبت بازمی‌گردانند.

چرخه حیات وظیفه

وظیفه موسیقی همان حالت‌های رجیستری عمومی وظایف را ارائه می‌کند (برای ماشین حالت کامل، شامل timed_out، cancelled و lost، به وظایف پس‌زمینه مراجعه کنید). بیشتر اجراهای موسیقی از حالت‌های زیر عبور می‌کنند:

وضعیت را از CLI بررسی کنید:

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

پیکربندی

انتخاب مدل

{  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. تشخیص خودکار، فقط با استفاده از پیش‌فرض‌های ارائه‌دهنده مبتنی بر احراز هویت:
   • ابتدا ارائه‌دهنده فعلی مدل متنی، اگر تولید موسیقی را نیز ارائه دهد؛
   • سپس سایر ارائه‌دهندگان ثبت‌شده تولید موسیقی، به‌ترتیب الفبایی شناسه ارائه‌دهنده.

اگر ارائه‌دهنده‌ای ناموفق باشد، نامزد بعدی به‌طور خودکار امتحان می‌شود. اگر همه ناموفق باشند، خطا جزئیات هر تلاش را شامل می‌شود.

برای استفاده صرفاً از ورودی‌های صریح model، primary و fallbacks، agents.defaults.mediaGenerationAutoProviderFallback: false را تنظیم کنید.

نکات ارائه‌دهندگان

انتخاب مسیر مناسب

• مبتنی بر ارائه‌دهنده مشترک هنگامی که انتخاب مدل، جایگزینی خودکار ارائه‌دهنده و جریان داخلی ناهمگام وظیفه/وضعیت را می‌خواهید.
• مسیر Plugin ‏(ComfyUI) هنگامی که به یک گراف گردش‌کار سفارشی یا ارائه‌دهنده‌ای نیاز دارید که بخشی از قابلیت مشترک و همراه موسیقی نیست.

اگر در حال اشکال‌زدایی رفتار مختص ComfyUI هستید، به ComfyUI مراجعه کنید. اگر در حال اشکال‌زدایی رفتار ارائه‌دهنده مشترک هستید، با fal، Google (Gemini)، MiniMax یا OpenRouter شروع کنید.

حالت‌های قابلیت ارائه‌دهنده

قرارداد مشترک تولید موسیقی از اعلان صریح حالت‌ها پشتیبانی می‌کند:

• generate برای تولید صرفاً بر اساس پرامپت.
• edit هنگامی که درخواست شامل یک یا چند تصویر مرجع است.

پیاده‌سازی‌های جدید ارائه‌دهنده باید بلوک‌های صریح حالت را ترجیح دهند:

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):

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

پوشش‌دهنده معادل مخزن که همان فایل آزمون را اجرا می‌کند:

pnpm test:live:media:music

این فایل زنده به‌طور پیش‌فرض از متغیرهای محیطی ازپیش‌صادرشده ارائه‌دهنده، پیش از پروفایل‌های احراز هویت ذخیره‌شده استفاده می‌کند و هنگامی که ارائه‌دهنده حالت ویرایش را فعال کرده باشد، پوشش generate و edit اعلام‌شده را اجرا می‌کند. پوشش فعلی:

• google: ‏generate به‌همراه edit
• fal: فقط generate
• minimax: فقط generate
• openrouter: ‏generate به‌همراه edit
• comfy: پوشش زنده جداگانه Comfy، نه پیمایش مشترک ارائه‌دهندگان

پوشش زنده اختیاری برای مسیر همراه موسیقی ComfyUI:

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

فایل زنده Comfy هنگامی که بخش‌های مربوطه پیکربندی شده باشند، گردش‌کارهای تصویر و ویدیوی comfy را نیز پوشش می‌دهد.

مرتبط

• وظایف پس‌زمینه — ردیابی وظیفه برای اجراهای جداشده music_generate
• ComfyUI
• مرجع پیکربندی — پیکربندی musicGenerationModel
• Google (Gemini)
• MiniMax
• مدل‌ها — پیکربندی مدل و جایگزینی خودکار
• نمای کلی ابزارها