Tạo nhạc

Lời nhắc tạo nhạc. Bắt buộc đối với action: "generate".

"status" trả về tác vụ phiên hiện tại; "list" kiểm tra các nhà cung cấp.

Ghi đè nhà cung cấp/mô hình (ví dụ: google/lyria-3-pro-preview, comfy/workflow).

Lời bài hát không bắt buộc khi nhà cung cấp hỗ trợ đầu vào lời bài hát rõ ràng.

Yêu cầu đầu ra chỉ có nhạc không lời khi nhà cung cấp hỗ trợ.

Đường dẫn hoặc URL của một hình ảnh tham chiếu.

Nhiều hình ảnh tham chiếu (tối đa 10 trên các nhà cung cấp hỗ trợ).

Thời lượng mục tiêu tính bằng giây khi nhà cung cấp hỗ trợ gợi ý thời lượng.

Gợi ý định dạng đầu ra khi nhà cung cấp hỗ trợ.

Thời gian chờ yêu cầu nhà cung cấp chỉ là cấu hình dành cho người vận hành. OpenClaw sử dụng agents.defaults.musicGenerationModel.timeoutMs khi được cấu hình, nâng các giá trị dưới 120000ms lên 120000ms và nếu không thì mặc định thời gian chờ yêu cầu nhà cung cấp là 300000ms.

Hành vi bất đồng bộ

Việc tạo nhạc có phiên hỗ trợ chạy dưới dạng tác vụ nền:

• Tác vụ nền: music_generate tạo tác vụ nền, ngay lập tức trả về phản hồi đã khởi chạy/tác vụ và đăng bản nhạc hoàn chỉnh sau đó trong tin nhắn tiếp theo của tác nhân.
• Ngăn trùng lặp: khi một tác vụ đang ở trạng thái queued hoặc running, các lần gọi music_generate tiếp theo trong cùng phiên sẽ trả về trạng thái tác vụ thay vì bắt đầu một lần tạo khác. Dùng action: "status" để kiểm tra rõ ràng. Yêu cầu khớp mới hoàn tất gần đây cũng được loại bỏ trùng lặp trong 2 phút.
• Tra cứu trạng thái: openclaw tasks list hoặc openclaw tasks show <taskId> kiểm tra trạng thái đang chờ, đang chạy và kết thúc.
• Đánh thức khi hoàn tất: OpenClaw chèn một sự kiện hoàn tất nội bộ trở lại cùng phiên để mô hình có thể tự viết thông báo tiếp theo hướng đến người dùng.
• Gợi ý lời nhắc: các lượt người dùng/thủ công sau đó trong cùng phiên nhận được một gợi ý nhỏ khi chạy nếu tác vụ âm nhạc đã đang được xử lý, để mô hình không gọi lại music_generate một cách mù quáng.
• Phương án dự phòng khi không có phiên: các ngữ cảnh trực tiếp/cục bộ không có phiên tác nhân thực sự sẽ chạy nội tuyến và trả về kết quả âm thanh cuối cùng trong cùng lượt.

Vòng đời tác vụ

Tác vụ âm nhạc hiển thị các trạng thái giống như sổ đăng ký tác vụ chung (xem Tác vụ nền để biết toàn bộ máy trạng thái, bao gồm timed_out, cancelled và lost). Hầu hết lượt chạy âm nhạc chuyển qua:

Kiểm tra trạng thái từ CLI:

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

Cấu hình

Lựa chọn mô hình

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

Thứ tự lựa chọn nhà cung cấp

OpenClaw thử các nhà cung cấp theo thứ tự sau:

1. Tham số model từ lệnh gọi công cụ (nếu tác nhân chỉ định).
2. musicGenerationModel.primary từ cấu hình.
3. musicGenerationModel.fallbacks theo thứ tự.
4. Tự động phát hiện chỉ bằng các giá trị mặc định của nhà cung cấp có xác thực:
   • nhà cung cấp mô hình văn bản mặc định hiện tại trước, nếu nhà cung cấp đó cũng hỗ trợ tạo nhạc;
   • các nhà cung cấp tạo nhạc đã đăng ký còn lại, theo thứ tự chữ cái của mã định danh nhà cung cấp.

