---
read_when:
    - การสร้างเพลงหรือเสียงผ่านเอเจนต์
    - การกำหนดค่าผู้ให้บริการและโมเดลสำหรับการสร้างเพลง
    - ทำความเข้าใจพารามิเตอร์ของเครื่องมือ music_generate
sidebarTitle: Music generation
summary: สร้างเพลงผ่าน music_generate ในเวิร์กโฟลว์ของ Google Lyria, MiniMax และ ComfyUI
title: การสร้างเพลง
x-i18n:
    generated_at: "2026-05-02T10:31:54Z"
    model: gpt-5.5
    provider: openai
    source_hash: 9199afe17b2641efb1a7523c651724af9c312c1415c7e60ca736341699f6bc26
    source_path: tools/music-generation.md
    workflow: 16
---

เครื่องมือ `music_generate` ช่วยให้เอเจนต์สร้างเพลงหรือเสียงผ่านความสามารถการสร้างเพลงแบบใช้ร่วมกันกับผู้ให้บริการที่กำหนดค่าไว้ ซึ่งปัจจุบันคือ Google, MiniMax และ ComfyUI ที่กำหนดค่าผ่านเวิร์กโฟลว์

สำหรับการรันเอเจนต์ที่มีเซสชันรองรับ OpenClaw จะเริ่มการสร้างเพลงเป็นงานเบื้องหลัง ติดตามไว้ในบัญชีแยกประเภทของงาน จากนั้นปลุกเอเจนต์อีกครั้งเมื่อแทร็กพร้อม เพื่อให้เอเจนต์โพสต์เสียงที่เสร็จแล้วกลับไปยังช่องทางเดิม

<Note>
เครื่องมือแบบใช้ร่วมกันในตัวจะแสดงเฉพาะเมื่อมีผู้ให้บริการการสร้างเพลงอย่างน้อยหนึ่งรายพร้อมใช้งาน หากคุณไม่เห็น `music_generate` ในเครื่องมือของเอเจนต์ ให้กำหนดค่า `agents.defaults.musicGenerationModel` หรือตั้งค่าคีย์ API ของผู้ให้บริการ
</Note>

## เริ่มต้นอย่างรวดเร็ว

<Tabs>
  <Tab title="ผู้ให้บริการแบบใช้ร่วมกันรองรับ">
    <Steps>
      <Step title="กำหนดค่าการยืนยันตัวตน">
        ตั้งค่าคีย์ API สำหรับผู้ให้บริการอย่างน้อยหนึ่งราย เช่น
        `GEMINI_API_KEY` หรือ `MINIMAX_API_KEY`
      </Step>
      <Step title="เลือกรุ่นเริ่มต้น (ไม่บังคับ)">
        ```json5
        {
          agents: {
            defaults: {
              musicGenerationModel: {
                primary: "google/lyria-3-clip-preview",
              },
            },
          },
        }
        ```
      </Step>
      <Step title="ถามเอเจนต์">
        _"สร้างแทร็กซินธ์ป็อปจังหวะสดใสเกี่ยวกับการขับรถยามค่ำคืนผ่านเมืองนีออน"_

        เอเจนต์จะเรียก `music_generate` โดยอัตโนมัติ ไม่ต้องเพิ่มเครื่องมือในรายการอนุญาต
      </Step>
    </Steps>

    สำหรับบริบทแบบซิงโครนัสโดยตรงที่ไม่มีการรันเอเจนต์ซึ่งมีเซสชันรองรับ เครื่องมือในตัวยังคงถอยกลับไปใช้การสร้างแบบอินไลน์และคืนพาธสื่อสุดท้ายในผลลัพธ์ของเครื่องมือ

  </Tab>
  <Tab title="เวิร์กโฟลว์ ComfyUI">
    <Steps>
      <Step title="กำหนดค่าเวิร์กโฟลว์">
        กำหนดค่า `plugins.entries.comfy.config.music` ด้วย JSON ของเวิร์กโฟลว์และโหนดพรอมป์/เอาต์พุต
      </Step>
      <Step title="การยืนยันตัวตนบนคลาวด์ (ไม่บังคับ)">
        สำหรับ Comfy Cloud ให้ตั้งค่า `COMFY_API_KEY` หรือ `COMFY_CLOUD_API_KEY`
      </Step>
      <Step title="เรียกเครื่องมือ">
        ```text
        /tool music_generate prompt="Warm ambient synth loop with soft tape texture"
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

ตัวอย่างพรอมป์:

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

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

## ผู้ให้บริการที่รองรับ

| ผู้ให้บริการ | รุ่นเริ่มต้น          | อินพุตอ้างอิง | การควบคุมที่รองรับ                                        | การยืนยันตัวตน                                   |
| -------- | ---------------------- | ---------------- | --------------------------------------------------------- | -------------------------------------- |
| ComfyUI  | `workflow`             | สูงสุด 1 ภาพ    | เพลงหรือเสียงที่กำหนดโดยเวิร์กโฟลว์                           | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google   | `lyria-3-clip-preview` | สูงสุด 10 ภาพ  | `lyrics`, `instrumental`, `format`                        | `GEMINI_API_KEY`, `GOOGLE_API_KEY`     |
| MiniMax  | `music-2.6`            | ไม่มี             | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` หรือ MiniMax OAuth     |