Nếu một nhà cung cấp thất bại, ứng viên tiếp theo sẽ tự động được thử. Nếu tất cả đều thất bại, lỗi sẽ bao gồm thông tin chi tiết từ mỗi lần thử.

Đặt agents.defaults.mediaGenerationAutoProviderFallback: false để chỉ sử dụng các mục model, primary và fallbacks được chỉ định rõ ràng.

Ghi chú về nhà cung cấp

Chọn đường dẫn phù hợp

• Dựa trên nhà cung cấp dùng chung khi bạn muốn chọn mô hình, chuyển đổi dự phòng giữa các nhà cung cấp và luồng tác vụ/trạng thái bất đồng bộ tích hợp sẵn.
• Đường dẫn Plugin (ComfyUI) khi bạn cần một biểu đồ quy trình tùy chỉnh hoặc một nhà cung cấp không thuộc khả năng tạo nhạc dùng chung đi kèm.

Nếu bạn đang gỡ lỗi hành vi riêng của ComfyUI, hãy xem ComfyUI. Nếu bạn đang gỡ lỗi hành vi của nhà cung cấp dùng chung, hãy bắt đầu với fal, Google (Gemini), MiniMax hoặc OpenRouter.

Các chế độ khả năng của nhà cung cấp

Hợp đồng tạo nhạc dùng chung hỗ trợ khai báo chế độ tường minh:

• generate dành cho việc tạo chỉ từ lời nhắc.
• edit khi yêu cầu bao gồm một hoặc nhiều hình ảnh tham chiếu.

Các triển khai nhà cung cấp mới nên ưu tiên các khối chế độ tường minh:

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

Các trường phẳng cũ như maxInputImages, supportsLyrics và supportsFormat không đủ để công bố hỗ trợ chỉnh sửa. Các nhà cung cấp nên khai báo tường minh generate và edit để các kiểm thử trực tiếp, kiểm thử hợp đồng và công cụ music_generate dùng chung có thể xác thực khả năng hỗ trợ chế độ một cách xác định.

Kiểm thử trực tiếp

Phạm vi kiểm thử trực tiếp tùy chọn cho các nhà cung cấp dùng chung đi kèm (fal, Google, MiniMax, OpenRouter):

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

Trình bao bọc kho lưu trữ tương đương, chạy cùng một tệp kiểm thử:

pnpm test:live:media:music

Theo mặc định, tệp kiểm thử trực tiếp này ưu tiên sử dụng các biến môi trường của nhà cung cấp đã được xuất trước các hồ sơ xác thực đã lưu trữ, đồng thời chạy cả phạm vi generate và edit đã khai báo khi nhà cung cấp bật chế độ chỉnh sửa. Phạm vi hiện tại:

• google: generate cùng với edit
• fal: chỉ generate
• minimax: chỉ generate
• openrouter: generate cùng với edit
• comfy: phạm vi kiểm thử trực tiếp Comfy riêng, không thuộc lượt quét nhà cung cấp dùng chung

Phạm vi kiểm thử trực tiếp tùy chọn cho đường dẫn tạo nhạc ComfyUI đi kèm:

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

Tệp kiểm thử trực tiếp Comfy cũng bao quát các quy trình hình ảnh và video của comfy khi các phần đó được cấu hình.

Liên quan

• Tác vụ nền — theo dõi tác vụ cho các lần chạy music_generate tách rời
• ComfyUI
• Tham chiếu cấu hình — cấu hình musicGenerationModel
• Google (Gemini)
• MiniMax
• Mô hình — cấu hình mô hình và chuyển đổi dự phòng
• Tổng quan về công cụ