### เมทริกซ์ความสามารถ

สัญญาโหมดแบบชัดเจนที่ใช้โดย `music_generate`, การทดสอบสัญญา และการกวาดทดสอบสดแบบใช้ร่วมกัน:

| ผู้ให้บริการ | `generate` | `edit` | ขีดจำกัดการแก้ไข | เลนสดแบบใช้ร่วมกัน                                                         |
| -------- | :--------: | :----: | ---------- | ------------------------------------------------------------------------- |
| ComfyUI  |     ✓      |   ✓    | 1 ภาพ    | ไม่อยู่ในการกวาดแบบใช้ร่วมกัน; ครอบคลุมโดย `extensions/comfy/comfy.live.test.ts` |
| Google   |     ✓      |   ✓    | 10 ภาพ  | `generate`, `edit`                                                        |
| MiniMax  |     ✓      |   —    | ไม่มี       | `generate`                                                                |

ใช้ `action: "list"` เพื่อตรวจสอบผู้ให้บริการและรุ่นแบบใช้ร่วมกันที่พร้อมใช้งานขณะรันไทม์:

```text
/tool music_generate action=list
```

ใช้ `action: "status"` เพื่อตรวจสอบงานเพลงที่มีเซสชันรองรับซึ่งกำลังทำงานอยู่:

```text
/tool music_generate action=status
```

ตัวอย่างการสร้างโดยตรง:

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

## พารามิเตอร์เครื่องมือ

<ParamField path="prompt" type="string" required>
  พรอมป์การสร้างเพลง จำเป็นสำหรับ `action: "generate"`
</ParamField>
<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
  `"status"` คืนค่างานเซสชันปัจจุบัน; `"list"` ตรวจสอบผู้ให้บริการ
</ParamField>
<ParamField path="model" type="string">
  การแทนที่ผู้ให้บริการ/รุ่น (เช่น `google/lyria-3-pro-preview`,
  `comfy/workflow`)
</ParamField>
<ParamField path="lyrics" type="string">
  เนื้อร้องเสริมเมื่อผู้ให้บริการรองรับอินพุตเนื้อร้องแบบชัดเจน
</ParamField>
<ParamField path="instrumental" type="boolean">
  ขอเอาต์พุตเฉพาะดนตรีบรรเลงเมื่อผู้ให้บริการรองรับ
</ParamField>
<ParamField path="image" type="string">
  พาธหรือ URL ของภาพอ้างอิงเดี่ยว
</ParamField>
<ParamField path="images" type="string[]">
  ภาพอ้างอิงหลายภาพ (สูงสุด 10 ภาพบนผู้ให้บริการที่รองรับ)
</ParamField>
<ParamField path="durationSeconds" type="number">
  ระยะเวลาเป้าหมายเป็นวินาทีเมื่อผู้ให้บริการรองรับคำใบ้ระยะเวลา
</ParamField>
<ParamField path="format" type='"mp3" | "wav"'>
  คำใบ้รูปแบบเอาต์พุตเมื่อผู้ให้บริการรองรับ
</ParamField>
<ParamField path="filename" type="string">คำใบ้ชื่อไฟล์เอาต์พุต</ParamField>
<ParamField path="timeoutMs" type="number">เวลาหมดอายุคำขอผู้ให้บริการแบบไม่บังคับเป็นมิลลิวินาที ค่าที่ต่ำกว่า 10000ms จะถูกยกขึ้นเป็น 10000ms และรายงานในผลลัพธ์ของเครื่องมือ</ParamField>

<Note>
ผู้ให้บริการบางรายไม่ได้รองรับพารามิเตอร์ทั้งหมด OpenClaw ยังคงตรวจสอบขีดจำกัดแบบแข็ง เช่น จำนวนอินพุตก่อนส่ง เมื่อผู้ให้บริการรองรับระยะเวลาแต่ใช้ค่าสูงสุดที่สั้นกว่าค่าที่ร้องขอ OpenClaw จะจำกัดไว้ที่ระยะเวลาที่รองรับซึ่งใกล้ที่สุด คำใบ้เสริมที่ไม่รองรับจริงจะถูกละเว้นพร้อมคำเตือนเมื่อผู้ให้บริการหรือรุ่นที่เลือกไม่สามารถทำตามได้ ผลลัพธ์ของเครื่องมือจะรายงานการตั้งค่าที่ใช้จริง; `details.normalization` บันทึกการแมปจากค่าที่ร้องขอไปเป็นค่าที่ใช้จริง
</Note>

## พฤติกรรมอะซิงโครนัส

การสร้างเพลงที่มีเซสชันรองรับทำงานเป็นงานเบื้องหลัง:

- **งานเบื้องหลัง:** `music_generate` สร้างงานเบื้องหลัง คืนการตอบกลับว่าเริ่มแล้ว/งานแล้วทันที และโพสต์แทร็กที่เสร็จแล้วภายหลังในข้อความติดตามผลของเอเจนต์
- **การป้องกันรายการซ้ำ:** ขณะที่งานอยู่ในสถานะ `queued` หรือ `running` การเรียก `music_generate` ภายหลังในเซสชันเดียวกันจะคืนสถานะงานแทนการเริ่มการสร้างอีกครั้ง ใช้ `action: "status"` เพื่อตรวจสอบอย่างชัดเจน
- **การค้นหาสถานะ:** `openclaw tasks list` หรือ `openclaw tasks show <taskId>` ตรวจสอบสถานะที่อยู่ในคิว กำลังทำงาน และสถานะปลายทาง
- **การปลุกเมื่อเสร็จสิ้น:** OpenClaw ฉีดเหตุการณ์เสร็จสิ้นภายในกลับเข้าไปในเซสชันเดียวกัน เพื่อให้โมเดลเขียนข้อความติดตามผลสำหรับผู้ใช้เองได้
- **คำใบ้พรอมป์:** เทิร์นของผู้ใช้/แบบแมนนวลภายหลังในเซสชันเดียวกันจะได้รับคำใบ้รันไทม์ขนาดเล็กเมื่อมีงานเพลงกำลังดำเนินอยู่ เพื่อให้โมเดลไม่เรียก `music_generate` ซ้ำโดยไม่ตั้งใจ
- **การถอยกลับเมื่อไม่มีเซสชัน:** บริบทโดยตรง/โลคัลที่ไม่มีเซสชันเอเจนต์จริงจะรันแบบอินไลน์และคืนผลลัพธ์เสียงสุดท้ายในเทิร์นเดียวกัน

### วงจรชีวิตของงาน

| สถานะ       | ความหมาย                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------- |
| `queued`    | สร้างงานแล้ว รอให้ผู้ให้บริการยอมรับ                                           |
| `running`   | ผู้ให้บริการกำลังประมวลผล (โดยทั่วไป 30 วินาทีถึง 3 นาที ขึ้นอยู่กับผู้ให้บริการและระยะเวลา) |
| `succeeded` | แทร็กพร้อมแล้ว; เอเจนต์ถูกปลุกและโพสต์ลงในการสนทนา                                 |
| `failed`    | ข้อผิดพลาดของผู้ให้บริการหรือหมดเวลา; เอเจนต์ถูกปลุกพร้อมรายละเอียดข้อผิดพลาด                                 |

ตรวจสอบสถานะจาก CLI:

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

## การกำหนดค่า

### การเลือกรุ่น

```json5
{
  agents: {
    defaults: {
      musicGenerationModel: {
        primary: "google/lyria-3-clip-preview",
        fallbacks: ["minimax/music-2.6"],
      },
    },
  },
}
```

### ลำดับการเลือกผู้ให้บริการ

OpenClaw ลองใช้ผู้ให้บริการตามลำดับนี้:

1. พารามิเตอร์ `model` จากการเรียกเครื่องมือ (หากเอเจนต์ระบุไว้)
2. `musicGenerationModel.primary` จากการกำหนดค่า
3. `musicGenerationModel.fallbacks` ตามลำดับ
4. การตรวจจับอัตโนมัติโดยใช้เฉพาะค่าเริ่มต้นของผู้ให้บริการที่มีการยืนยันตัวตนรองรับ:
   - ผู้ให้บริการเริ่มต้นปัจจุบันก่อน;
   - ผู้ให้บริการการสร้างเพลงที่ลงทะเบียนไว้ที่เหลือตามลำดับรหัสผู้ให้บริการ

หากผู้ให้บริการล้มเหลว ระบบจะลองผู้สมัครรายถัดไปโดยอัตโนมัติ หากทั้งหมดล้มเหลว ข้อผิดพลาดจะรวมรายละเอียดจากแต่ละความพยายาม

ตั้งค่า `agents.defaults.mediaGenerationAutoProviderFallback: false` เพื่อใช้เฉพาะรายการ `model`, `primary` และ `fallbacks` ที่ระบุอย่างชัดเจนเท่านั้น

## หมายเหตุผู้ให้บริการ

<AccordionGroup>
  <Accordion title="ComfyUI">
    ขับเคลื่อนด้วยเวิร์กโฟลว์และขึ้นอยู่กับกราฟที่กำหนดค่าไว้รวมถึงการแมปโหนดสำหรับฟิลด์พรอมป์/เอาต์พุต Plugin `comfy` ที่มาพร้อมกันเชื่อมเข้ากับเครื่องมือ `music_generate` แบบใช้ร่วมกันผ่านรีจิสทรีผู้ให้บริการการสร้างเพลง
  </Accordion>
  <Accordion title="Google (Lyria 3)">
    ใช้การสร้างแบบแบตช์ของ Lyria 3 โฟลว์ที่มาพร้อมกันปัจจุบันรองรับพรอมป์ ข้อความเนื้อร้องเสริม และภาพอ้างอิงเสริม
  </Accordion>
  <Accordion title="MiniMax">
    ใช้เอนด์พอยต์แบบแบตช์ `music_generation` รองรับพรอมป์ เนื้อร้องเสริม โหมดดนตรีบรรเลง การกำกับระยะเวลา และเอาต์พุต mp3 ผ่านการยืนยันตัวตนด้วยคีย์ API ของ `minimax` หรือ OAuth ของ `minimax-portal`
  </Accordion>
</AccordionGroup>

## การเลือกเส้นทางที่เหมาะสม

- **ผู้ให้บริการแบบใช้ร่วมกันรองรับ** เมื่อคุณต้องการการเลือกรุ่น การเฟลโอเวอร์ของผู้ให้บริการ และโฟลว์งาน/สถานะแบบอะซิงโครนัสในตัว
- **เส้นทาง Plugin (ComfyUI)** เมื่อคุณต้องการกราฟเวิร์กโฟลว์แบบกำหนดเองหรือผู้ให้บริการที่ไม่ได้เป็นส่วนหนึ่งของความสามารถเพลงแบบใช้ร่วมกันที่มาพร้อมกัน

หากคุณกำลังดีบักพฤติกรรมเฉพาะของ ComfyUI โปรดดู
[ComfyUI](/th/providers/comfy) หากคุณกำลังดีบักพฤติกรรมผู้ให้บริการแบบใช้ร่วมกัน ให้เริ่มจาก [Google (Gemini)](/th/providers/google) หรือ
[MiniMax](/th/providers/minimax)

## โหมดความสามารถของผู้ให้บริการ

สัญญาการสร้างเพลงแบบใช้ร่วมกันรองรับการประกาศโหมดแบบชัดเจน:

- `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` แบบใช้ร่วมกันตรวจสอบการรองรับโหมดได้อย่างกำหนดแน่นอน

## การทดสอบสด

ความครอบคลุมสดแบบเลือกเปิดใช้สำหรับผู้ให้บริการที่มาพร้อมกันแบบใช้ร่วมกัน:

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

ตัวครอบของรีโป:

```bash
pnpm test:live:media music
```

ไฟล์สดนี้โหลดตัวแปรสภาพแวดล้อมของผู้ให้บริการที่ขาดหายไปจาก `~/.profile` เลือกใช้คีย์ API สด/จากสภาพแวดล้อมก่อนโปรไฟล์การยืนยันตัวตนที่จัดเก็บไว้โดยค่าเริ่มต้น และรันความครอบคลุมทั้ง `generate` และ `edit` ที่ประกาศไว้เมื่อผู้ให้บริการเปิดใช้โหมดแก้ไข ความครอบคลุมปัจจุบัน:

- `google`: `generate` พร้อม `edit`
- `minimax`: เฉพาะ `generate`
- `comfy`: ความครอบคลุมสดของ Comfy แยกต่างหาก ไม่ใช่การกวาดผู้ให้บริการแบบใช้ร่วมกัน

ความครอบคลุมสดแบบเลือกเปิดใช้สำหรับเส้นทางเพลง ComfyUI ที่มาพร้อมกัน:

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

ไฟล์ไลฟ์ของ Comfy ยังครอบคลุมเวิร์กโฟลว์ภาพและวิดีโอของ Comfy เมื่อกำหนดค่าส่วนเหล่านั้นแล้ว

## ที่เกี่ยวข้อง

- [งานเบื้องหลัง](/th/automation/tasks) — การติดตามงานสำหรับการรัน `music_generate` แบบแยกตัว
- [ComfyUI](/th/providers/comfy)
- [อ้างอิงการกำหนดค่า](/th/gateway/config-agents#agent-defaults) — การกำหนดค่า `musicGenerationModel`
- [Google (Gemini)](/th/providers/google)
- [MiniMax](/th/providers/minimax)
- [โมเดล](/th/concepts/models) — การกำหนดค่าโมเดลและการสลับสำรองเมื่อขัดข้อง
- [ภาพรวมเครื่องมือ](/th/tools)
